System Events¶

System events provide liveness and round-trip checks that work on any authenticated connection.

Reference: protocol.md · connection.md · lifecycle.md

Event list¶

system.ping¶

Description¶

An application-level liveness and latency probe. The client sends system.ping and measures the round trip against the pong acknowledgement. It is independent of the transport-level heartbeat (see connection.md) and is useful for pre-flight checks and app-level keepalive.

Direction¶

Client → Server

Roles Allowed¶

All roles: SUBSCRIBER, COMPANY, SUPERADMIN.

Permissions Required¶

None. system.ping has no permission requirement.

Request Schema¶

The event accepts an empty or omitted data object.

Response Schema¶

The handler returns acknowledgement data containing a pong marker and the server timestamp:

Success Response¶

{
  "type": "ack",
  "requestId": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "eventType": "system.ping",
  "data": {
    "type": "system.pong",
    "occurredAt": "2026-08-03T10:00:00.000Z"
  }
}

Error Responses¶

system.ping does not throw application errors. Malformed envelopes still return standard validation errors (see errors.md).

Validation Rules¶

Example Request¶

{
  "type": "system.ping",
  "requestId": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "data": {}
}

Example Response¶

{
  "type": "ack",
  "requestId": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "eventType": "system.ping",
  "data": {
    "type": "system.pong",
    "occurredAt": "2026-08-03T10:00:00.000Z"
  }
}

Broadcast Behaviour¶

None. system.ping is unicast to the requesting connection only. It is never broadcast to a room.

Related Events¶

• connection.md — transport-level heartbeat (ping/pong control frames), which is separate from system.ping.
• events/auth.md — auth.login (planned) for connection handshake.

Notes¶

• Implementation status: Implemented (src/interfaces/websocket/handlers/system.ts).
• The transport heartbeat is automatic and does not require application messages. Use system.ping only for latency measurement or app-level keepalive.
• Rate limiting applies to system.ping with the default limit (see rate-limits.md); do not ping more often than needed.

Best Practices¶

• Ping at most a few times per minute; excessive pings consume rate-limit budget.
• Use Date.now() deltas from the client to measure RTT, not wall-clock alignment.
• Treat a system.pong as liveness only after the connection is open.

system.pong¶

Description¶

system.pong is the acknowledgement data returned for system.ping. It is not a client-sendable event; clients receive it inside the ack envelope and should not construct it.

Direction¶

Server → Client (inside the system.ping acknowledgement).

Roles Allowed¶

N/A (server-generated).

Permissions Required¶

None.

Request Schema¶

N/A — clients do not send system.pong.

Response Schema¶

Not applicable; this is response data, documented under system.ping.

Success Response¶

See system.ping → Success Response.

Error Responses¶

None.

Validation Rules¶

N/A.

Example Response¶

{
  "type": "ack",
  "requestId": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "eventType": "system.ping",
  "data": {
    "type": "system.pong",
    "occurredAt": "2026-08-03T10:00:00.000Z"
  }
}

Broadcast Behaviour¶

None.

Related Events¶

• system.ping

Notes¶

• Implementation status: Server-generated response data.
• Keep clients tolerant: always treat system.pong as advisory, never as the source of truth for connectivity (use the socket open/close events).

Best Practices¶

• Measure RTT from system.ping; do not rely on occurredAt for time sync (NTP/HTTP date headers are more accurate).