feat(service-worker): standalone service worker runtime

examples/helloworld-service-worker/README.md

@@ -0,0 +1,46 @@
+# helloworld-service-worker
+
+Minimal example of `@eggjs/service-worker`: a tegg module served through the
+standalone service worker runtime — HTTP controllers and MCP tools over the
+same fetch event loop, no egg application required.
+
+## Run
+
+```bash
+# from the monorepo root
+ut install --from pnpm
+node --import=@oxc-node/core/register examples/helloworld-service-worker/main.ts
+```
+
+Then:
+
+```bash
+curl 'http://127.0.0.1:7001/hello/?name=you'
+# {"message":"hello, you"}
+
+curl -X POST 'http://127.0.0.1:7001/mcp/calc/stream' \
+  -H 'accept: application/json, text/event-stream' \
+  -H 'content-type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"add","arguments":{"a":1,"b":41}}}'
+```
+
+## What's inside
+
+- `app/` — the tegg module (its `package.json` declares `eggModule.name`):
+  - `HelloController.ts` — an `@HTTPController` bound to `GET /hello/`.
+  - `CalcMCPController.ts` — an `@MCPController` exposing an `add` tool over
+    MCP stateless streamable HTTP at `/mcp/calc`.
+  - `HelloService.ts` — a `@ContextProto` service injected into both.
+- `main.ts` — boots `ServiceWorkerApp` on the module dir and serves it over
+  `node:http`. The entry lives outside `app/` so the module scan doesn't
+  execute it.
+- `fetch-event.ts` — the same app driven through the Web Service Worker fetch
+  interface (`self.addEventListener('fetch', e => e.respondWith(app.handleEvent(e)))`)
+  instead of `serve()`. Run with `npm run start:fetch-event`.
+
+## Test
+
+```bash
+# from the monorepo root
+utx vitest run examples/helloworld-service-worker --config examples/helloworld-service-worker/vitest.config.ts
+```

examples/helloworld-service-worker/app/CalcMCPController.ts

@@ -0,0 +1,27 @@
+import { Inject, MCPController, MCPTool, ToolArgsSchema } from '@eggjs/tegg';
+import { z } from 'zod';
+
+import { HelloService } from './HelloService.ts';
+
+const AddArgsSchema = {
+  a: z.number(),
+  b: z.number(),
+};
+
+@MCPController({ name: 'calc' })
+export class CalcMCPController {
+  @Inject()
+  private readonly helloService: HelloService;
+
+  @MCPTool({ description: 'add two numbers' })
+  async add(@ToolArgsSchema(AddArgsSchema) args: { a: number; b: number }) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `${this.helloService.hello('mcp')}: ${args.a + args.b}`,
+        },
+      ],
+    };
+  }
+}

examples/helloworld-service-worker/app/HelloController.ts

@@ -0,0 +1,14 @@
+import { HTTPController, HTTPMethod, HTTPMethodEnum, HTTPQuery, Inject } from '@eggjs/tegg';
+
+import { HelloService } from './HelloService.ts';
+
+@HTTPController({ path: '/hello' })
+export class HelloController {
+  @Inject()
+  private readonly helloService: HelloService;
+
+  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/' })
+  async hello(@HTTPQuery({ name: 'name' }) name: string) {
+    return { message: this.helloService.hello(name ?? 'service worker') };
+  }
+}

examples/helloworld-service-worker/app/HelloService.ts

@@ -0,0 +1,8 @@
+import { ContextProto } from '@eggjs/tegg';
+
+@ContextProto()
+export class HelloService {
+  hello(name: string): string {
+    return `hello, ${name}`;
+  }
+}

examples/helloworld-service-worker/app/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "helloworld-service-worker-app",
+  "type": "module",
+  "eggModule": {
+    "name": "helloWorldServiceWorker"
+  }
+}

examples/helloworld-service-worker/fetch-event.ts

@@ -0,0 +1,34 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { ServiceWorkerApp } from '@eggjs/service-worker';
+import { FetchEventImpl } from '@eggjs/service-worker-controller';
+
+// A ServiceWorkerApp plugs straight into the Web Service Worker fetch model:
+//   self.addEventListener('fetch', event => event.respondWith(app.handleEvent(event)));
+// Node has no ServiceWorker global, so this shims `self` to show the exact wiring,
+// then dispatches one FetchEvent through it. `app.handleEvent(event)` returns the
+// Response you hand to `event.respondWith(...)`.
+
+const app = new ServiceWorkerApp(path.join(path.dirname(fileURLToPath(import.meta.url)), 'app'));
+await app.init();
+
+let fetchListener: ((event: FetchEventImpl) => void) | undefined;
+const self = {
+  addEventListener(type: 'fetch', listener: (event: FetchEventImpl) => void) {
+    if (type === 'fetch') fetchListener = listener;
+  },
+};
+
+// Identical to the wiring inside a browser/edge Service Worker:
+self.addEventListener('fetch', (event) => {
+  event.respondWith(app.handleEvent<Response>(event));
+});
+
+// Dispatch one request the way the runtime does, then read what respondWith captured:
+const event = new FetchEventImpl(new Request('http://localhost/hello/?name=you'));
+fetchListener!(event);
+const response = await event.responsePromise!;
+console.log(response.status, await response.json()); // 200 { message: 'hello, you' }
+
+await app.destroy();

