Skip to content

chore: effect rpc and layer based startup#929

Draft
juliusmarminge wants to merge 28 commits intomainfrom
effect-http-router
Draft

chore: effect rpc and layer based startup#929
juliusmarminge wants to merge 28 commits intomainfrom
effect-http-router

Conversation

@juliusmarminge
Copy link
Copy Markdown
Member

@juliusmarminge juliusmarminge commented Mar 11, 2026

What Changed

Why

UI Changes

Checklist

  • This PR is small and focused
  • I explained what changed and why
  • I included before/after screenshots for any UI changes
  • I included a video for animation/interaction changes

Note

Medium Risk
Refactors core server startup and WebSocket request handling to a new Effect RpcServer/HttpRouter composition, so regressions could break connectivity or endpoint behavior. Adds new path/attachment handling and command normalization that touches filesystem writes and validation logic.

Overview
Migrates the server’s WebSocket request/response handling from the legacy wsServer.ts switch/envelope path to Effect RPC routes in apps/server/src/ws.ts, wiring many existing WS_METHODS/orchestration procedures into a shared WsRpcGroup with typed errors and a new integration-heavy server.test.ts.

Restructures startup into a layer-based CLI entrypoint (src/bin.ts + src/cli.ts) and a new server.ts that composes HTTP routes (health, static/dev redirect, attachments) plus the WebSocket RPC route, and tightens filesystem safety via resolveWorkspaceWritePath and orchestration command normalization for attachment persistence.

Also centralizes several error types by re-exporting them from @t3tools/contracts, updates package bin/start scripts accordingly, and adds a .plans/ws-rpc-endpoint-port-plan.md plus formatter ignore for .reference.

Written by Cursor Bugbot for commit e3ac9ed. This will update automatically on new commits. Configure here.

Note

Replace WebSocket request handling with Effect RPC layer and restructure server startup

  • Introduces a typed WebSocket RPC API at /ws via WsRpcLayer in ws.ts, covering orchestration, git, terminal, project file ops, keybindings, and shell open. Contracts are defined in the new wsRpc.ts.
  • Replaces the previous ServerLive service/layer pattern with ServerLayer (a Layer.effectDiscard) and adds a CLI entrypoint in bin.ts with flag/env-based config resolution in cli.ts.
  • Moves HTTP routes (health, attachments, static/dev redirect) into dedicated layers in http.ts, assembled in server.ts.
  • Adds structured error types across contracts (GitManagerServiceError, TerminalError, OrchestrationDispatchCommandError, OpenError, etc.) used as typed RPC error channels.
  • Adds a reference server implementation under .reference/server/ as a working example of the Effect RPC + WebSocket pattern.
  • Risk: WebSocket requests previously handled in-process now return a RouteRequestError; clients must migrate to the /ws RPC endpoint.
📊 Macroscope summarized eb8ee3f. 24 files reviewed, 3 issues evaluated, 1 issue filtered, 1 comment posted

🗂️ Filtered Issues

apps/web/src/wsTransport.ts — 0 comments posted, 1 evaluated, 1 filtered
  • line 140: In subscribe(), when the RPC method doesn't exist, WsTransportStreamMethodError is thrown and caught by Effect.catch(), which logs a warning, sleeps, and then Effect.forever retries the operation. Since the method still won't exist on retry, this creates an infinite retry loop with console spam. The catch handler should distinguish between retryable errors (like connection failures) and non-retryable errors (like invalid method names) and only retry the former. [ Already posted ]
>

@juliusmarminge juliusmarminge marked this pull request as draft March 11, 2026 18:53
@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Mar 11, 2026

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 71c984b2-729c-45ee-8fcb-74b0b22b07c8

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch effect-http-router

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions github-actions bot added the vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. label Mar 11, 2026
Copy link
Copy Markdown
Contributor

@cursor cursor bot left a comment

Choose a reason for hiding this comment

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

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

  • ✅ Fixed: Dev URL redirect drops request path and query
    • Fixed the redirect to construct a new URL from the request's pathname and search params against the dev origin, and updated the test to assert the correct behavior.

Create PR

Or push these changes by commenting:

@cursor push 089fb595df
Preview (089fb595df)
diff --git a/apps/server/src/http.ts b/apps/server/src/http.ts
--- a/apps/server/src/http.ts
+++ b/apps/server/src/http.ts
@@ -90,7 +90,8 @@
 
     const config = yield* ServerConfig;
     if (config.devUrl) {
-      return HttpServerResponse.redirect(config.devUrl.href, { status: 302 });
+      const devTarget = new URL(`${url.pathname}${url.search}`, config.devUrl);
+      return HttpServerResponse.redirect(devTarget.href, { status: 302 });
     }
 
     if (!config.staticDir) {

diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -266,7 +266,7 @@
       const response = yield* Effect.promise(() => fetch(url, { redirect: "manual" }));
 
       assert.equal(response.status, 302);
-      assert.equal(response.headers.get("location"), "http://127.0.0.1:5173/");
+      assert.equal(response.headers.get("location"), "http://127.0.0.1:5173/foo/bar");
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );


