refactor(kernel-browser-runtime): Add simple message queue to receiveInternalConnections #718

rekmarks · 2026-01-05T21:39:04Z

Summary

Eliminates the convoluted promise-chaining pattern in kernel worker initialization where every incoming message had to traverse a promise chain, even after the server was initialized.

Changes

Updates receiveInternalConnections to accept either a direct handler function or a promise that resolves to a handler
Implements a lazy cache pattern: once the promise resolves, subsequent messages use the cached handler directly with zero promise overhead
Simplifies kernel-worker.ts to pass a handler promise instead of wrapping every message in a promise chain
Maintains backward compatibility with existing tests that pass direct handlers

Benefits

No performance penalty: Once initialized, messages are handled directly with zero promise overhead
Cleaner code: The initialization flow is more explicit
Flexible API: Supports both sync (tests) and async (production) initialization
Early listening: Still starts listening immediately to avoid missing connections

Test Plan

Existing tests pass
Type-safe implementation

🤖 Generated with Claude Code

Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com

Note

Introduces a flexible message handling API for internal comms and simplifies kernel worker initialization.

Refactors receiveInternalConnections to accept either a handler or a handlerPromise, caching the resolved handler and queuing messages until available; preserves logging, validation, and connection lifecycle
Updates kernel-worker.ts to construct a JsonRpcServer and pass its handler via handlerPromise, removing per-message promise chaining
Expands tests to cover promised handler resolution and message queuing; renames option to handler in tests and switches expectations to toHaveBeenCalledExactlyOnceWith where applicable

^{Written by Cursor Bugbot for commit adfee03. This will update automatically on new commits. Configure here.}

The kernel worker initialization was using a convoluted pattern where every incoming message had to traverse a promise chain, even after the server was initialized. This refactoring updates receiveInternalConnections to accept either a direct handler function or a promise that resolves to a handler, implements a lazy cache pattern where subsequent messages use the cached handler directly with zero promise overhead, and simplifies kernel-worker.ts to pass a handler promise instead of wrapping every message in a promise chain. The synchronous listener setup is preserved to avoid missing early connections, while eliminating the performance overhead of promise chaining on every message after initialization. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

FUDCo · 2026-01-05T22:40:05Z

packages/kernel-browser-runtime/src/internal-comms/internal-connections.ts

+  // Support both direct handler and promise-based handler
+  let handler: HandleInternalMessage | null = null;
+  let handlerReady: Promise<HandleInternalMessage>;
+
+  if (typeof handleInternalMessage === 'function') {
+    // Direct handler - use immediately
+    handler = handleInternalMessage;
+    handlerReady = Promise.resolve(handleInternalMessage);
+  } else {
+    // Promise-based handler - cache once resolved
+    handlerReady = handleInternalMessage.then((resolvedHandler) => {
+      handler = resolvedHandler;
+      return resolvedHandler;
+    });
+  }


My gut says could-be-a-promise-or-could-be-immediate is an anti-pattern.

How about mutually exclusive options via an options bag?

No description provided.

@claude replace the handleInternalMessage option with two mutually exclusive options.

Replace the union type parameter with discriminated union options: - `handler`: Direct handler function (for tests) - `handlerPromise`: Promise-based handler (for async initialization) This addresses the anti-pattern of accepting either a value or a promise of that value, making the API more explicit and easier to understand. Co-authored-by: Erik Marks <rekmarks@users.noreply.github.com>

rekmarks · 2026-01-07T22:45:00Z

@claude address the concerns you raised in your review except number 2 (which you note is actually fine)

- Add test coverage for handlerPromise with delayed resolution - Fix documentation to clarify caching behavior (not buffering) - Add explicit error handling for handlerPromise rejection - Rename handlerReady to handlerResolution for clarity Co-authored-by: Erik Marks <rekmarks@users.noreply.github.com>

packages/kernel-browser-runtime/src/internal-comms/internal-connections.ts

…-connections Remove overly complex error handling logic that differentiated between handler initialization errors and message handling errors. Replace with simple one-liner handler resolution and single catch block. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

This edge case is not expected to occur in practice. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

FUDCo

Ya shoor.

rekmarks marked this pull request as ready for review January 5, 2026 21:53

rekmarks requested a review from a team as a code owner January 5, 2026 21:53

rekmarks enabled auto-merge (squash) January 5, 2026 21:53

rekmarks changed the title ~~refactor(kernel-browser-runtime): Simplify kernel worker initialization~~ refactor(kernel-browser-runtime): Add simple message queue to receiveInternalConnections Jan 5, 2026

FUDCo reviewed Jan 5, 2026

View reviewed changes