@dogsvr/cl-tsrpc

TSRPC connection layer for @dogsvr/dogsvr — inbound WebSocket and HTTP transport, with per-connection auth and identity binding (openId / zoneId / gid).

Install

npm install @dogsvr/cl-tsrpc

Node.js: tested on v24.13.0 on Linux (x86-64); other maintained LTS lines are expected to work but are not routinely exercised. File an issue if something breaks on your runtime.

Usage

Importing the package in the main thread self-registers a "tsrpc" CL factory with @dogsvr/dogsvr:

import * as dogsvr from '@dogsvr/dogsvr/main_thread';
import '@dogsvr/cl-tsrpc';
dogsvr.startServer(__dirname + '/main_thread_config.json');

Add a CL entry to main_thread_config.json:

{
    "cl": {
        "tsrpc": { "type": "tsrpc", "svrType": "ws",   "port": 20000 }
        // or:    { "type": "tsrpc", "svrType": "http", "port": 10000 }
    }
}

The layer hooks ApiCommon on each incoming call: the first request must carry openId + zoneId; once authenticated, the identity is bound to the connection. gid is populated from the first worker response and auto-filled on subsequent messages.

Logging

tsrpc's internal logs (connection accept/disconnect, [ApiReq]/[ApiRes]/[SendMsg]/[RecvMsg], etc.) are routed through dogsvr's logger as module: "tsrpc".

Default level: warn. This is intentional: tsrpc emits per-RPC bodies at info (request and response payloads). Defaulting to warn keeps prod logs clean and avoids accidentally logging request bodies (PII / auth tokens). Override per-CL when you need protocol detail:

"cl": {
    "tsrpc": { "type": "tsrpc", "svrType": "ws", "port": 20000, "log": { "level": "debug" } }
}

Accepts tsrpc-proto's LogLevel: "debug" | "info" | "warn" | "error" | "none" — all lower-case, no other spellings accepted. Values pass straight to the tsrpc server's logLevel. Case-sensitive: any other spelling (e.g. "WARN", "Warn") makes tsrpc throw Invalid logLevel: '...' at construction.

Regenerating TSRPC protos

This package owns the TSRPC proto used internally:

npm run protoc      # tsrpc-cli

Role in dogsvr

One of several pluggable connection layers that plug into the dogsvr main thread. See the dogsvr README for how CL factories are registered and how worker threads consume the routed messages.

See also

• example-proj — three-server reference that uses this CL on dir (HTTP) and zonesvr (WS)
• @dogsvr/cl-grpc — gRPC CL for server-to-server calls