const config = yield* ServerConfig;
if (config.devUrl) {
return HttpServerResponse.redirect(config.devUrl.href, { status: 302 });
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.

Dev URL redirect drops request path and query

High Severity

The dev URL redirect uses config.devUrl.href without appending the incoming request's pathname or search params. Every GET request (e.g. /settings?tab=general) redirects to the dev server root (http://127.0.0.1:5173/) instead of the matching route (http://127.0.0.1:5173/settings?tab=general). The reference implementation correctly constructs new URL(url.pathname + url.search, origin). The test at line 269 asserts the broken behavior, masking the regression.

Additional Locations (1)
Fix in Cursor Fix in Web

@github-actions github-actions bot added the size:XXL 1,000+ changed lines (additions + deletions). label Mar 13, 2026
? Deferred.succeed(deferred, exit.value)
: Deferred.failCause(deferred, exit.cause);

export const makeCommandGate = Effect.gen(function* () {
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.

🟢 Low src/serverRuntimeStartup.ts:62

Once signalCommandReady sets commandReadinessState to "ready", enqueueCommand bypasses the queue and runs effects directly (line 86-87), while commands already in the queue are still being processed by commandWorker. This allows commands arriving after the state transition to execute concurrently with queued commands, breaking the sequential ordering guarantee that the queue was designed to provide.

Also found in 1 other location(s)

.reference/server/src/model-store.ts:218

Race condition in subscribe: Events published to eventsPubSub during the catchup query execution will be missed. Stream.concat(catchup, live) only subscribes to the PubSub after catchup completes. If append publishes events while catchup is querying the database, those events won't be in the catchup results (they occurred after the query started) and won't be captured by live (subscription wasn't established yet). This causes event loss for concurrent subscriptions.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:
In file apps/server/src/serverRuntimeStartup.ts around line 62:

Once `signalCommandReady` sets `commandReadinessState` to `"ready"`, `enqueueCommand` bypasses the queue and runs effects directly (line 86-87), while commands already in the queue are still being processed by `commandWorker`. This allows commands arriving after the state transition to execute concurrently with queued commands, breaking the sequential ordering guarantee that the queue was designed to provide.

Evidence trail:
apps/server/src/serverRuntimeStartup.ts lines 64-67 (commandWorker forked in separate fiber), lines 69-72 (signalCommandReady sets state to ready first, then succeeds deferred), lines 79-97 (enqueueCommand checks state and runs directly if ready at lines 82-83, or queues with Deferred.await(commandReady) at lines 90-95)

Also found in 1 other location(s):
- .reference/server/src/model-store.ts:218 -- Race condition in `subscribe`: Events published to `eventsPubSub` during the `catchup` query execution will be missed. `Stream.concat(catchup, live)` only subscribes to the PubSub after `catchup` completes. If `append` publishes events while `catchup` is querying the database, those events won't be in the catchup results (they occurred after the query started) and won't be captured by `live` (subscription wasn't established yet). This causes event loss for concurrent subscriptions.

juliusmarminge and others added 5 commits March 24, 2026 01:40
- Replace state-dir config with T3CODE_HOME/base-dir derivation
- Route attachments and provider logs through derived paths
- Lazily load Bun/Node HTTP, PTY, and platform services
Co-authored-by: codex <codex@users.noreply.github.com>
Comment on lines +148 to +158
[WS_METHODS.subscribeOrchestrationDomainEvents]: (_input) =>
Stream.unwrap(
Effect.gen(function* () {
const snapshot = yield* orchestrationEngine.getReadModel();
const fromSequenceExclusive = snapshot.snapshotSequence;
const replayEvents: Array<OrchestrationEvent> = yield* Stream.runCollect(
orchestrationEngine.readEvents(fromSequenceExclusive),
).pipe(
Effect.map((events) => Array.from(events)),
Effect.catch(() => Effect.succeed([] as Array<OrchestrationEvent>)),
);
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.

🟡 Medium src/ws.ts:148

In subscribeOrchestrationDomainEvents, when orchestrationEngine.readEvents() fails, the error is silently caught and replaced with an empty array. The state machine then initializes nextSequence = fromSequenceExclusive + 1, but since the replay failed, events with that sequence number will never arrive. Live events accumulate in pendingBySequence waiting for the missing sequence, causing the subscription to hang indefinitely and leak memory. Consider propagating the replay error instead of silently succeeding so the client receives a failure indication.

            const replayEvents: Array<OrchestrationEvent> = yield* Stream.runCollect(
              orchestrationEngine.readEvents(fromSequenceExclusive),
            ).pipe(
              Effect.map((events) => Array.from(events)),
-             Effect.catch(() => Effect.succeed([] as Array<OrchestrationEvent>)),
+             Effect.mapError(
+               (cause) =>
+                 new OrchestrationReplayEventsError({
+                   message: "Failed to replay orchestration events for subscription",
+                   cause,
+                 }),
+             ),
            );
🚀 Reply "fix it for me" or copy this AI Prompt for your agent:
In file apps/server/src/ws.ts around lines 148-158:

In `subscribeOrchestrationDomainEvents`, when `orchestrationEngine.readEvents()` fails, the error is silently caught and replaced with an empty array. The state machine then initializes `nextSequence = fromSequenceExclusive + 1`, but since the replay failed, events with that sequence number will never arrive. Live events accumulate in `pendingBySequence` waiting for the missing sequence, causing the subscription to hang indefinitely and leak memory. Consider propagating the replay error instead of silently succeeding so the client receives a failure indication.

Evidence trail:
apps/server/src/ws.ts lines 148-200 at REVIEWED_COMMIT:
- Line 157: `Effect.catch(() => Effect.succeed([] as Array<OrchestrationEvent>))` silently catches errors
- Lines 164-167: State initialization with `nextSequence: fromSequenceExclusive + 1`
- Line 160: `Stream.merge(replayStream, orchestrationEngine.streamDomainEvents)` merges replay with live
- Lines 170-198: State machine logic that buffers out-of-order events in `pendingBySequence` and only emits when `nextSequence` matches

juliusmarminge and others added 2 commits March 28, 2026 20:39
Co-authored-by: codex <codex@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:XXL 1,000+ changed lines (additions + deletions). vouch:trusted PR author is trusted by repo permissions or the VOUCHED list.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant