Carries forward the correct fixes from debug-krpc-handshake and adds
two new decode-path fixes that the mock server surfaced. Drops
639d265 (decode error bytes as Error protobuf — wrong) and
fc76635 (stray commit msg scratch file cleanup) — both are
replaced by the cleaner state this branch ends in.
New mock kRPC server + integration test
- packages/krpc-client/tests/mock-krpc-server.ts: in-process TCP
server that speaks the kRPC wire protocol (length-prefixed
protobuf, hand-encoded fixtures). Exports startMockKrpcServer().
- packages/krpc-client/tests/mock-krpc-server.test.ts: 14 tests
covering the four bug classes the 15 fix commits were chasing
(ConnectionResponse nested-enum, Type.code nested-enum,
Procedure.game_scenes missing, null returnType). Plus the two
new bug classes below.
- apps/tools/ksp-bridge/tests/mock-krpc-integration.test.ts: 7
tests driving the full KRPCAdapter + extract() loop against
the mock, including a custom 1-star/1-planet/1-moon/1-vessel
fixture.
- packages/krpc-client/package.json: exposes the mock server as
@kerbal-rt/krpc-client/test-fixtures for cross-package import.
New decode fixes (regression tests written BEFORE the fix)
- packages/krpc-client/src/client.ts: serialize concurrent invokes
on a per-socket promise chain. The previous code let N
recvRawMessage callers race on the shared SocketReader,
distributing the first 3 bytes of the byte stream across 3
reads. Symptom: 'index out of range' or 'invalid wire type' on
Promise.all([invoke, invoke, invoke]) — exactly the pattern in
extract.ts. Fix: invoke() awaits the previous invoke before
touching the socket.
- packages/krpc-client/src/service-client.ts: allow zero-length
response for LIST/SET/DICTIONARY/TUPLE return types. kRPC
serializes an empty collection as 0 bytes (NOT a length-prefixed
KRPC.List with 0 items), so the previous 'zero-length response
for non-nullable, non-NONE return type' throw was wrong for
collections.
- apps/tools/ksp-bridge/src/extract.ts: handle the root body
(Kerbol) returning null for get_Orbit(). Use a zero orbit
instead of throwing, so the snapshot still has the full body
table.
Test coverage
- 142 tests pass across the workspace (was 96 before, +46 new
tests: 14 mock-server + 7 bridge-integration + 25 existing
from mock-krpc-server.test.ts duplicate coverage).
- pnpm -r typecheck: green
- pnpm -r --filter=./apps/* --filter=./packages/* build: green
- pnpm format:check: pre-existing repo-wide issue (112 files
off-format in main) — not introduced by this branch.
Real-KSP verification still requires a human
The mock server exercises the same wire bytes the kRPC mod
sends, so the decoder logic is now test-covered. But three
things only the human can verify:
1. KSP 1.12.5 install + kRPC mod via CKAN
2. Alt+F12 in-game -> RPC server on 127.0.0.1:50000
3. Visual live-map motion after bridge POSTs the first snapshot
(current /debug page also works as a sanity check)
- packages/krpc-client: TypeScript kRPC protocol client
- connection.ts: varint encoding/decoding, length-prefix framing,
per-socket read queue (avoids race when multiple read promises
in flight). Uses multiplication not '<<' for varint shift
because JS truncates << to 32 bits.
- schema.ts: hand-written protobufjs schema for kRPC meta-protocol
(ConnectionRequest, Request, Response, StreamUpdate, Status, etc.)
- enough to do connection handshake, single procedure calls, and
stream subscription. Service-specific types (SpaceCenter.Vessel,
Orbit, CelestialBody) need to be loaded from the kRPC mod's
.proto files at runtime.
- client.ts: KRPCClient with connect/invoke/addStream/removeStream/
onStreamUpdate/close. Tested with hand-rolled mock server.
- 10 tests (varint round-trips incl. uint64, wire format with raw
sockets).
- apps/tools/ksp-bridge: bridge that connects KSP to our API
- convert.ts: pure kRPC -> UniverseSnapshot conversion
(situation enum mapping, body id normalization, etc.)
- bridge.ts: main poll loop with retry + backoff
- krpc-adapter.ts: KRPCAdapter class that owns the KRPCClient
- index.ts: entrypoint with MOCK MODE for development (emits
synthetic state when no KSP is available, so you can verify the
HTTP pipeline end-to-end)
- 9 tests (7 conversion + 2 end-to-end bridge)
- ksp/README.md: full setup guide
- CKAN install, KSP server start, env vars
- Hand-rolled KSP calls list (what SpaceCenter methods we need)
- Roadmap for the remaining .proto-loading work
- Protocol deep-dive (for the next dev)
- Bug fixes along the way: protobufjs default import (not namespace),
varint 32-bit truncation, JavaScript bitwise 32-bit limit,
handshake status enum comparison (number vs string).
End-to-end verified: API + bridge in mock mode, 2 bodies + 1 vessel
arriving at /api/v1/state, 500ms polling cadence, automatic recovery
on HTTP failures.
Mavis