The same contract over WebSocket

What you need before you start

The commands below run in the prepared ~/Desktop/SumDoc-API-first-run folder. It comes, together with the a4-api-demo.mjs and start-web-demo.sh scripts, from the Evaluation Kit — a separate delivery artifact (see What is delivered). It is not part of the SumDoc installer and cannot be downloaded from dl.layers.md: request it from the vendor.

If you don’t have the Evaluation Kit yet, an installed SumDoc is enough to follow the same path manually: fastdoc-cli lives inside the application (see Installation and verification), the request format is described in Request and response objects, and the full list of commands is in the reference. SumSheet has an example of a fully written-out script: verified script. :::

WebSocket is convenient when your product’s shell is already asynchronous and built on web technologies. The core picks a free local port itself and prints a single line with the connection address and a one-time pass.

macOS

cd ~/Desktop/SumDoc-API-first-run
node a4-websocket-demo.mjs

Windows

cd $HOME\Desktop\SumDoc-API-first-run
node a4-websocket-demo.mjs

Linux

cd ~/Desktop/SumDoc-API-first-run
node a4-websocket-demo.mjs

Connection sequence

1. Start fastdoc-cli serve --ws 0 as a child process. Zero means “any free port”.
2. Read the first line of stdout — it has host, port, token, and schema.
3. Connect to ws://127.0.0.1:<port>/?token=<token>, substituting the values from that line.
4. Wait for the session greeting with the fastdoc.session-serve.v1 schema.
5. Send the same JSON objects as over JSONL.
6. When closing the application, send shutdown first, then close the socket and the child process.

Actual result

1. WebSocket: ws://127.0.0.1:52601
2. Session protocol: fastdoc.session-serve.v1
3. Ping: true
4. Before: This is a sample word document. It has two pages, but no headers or footers.
5. After:  WS API DEMO: This is a sample word document. It has two pages, but no headers or footers.
6. Saved: /Users/tester/Desktop/SumDoc-API-first-run/api-demo-websocket-result.docx
7. Reopened from disk: WS API DEMO: This is a sample word document. It has two pages, but no headers or footers.
RESULT: PASS

Transport security

Listen only on 127.0.0.1, use the issued token, don’t expose the port externally, and don’t pass a path to an arbitrary file without your own access check. :::

Minimal client loop

const child = spawn(cli, ["serve", "--ws", "0"]);
const bootstrap = JSON.parse(await firstLine(child.stdout));
const ws = new WebSocket(
  `ws://${bootstrap.host}:${bootstrap.port}/?token=${bootstrap.token}`
);
await new Promise(resolve =>
  ws.addEventListener("open", resolve, { once: true }));

ws.send(JSON.stringify({ id: "p1", cmd: "ping" }));

Frames are text-only

The exchange uses text WebSocket frames: each request is one line of JSON, and each response arrives the same way.

The session refuses a binary frame but doesn’t drop the connection: it responds with

{"id":null,"ok":false,
 "error":"session WebSocket requests must be UTF-8 text frames"}

and you can keep working on the same connection. Note the id: null — with this kind of refusal, the session doesn’t yet know which request the frame came from. :::