request.zeek

Management::Request

This module implements a request state abstraction in the Management framework that both controller and agent use to connect request events to subsequent response ones, and to be able to time out such requests.

Namespace: Management::Request
Imports: policy/frameworks/management/config.zeek, policy/frameworks/management/types.zeek

Summary

Redefinable Options

Management::Request::timeout_interval: interval &redef

The timeout interval for request state.

State Variables

Management::Request::null_req: Management::Request::Request

A token request that serves as a null/nonexistent request.

Types

Management::Request::Request: record

Request records track state associated with a request/response event pair.

Redefinitions

Management::Request::Request: record

New Fields

Management::Request::Request

finish: function (req: Management::Request::Request)void &optional: A callback to invoke when this request is finished via Management::Request::finish.

Events

Management::Request::request_expired: event

This event fires when a request times out (as per the Management::Request::timeout_interval) before it has been finished via Management::Request::finish().

Functions

`Management::Request::create`: `function`	This function establishes request state.
`Management::Request::finish`: `function`	This function marks a request as complete and causes Zeek to release its internal state.
`Management::Request::is_null`: `function`	This function is a helper predicate to indicate whether a given request is null.
`Management::Request::lookup`: `function`	This function looks up the request for a given request ID and returns it.
`Management::Request::to_string`: `function`	For troubleshooting, this function renders a request record to a string.

Detailed Interface

Redefinable Options

Management::Request::timeout_interval 

Type

interval

Attributes

&redef

Default

10.0 secs

Redefinition

from policy/frameworks/management/agent/main.zeek

=:

5.0 secs

The timeout interval for request state. Such state (see the Management::Request module) ties together request and response event pairs. A timeout causes cleanup of request state if regular request/response processing hasn’t already done so. It applies both to request state kept in the controller and the agent, though the two use different timeout values: agent-side requests time out more quickly. This allows agents to send more meaningful error messages, while the controller’s timeouts serve as a last resort to ensure response to the client.

State Variables

Management::Request::null_req 

Type

Management::Request::Request

Default

{
   id=""
   parent_id=<uninitialized>
   results=[]
   finished=T
   finish=<uninitialized>
   supervisor_state_agent=<uninitialized>
   deploy_state_agent=<uninitialized>
   node_dispatch_state_agent=<uninitialized>
   restart_state_agent=<uninitialized>
   deploy_state=<uninitialized>
   get_nodes_state=<uninitialized>
   node_dispatch_state=<uninitialized>
   restart_state=<uninitialized>
   test_state=<uninitialized>
}

A token request that serves as a null/nonexistent request.

Types

Management::Request::Request 

Type

record

id: string: Each request has a hopefully unique ID provided by the requester.
parent_id: string &optional: For requests that result based upon another request (such as when the controller sends requests to agents based on a request it received by the client), this specifies that original, “parent” request.
results: Management::ResultVec &default = [] &optional: The results vector builds up the list of results we eventually send to the requestor when we have processed the request.
finished: bool &default = F &optional: An internal flag to track whether a request is complete.
finish: function (<recursion>)void &optional: A callback to invoke when this request is finished via Management::Request::finish.
supervisor_state_agent: Management::Agent::Runtime::SupervisorState &optional: (present if policy/frameworks/management/agent/main.zeek is loaded)
deploy_state_agent: Management::Agent::Runtime::DeployState &optional: (present if policy/frameworks/management/agent/main.zeek is loaded)
node_dispatch_state_agent: Management::Agent::Runtime::NodeDispatchState &optional: (present if policy/frameworks/management/agent/main.zeek is loaded)
restart_state_agent: Management::Agent::Runtime::RestartState &optional: (present if policy/frameworks/management/agent/main.zeek is loaded)
deploy_state: Management::Controller::Runtime::DeployState &optional: (present if policy/frameworks/management/controller/main.zeek is loaded)
get_nodes_state: Management::Controller::Runtime::GetNodesState &optional: (present if policy/frameworks/management/controller/main.zeek is loaded)
node_dispatch_state: Management::Controller::Runtime::NodeDispatchState &optional: (present if policy/frameworks/management/controller/main.zeek is loaded)
restart_state: Management::Controller::Runtime::RestartState &optional: (present if policy/frameworks/management/controller/main.zeek is loaded)
test_state: Management::Controller::Runtime::TestState &optional: (present if policy/frameworks/management/controller/main.zeek is loaded)

Request records track state associated with a request/response event pair. Calls to Management::Request::create establish such state when an entity sends off a request event, while Management::Request::finish clears the state when a corresponding response event comes in, or the state times out.

Events

Management::Request::request_expired 

Type: event (req: Management::Request::Request)

This event fires when a request times out (as per the Management::Request::timeout_interval) before it has been finished via Management::Request::finish().