Skip to main content

Events

FlowLayer V1 emits server-initiated event messages over the same WebSocket used for commands.

Event catalog​

Event nameScopeWhen emitted
helloPrivate (new connection only)Immediately after WebSocket upgrade
snapshotPrivate (new connection only)Immediately after hello
service_statusBroadcast (all connected sessions)On service state changes
logBroadcast (all connected sessions)On new service log lines

hello​

hello advertises protocol version, server identity, and command 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 contains service statuses at connection time.

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

Services in snapshot are emitted in deterministic name order.

service_status​

service_status is broadcast whenever runtime status changes.

{
	"type": "event",
	"name": "service_status",
	"payload": {
		"service": "api",
		"status": "stopping",
		"timestamp": "2026-04-25T10:05:00Z"
	}
}

log​

log carries live log lines with sequence number metadata.

{
	"type": "event",
	"name": "log",
	"payload": {
		"seq": 1042,
		"service": "api",
		"phase": "running",
		"stream": "stdout",
		"message": "listening on :3000",
		"timestamp": "2026-04-25T10:05:01Z"
	}
}

Private vs broadcast scopes​

For protocol consumers:

  • Private per connection: hello, snapshot
  • Broadcast to all sessions: service_status, log

Related private response messages are documented in Message Envelopes: ack, result, error.

Log delivery model and continuity​

Live log events are best-effort. Under burst load, log events may be dropped instead of blocking command/control traffic.

Use stream vs pull this way:

NeedRecommended source
Live tail in UIlog events
Recover after reconnectget_logs with after_seq
Fill gaps after slow consumer periodsget_logs with last seen seq
Bounded history retrievalget_logs with limit

get_logs returns entries, truncated, and effective_limit; use seq as the continuity marker.

See WebSocket Lifecycle for reconnect semantics and Logs API semantics for pull-command details.