Skip to main content

Overview

FlowLayer protocol V1 defines how external clients talk to the running server session.

Transport and session model​

  • Transport: WebSocket on /ws
  • Authentication: Authorization: Bearer <token> on the upgrade request
  • Each WebSocket connection is an independent session
  • No session persistence across reconnects

Message envelope​

All messages use the same high-level structure:

{
	"type": "<message_type>",
	"id": "<correlation_id>",
	"name": "<command_or_event_name>",
	"payload": {}
}

Envelope fields are optional when not applicable.

Message types​

  • command: client -> server request
  • ack: immediate command acceptance/rejection (private to sender)
  • result: final command outcome (private to sender)
  • event: asynchronous server message
  • error: protocol-level error (private to sender)

Command flow​

Normal flow:

  1. client sends command with unique id
  2. server sends ack for that id
  3. if ack.accepted is true, server sends result

ack.accepted = false means the command is rejected and no result follows.

Message scope​

  • private to command sender: ack, result, error
  • private to one connection: hello, snapshot
  • broadcast to all sessions: service_status, log

log events are best-effort and may be dropped under load.

Runtime command catalog​

  • get_snapshot
  • get_logs
  • start_service
  • stop_service
  • restart_service
  • start_all
  • stop_all

Where to continue​