Skip to content

strategy/server and the strategy service in trader serve (#701) - #708

Merged
rustyeddy merged 3 commits into
mainfrom
strategy-server-701
Nov 20, 2026
Merged

rustyeddy merged 3 commits into
mainfrom
strategy-server-701

Conversation

@rustyeddy

@rustyeddy rustyeddy commented Nov 20, 2026 •

Copy link
Copy Markdown
Owner

Closes #701

Part of the Strategy Protocol milestone (#690, ADR-094).

strategy/server (owner decision on #701: the package lives here). It imports only the standard library, strategy and strategy/proto; tests enforce that, and that no guest package (strategy, strategy/proto, strategy/client) imports it.

  • Listen refuses a non-loopback address; Serve refuses a non-loopback or non-TCP listener whoever opened it.
  • One connection is one run: read register within the registration timeout (10 s), strict decode, Register.Validate, the host's Admit callback (the only place account, risk and instruments are decided), issue a RunID (r-<UTC date>-<6 hex>, injectable), reply accepted or an error (rejected, version, protocol, timeout, internal) and close. Host failures during admission are internal and leak no detail.
  • Session.Exchange: stamps the header, sends one bars, reads one orders within the reply timeout (30 s) and checks seq, run_id, in_reply_to, no orders on a warm-up frame, Orders.Validate(frameAt) and that every instrument belongs to the run. A refused batch hands over nothing. Reply timeout, malformed or oversized frames, disconnect, a worker error and context cancellation each end the run closed and are returned.
  • Finish/Fail: done or error, once; the connection closes after a short grace. A handler returning nil completes the run, an error fails it, shutdown cancels it.

trader serve (owner decision on #701: it starts the strategy service by default): on 127.0.0.1:8081; --strategy-listen host:port changes the address, off turns it off; a non-loopback address is refused (no TLS or token in v1) and a taken port is a startup error. Until the engine is attached (#703) the admission callback refuses every registration with an explanatory rejected, so the service is observable and starts no run; nothing can reach an account or a broker through it. Docs updated (DevelopersGuide, README).

Verification

  • Real loopback TCP tests, also under -race: accepted, host grant, rejected and internal admission, validation failures never reach Admit, wrong version, non-register first message, register seq 2, malformed/duplicate/zero-length/hostile-length frames, registration timeout, half-sent register, hang-ups before registering, unique RunIDs, concurrent runs, the RunID on every message, handler outcomes, shutdown cancels runs, bad seq, wrong run_id, wrong in_reply_to, invalid and host-owned order members, unregistered instruments, a refused batch submitting nothing, warm-up frames, reply timeout, disconnect mid-run, worker error, cancellation, double Finish/Fail.
  • cmd/trader: the service announces its address, refuses a real registration with the explanation, stops cleanly with the API, can be turned off, refuses non-loopback and malformed addresses and a taken port; the default is loopback and distinct from the API's port.
  • Eleven checks in the server were each broken in turn and each break fails a test. (Breaking the flag's own loopback guard in serve.go is not caught: strategyserver.Listen refuses non-loopback addresses too, so it is a second layer.)
  • make check clean; EMAX md5 unchanged (195e457a…).

Not here: the engine bridge (#703), broker feedback (#698), the journal (#702), the Go client (#704).

🤖 Generated with Claude Code

https://claude.ai/code/session_01DzeiWMoBKxFP8WVjepv2fP

…step session (#701)

The host side of ADR-094. Server.Serve accepts loopback connections, reads a
register within a timeout, validates it, asks the host's Admit callback,
issues a RunID and replies accepted or error. A Session carries the RunID and
drives Exchange: one bars message, one orders reply, checking seq, run_id,
in_reply_to, order validity, instruments of the run and the reply timeout;
failures send the error message, close the connection and are returned. No
engine, account or broker is imported: the host supplies Admit and Handle.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01DzeiWMoBKxFP8WVjepv2fP
Copilot AI balanced review requested due to automatic review settings November 20, 2026 05:23

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@rustyeddy rustyeddy left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review of 0356df6: The package boundary, loopback-only listen/serve guards, admission callback, lock-step validation and failure-mode test coverage look aligned with ADR-094. I found three concrete items to fix before merging:

  1. strategy/server/server.go, Serve shutdown on listener failure: The deferred wg.Wait() runs before the deferred cancel() (LIFO). If ln.Accept() fails unexpectedly while any handler is active, Serve returns into wg.Wait() with its child context still live. A worker that never responds can keep shutdown stuck, potentially forever. Explicitly cancel() and close the listener before waiting for handlers on every exit path, and add a test with an injected failing listener plus an active session.
  2. RandomRunID uniqueness: three random bytes give only 24 bits of entropy; birthday collisions become plausible after a few thousand runs on one day, and there is no collision check. RunID is the durable result key, so use a sufficiently strong identifier (e.g. crypto-random 128-bit+ or the repo's existing ULID machinery) and test generator injection/uniqueness expectations. The example wire ID need not constrain actual entropy.
  3. Session.checkReplyLocked worker error messages: The *proto.Failure case immediately drops the run without checking Seq == wkSeq or RunID == s.runID. ADR-094 requires matching RunID and monotonically incremented per-direction sequence on every post-registration message, including an error. Validate those before accepting it as the worker's termination; add wrong-seq/wrong-RunID worker-error cases.

I haven't run make check independently; PR reports it passed. Please address these and I will re-review.

…701)

127.0.0.1:8081 by default; --strategy-listen host:port changes it and "off"
turns it off; a non-loopback address is refused. Until the engine is attached
(#703) the host's admission refuses every registration with an explanation, so
the service is observable and starts no run.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01DzeiWMoBKxFP8WVjepv2fP
@rustyeddy rustyeddy changed the title strategy/server: loopback listener, registration, RunID, lock-step session (#701) strategy/server and the strategy service in trader serve (#701) Nov 20, 2026

Copy link
Copy Markdown
Owner Author

Follow-up to my review (three findings already posted above): Rusty and I agreed that RunIDs should be ULIDs—time-sortable, sufficiently unique IDs without a centralized counter. Please replace RandomRunID() (r-<date>-<6 hex>, 24 random bits) with a ULID generator, retain RunID as a string on the wire, and keep the injectable NewRunID hook for deterministic tests. A monotonic ULID source is useful if strict creation order within the same millisecond matters.

The other two review findings remain: ensure cancellation precedes waiting for active handlers on unexpected Accept failure, and validate seq/run_id on worker error frames. I'll re-review after the fixes are pushed.

… errors validated (#701)

- RunIDs are monotonic ULIDs (48-bit ms + 80 random bits), replacing the
  24-bit r-<date>-<hex> form; Config.NewRunID stays injectable.
- Serve cancels the runs and closes the listener before waiting for them on
  every exit, so a silent worker cannot hold shutdown after an Accept failure.
- A worker error message must carry the expected seq and run_id like any other.
- ADR-094 and golden examples use a ULID RunID.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01DzeiWMoBKxFP8WVjepv2fP
@rustyeddy

Copy link
Copy Markdown
Owner Author

Pushed the three fixes in the latest commit: ULID RunIDs (monotonic, injectable via Config.NewRunID; ADR-094 and goldens updated), Serve cancels and closes the listener before waiting (new failing-listener test with a silent worker), worker error frames checked for seq and run_id. Each fix was mutation-checked; make check is clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DzeiWMoBKxFP8WVjepv2fP

@rustyeddy
rustyeddy merged commit 6ce41d6 into main Nov 20, 2026
1 check passed
@rustyeddy
rustyeddy deleted the strategy-server-701 branch November 20, 2026 12:55
rustyeddy added a commit that referenced this pull request Nov 20, 2026
Reverts PRs #697, #706, #707 and #708 while preserving PR #696 engine stop amendments and ADR-093. Document historical external strategy ADR scope.
rustyeddy added a commit that referenced this pull request Nov 20, 2026
…709)

Reverts PRs #697, #706, #707 and #708 while preserving PR #696 engine stop amendments and ADR-093. Document historical external strategy ADR scope.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Strategy Protocol: Trader loopback TCP listener, registration and RunID

2 participants