Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-06 08:38:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Management framework: edit pass over docstrings

Browse source 
This expands cross-referencing in the doc strings and adds a bit more
explanation.
This commit is contained in:
Christian Kreibich 2022-06-22 17:33:11 -07:00
parent b9879a50a0
commit 3aa0409792
2 changed files with 49 additions and 30 deletions
Download patch file Download diff file Expand all files Collapse all files

33
scripts/policy/frameworks/management/agent/api.zeek
View file

@ -33,8 +33,8 @@ export {
global deploy_request: event(reqid: string, global deploy_request: event(reqid: string,
config: Management::Configuration, force: bool &default=F); config: Management::Configuration, force: bool &default=F);
## Response to a deploy_request event. The agent sends ## Response to a :zeek:see:`Management::Agent::API::deploy_request`
## this back to the controller. ## event. The agent sends this back to the controller.
## ##
## reqid: the request identifier used in the request event. ## reqid: the request identifier used in the request event.
## ##
@ -56,8 +56,8 @@ export {
## ##
global get_nodes_request: event(reqid: string); global get_nodes_request: event(reqid: string);
## Response to a get_nodes_request event. The agent sends this back to the ## Response to a :zeek:see:`Management::Agent::API::get_nodes_request`
## controller. ## event. The agent sends this back to the controller.
## ##
## reqid: the request identifier used in the request event. ## reqid: the request identifier used in the request event.
## ##
@ -89,9 +89,10 @@ export {
global node_dispatch_request: event(reqid: string, action: vector of string, global node_dispatch_request: event(reqid: string, action: vector of string,
nodes: set[string] &default=set()); nodes: set[string] &default=set());
## Response to a node_dispatch_request event. Each agent sends this back ## Response to a
## to the controller to report the dispatch outcomes on all nodes managed ## :zeek:see:`Management::Agent::API::node_dispatch_request` event. Each
## by that agent. ## agent sends this back to the controller to report the dispatch
## outcomes on all nodes managed by that agent.
## ##
## reqid: the request identifier used in the request event. ## reqid: the request identifier used in the request event.
## ##
@ -105,15 +106,18 @@ export {
## The controller sends this event to confirm to the agent that it is ## The controller sends this event to confirm to the agent that it is
## part of the current cluster topology. The agent acknowledges with the ## part of the current cluster topology. The agent acknowledges with a
## corresponding response event. ## :zeek:see:`Management::Agent::API::agent_welcome_response` event,
## upon which the controller may proceed with a cluster deployment to
## this agent.
## ##
## reqid: a request identifier string, echoed in the response event. ## reqid: a request identifier string, echoed in the response event.
## ##
global agent_welcome_request: event(reqid: string); global agent_welcome_request: event(reqid: string);
## Response to an agent_welcome_request event. The agent sends this ## Response to a
## back to the controller. ## :zeek:see:`Management::Agent::API::agent_welcome_request` event. The
## agent sends this back to the controller.
## ##
## reqid: the request identifier used in the request event. ## reqid: the request identifier used in the request event.
## ##
@ -135,8 +139,9 @@ export {
## ##
global agent_standby_request: event(reqid: string); global agent_standby_request: event(reqid: string);
## Response to an agent_standby_request event. The agent sends this ## Response to a
## back to the controller. ## :zeek:see:`Management::Agent::API::agent_standby_request` event. The
## agent sends this back to the controller.
## ##
## reqid: the request identifier used in the request event. ## reqid: the request identifier used in the request event.
## ##
@ -196,7 +201,7 @@ export {
connecting: bool, api_version: count); connecting: bool, api_version: count);
# The following are not yet implemented. # The following are not yet meaningfully implemented.
# Report node state changes. # Report node state changes.
global notify_change: event(instance: string, global notify_change: event(instance: string,

46
scripts/policy/frameworks/management/controller/api.zeek
View file

@ -20,13 +20,14 @@ export {
## ##
global get_instances_request: event(reqid: string); global get_instances_request: event(reqid: string);
## Response to a get_instances_request event. The controller sends ## Response to a
## this back to the client. ## :zeek:see:`Management::Controller::API::get_instances_request`
## event. The controller sends this back to the client.
## ##
## reqid: the request identifier used in the request event. ## reqid: the request identifier used in the request event.
## ##
## result: the result record. Its data member is a ## result: a :zeek:see:`Management::Result`. Its data member is a vector
## :zeek:see:`Management::Instance` record. ## of :zeek:see:`Management::Instance` records.
## ##
global get_instances_response: event(reqid: string, global get_instances_response: event(reqid: string,
result: Management::Result); result: Management::Result);
@ -47,8 +48,10 @@ export {
global stage_configuration_request: event(reqid: string, global stage_configuration_request: event(reqid: string,
config: Management::Configuration); config: Management::Configuration);
## Response to a stage_configuration_request event. The controller sends ## Response to a
## this back to the client, conveying validation results. ## :zeek:see:`Management::Controller::API::stage_configuration_request`
## event. The controller sends this back to the client, conveying
## validation results.
## ##
## reqid: the request identifier used in the request event. ## reqid: the request identifier used in the request event.
## ##
@ -71,8 +74,10 @@ export {
## ##
global get_configuration_request: event(reqid: string, deployed: bool); global get_configuration_request: event(reqid: string, deployed: bool);
## Response to a get_configuration_request event. The controller sends ## Response to a
## this back to the client. ## :zeek:see:`Management::Controller::API::get_configuration_request`
## event. The controller sends this back to the client, with the
## requested configuration.
## ##
## reqid: the request identifier used in the request event. ## reqid: the request identifier used in the request event.
## ##
@ -100,8 +105,9 @@ export {
## ##
global deploy_request: event(reqid: string); global deploy_request: event(reqid: string);
## Response to a deploy_request event. The controller sends this ## Response to a :zeek:see:`Management::Controller::API::deploy_request`
## back to the client. ## event. The controller sends this back to the client, conveying the
## outcome of the deployment.
## ##
## reqid: the request identifier used in the request event. ## reqid: the request identifier used in the request event.
## ##
@ -123,8 +129,12 @@ export {
## ##
global get_nodes_request: event(reqid: string); global get_nodes_request: event(reqid: string);
## Response to a get_nodes_request event. The controller sends this ## Response to a
## back to the client. ## :zeek:see:`Management::Controller::API::get_nodes_request` event. The
## controller sends this back to the client, with a description of the
## nodes currently managed by the Supervisors on all connected
## instances. This includes agents and possibly the controller, if it
## runs jointly with an agent.
## ##
## reqid: the request identifier used in the request event. ## reqid: the request identifier used in the request event.
## ##
@ -156,8 +166,10 @@ export {
global get_id_value_request: event(reqid: string, id: string, global get_id_value_request: event(reqid: string, id: string,
nodes: set[string] &default=set()); nodes: set[string] &default=set());
## Response to a get_id_value_request event. The controller sends this ## Response to a
## back to the client. ## :zeek:see:`Management::Controller::API::get_id_value_request`
## event. The controller sends this back to the client, with a JSON
## representation of the requested global ID on all relevant instances.
## ##
## reqid: the request identifier used in the request event. ## reqid: the request identifier used in the request event.
## ##
@ -216,8 +228,10 @@ export {
## ##
global test_timeout_request: event(reqid: string, with_state: bool); global test_timeout_request: event(reqid: string, with_state: bool);
## Response to a test_timeout_request event. The controller sends this ## Response to a
## back to the client if the original request had the with_state flag. ## :zeek:see:`Management::Controller::API::test_timeout_request`
## event. The controller sends this back to the client if the original
## request had the with_state flag.
## ##
## reqid: the request identifier used in the request event. ## reqid: the request identifier used in the request event.
## ##