main.bro¶

Broker¶

The Broker-based communication API and its various options.

Namespace:	Broker
Imports:	base/bif/comm.bif.bro, base/bif/messaging.bif.bro

Summary¶

Redefinable Options¶

`Broker::aggressive_interval`: `count` `&redef`	Frequency of work-stealing polling attempts for Broker/CAF threads in “aggressive” mode.
`Broker::aggressive_polls`: `count` `&redef`	Number of work-stealing polling attempts for Broker/CAF threads in “aggressive” mode.
`Broker::congestion_queue_size`: `count` `&redef`	The number of buffered messages at the Broker/CAF layer after which a subscriber considers themselves congested (i.e.
`Broker::default_connect_retry`: `interval` `&redef`	Default interval to retry connecting to a peer if it cannot be made to work initially, or if it ever becomes disconnected.
`Broker::default_listen_address`: `string` `&redef`	Default address on which to listen.
`Broker::default_listen_retry`: `interval` `&redef`	Default interval to retry listening on a port if it’s currently in use already.
`Broker::default_log_topic_prefix`: `string` `&redef`	The default topic prefix where logs will be published.
`Broker::default_port`: `port` `&redef`	Default port for Broker communication.
`Broker::disable_ssl`: `bool` `&redef`	If true, do not use SSL for network connections.
`Broker::forward_messages`: `bool` `&redef`	Forward all received messages to subscribing peers.
`Broker::max_threads`: `count` `&redef`	Max number of threads to use for Broker/CAF functionality.
`Broker::moderate_interval`: `count` `&redef`	Frequency of work-stealing polling attempts for Broker/CAF threads in “moderate” mode.
`Broker::moderate_polls`: `count` `&redef`	Number of work-stealing polling attempts for Broker/CAF threads in “moderate” mode.
`Broker::moderate_sleep`: `interval` `&redef`	Interval of time for under-utilized Broker/CAF threads to sleep when in “moderate” mode.
`Broker::relaxed_interval`: `count` `&redef`	Frequency of work-stealing polling attempts for Broker/CAF threads in “relaxed” mode.
`Broker::relaxed_sleep`: `interval` `&redef`	Interval of time for under-utilized Broker/CAF threads to sleep when in “relaxed” mode.
`Broker::ssl_cafile`: `string` `&redef`	Path to a file containing concatenated trusted certificates in PEM format.
`Broker::ssl_capath`: `string` `&redef`	Path to an OpenSSL-style directory of trusted certificates.
`Broker::ssl_certificate`: `string` `&redef`	Path to a file containing a X.509 certificate for this node in PEM format.
`Broker::ssl_keyfile`: `string` `&redef`	Path to the file containing the private key for this node’s certificate.
`Broker::ssl_passphrase`: `string` `&redef`	Passphrase to decrypt the private key specified by `Broker::ssl_keyfile`.

Types¶

`Broker::Data`: `record`	Opaque communication data.
`Broker::DataVector`: `vector`	Opaque communication data sequence.
`Broker::EndpointInfo`: `record`
`Broker::ErrorCode`: `enum`	Enumerates the possible error types.
`Broker::Event`: `record`	Opaque event communication data.
`Broker::NetworkInfo`: `record`
`Broker::PeerInfo`: `record`
`Broker::PeerInfos`: `vector`
`Broker::PeerStatus`: `enum`	The possible states of a peer endpoint.
`Broker::TableItem`: `record`	Opaque communication data used as a convenient way to wrap key-value pairs that comprise table entries.

Functions¶

`Broker::auto_publish`: `function`	Automatically send an event to any interested peers whenever it is locally dispatched.
`Broker::auto_unpublish`: `function`	Stop automatically sending an event to peers upon local dispatch.
`Broker::default_log_topic`: `function`	The default implementation for `Broker::log_topic`.
`Broker::flush_logs`: `function`	Sends all pending log messages to remote peers.
`Broker::forward`: `function`	Register a topic prefix subscription for events that should only be forwarded to any subscribing peers and not raise any event handlers on the receiving/forwarding node.
`Broker::listen`: `function`	Listen for remote connections.
`Broker::log_topic`: `function` `&redef`	A function that will be called for each log entry to determine what broker topic string will be used for sending it to peers.
`Broker::node_id`: `function`	Get a unique identifier for the local broker endpoint.
`Broker::peer`: `function`	Initiate a remote connection.
`Broker::peers`: `function`	Get a list of all peer connections.
`Broker::publish_id`: `function`	Publishes the value of an identifier to a given topic.
`Broker::subscribe`: `function`	Register interest in all peer event messages that use a certain topic prefix.
`Broker::unpeer`: `function`	Remove a remote connection.
`Broker::unsubscribe`: `function`	Unregister interest in all peer event messages that use a topic prefix.

Detailed Interface¶

Redefinable Options¶

Broker::aggressive_interval¶

Type:	`count`
Attributes:	`&redef`
Default:	`4`

Frequency of work-stealing polling attempts for Broker/CAF threads in “aggressive” mode.

Broker::aggressive_polls¶

Type:	`count`
Attributes:	`&redef`
Default:	`5`

Number of work-stealing polling attempts for Broker/CAF threads in “aggressive” mode.

Broker::congestion_queue_size¶

Type:	`count`
Attributes:	`&redef`
Default:	`200`

The number of buffered messages at the Broker/CAF layer after which a subscriber considers themselves congested (i.e. tune the congestion control mechanisms).

Broker::default_connect_retry¶

Type:	`interval`
Attributes:	`&redef`
Default:	`30.0 secs`

Default interval to retry connecting to a peer if it cannot be made to work initially, or if it ever becomes disconnected. Use of the BRO_DEFAULT_CONNECT_RETRY environment variable (set as number of seconds) will override this option and also any values given to Broker::peer.

Broker::default_listen_address¶

Type:	`string`
Attributes:	`&redef`
Default:	`""`

Default address on which to listen.

Types¶

Broker::Data¶

Type:

record

data: opaque of Broker::Data &optional

Opaque communication data.

Broker::DataVector¶

Type:	`vector` of `Broker::Data`

Opaque communication data sequence.

Broker::EndpointInfo¶

Type:

record

id: string: A unique identifier of the node.
network: Broker::NetworkInfo &optional: Network-level information.

Broker::ErrorCode¶

Type:

enum

Broker::UNSPECIFIED¶: The unspecified default error code.

Broker::PEER_INCOMPATIBLE¶: Version incompatibility.

Broker::PEER_INVALID¶: Referenced peer does not exist.

Broker::PEER_UNAVAILABLE¶: Remote peer not listening.

Broker::PEER_TIMEOUT¶: A peering request timed out.

Broker::MASTER_EXISTS¶: Master with given name already exists.

Broker::NO_SUCH_MASTER¶: Master with given name does not exist.

Broker::NO_SUCH_KEY¶: The given data store key does not exist.

Broker::REQUEST_TIMEOUT¶: The store operation timed out.

Broker::TYPE_CLASH¶: The operation expected a different type than provided.

Broker::INVALID_DATA¶: The data value cannot be used to carry out the desired operation.

Broker::BACKEND_FAILURE¶: The storage backend failed to execute the operation.

Broker::STALE_DATA¶: The storage backend failed to execute the operation.

Broker::CAF_ERROR¶: Catch-all for a CAF-level problem.

Enumerates the possible error types.

Broker::Event¶

Type:

record

name: string &optional: The name of the event. Not set if invalid event or arguments.
args: Broker::DataVector: The arguments to the event.

Opaque event communication data.

Broker::NetworkInfo¶

Type:

record

address: string &log: The IP address or hostname where the endpoint listens.
bound_port: port &log: The port where the endpoint is bound to.

Broker::PeerInfo¶

Type:

record

peer: Broker::EndpointInfo

status: Broker::PeerStatus

Broker::PeerInfos¶

Type:	`vector` of `Broker::PeerInfo`

Broker::PeerStatus¶

Type:

enum

Broker::INITIALIZING¶: The peering process is initiated.

Broker::CONNECTING¶: Connection establishment in process.

Broker::CONNECTED¶: Connection established, peering pending.

Broker::PEERED¶: Successfully peered.

Broker::DISCONNECTED¶: Connection to remote peer lost.

Broker::RECONNECTING¶: Reconnecting to peer after a lost connection.

The possible states of a peer endpoint.

Broker::TableItem¶

Type:

record

key: Broker::Data

val: Broker::Data

Opaque communication data used as a convenient way to wrap key-value pairs that comprise table entries.

Functions¶

Broker::auto_publish¶

Type:	`function` (topic: `string`, ev: `any`) : `bool`

Automatically send an event to any interested peers whenever it is locally dispatched. (For example, using “event my_event(…);” in a script.)

Topic:	a topic string associated with the event message. Peers advertise interest by registering a subscription to some prefix of this topic name.
Ev:	a Bro event value.
Returns:	true if automatic event sending is now enabled.

Broker::auto_unpublish¶

Type:	`function` (topic: `string`, ev: `any`) : `bool`

Stop automatically sending an event to peers upon local dispatch.

Topic:	a topic originally given to `Broker::auto_publish`.
Ev:	an event originally given to `Broker::auto_publish`.
Returns:	true if automatic events will not occur for the topic/event pair.

Broker::default_log_topic¶

Type:	`function` (id: `Log::ID`, path: `string`) : `string`

The default implementation for Broker::log_topic.

Broker::flush_logs¶

Type:	`function` () : `count`

Sends all pending log messages to remote peers. This normally doesn’t need to be used except for test cases that are time-sensitive.

Broker::forward¶

Type:	`function` (topic_prefix: `string`) : `bool`

Register a topic prefix subscription for events that should only be forwarded to any subscribing peers and not raise any event handlers on the receiving/forwarding node. i.e. it’s the same as Broker::subscribe except matching events are not raised on the receiver, just forwarded. Use Broker::unsubscribe with the same argument to undo this operation.

Topic_prefix:	a prefix to match against remote message topics. e.g. an empty prefix matches everything and “a” matches “alice” and “amy” but not “bob”.
Returns:	true if a new event forwarding/subscription is now registered.

Broker::listen¶

Type:	`function` (a: `string` `&default` = `Broker::default_listen_address` `&optional`, p: `port` `&default` = `Broker::default_port` `&optional`, retry: `interval` `&default` = `Broker::default_listen_retry` `&optional`) : `port`

Listen for remote connections.

A:	an address string on which to accept connections, e.g. “127.0.0.1”. An empty string refers to INADDR_ANY.
P:	the TCP port to listen on. The value 0 means that the OS should choose the next available free port.
Retry:	If non-zero, retries listening in regular intervals if the port cannot be acquired immediately. 0 disables retries. If the BRO_DEFAULT_LISTEN_RETRY environment variable is set (as number of seconds), it overrides any value given here.
Returns:	the bound port or 0/? on failure.

Id:	the ID associated with the log stream entry that will be sent.
Path:	the path to which the log stream entry will be output.
Returns:	a string representing the broker topic to which the log will be sent.

Topic:	a topic associated with the message.
Id:	the identifier to publish.
Returns:	true if the message is sent.

A:	the address used in previous successful call to `Broker::peer`.
P:	the port used in previous successful call to `Broker::peer`.
Returns:	true if the arguments match a previously successful call to `Broker::peer`.
TODO:	We do not have a function yet to terminate a connection.