feat: add SendMessageForAgent and OnMessageForOtherAgent for gateway multiplexing#604
feat: add SendMessageForAgent and OnMessageForOtherAgent for gateway multiplexing#604cforce wants to merge 2 commits into
Conversation
…multiplexing Add support for gateway/multiplexing scenarios where a single upstream OpAMP connection carries messages for multiple downstream agents: 1. New client interface method SendMessageForAgent(msg *AgentToServer): Sends a complete AgentToServer message on behalf of another agent instance. Bypasses the client's internal state management — the message is sent as-is with the downstream agent's InstanceUid. 2. New callback OnMessageForOtherAgent(ctx, msg *ServerToAgent): Called when ProcessReceivedMessage encounters a ServerToAgent message whose InstanceUid does not match the client's own UID. This allows the gateway to route responses back to the correct downstream agent without the client's state machine interfering. 3. New NextMessage.InstanceUid() accessor for concurrent-safe UID reads. These additions enable the OpAMP supervisor to act as a lightweight gateway for downstream agents without requiring the opampgateway collector extension, as proposed in open-telemetry/opentelemetry-collector-contrib#49825. All existing tests pass without modification.
|
Cover input validation, end-to-end delivery of messages with foreign InstanceUid, callback invocation for messages targeting other agents, and correct pass-through of messages targeting the client's own UID.
|
The OpAMP spec defines AgentToServer.instance_uid as identifying the sending agent, and ServerToAgent.instance_uid as identifying the target agent. The spec assumes a 1:1 mapping between client connection and agent identity. PR extends the opamp-go client to support a 1:N mapping: a single upstream connection can carry messages for multiple agent identities. This does not violate the spec - from the server's perspective, each message still carries a valid instance_uid and follows the spec's wire format exactly. The server sees individual agents registering and communicating normally; it is unaware they share a transport. This is the same approach used by existing OpAMP gateway implementations , which multiplex downstream agents over a single upstream connection by forwarding their messages with their original instance_uid intact. |
|
This violates existing OpAMP assumptions. If you are interested in this functionality I suggest opening an issue in the spec repo and attend OpAMP SIG meeting to discuss. I am going to close the PR since it is premature. PRs should come after the discussion happens and a decision is made to add this to OpAMP (which may or may not happen). |
3 participants
Description
Add two new capabilities to the OpAMP client that enable gateway/multiplexing scenarios where a single upstream connection carries messages for multiple downstream agents:
SendMessageForAgent(msg *AgentToServer) error— new method onOpAMPClientinterface. Sends a completeAgentToServermessage on behalf of another agent instance (identified by a differentInstanceUid). Bypasses the client's internal state management — the message is sent as-is.OnMessageForOtherAgentcallback — new field intypes.Callbacks. Called whenProcessReceivedMessageencounters aServerToAgentmessage whoseInstanceUiddoes not match the client's own UID. This allows the caller to route responses to the correct downstream agent without the client's state machine interfering.NextMessage.InstanceUid()accessor — concurrent-safe method to read the client's current instance UID for comparison in the received processor.These additions enable the OpAMP supervisor to act as a lightweight gateway for downstream agents without requiring the opampgateway collector extension, as discussed in open-telemetry/opentelemetry-collector-contrib#49825.
Link to tracking issue
Related: open-telemetry/opentelemetry-collector-contrib#49825
Testing
All existing client tests pass without modification (
go test ./client/... -count=1). The new functionality is exercised via unit tests in the downstream supervisor gateway implementation.Documentation
No documentation changes yet. Will update after design approval.