diff --git a/specification.md b/specification.md index 4193988..9637ecd 100644 --- a/specification.md +++ b/specification.md @@ -105,9 +105,9 @@ ServerToAgent Protobuf messages: Typically a single Server accepts WebSocket connections from many agents. Agents -are identified by self-assigned globally unique instance identifiers (or -instance_uid for short). The instance_uid is recorded in each message sent from -the Agent to the Server and from the Server to the Agent. +are identified by self-assigned or server-assigned globally unique instance +identifiers (or instance_uid for short). The instance_uid is recorded in each +message sent from the Agent to the Server and from the Server to the Agent. The default URL path for the initial WebSocket's HTTP connection is /v1/opamp. The URL path MAY be configurable on the Agent and on the Server. @@ -159,6 +159,7 @@ message AgentToServer { AgentAddonStatuses addon_statuses = 3; AgentInstallStatus agent_install_status = 4; AgentDisconnect agent_disconnect = 5; + AgentToServerFlags flags = 6; } ``` @@ -175,6 +176,9 @@ created by other Agents. The instance_uid SHOULD remain unchanged for the lifetime of the agent process. The recommended format for the instance_uid is [ULID](https://github.com/ulid/spec). +In case the Agent wants to use an identifier generated by the Server, the field +SHOULD be set with a temporary value and RequestInstanceUid flag MUST be set. + #### status_report The status of the Agent. MUST be set in the first AgentToServer message that the @@ -199,6 +203,23 @@ the last AgentToServer message. AgentDisconnect MUST be set in the last AgentToServer message sent from the agent to the server. +#### flags + + +Bit flags as defined by AgentToServerFlags bit masks. + +```protobuf +enum AgentToServerFlags { + FlagsUnspecified = 0; + + // Flags is a bit mask. Values below define individual bits. + + // The agent requests server go generate a new instance_uid, which will + // be sent back in ServerToAgent message + RequestInstanceUid = 0x00000001; +} +``` + ## ServerToAgent Message @@ -248,7 +269,8 @@ message ServerToAgent { AgentPackageAvailable agent_package_available = 6; Flags flags = 7; ServerCapabilities capabilities = 8; - ServerToAgentCommand command = 9; + AgentIdentification agent_identification = 9; + ServerToAgentCommand command = 10; } ``` @@ -261,6 +283,10 @@ is multiplexed into one WebSocket connection (for example when a terminating proxy is used) the instance_uid field allows to distinguish which Agent the ServerToAgent message is addressed to. +Note: the value can be overriden by server by sending a new one in the +AgentIdentification field. When this happens then Agent MUST update its +instance_uid to the value provided and use it for all further communication. + #### error_response error_response is set if the Server wants to indicate that something went wrong @@ -358,6 +384,19 @@ enum ServerCapabilities { } ``` + +#### agent_identification + +Properties related to identification of the agent, which can be overriden by the +server if needed. When new_instance_uid is set, Agent MUST update instance_uid +to the value provided and use it for all further communication. + +```protobuf +message AgentIdentification { + string new_instance_uid = 1; +} +``` + #### command This field is set when the server wants the agent to @@ -366,8 +405,6 @@ besides instance_uid or capabilities. All other fields will be ignored and the agent will execute the command. See [ServerToAgentCommand Message](#servertoagentcommand-message) for details. - -