Arborist

Constants

API_VERSION: The version of the client.

Attributes

event_api_url[RW]: The ZeroMQ URI required to speak to the Arborist event API.
tree_api_url[RW]: The ZeroMQ URI required to speak to the Arborist tree API.

Public Class Methods

anchor

instance()

Create and return a singleton instance with configured endpoints.

# File lib/arborist/client.rb, line 22
def self::instance
        return @instance ||= new
end

anchor

new( tree_api_url: nil, event_api_url: nil )

Create a new Client with the given API socket URIs.

# File lib/arborist/client.rb, line 28
def initialize( tree_api_url: nil, event_api_url: nil )
        @tree_api_url  = tree_api_url  || Arborist.tree_api_url
        @event_api_url = event_api_url || Arborist.event_api_url
end

Public Instance Methods

anchor

ack( *args )

Alias for: acknowledge

anchor

acknowledge( *args )

Mark a node as 'acknowledged' if it's down, or 'disabled' if it's up. (A pre-emptive acknowledgement.) Requires the node identifier, an acknowledgement message, and sender. You can optionally include a via (source), and override the default time of now.

# File lib/arborist/client.rb, line 263
def acknowledge( *args )
        request = self.make_acknowledge_request( *args )
        response = self.send_tree_api_request( request )
        return true
end

Also aliased as: ack

anchor

clear_ack( *args )

Alias for: clear_acknowledgement

anchor

clear_acknowledgement( *args )

Clear the acknowledgement for a node.

# File lib/arborist/client.rb, line 286
def clear_acknowledgement( *args )
        request = self.make_unack_request( *args )
        response = self.send_tree_api_request( request )
        return true
end

Also aliased as: unack , clear_ack , unacknowledge

anchor

dependencies_of( identifier, partition: nil, properties: :all )

Return dependencies of the given identifier as an array.

# File lib/arborist/client.rb, line 51
def dependencies_of( identifier, partition: nil, properties: :all )
        dependencies = self.deps( identifier: identifier )[ 'deps' ]
        dependencies = self.search(
                criteria: { identifier: dependencies },
                options:  { properties: properties }
        )

        if partition
                partition = partition.to_s
                dependencies.keys.each{|id| dependencies[id]['identifier'] = id }
                dependencies = dependencies.values.group_by do |node|
                        node[ partition ]
                end
        end

        return dependencies
end

anchor

deps( identifier: )

Return the identifiers that have a dependency on the node with the specified identifier.

# File lib/arborist/client.rb, line 135
def deps( identifier: )
        request = self.make_deps_request( identifier )
        return self.send_tree_api_request( request )
end

anchor

event_api()

Return a ZMQ SUB socket connected to the manager's event API, instantiating it if necessary.

# File lib/arborist/client.rb, line 342
def event_api
        return @event_api ||= self.make_event_api_socket
end

anchor

fetch( **args )

Fetch the manager's current node tree.

# File lib/arborist/client.rb, line 95
def fetch( **args )
        request = self.make_fetch_request( **args )
        return self.send_tree_api_request( request )
end

anchor

fetch_node( identifier )

Retreive a single node.

# File lib/arborist/client.rb, line 71
def fetch_node( identifier )
        request = self.make_fetch_request( from: identifier, depth: 0 )
        return self.send_tree_api_request( request ).first
end

anchor

graft( *args )

Add a new node to the tree.

# File lib/arborist/client.rb, line 219
def graft( *args )
        request = self.make_graft_request( *args )
        response = self.send_tree_api_request( request )
        return response
end

anchor

make_acknowledge_request( identifier:, message:, sender:, via: nil, time: Time.now )

Return an `ack` request as a zmq message (a CZTop::Message) with the specified attributes.

# File lib/arborist/client.rb, line 273
def make_acknowledge_request( identifier,, message,, sender,, via: nil, time: Time.now )
        ack = {
                message: message,
                sender:  sender,
                via:     via,
                time:    time.to_s
        }

        return Arborist::TreeAPI.request( :ack, {identifier: identifier}, ack )