examples/helloworld-service-worker/main.ts

@@ -0,0 +1,25 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { ServiceWorkerApp } from '@eggjs/service-worker';
+
+const app = new ServiceWorkerApp(path.join(path.dirname(fileURLToPath(import.meta.url)), 'app'));
+const server = await app.serve({ port: 7001 });
+console.log('service worker listening on http://127.0.0.1:7001');
+console.log('  GET  /hello/?name=you');
+console.log('  POST /mcp/calc (MCP streamable http)');
+
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+  process.once(signal, () => {
+    console.log(`received ${signal}, shutting down`);
+    app
+      .destroy()
+      .then(() => process.exit(0))
+      .catch((e) => {
+        console.error(e);
+        process.exit(1);
+      });
+  });
+}
+
+void server;

examples/helloworld-service-worker/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "helloworld-service-worker",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Hello World example using the standalone service worker",
+  "type": "module",
+  "scripts": {
+    "start": "node --import=@oxc-node/core/register main.ts",
+    "start:fetch-event": "node --import=@oxc-node/core/register fetch-event.ts",
+    "test": "vitest run",
+    "typecheck": "tsgo --noEmit"
+  },
+  "dependencies": {
+    "@eggjs/service-worker": "workspace:*",
+    "@eggjs/service-worker-controller": "workspace:*",
+    "@eggjs/tegg": "workspace:*",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@eggjs/tsconfig": "workspace:*",
+    "@oxc-node/core": "catalog:",
+    "@types/node": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  }
+}

examples/helloworld-service-worker/test/index.test.ts

@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict';
+import type { AddressInfo } from 'node:net';
+import path from 'node:path';
+
+import { ServiceWorkerApp } from '@eggjs/service-worker';
+import { afterAll, beforeAll, describe, it } from 'vitest';
+
+describe('examples/helloworld-service-worker', () => {
+  let app: ServiceWorkerApp;
+  let base: string;
+
+  beforeAll(async () => {
+    app = new ServiceWorkerApp(path.join(__dirname, '../app'));
+    const server = await app.serve();
+    const { address, port } = server.address() as AddressInfo;
+    base = `http://${address}:${port}`;
+  });
+
+  afterAll(async () => {
+    await app.destroy();
+  });
+
+  it('should say hello over http', async () => {
+    const res = await fetch(`${base}/hello/?name=egg`);
+    assert.deepEqual(await res.json(), { message: 'hello, egg' });
+  });
+
+  it('should serve the calc MCP tool', async () => {
+    const res = await fetch(`${base}/mcp/calc/stream`, {
+      method: 'POST',
+      headers: {
+        accept: 'application/json, text/event-stream',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/call',
+        params: { name: 'add', arguments: { a: 1, b: 41 } },
+      }),
+    });
+    assert.equal(res.status, 200);
+    const text = await res.text();
+    assert.match(text, /hello, mcp: 42/);
+  });
+});

examples/helloworld-service-worker/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "@eggjs/tsconfig"
+}

examples/helloworld-service-worker/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineProject } from 'vitest/config';
+
+export default defineProject({
+  test: {
+    include: ['test/**/*.test.ts'],
+  },
+});

tegg/core/background-task/src/BackgroundTaskHelper.ts

@@ -29,7 +29,10 @@ export class BackgroundTaskHelper implements EggObjectLifecycle {
         await this.doPreDestroy();
       },
     });
-    if (this.config.backgroundTask?.timeout) {
+    // `!== undefined` (not truthy) so an explicit `timeout: 0` — documented as
+    // "wait indefinitely" and honored by the `<= 0` branch in doPreDestroy —
+    // is not silently swallowed back to the 5s default.
+    if (this.config.backgroundTask?.timeout !== undefined) {
       this.timeout = this.config.backgroundTask.timeout;
     }
   }

tegg/core/controller-runtime/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@eggjs/controller-runtime",
+  "version": "4.0.2-beta.20",
+  "description": "tegg host-agnostic controller runtime",
+  "keywords": [
+    "controller",
+    "egg",
+    "runtime",
+    "tegg",
+    "typescript"
+  ],
+  "homepage": "https://github.com/eggjs/egg/tree/next/tegg/core/controller-runtime",
+  "bugs": {
+    "url": "https://github.com/eggjs/egg/issues"
+  },
+  "license": "MIT",
+  "author": "killagu <killa123@126.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eggjs/egg.git",
+    "directory": "tegg/core/controller-runtime"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./package.json": "./package.json"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsgo --noEmit"
+  },
+  "dependencies": {
+    "@eggjs/controller-decorator": "workspace:*",
+    "@eggjs/core-decorator": "workspace:*",
+    "@eggjs/lifecycle": "workspace:*",
+    "@eggjs/metadata": "workspace:*",
+    "@eggjs/router": "workspace:*",
+    "@eggjs/tegg-common-util": "workspace:*",
+    "@eggjs/tegg-runtime": "workspace:*",
+    "@eggjs/tegg-types": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.23.0",
+    "egg-errors": "catalog:",
+    "path-to-regexp": "catalog:path-to-regexp1"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "typescript": "catalog:"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  }
+}

