feat(service-worker): host seams for context, error mapping, config chain

Adds the extension points an embedding host needs to reuse the fetch runtime
without forking:

- FetchContextFactory / ErrorResponseMapper inner objects (defaults preserve
  current behavior): the host can build a richer per-request context
  (logger/tracer/user) and map its own error types to a Response instead of the
  fixed 500. Wired through ServiceWorkerAppOptions.fetchContextFactory /
  errorResponseMapper.
- StandaloneApp no longer clobbers a pre-set ModuleConfigUtil.configNames — a
  host sets its own module-config selection chain (deployType/serverScope) in
  the app's TeggScope bag before init(); the default only fills when unset. No
  new option, and it fixes the prior "pre-set configNames is overwritten" bug.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: gxkl

tegg/standalone/service-worker-controller/src/http/FetchEventHandler.ts

@@ -9,8 +9,9 @@ import { MCPRegisterProvider } from '../mcp/MCPRegisterProvider.ts';
 import type { FetchEvent } from '../types.ts';
 import { ResponseUtils } from '../utils/ResponseUtils.ts';
 import { FetchRouter } from './FetchRouter.ts';
+import type { ErrorResponseMapper, FetchContextFactory } from './hostSeams.ts';
 import { HTTPRegisterProvider } from './HTTPRegisterProvider.ts';
-import { ServiceWorkerFetchContext } from './ServiceWorkerFetchContext.ts';
+import type { ServiceWorkerFetchContext } from './ServiceWorkerFetchContext.ts';
 
 type RouterMiddleware = (ctx: ServiceWorkerFetchContext, next: () => Promise<void>) => Promise<void>;
 
@@ -28,6 +29,12 @@ export class FetchEventHandler extends AbstractEventHandler<FetchEvent, Response
   @Inject()
   private readonly mcpRegisterProvider: MCPRegisterProvider;
 
+  @Inject()
+  private readonly fetchContextFactory: FetchContextFactory;
+
+  @Inject()
+  private readonly errorResponseMapper: ErrorResponseMapper;
+
   #routes?: RouterMiddleware;
   #initPromise?: Promise<void>;
 
@@ -52,7 +59,7 @@ export class FetchEventHandler extends AbstractEventHandler<FetchEvent, Response
 
   async handleEvent(event: FetchEvent): Promise<Response> {
     await this.initRoutes();
-    const ctx = new ServiceWorkerFetchContext({ event });
+    const ctx = this.fetchContextFactory.create({ event });
     try {
       await this.#routes!(ctx, async () => {
         /* noop */
@@ -63,6 +70,10 @@ export class FetchEventHandler extends AbstractEventHandler<FetchEvent, Response
       }
       return await this.#guardResponseStream(this.#mergeResponseHeaders(response, ctx.responseHeaders));
     } catch (e: any) {
+      const mapped = this.errorResponseMapper.toResponse(e, ctx);
+      if (mapped) {
+        return mapped;
+      }
       console.error('[service-worker] handle fetch event failed:', e);
       return ResponseUtils.createErrorResponse(500, 'INTERNAL_SERVER_ERROR', e?.message ?? 'internal error');
     }

tegg/standalone/service-worker-controller/src/http/hostSeams.ts

@@ -0,0 +1,34 @@
+import type { FetchEvent, ServiceWorkerContextInit } from '../types.ts';
+import { ServiceWorkerFetchContext } from './ServiceWorkerFetchContext.ts';
+
+/**
+ * Host seam for creating the per-request fetch context. A host that needs a
+ * richer context (logger/tracer/user, extra container lookups) provides its own
+ * factory as the `fetchContextFactory` inner object; the default builds the
+ * plain {@link ServiceWorkerFetchContext}.
+ */
+export interface FetchContextFactory {
+  create(init: ServiceWorkerContextInit<FetchEvent>): ServiceWorkerFetchContext;
+}
+
+export const DEFAULT_FETCH_CONTEXT_FACTORY: FetchContextFactory = {
+  create(init) {
+    return new ServiceWorkerFetchContext(init);
+  },
+};
+
+/**
+ * Host seam for turning an unhandled controller error into a Response. Return
+ * `undefined` to fall back to the framework's unified `{ code, message }` 500.
+ * A host maps its own error types (business status/body) here as the
+ * `errorResponseMapper` inner object.
+ */
+export interface ErrorResponseMapper {
+  toResponse(error: unknown, ctx: ServiceWorkerFetchContext): Response | undefined;
+}
+
+export const DEFAULT_ERROR_RESPONSE_MAPPER: ErrorResponseMapper = {
+  toResponse() {
+    return undefined;
+  },
+};

