OpAMP Protocol Sequence

Mon, 01 Jan 0001 00:00:00 +0000

OpAMP Protocol Execution Sequence

Agent Connection and Message Exchange Flow

sequenceDiagram
 participant Agent as OpAMP Agent
 participant Controller as opamp.Controller
 participant OpAMPLib as OpAMP Server Lib
 participant Service as opamp.Service
 participant AgentUC as AgentUsecase
 participant ConnUC as ConnectionUsecase
 participant WS as WebSocketRegistry
 participant DB as MongoDB Repository

 Note over Agent,DB: Connection Phase
 
 Agent->>Controller: GET/POST /api/v1/opamp
 Controller->>OpAMPLib: handler(writer, request)
 OpAMPLib->>Controller: OnConnecting(request)
 Controller-->>OpAMPLib: ConnectionResponse {Accept: true}
 OpAMPLib-->>Agent: Connection Accepted
 
 OpAMPLib->>Service: OnConnected(ctx, connection)
 Service->>Service: detectConnectionType(conn)
 Service->>Service: NewConnection(conn, type)
 alt WebSocket
 Service->>WS: Register(connID, wsConn)
 end
 Service->>ConnUC: SaveConnection(ctx, connection)
 ConnUC->>DB: Save
 
 Note over Agent,DB: Message Exchange Phase
 
 loop Active Connection
 Agent->>OpAMPLib: AgentToServer Message
 Note right of Agent: - InstanceUID<br/>- AgentDescription<br/>- Health<br/>- Capabilities<br/>- EffectiveConfig<br/>- RemoteConfigStatus<br/>- PackageStatuses
 
 OpAMPLib->>Service: OnMessage(ctx, conn, message)
 Service->>ConnUC: GetConnectionByID(ctx, conn)
 ConnUC->>DB: Find
 DB-->>ConnUC: connection
 ConnUC-->>Service: connection
 
 Service->>Service: Update connection.InstanceUID
 alt WebSocket
 Service->>WS: UpdateInstanceUID(connID, instanceUID)
 end
 Service->>ConnUC: SaveConnection(ctx, connection)
 ConnUC->>DB: Save
 
 Service->>AgentUC: GetOrCreateAgent(ctx, instanceUID)
 AgentUC->>DB: Find/Create
 DB-->>AgentUC: agent
 AgentUC-->>Service: agent
 Service->>Service: Update agent.Status (Connected=true)
 
 Service->>Service: report(agent, message, server)
 Note right of Service: Update agent from message:<br/>- AgentDescription<br/>- Health<br/>- RemoteConfigStatus<br/>- PackageStatuses<br/>- EffectiveConfig
 
 Service->>AgentUC: SaveAgent(ctx, agent)
 AgentUC->>DB: Save
 
 Service->>Service: fetchServerToAgent(ctx, agent)
 Note right of Service: Build response:<br/>- RemoteConfig<br/>- ConnectionSettings<br/>- PackagesAvailable<br/>- Flags<br/>- Command
 
 Service-->>OpAMPLib: ServerToAgent Response
 OpAMPLib-->>Agent: ServerToAgent Message
 Note left of Agent: - InstanceUID<br/>- RemoteConfig<br/>- ConnectionSettings<br/>- PackagesAvailable<br/>- Flags<br/>- Command
 end
 
 Note over Agent,DB: Error Handling (if occurs)
 
 opt Read Error
 OpAMPLib->>Service: OnReadMessageError(conn, type, msg, err)
 Note right of Service: Log error details
 end
 
 opt Response Error
 OpAMPLib->>Service: OnMessageResponseError(conn, msg, err)
 Note right of Service: Log error details
 end
 
 Note over Agent,DB: Disconnection Phase
 
 Agent->>OpAMPLib: Disconnect
 OpAMPLib->>Service: OnConnectionClose(connection)
 Service->>Service: Queue background cleanup
 Note right of Service: Return immediately
 
 Service->>Service: Background Loop executes
 Service->>ConnUC: GetConnectionByID(ctx, conn)
 ConnUC->>DB: Find
 DB-->>ConnUC: connection
 ConnUC-->>Service: connection
 
 alt Not Anonymous
 Service->>AgentUC: GetAgent(ctx, instanceUID)
 AgentUC->>DB: Find
 DB-->>AgentUC: agent
 AgentUC-->>Service: agent
 Service->>Service: Update agent.Status (Connected=false)
 Service->>AgentUC: SaveAgent(ctx, agent)
 AgentUC->>DB: Save
 end
 Service->>ConnUC: DeleteConnection(ctx, connection)
 ConnUC->>DB: Delete
 Note right of WS: WebSocket registry<br/>auto-cleanup

OpAMP Callbacks Summary

Callback	When Called	Purpose
OnConnecting	Before accepting connection	Validate and decide whether to accept
OnConnected	After connection established	Initialize connection tracking
OnMessage	When message received from agent	Process agent data and send response
OnReadMessageError	When failed to read message	Log and handle read errors
OnMessageResponseError	When failed to send response	Log and handle send errors
OnConnectionClose	When connection closed	Cleanup resources asynchronously

Architecture Layers

The diagram follows Hexagonal Architecture (Ports and Adapters):

Overview on OpAMP Commander

OpAMP Protocol Sequence

OpAMP Protocol Execution Sequence

Agent Connection and Message Exchange Flow

OpAMP Callbacks Summary

Architecture Layers