tegg/core/controller-runtime/src/index.ts

@@ -0,0 +1,17 @@
+// tegg host-agnostic controller runtime surface: both the egg plugin host and
+// the standalone service-worker host subclass/consume these.
+export * from './lib/ControllerLoadUnit.ts';
+export * from './lib/ControllerLoadUnitHook.ts';
+export * from './lib/ControllerLoadUnitInstance.ts';
+export * from './lib/ControllerMetadataManager.ts';
+export * from './lib/ControllerPrototypeHook.ts';
+export * from './lib/ControllerRegister.ts';
+export * from './lib/ControllerRegisterFactory.ts';
+export * from './lib/MiddlewareGraphHook.ts';
+export * from './lib/RootProtoManager.ts';
+export * from './lib/errors.ts';
+export * from './lib/impl/http/HTTPControllerRegister.ts';
+export * from './lib/impl/http/HTTPMethodRegister.ts';
+export * from './lib/impl/mcp/McpRouter.ts';
+export * from './lib/impl/mcp/MCPServerHelper.ts';
+export * from './lib/impl/mcp/MCPControllerRegister.ts';

tegg/plugin/controller/src/lib/AppLoadUnitControllerHook.ts → tegg/core/controller-runtime/src/lib/ControllerLoadUnitHook.ts

@@ -1,18 +1,17 @@
 import { CONTROLLER_META_DATA, type ControllerMetadata } from '@eggjs/controller-decorator';
+import { Inject, LoadUnitLifecycleProto } from '@eggjs/core-decorator';
 import type { LifecycleHook } from '@eggjs/lifecycle';
 import type { LoadUnit, LoadUnitLifecycleContext } from '@eggjs/metadata';
 
 import { ControllerMetadataManager } from './ControllerMetadataManager.ts';
 import { ControllerRegisterFactory } from './ControllerRegisterFactory.ts';
-import { RootProtoManager } from './RootProtoManager.ts';
 
-export class AppLoadUnitControllerHook implements LifecycleHook<LoadUnitLifecycleContext, LoadUnit> {
-  private readonly controllerRegisterFactory: ControllerRegisterFactory;
-  private readonly rootProtoManager: RootProtoManager;
+@LoadUnitLifecycleProto()
+export class ControllerLoadUnitHook implements LifecycleHook<LoadUnitLifecycleContext, LoadUnit> {
+  private readonly controllerRegisterFactory: ControllerRegisterFactory<any>;
 
-  constructor(controllerRegisterFactory: ControllerRegisterFactory, rootProtoManager: RootProtoManager) {
+  constructor(@Inject() controllerRegisterFactory: ControllerRegisterFactory<any>) {
     this.controllerRegisterFactory = controllerRegisterFactory;
-    this.rootProtoManager = rootProtoManager;
   }
 
   async postCreate(_: LoadUnitLifecycleContext, obj: LoadUnit): Promise<void> {
@@ -27,7 +26,7 @@ export class AppLoadUnitControllerHook implements LifecycleHook<LoadUnitLifecycl
         throw new Error(`not find controller implement for ${String(proto.name)} which type is ${metadata.type}`);
       }
       ControllerMetadataManager.instance.addController(metadata);
-      await register.register(this.rootProtoManager, obj);
+      await register.register(obj);
     }
   }
 }

tegg/plugin/controller/src/lib/EggControllerPrototypeHook.ts → tegg/core/controller-runtime/src/lib/ControllerPrototypeHook.ts

@@ -1,8 +1,10 @@
 import { ControllerMetaBuilderFactory, ControllerMetadataUtil } from '@eggjs/controller-decorator';
+import { EggPrototypeLifecycleProto } from '@eggjs/core-decorator';
 import type { LifecycleHook } from '@eggjs/lifecycle';
 import type { EggPrototype, EggPrototypeLifecycleContext } from '@eggjs/metadata';
 
-export class EggControllerPrototypeHook implements LifecycleHook<EggPrototypeLifecycleContext, EggPrototype> {
+@EggPrototypeLifecycleProto()
+export class ControllerPrototypeHook implements LifecycleHook<EggPrototypeLifecycleContext, EggPrototype> {
   async postCreate(ctx: EggPrototypeLifecycleContext): Promise<void> {
     const metadata = ControllerMetaBuilderFactory.build(ctx.clazz);
     if (metadata) {