WebSocket Lifecycle

FlowLayer V1 uses one WebSocket channel for both command traffic and runtime events.

Endpoint and authentication

Clients connect to ws://<host>:<port>/ws.

The upgrade request must include:

Authorization: Bearer <token>

Authentication outcomes during the HTTP upgrade step:

Condition	Outcome
Missing Authorization header	401
Invalid token	403
Valid token	WebSocket upgrade accepted

After a successful upgrade, that socket is one independent session.

Lifecycle sequence

1. Client opens WebSocket connection on /ws with Bearer token.
2. Server upgrades the connection.
3. Server sends event named hello.
4. Server sends event named snapshot.
5. Session becomes operational:
   • client can send command messages at any time;
   • server pushes live event messages (service_status, log).
6. Disconnection ends the session.
7. Reconnection creates a new independent session.

Initial server messages

hello

hello is sent immediately after upgrade and announces protocol and server capabilities.

{
  "type": "event",
  "name": "hello",
  "payload": {
    "protocol_version": 1,
    "server": "flowlayer",
    "capabilities": [
      "get_snapshot",
      "get_logs",
      "start_service",
      "stop_service",
      "restart_service",
      "start_all",
      "stop_all"
    ]
  }
}

snapshot

snapshot is sent right after hello and provides the current service states.

{
  "type": "event",
  "name": "snapshot",
  "payload": {
    "services": [
      { "name": "api", "status": "running" },
      { "name": "worker", "status": "ready" }
    ]
  }
}

Commands during live events

Once connected, command handling and event streaming are concurrent:

• Commands are sent as type: "command".
• Server replies with ack and, when accepted, result.
• service_status and log events continue to arrive asynchronously.

See Message Envelopes for correlation rules and Events for event payload details.

Reconnection semantics

FlowLayer does not persist protocol session state across disconnects:

• a reconnect is a new session;
• no automatic replay of prior commands;
• no automatic replay of missed events.

For log continuity after reconnect, use get_logs with after_seq as described in Events and Reference.