Skip to content
flowlayer

Overview

// Protocol V1specification

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

Transport and session model

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “Runtime command catalog”
  • get_snapshot
  • get_logs
  • start_service
  • stop_service
  • restart_service
  • start_all
  • stop_all

Where to continue

Section titled “Where to continue”