Interface control document

1. Identification

2. Scope

This document defines the supported integration boundary around HEAT Capture:

• REST session control and operational monitoring
• WebSocket frame publishing by simulator plugins and other publishers
• WebSocket event, live-view and administrator streams
• the named-pipe protocol between HEAT Capture and an isolated capture module
• the HEAT platform calls consumed for authentication, sessions and data delivery

Settings, package, inference, after-action and system-management routes used by the browser UI are private interfaces. They are not a supported third-party contract and may change with the UI. Their network exposure is still material; see Section 12.

Individual gaze, simulator, physiology and other payload components are defined by HEAT ProtoLib and the module or plugin ICD that populates them.

3. Interface inventory

4. IF-CAPTUREAPP-01 Session control and monitoring

4.1 Transport and addressing

WebSettings:Host, Port, EnableHttps and HttpsPort configure the listener and require a restart. The HTTPS certificate is self-signed. HTTPS binds every interface regardless of Host.

4.2 Lifecycle and access control

A user signs in through HEAT Capture, then the peer starts, optionally pauses or resumes, and stops the session. Authentication state belongs to the process, not to the HTTP client. Session routes return 401 when no user is signed in. Storage administration requires the Admin role.

Pause rejects new packets before local storage and delivery. Modules and plugins may continue producing data, but data received during the pause is discarded. Resume accepts newly arriving packets; it cannot recover packets produced during the pause.

4.3 Messages

GET requests to the start, pause, resume and stop action paths return 400 with {"error":"Invalid request, use post method"}.

4.4 Data elements

The platform-owned session object can also contain project, sessionTemplate, metadataJson, sessionUsers and nodeInstances. Clients must tolerate null, absent and additional fields.

4.5 Timing, ordering and errors

State-changing requests are serialised. Callers must wait for each response before the next transition. Stopping allows up to 15 seconds for in-flight delivery, 30 seconds to drain disk writes and a further 30 seconds for final delivery.

There are no idempotency keys. After a lost response, read current-session before retrying.

5. IF-CAPTUREAPP-02 Frame publish

5.1 Transport, lifecycle and authentication

Open /ws/publish on the IF-CAPTUREAPP-01 listener, using ws for HTTP or wss for HTTPS. The server keep-alive interval is 10 seconds. A user must already be signed in to the HEAT Capture process; the client presents no token. Otherwise the upgrade returns HTTP 401.

Each complete binary WebSocket message is one serialized google.protobuf.Any. Fragmentation is allowed. The socket may stay connected without an active session, but messages sent then are discarded. Reconnecting creates an independent ingress stream.

5.2 Message and data elements

HEAT Capture wraps accepted data in a DataPacket, stamps signed 64-bit milliseconds since the Unix epoch from its UTC wall clock, and injects the signed-in user’s UUID when no origin is present. There is no application acknowledgement.

5.3 Timing, ordering and errors

The interface has no prescribed period, frequency or latency budget. Messages on one socket are parsed sequentially in arrival order; there is no global order across sockets.

6. IF-CAPTUREAPP-03 Events and live monitoring

6.1 Paths and access

For events and operator streams, send {"op":"subscribe","topics":[...]}. It replaces the current subscription set. Event topics are session, config, packages and auth; operator topics are logs and operations. Unknown topics are ignored. There is no replay.

If the Admin user signs out or loses the role, HEAT Capture closes /ws/operator and checks the role again before each send. /ws/live ignores client data except close frames.

6.2 Data elements

Non-finite live floating-point values are JSON null.

6.3 Timing and errors

These streams are deliberately lossy and are not durable capture feeds. Events and operator streams hold 512 messages per connection and drop the oldest when full. Live streams hold eight messages per type per connection and drop the oldest of that type. Slow viewers never back-pressure capture.

Malformed subscription JSON and unknown topics are ignored without closing the socket. An unserialisable outbound value is dropped. A non-upgrade request returns 400; a non-Admin operator upgrade returns 403.

7. IF-CAPTUREAPP-04 Isolated module transport

7.1 Addressing and framing

HEAT Capture creates one full-duplex byte-mode named pipe per module. Its name is heat.capture.module. followed by 32 random uppercase hexadecimal characters. It permits one server instance and grants full control only to the Windows user that launched HEAT Capture.

