Module: Arborist::TreeAPI

Extended by:
HashUtilities, MethodUtilities, Loggability
Defined in:
lib/arborist/tree_api.rb

Constant Summary collapse

PROTOCOL_VERSION =

The version of the application protocol

1

Class Method Summary collapse

Methods included from HashUtilities

compact_hash, hash_matches, merge_recursively, stringify_keys, symbolify_keys

Methods included from MethodUtilities

attr_predicate, attr_predicate_accessor, dsl_accessor, singleton_attr_accessor, singleton_attr_reader, singleton_attr_writer, singleton_method_alias, singleton_predicate_accessor, singleton_predicate_reader

Class Method Details

.check_body(body) ⇒ Object

Check the given body for validity, raising an Arborist::MessageError if it isn’t.



108
109
110
111
112
113
114
115
 
# File 'lib/arborist/tree_api.rb', line 108

def self::check_body( body )
	unless body.is_a?( Hash ) ||
		   body.nil? ||
	       ( body.is_a?(Array) && body.all? {|obj| obj.is_a?(Hash) } )
		self.log.error "Invalid message body: %p" % [ body]
		raise Arborist::MessageError, "body must be Nil, a Map, or an Array of Maps"
	end
end

.check_header(header) ⇒ Object

Check the given header for validity, raising an Arborist::MessageError if it isn’t.

Raises:



96
97
98
99
100
101
102
103
 
# File 'lib/arborist/tree_api.rb', line 96

def self::check_header( header )
	raise Arborist::MessageError, "header is not a Map" unless
		header.is_a?( Hash )
	version = header['version'] or
		raise Arborist::MessageError, "missing required header 'version'"
	raise Arborist::MessageError, "unknown protocol version %p" % [version] unless
		version == PROTOCOL_VERSION
end

.decode(msg) ⇒ Object

Return the header and body from the TreeAPI request or response in the specified msg (a CZTop::Message).

Raises:



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/arborist/tree_api.rb', line 45

def self::decode( msg )
	raw_message = msg.pop or raise Arborist::MessageError, "empty message"

	parts = begin
		MessagePack.unpack( raw_message )
	rescue => err
		raise Arborist::MessageError, err.message
	end

	raise Arborist::MessageError, 'not an Array' unless parts.is_a?( Array )
	raise Arborist::MessageError,
		"malformed message: expected 1-2 parts, got %d" % [ parts.length ] unless
		parts.length.between?( 1, 2 )

	header = parts.shift or
		raise Arborist::MessageError, "no header"
	self.check_header( header )

	body = parts.shift
	self.check_body( body )

	return header, body
end

.encode(header, body = nil) ⇒ Object

Return a CZTop::Message with a payload containing the specified header and body.

Raises:



25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/arborist/tree_api.rb', line 25

def self::encode( header, body=nil )
	raise Arborist::MessageError, "header is not a Map" unless
		header.is_a?( Hash )

	self.log.debug "Encoding header: %p with body: %p" % [ header, body ]
	header = stringify_keys( header )
	header['version'] = PROTOCOL_VERSION

	self.check_header( header )
	self.check_body( body )

	payload = MessagePack.pack([ header, body ])

	self.log.debug "Making zmq message with payload: %p" % [ payload ]
	return CZTop::Message.new( payload )
end

.error_response(category, reason) ⇒ Object

Build an error response message for the specified category and reason.



83
84
85
 
# File 'lib/arborist/tree_api.rb', line 83

def self::error_response( category, reason )
	return self.encode({ category: category, reason: reason, success: false })
end

.request(verb, *data) ⇒ Object

Return a CZTop::Message containing a TreeAPI request with the specified verb and data.



72
73
74
75
76
77
78
79
 
# File 'lib/arborist/tree_api.rb', line 72

def self::request( verb, *data )
	body   = data.pop
	header = data.pop || {}

	header.merge!( action: verb )

	return self.encode( header, body )
end

.successful_response(body) ⇒ Object

Build a successful response with the specified body.



89
90
91
 
# File 'lib/arborist/tree_api.rb', line 89

def self::successful_response( body )
	return self.encode({ success: true }, body )
end