Set instance_uid by Server on conflict or request for generation

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
 
@@ -260,6 +281,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: If UpdateInstanceUid flag is set then Agent MUST update its instance_uid to
+the value provided in AgentRemoteConfig and use it for further communication.
+value.
+
 #### error_response
 
 error_response is set if the Server wants to indicate that something went wrong
@@ -318,6 +343,9 @@ enum Flags {
     // set if the Agent indicated it cannot report addon status by setting
     // the ReportsAddonStatus bit to 0 in StatusReport.capabilities field.
     ReportAddonStatus     = 0x00000002;
+
+    // The server requests the agent to change its instance_uid to the provided value.
+    UpdateInstanceUid     = 0x00000004;
 }
 ```
 
@@ -1678,9 +1706,14 @@ The message has the following structure:
 ```protobuf
 message AgentRemoteConfig {
   AgentConfigMap config = 1;
+  string new_instance_uid = 2;
 }
 ```
 
+When UpdateInstanceUid flag is set, new_instance_uid MUST be not empty, Agent
+MUST update instance_uid to the value provided in it and use it for all further
+communication.
+
 
 <h2 id="addons">Addons</h2>
 
@@ -2136,10 +2169,11 @@ The Server MAY disconnect or deny serving requests if it detects that the same
 Agent instance has more than one simultaneous connection or if multiple Agent
 instances are using the same instance_uid.
 
-Open Question: does the Server need to actively detect duplicate instance_uids,
-which may happen due to Agents using bad UID generators which create globally
-non-unique UIDs or for example because of cloning of the VMs where the Agent
-runs?
+The Server SHOULD detect duplicate instance_uids (which may happen for example
+when Agents are using bad UID generators or due to cloning of the VMs where the
+Agent runs). When a duplicate instance_uid is detected, Server SHOULD generate
+a new instance_uid, set UpdateInstanceUid flag of ServerToAgent message and
+set the new_instance_uid value in AgentRemoteConfig.
 
 <h2 id="authentication">Authentication</h2>
 
@@ -2438,9 +2472,9 @@ TBD
 * ~~Do we need the sequence_num concept?~~ Deleted for now, not necessary for
   current feature set, but may need to be restored for other features (e.g.
   custom "extensions").
-* Does the Server need to actively detect duplicate instance_uids, which may
+* ~~Does the Server need to actively detect duplicate instance_uids, which may
   happen due to Agents using bad UID generators which create globally non-unique
-  UIDs?
+  UIDs?~~ Added.
 * ~~Do we need to split the AddonStatus and AgentStatus from the general
   StatusReport?~~ Yes, splitted.
 * Does WebSocket frame compression work for us or do we need our own mechanism?