The module host receives --pipe, --module-file and --module-type, then connects locally. Each frame is:

7.2 Lifecycle and trust

1. HEAT Capture verifies the module package signature.
2. It creates the pipe and starts the module process.
3. The module has 10 seconds to connect.
4. HEAT Capture sends init, negotiates the maximum protocol version, then sends start.
5. It sends ping every 10 seconds. Two missed heartbeats mark the module crashed.
6. On stop it sends stop with a 15-second RPC timeout. A process that does not exit within 5 seconds is killed.

There is no protocol credential. Trust comes from package verification, the unpredictable pipe name passed to the child and the current-user pipe ACL.

7.3 Control messages

Channel 0 is a UTF-8 JSON envelope.

Protocol version is integer 3 at this product ref. Initialization and configuration contain either typed settingsJson or flattened settingsValues, plus locale and localized strings. http.send uses required method and uri, multi-value headers, optional Base64 body and a 32-bit signed HTTP status response. Every control frame remains subject to the 16 MiB limit.

7.4 Data channel, timing and errors

Channel 1 is four bytes of signed little-endian destination node id followed by one serialized HEAT DataPacket. Node id range is -2,147,483,648 to 2,147,483,647. Total channel payload must not exceed 16,777,216 bytes. There is no per-packet acknowledgement. During pause the frame is accepted from the pipe, but its packet is rejected before storage.

Writes retain frame order per pipe. Normal RPC timeout is 15 seconds; asynchronous value discovery allows 45 seconds. Framing errors, unknown channels and partial writes close and poison the connection. Two missed heartbeats mark the module crashed. Failed graceful stop leads to process termination and may quarantine the module for the application run.

8. IF-CAPTUREAPP-05 HEAT platform service

8.1 Addressing, authentication and lifecycle

HEATSettings:HEAT_URL is the base URI. Production deployments must use HTTPS. The operator signs in with username and password; HEAT Capture then sends a bearer access token and refreshes the token pair when required. Changing the URL signs the user out and recreates HTTP clients.

A session creates or joins a platform shared session, resolves template nodes to session node instances, uploads locally stored packets, and closes the session. Network failure does not stop capture; packets remain on disk.

8.2 Messages

Delivery retries with exponential backoff from 250 ms to 5 seconds for 10 attempts by default. A failed packet is then parked for a later launch. Replay requires a signed-in user and an exact match between the stored platform URL and current HEAT_URL. The interface does not promise exactly-once delivery.

9. Data model, units and conventions

HEAT Capture Module SDK 2.0.5 supplies HEAT.ProtoLib.CSharp 0.37.0, pinned by its assembly product version to commit 05270c5d.

IF-CAPTUREAPP-02 accepts any protobuf Any with a non-empty type_url. IF-CAPTUREAPP-04 and IF-CAPTUREAPP-05 carry DataPacket. Module and plugin ICDs define the message types they produce.

10. Configuration affecting interfaces

See Configure HEAT Capture.

11. Compatibility and versioning

• JSON clients must ignore unknown properties and event names. Optional nested session values may be null or absent.
• Protobuf peers must tolerate unknown fields and use messages compatible with HEAT ProtoLib 0.37.0.
• IF-CAPTUREAPP-04 peers negotiate their maximum integer protocol version in init; this ref supports up to 3. Unknown frame channels close the pipe.
• IF-CAPTUREAPP-05 depends on the platform’s /api/authorization and /api/v2 contracts.
• An interface identifier remains assigned if the interface is deprecated or withdrawn.

12. Security considerations

Bind to localhost unless a remote peer needs access. Otherwise use a host firewall allowlist, enable HTTPS and establish explicit trust for the self-signed certificate.

• /ws/events and /ws/live disclose product and capture data without authentication.
• /ws/publish checks process sign-in, not peer identity. Any reachable client can publish under the active user’s session.
• Private package, settings and restart routes are unauthenticated.
• Module trust depends on package signatures and the current-user named-pipe ACL.
• Platform tokens are encrypted, but their master key is stored on the same workstation.
• A Module Library token in heat.modules.json is clear text. Remove it from support bundles.

13. Conformance

13.1 REST and publish peer

13.2 Event peer

13.3 Module peer

14. Revision history

HEAT Capture team. Last updated 2 October 2026.