end

anchor

make_deps_request( identifier )

Return a `deps` request as a ZMQ message (a CZTop::Message) with the given identifier.

# File lib/arborist/client.rb, line 143
def make_deps_request( identifier )
        return Arborist::TreeAPI.request( :deps, { from: identifier }, nil )
end

anchor

make_event_api_socket()

Create a new ZMQ SUB socket connected to the manager's event API.

# File lib/arborist/client.rb, line 348
def make_event_api_socket
        self.log.info "Connecting to the event socket %p" % [ self.event_api_url ]
        return CZTop::Socket::SUB.new( self.event_api_url )
end

anchor

make_fetch_request( from: nil, depth: nil, tree: false )

Return a `fetch` request as a ZMQ message (a CZTop::Message) with the given attributes.

# File lib/arborist/client.rb, line 103
def make_fetch_request( from: nil, depth: nil, tree: false )
        header = {}
        self.log.debug "From is: %p" % [ from ]
        header[:from] = from if from
        header[:depth] = depth if depth
        header[:tree] = 'true' if tree

        return Arborist::TreeAPI.request( :fetch, header, nil )
end

anchor

make_graft_request( identifier:, type:, parent: nil, attributes:{} )

Return a `graft` request as a zmq message (a CZTop::Message) with the specified attributes.