tegg/standalone/service-worker-controller/src/index.ts

@@ -2,6 +2,7 @@ export * from './controller/ServiceWorkerContext.ts';
 export * from './event/FetchEventImpl.ts';
 export * from './http/FetchEventHandler.ts';
 export * from './http/FetchHTTPMethodRegister.ts';
+export * from './http/hostSeams.ts';
 export * from './http/FetchRouter.ts';
 export * from './http/HTTPRegisterProvider.ts';
 export * from './http/ServiceWorkerFetchContext.ts';

tegg/standalone/service-worker/src/ServiceWorkerApp.ts

@@ -4,7 +4,15 @@ import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { fileURLToPath } from 'node:url';
 
-import { FetchEventImpl, type MCPAuthHandler, type MCPTransportOptions } from '@eggjs/service-worker-controller';
+import {
+  DEFAULT_ERROR_RESPONSE_MAPPER,
+  DEFAULT_FETCH_CONTEXT_FACTORY,
+  FetchEventImpl,
+  type ErrorResponseMapper,
+  type FetchContextFactory,
+  type MCPAuthHandler,
+  type MCPTransportOptions,
+} from '@eggjs/service-worker-controller';
 import { ContextProtoProperty } from '@eggjs/service-worker-runtime';
 import {
   StandaloneApp,
@@ -20,6 +28,10 @@ export interface ServiceWorkerAppOptions extends StandaloneAppOptions {
   mcpAuthHandler?: MCPAuthHandler;
   /** DNS-rebinding protection for the MCP transport (Host/Origin allow-lists). */
   mcp?: MCPTransportOptions;
+  /** Override the per-request fetch context factory (e.g. to add logger/tracer/user). */
+  fetchContextFactory?: FetchContextFactory;
+  /** Map unhandled controller errors to a Response; return undefined for the default 500. */
+  errorResponseMapper?: ErrorResponseMapper;
 }
 
 const PASS_THROUGH_MCP_AUTH_HANDLER: MCPAuthHandler = {
@@ -45,7 +57,8 @@ export class ServiceWorkerApp {
   #initialized = false;
 
   constructor(cwd: string, options?: ServiceWorkerAppOptions) {
-    const { config, mcpAuthHandler, mcp, ...standaloneOptions } = options ?? {};
+    const { config, mcpAuthHandler, mcp, fetchContextFactory, errorResponseMapper, ...standaloneOptions } =
+      options ?? {};
     // Scan this package's own root so its framework-module deps
     // (service-worker-runtime + -controller) are auto-discovered via the
     // node_modules eggModule convention. `!test/**` keeps their test fixtures out.
@@ -67,6 +80,8 @@ export class ServiceWorkerApp {
         config: [{ obj: config ?? {} }],
         mcpAuthHandler: [{ obj: mcpAuthHandler ?? PASS_THROUGH_MCP_AUTH_HANDLER }],
         mcpTransportOptions: [{ obj: mcp ?? {} }],
+        fetchContextFactory: [{ obj: fetchContextFactory ?? DEFAULT_FETCH_CONTEXT_FACTORY }],
+        errorResponseMapper: [{ obj: errorResponseMapper ?? DEFAULT_ERROR_RESPONSE_MAPPER }],
         ...standaloneOptions.innerObjectHandlers,
       },
     });

tegg/standalone/service-worker/test/ServiceWorkerApp.test.ts

@@ -3,12 +3,16 @@ import type http from 'node:http';
 import type { AddressInfo } from 'node:net';
 import path from 'node:path';
 
-import { FetchEventImpl } from '@eggjs/service-worker-controller';
+import { FetchEventImpl, ServiceWorkerFetchContext } from '@eggjs/service-worker-controller';
+import { ModuleConfigUtil } from '@eggjs/tegg-common-util';
+import { TeggScope } from '@eggjs/tegg-types';
 import { afterAll, beforeAll, describe, it } from 'vitest';
 
 import { ServiceWorkerApp } from '../src/index.ts';
 import { backgroundFlags } from './fixtures/hello-app/HelloController.ts';
 
+const HELLO_APP = path.join(__dirname, 'fixtures/hello-app');
+
 describe('standalone/service-worker/test/ServiceWorkerApp.test.ts', () => {
   let app: ServiceWorkerApp;
   let server: http.Server;
@@ -176,3 +180,63 @@ describe('standalone/service-worker/test/ServiceWorkerApp.test.ts', () => {
     assert.deepEqual(await response.json(), { message: 'hello, tegg' });
   });
 });
+
+describe('standalone/service-worker/test/ServiceWorkerApp.test.ts host seams', () => {
+  it('should map controller errors through a custom errorResponseMapper', async () => {
+    const app = new ServiceWorkerApp(HELLO_APP, {
+      errorResponseMapper: {
+        toResponse(error) {
+          return new Response(JSON.stringify({ mapped: (error as Error).message }), {
+            status: 418,
+            headers: { 'content-type': 'application/json' },
+          });
+        },
+      },
+    });
+    const server = await app.serve();
+    const { address, port } = server.address() as AddressInfo;
+    try {
+      const res = await fetch(`http://${address}:${port}/stream/boom`);
+      assert.equal(res.status, 418);
+      assert.deepEqual(await res.json(), { mapped: 'stream controller boom' });
+    } finally {
+      await app.destroy();
+    }
+  });
+
+  it('should build the request context through a custom fetchContextFactory', async () => {
+    const seen: string[] = [];
+    const app = new ServiceWorkerApp(HELLO_APP, {
+      fetchContextFactory: {
+        create(init) {
+          seen.push(new URL(init.event.request.url).pathname);
+          return new ServiceWorkerFetchContext(init);
+        },
+      },
+    });
+    const server = await app.serve();
+    const { address, port } = server.address() as AddressInfo;
+    try {
+      await fetch(`http://${address}:${port}/hello/`);
+      assert.deepEqual(seen, ['/hello/']);
+    } finally {
+      await app.destroy();
+    }
+  });
+
+  it('should not clobber a pre-set ModuleConfigUtil.configNames', async () => {
+    const app = new ServiceWorkerApp(HELLO_APP);
+    // Host selection chain set in the app's scope bag before init must survive.
+    TeggScope.run(app.app.scopeBag, () => {
+      ModuleConfigUtil.configNames = ['module.default', 'module.beta'];
+    });
+    const server = await app.serve();
+    const { address, port } = server.address() as AddressInfo;
+    try {
+      const res = await fetch(`http://${address}:${port}/hello/module-config`);
+      assert.deepEqual(await res.json(), { features: { greeting: 'beta-hi' } });
+    } finally {
+      await app.destroy();
+    }
+  });
+});

tegg/standalone/service-worker/test/fixtures/hello-app/module.beta.yml

@@ -0,0 +1,2 @@
+features:
+  greeting: 'beta-hi'

tegg/standalone/standalone/src/StandaloneApp.ts

@@ -151,9 +151,14 @@ export class StandaloneApp {
     this.#runtimeConfig.env = opts.env ?? '';
     this.#runtimeConfig.baseDir = opts.baseDir;
 
-    // Load module.yml and module.env.yml by default. The override is scoped to
-    // this app's TeggScope bag.
-    ModuleConfigUtil.configNames = opts.env ? ['module.default', `module.${opts.env}`] : ['module.default'];
+    // Load module.default.yml and module.${env}.yml by default. A host that
+    // needs a custom selection chain (deployType/serverScope/...) sets
+    // `ModuleConfigUtil.configNames` inside this app's TeggScope bag before
+    // init(); only fill the default when nothing was pre-set, so that override
+    // is not clobbered.
+    if (ModuleConfigUtil.configNames === undefined) {
+      ModuleConfigUtil.configNames = opts.env ? ['module.default', `module.${opts.env}`] : ['module.default'];
+    }
   }
 
   /** Load every module's config and expose it as a qualified `moduleConfig` inner object. */