WebSocket API

Start the WebSocket server with:

graphwalker online -s WEBSOCKET -p 8887 -m model.json "random(edge_coverage(100))"

Connect with any WebSocket client to ws://localhost:8887/graphwalker.

All messages are JSON objects. Commands from the client include a "command" field. Responses include "success": true or "success": false with a "message" field on failure.

---

Commands

start

Create a new execution session.

Request:

{
  "command": "start",
  "gw": { "models": [ ... ] },
  "seed": 12345,
  "globalData": "x = 0; y = 0;",
  "name": "My Test Session"
}

Field	Required	Description
gw	Yes	Model definition (same format as the JSON model file)
seed	No	Random seed for deterministic execution
globalData	No	Initialization script for global variables
name	No	Session name (defaults to the first model’s name)

Response:

{
  "command": "start",
  "success": true,
  "seed": 12345,
  "sessionId": "session-1"
}

---

getNext

Advance the execution by one step.

Request:

{ "command": "getNext" }

Response:

{
  "command": "visitedElement",
  "success": true,
  "modelId": "model-id",
  "elementId": "e1",
  "name": "e_Login",
  "visitedCount": 1,
  "totalCount": 12,
  "stopConditionFulfillment": 0.45,
  "data": "loggedIn=false"
}

Field	Description
modelId	ID of the model containing the element
elementId	ID of the visited element
name	Name of the visited element
visitedCount	How many times this element has been visited
totalCount	Total elements in the model
stopConditionFulfillment	Progress toward the stop condition (0.0 to 1.0)
data	Current variable values

If the session is paused, getNext blocks until the session is resumed or stepped.

---

hasNext

Check whether more steps are available.

Request:

{ "command": "hasNext" }

Response:

{
  "command": "hasNext",
  "success": true,
  "hasNext": true
}

---

getData

Get current execution variables.

Request:

{ "command": "getData" }

Response:

{
  "command": "getData",
  "success": true,
  "data": "loggedIn=true; count=5"
}

---

setData

Modify execution variables.

Request:

{
  "command": "setData",
  "action": "loggedIn = true;"
}

Response:

{
  "command": "setData",
  "success": true
}

---

getModel

Retrieve the loaded model definition.

Request:

{ "command": "getModel" }

Response:

{
  "command": "getModel",
  "success": true,
  "models": "{ \"models\": [ ... ] }"
}

The models field is a JSON string (not a parsed object).

---

updateAllElements

Get visit counts for all elements.

Request:

{ "command": "updateAllElements" }

Response:

{
  "command": "updateAllElements",
  "success": true,
  "elements": [
    { "modelId": "model-1", "elementId": "n0", "visitedCount": 3 },
    { "modelId": "model-1", "elementId": "e0", "visitedCount": 2 }
  ]
}

---

check

Validate a model without loading it.

Request:

{
  "command": "check",
  "gw": { "models": [ ... ] }
}

Response:

{
  "command": "check",
  "success": true,
  "issues": []
}

If there are issues:

{
  "command": "check",
  "success": true,
  "issues": ["Name of vertex cannot be null or empty"]
}

---

convertGraphml

Convert a GraphML model to JSON.

Request:

{
  "command": "convertGraphml",
  "graphml": "<graphml xmlns='...'> ... </graphml>"
}

Response:

{
  "command": "convertGraphml",
  "success": true,
  "models": "{ \"models\": [ ... ] }"
}

---

Session management

The WebSocket API supports multiple concurrent sessions. These commands control session execution and observation.

listSessions

List all active sessions.

Request:

{ "command": "listSessions" }

Response:

{
  "command": "sessions",
  "success": true,
  "sessions": [
    { "id": "session-1", "name": "Login Test" },
    { "id": "session-2", "name": "Payment Flow" }
  ]
}

---

subscribeSession

Subscribe to execution events from another session.

Request:

{
  "command": "subscribeSession",
  "sessionId": "session-1"
}

Response:

{
  "command": "subscribeSession",
  "success": true,
  "sessionId": "session-1",
  "name": "Login Test",
  "models": { "models": [ ... ] },
  "elements": [
    { "modelId": "model-1", "elementId": "n0", "visitedCount": 2 }
  ],
  "seed": 12345,
  "paused": false
}

After subscribing, you receive broadcast events (see below) whenever the session advances.

---

unsubscribeSession

Stop receiving events from a subscribed session.

Request:

{ "command": "unsubscribeSession" }

Response:

{
  "command": "unsubscribeSession",
  "success": true
}

---

pauseSession

Pause an active session. Subsequent getNext calls block until resumed.

Request:

{
  "command": "pauseSession",
  "sessionId": "session-1"
}

Response:

{
  "command": "pauseSession",
  "success": true
}

---

resumeSession

Resume a paused session.

Request:

{
  "command": "resumeSession",
  "sessionId": "session-1"
}

Response:

{
  "command": "resumeSession",
  "success": true
}

---

stepSession

Execute exactly one step, then pause again.

Request:

{
  "command": "stepSession",
  "sessionId": "session-1"
}

Response:

{
  "command": "stepSession",
  "success": true
}

---

setDelay

Set a delay (in milliseconds) between execution steps. Useful for watching execution in real time.

Request:

{
  "command": "setDelay",
  "sessionId": "session-1",
  "value": 500
}

Response:

{
  "command": "setDelay",
  "success": true
}

---

setBreakpoints

Set breakpoints on specific elements. When execution reaches a breakpoint, the session automatically pauses.

Request:

{
  "command": "setBreakpoints",
  "sessionId": "session-1",
  "breakpoints": ["model-1,n0", "model-1,e2"]
}

Breakpoint format: "modelId,elementId".

Response:

{
  "command": "setBreakpoints",
  "success": true
}

---

Broadcast events

These are unsolicited messages sent to subscribed clients.

visitedElement

Sent when a subscribed session traverses an element.

{
  "command": "visitedElement",
  "modelId": "model-1",
  "elementId": "e1",
  "name": "e_Login",
  "visitedCount": 1,
  "totalCount": 12,
  "stopConditionFulfillment": 0.45,
  "data": "loggedIn=false"
}

sessionCreated

Sent when a new session is created (to clients that called listSessions).

{
  "command": "sessionCreated",
  "sessionId": "session-2",
  "name": "New Session"
}

sessionEnded

Sent when a session terminates.

{
  "command": "sessionEnded",
  "sessionId": "session-1"
}

sessionPaused

Sent when a session is paused (manually or by breakpoint).

{
  "command": "sessionPaused",
  "sessionId": "session-1"
}

When triggered by a breakpoint:

{
  "command": "sessionPaused",
  "sessionId": "session-1",
  "reason": "breakpoint",
  "modelId": "model-1",
  "elementId": "n0"
}

sessionResumed

Sent when a session resumes.

{
  "command": "sessionResumed",
  "sessionId": "session-1"
}