policy/frameworks/management/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().

Parameters

req – the request state that is expiring.

Functions

Management::Request::create
Type

function (reqid: string &default = fD0qxAnfwOe &optional) : Management::Request::Request

This function establishes request state.

Parameters

reqid – the identifier to use for the request.

Management::Request::finish
Type

function (reqid: string) : bool

This function marks a request as complete and causes Zeek to release its internal state. When the request does not exist, this does nothing.

Parameters

reqid – the ID of the request state to release.

Management::Request::is_null
Type

function (request: Management::Request::Request) : bool

This function is a helper predicate to indicate whether a given request is null.

Parameters

request – a Request record to check.

Returns

T if the given request matches the null_req instance, F otherwise.

Management::Request::lookup
Type

function (reqid: string) : Management::Request::Request

This function looks up the request for a given request ID and returns it. When no such request exists, returns Management::Request::null_req.

Parameters

reqid – the ID of the request state to retrieve.

Management::Request::to_string
Type

function (request: Management::Request::Request) : string

For troubleshooting, this function renders a request record to a string.

Parameters

request – the request to render.