# File lib/arborist/client.rb, line 228
def make_graft_request( identifier,, type,, parent: nil, attributes{{} )
        self.log.debug "Making graft request for identifer: %s" % [ identifier ]

        header = {
                identifier: identifier,
                parent:     parent,
                type:       type
        }

        return Arborist::TreeAPI.request( :graft, header, attributes )
end

anchor

make_modify_request( identifier:, attributes: )

Return a `modify` request as a zmq message (a CZTop::Message) with the specified attributes.

# File lib/arborist/client.rb, line 251
def make_modify_request( identifier,, attributes: )
        self.log.debug "Making modify request for identifer: %s" % [ identifier ]

        return Arborist::TreeAPI.request( :modify, {identifier: identifier}, attributes )
end

anchor

make_prune_request( identifier: )

Return a `prune` request as a zmq message (a CZTop::Message) with the specified identifier.

# File lib/arborist/client.rb, line 211
def make_prune_request( identifier: )
        self.log.debug "Making prune request for identifier: %s" % [ identifier ]

        return Arborist::TreeAPI.request( :prune, {identifier: identifier}, nil )
end

anchor

make_search_request( criteria, exclude_down: false, properties: :all, exclude: {} )

Return a `search` request as a ZMQ message (a CZTop::Message) with the given attributes.

# File lib/arborist/client.rb, line 124
def make_search_request( criteria, exclude_down: false, properties: :all, exclude: {} )
        header = {}
        header[ :exclude_down ] = true if exclude_down
        header[ :return ] = properties if properties != :all

        return Arborist::TreeAPI.request( :search, header, [ criteria, exclude ] )
end

anchor

make_status_request()

Return a `status` request as a ZMQ message (a CZTop::Message).

# File lib/arborist/client.rb, line 89
def make_status_request
        return Arborist::TreeAPI.request( :status )
end

anchor

make_subscribe_request( criteria: {}, identifier: nil, event_type: nil, exclude: {} )

Return a `subscribe` request as a zmq message (a CZTop::Message) with the specified attributes.

# File lib/arborist/client.rb, line 173
def make_subscribe_request( criteria: {}, identifier: nil, event_type: nil, exclude: {} )
        self.log.debug "Making subscription request for identifier: %p, event_type: %p, criteria: %p" %
                [ identifier, event_type, criteria ]
        header = {}
        header[ :identifier ] = identifier if identifier
        header[ :event_type ] = event_type

        return Arborist::TreeAPI.request( :subscribe, header, [ criteria, exclude ] )
end

anchor

make_tree_api_socket()

Create a new ZMQ REQ socket connected to the manager's tree API.

# File lib/arborist/client.rb, line 334
def make_tree_api_socket
        self.log.info "Connecting to the tree socket %p" % [ self.tree_api_url ]
        return CZTop::Socket::REQ.new( self.tree_api_url )
end

anchor

make_unack_request( identifier: )

Return an `unack` request as a zmq message (a CZTop::Message) with the specified attribute.

# File lib/arborist/client.rb, line 298
def make_unack_request( identifier: )
        return Arborist::TreeAPI.request( :unack, {identifier: identifier}, nil )
end

anchor

make_unsubscribe_request( subid )

Return an `unsubscribe` request as a zmq message (a CZTop::Message) with the specified subid.

# File lib/arborist/client.rb, line 194
def make_unsubscribe_request( subid )
        self.log.debug "Making unsubscribe request for subid: %s" % [ subid ]

        return Arborist::TreeAPI.request( :unsubscribe, {subscription_id: subid}, nil )
end

anchor

make_update_request( data, header={} )

Return an `update` request as a zmq message (a CZTop::Message) with the given data.

# File lib/arborist/client.rb, line 158
def make_update_request( data, header={} )
        return Arborist::TreeAPI.request( :update, header, data )
end

anchor

modify( *args )

Modify operational attributes of a node.

# File lib/arborist/client.rb, line 242
def modify( *args )
        request = self.make_modify_request( *args )
        response = self.send_tree_api_request( request )
        return true
end

anchor

prune( *args )

Remove a node

# File lib/arborist/client.rb, line 202
def prune( *args )
        request = self.make_prune_request( *args )
        response = self.send_tree_api_request( request )
        return response
end

anchor

search( criteria:{}, options:{}, **args )

Return the manager's current node tree.

# File lib/arborist/client.rb, line 115
def search( criteria{{}, options{{}, **args )
        criteria = args if criteria.empty?
        request = self.make_search_request( criteria, **options )
        return self.send_tree_api_request( request )
end

anchor

send_tree_api_request( request )

Send the packed request via the Tree API socket, raise an error on unsuccessful response, and return the response body.

# File lib/arborist/client.rb, line 305
def send_tree_api_request( request )
        self.log.debug "Sending request: %p" % [ request ]
        request.send_to( self.tree_api )

        res = CZTop::Message.receive_from( self.tree_api )
        self.log.debug "Received response: %p" % [ res ]

        header, body = Arborist::TreeAPI.decode( res )
        unless header[ 'success' ]
                exception = header['category'] == 'client' ? Arborist::ClientError : Arborist::ServerError
                raise exception, "Arborist manager said: %s" % [ header['reason'] ]
        end

        return body
end

anchor

status()

Return the manager's current status as a hash.

# File lib/arborist/client.rb, line 82
def status
        request = self.make_status_request
        return self.send_tree_api_request( request )
end

anchor

subscribe( **args )

Add a subscription

# File lib/arborist/client.rb, line 164
def subscribe( **args )
        request = self.make_subscribe_request( **args )
        response = self.send_tree_api_request( request )
        return response['id']
end

anchor

tree_api()

Return a ZeroMQ REQ socket connected to the manager's tree API, instantiating it if necessary.

# File lib/arborist/client.rb, line 328
def tree_api
        return @tree_api ||= self.make_tree_api_socket
end

anchor

unack( *args )

Alias for: clear_acknowledgement

anchor

unacknowledge( *args )

Alias for: clear_acknowledgement

anchor

unsubscribe( *args )

Remove a subscription

# File lib/arborist/client.rb, line 185
def unsubscribe( *args )
        request = self.make_unsubscribe_request( *args )
        response = self.send_tree_api_request( request )
        return response
end

anchor

update( *args )

Update the identified nodes in the manager with the specified data.

# File lib/arborist/client.rb, line 149
def update( *args )
        request = self.make_update_request( *args )
        self.send_tree_api_request( request )
        return true
end