3.5 WebSocket
Clients send events to an environment and get its changes pushed over the WebSocket at ws://127.0.0.1:8080/ws, on the host and port of 3.3.4 Configuration. All messages are text frames.
3.5.1 Connecting#
A client first registers over HTTP with registerClientForWebSocket or observatory/registerClient of 3.4 HTTP API and gets an access key. Then it opens the WebSocket and sends as its first frame its client id, the key of the environment and the access key, separated by colons:
panel:env-1763035112345:ak-panel-1763035113001-4821
The runtime closes the connection with code 1003 and one of these reasons when the first frame is wrong:
| Reason | When |
|---|---|
First message must be text | The first frame is no text frame |
Invalid auth format | The frame does not have exactly three parts |
Invalid credentials | The access key is unknown, was used before, or belongs to another client or environment |
The runtime sends no answer to a correct first frame. A client knows that it is connected when observatory/subscribeModel succeeds or when the first message arrives. Each access key works for one connection; a client that connects again registers again. The runtime sends a ping every 60 s and closes a connection that does not answer within 15 s.
The connections stay open when the environment is stopped and started again; the clients learn both through engineStatus. Two closes end them from the side of the runtime:
| Code | Reason | When |
|---|---|---|
| 1000 | Environment dropped | POST /dropEnvironment dropped the environment of the connection |
| 1001 | Runtime stopped | The runtime itself ends |
After either close the access key of the connection is gone. After a drop the environment is gone too, and a client that wants to go on needs a new environment.
3.5.2 Sending events#
A client sends an event as a JSON object:
{"environmentKey": "switch", "messageType": "dim", "payload": "{\"bright\": true}", "payloadFormat": "json"}
| Entry | Meaning |
|---|---|
environmentKey | The domain of the event, as in EVENT("switch", "dim"). Despite its name it is not the key of the environment |
messageType | The name of the event |
payload | The payload as a string. Optional, empty by default |
payloadFormat | none, json or kmodel, in any case. Optional |
Without payloadFormat the runtime takes the format from the payload: empty is no payload, text that starts with { is JSON, text that starts with make object is KModel. The runtime reads the payload against the event type named like the event, as 3.1.7.4 Payloads describes. A payload in KModel is one make object of that type:
{"environmentKey": "switch", "messageType": "dim", "payload": "make object \"step\":\"dim\" { prop(\"bright\") -> \"true\" }"}
The event goes to the environment the connection belongs to. A frame that is no JSON object with environmentKey and messageType is ignored. Events sent before runEnvironment are dropped. Events sent after runEnvironment and before startEnvironment wait for the start. The runtime sends no answer to an event.
3.5.3 Pushed messages#
Every message the runtime pushes has the same frame:
{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"objectChanged","payload":{}}
Here environmentKey is the key of the environment. payload is a JSON object that depends on messageType. The runtime pushes nothing when websocket.enabled is false.
| Message | Who gets it | When |
|---|---|---|
objectChanged | Observers of the object, model subscribers | An action block changed a property or relation of the object |
objectDeleted | Observers of the object, model subscribers | An action removed the object |
stateChange | Clients of observatory/registerClient for this state machine or *, model subscribers | The stack of a state machine changed, and in the first tick after the first start |
stateMachineAttached | The same clients as stateChange of the object | A state machine instance joined: at the first start for every instance, and at the end of a tick for each that joined in it |
stateMachineDetached | The same clients as stateChange of the object | A state machine instance left, at the end of the tick in which it ended |
domainEvent | Listeners of the domain | An event of the domain reached the bus |
engineStatus | Every client connected to the environment | The run starts or ends a wait of TickByTick, the environment was stopped, or a stopped environment was started |
3.5.3.1 objectChanged#
{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"objectChanged","payload":{"objectId":"bulb","revision":7,"value":{"__id__": "bulb", "__type__": "Bulb", "maxWatts": 40, "watts": 40, "lit": true}}}
value is the whole object after the action block: __id__ with its key, __type__ with its type, its properties in the order of the model, and its relations with the objects in them, again whole. Objects in a knows relation are written whole as well. A property without a value is left out. The message names the object whose own property or relation changed. A change of the bulb gives a message for bulb and none for lamp, which holds it.
A block that changes several objects gives one message per object, after the block.
3.5.3.2 objectDeleted#
{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"objectDeleted","payload":{"objectId":"spare","revision":9}}
DROPOBJ("spare") gives objectDeleted for spare and every object it holds, and objectChanged for the lamp that held it. The messages of the changes come first.
3.5.3.3 stateChange#
{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"stateChange","payload":{"modelElementId":"lamp","stack":["on","full"],"revision":8}}
modelElementId is the key of the object of the state machine. stack is its stack from the outside in; in a split it is the stacks of all branches one after the other. The order of the entries in payload is not fixed.
Inside a container state the stack names the states of the fragment with their qualified names, as 3.1.14.2 Qualified names describes. A lamp in the self test of 2.3.12 Pages reports "stack":["self test","self test/powered"]. A stack never ends on a container state.
3.5.3.4 domainEvent#
{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"domainEvent","payload":{"domain":"switch","payload":{"event":"dim","payload":"{\"bright\": true}","payloadFormat":"json","source":"EXTERNAL_MESSAGE","timestamp":1763035114120,"ttlMs":5000}}}
| Entry | Meaning |
|---|---|
event | The name of the event |
payload | The payload as the sender wrote it, as a string |
payloadFormat | none, json or kmodel |
source | EXTERNAL_MESSAGE for events from clients and from EventInjection, INTERNAL for events raised with the action EVENT |
timestamp | When the runtime got or raised the event, in milliseconds since 1970 |
ttlMs | The time to live of the event |
The order of the entries inside the inner payload is not fixed. A domainEvent has no revision.
3.5.3.5 engineStatus#
{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"engineStatus","payload":{"paused":true,"waiting":true}}
The payload is the status of 3.2.5.3 Status, with halt while a breakpoint holds the run. An engineStatus has no revision.
A stop and a start after it are told with the member phase, stopped or running, the phase of the snapshot, next to the status at that moment; without TickByTick the status is {"paused":false,"waiting":false}:
{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"engineStatus","payload":{"phase":"stopped","paused":false,"waiting":false}}
{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"engineStatus","payload":{"phase":"running","paused":false,"waiting":false}}
The engineStatus messages of TickByTick have no phase. A stop while the run is paused says "paused":true and "waiting":true, and so does the start after it, because the run still waits. A client that reads only paused and waiting keeps working; it does not learn of the stop. The first start of an environment sends no engineStatus.
3.5.3.6 stateMachineAttached and stateMachineDetached#
{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"stateMachineAttached","payload":{"modelElementId":"gen_Bulb_0","stateMachine":"blinking","revision":12}}
{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"stateMachineDetached","payload":{"modelElementId":"bulb","stateMachine":"glowing","revision":15}}
modelElementId is the key of the object, the key that stateChange uses for the instance. stateMachine is the name of the attachable state machine the instance runs, and null for a state machine uploaded with attachedTo. So a client tells an instance, named by the object, from its definition, named by stateMachine. The order of the entries in payload is not fixed.
At the first start the runtime sends stateMachineAttached for every instance before the first tick, in the order in which they step. A start after a stop continues the run and announces nothing anew. During a run, an instance that joins is announced at the end of the tick it joined in, after the stateChange messages of that tick, and its first stateChange follows after its first step. An instance that leaves is announced at the end of the tick in which it ended, before the instances that join in the same tick; after it no stateChange comes for it. When EXCHANGE replaces an instance, stateMachineDetached with the old definition comes before stateMachineAttached with the new one, for the same object. objectDeleted of a removed object comes earlier, when the action removes it.
A client that does not know these messages can ignore them. It still gets stateChange for every instance, also for those that join during the run, but it does not learn when one leaves.
3.5.4 Revisions#
objectChanged, objectDeleted, stateChange, stateMachineAttached and stateMachineDetached carry a revision. Each environment counts its revisions from 1 on, one count for all five messages and all clients, in the order of the changes. The count goes on after a stop and a start; the two add no revision. A change of an object that cannot be written as JSON, because it reaches itself over its relations, uses up a revision and sends nothing.
3.5.5 Keeping a copy of the model#
A client that shows the whole model keeps a copy this way:
-
Register with
registerClientForWebSocket, connect, and callobservatory/subscribeModel. -
Read
observatory/model. Itsrevisionis the last change it contains. -
Ignore pushed messages with a revision up to the one of the snapshot, and apply the later ones in order: replace the object for
objectChanged, remove it forobjectDeleted, replace the stack forstateChange, add the object with its definition tostateMachinesforstateMachineAttached, and remove the object fromstateMachinesandactiveStatesforstateMachineDetached. -
When a revision is missing, read
observatory/modelagain.
3.5.6 Delivery#
The runtime sends the messages of one client in the order they were made. A client that has more than one connection to the same environment gets each message on one of them. Messages for a client without a connection are dropped. After 10 s without a connection, the runtime also ends the registration of the client made with observatory/registerClient.