@supacloud/elysia 0.22.0 → 0.23.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Elysia, type AnyElysia, type Context, type StatusMap } from "elysia";
 import type { CommandRuntimeAudit, CommandRuntimeAuthorizer, CommandRuntimeGovernance, CommandRuntimeInvocation, CommandRuntimeMiddleware } from "@supacloud/app";
+import { PendingWorkRegistry } from "@supacloud/app/runtime";
 import { type CommandPreview } from "@supacloud/contracts";
 import { type HttpPolicyRegistry } from "./http-policy";
 export { HttpPolicyConfigurationError } from "./http-policy";
@@ -247,7 +248,7 @@ export type ApplicationHttpContext<Http extends AnyElysia = Elysia> = Omit<Conte
     store: Http["~Singleton"]["store"];
     derive: Http["~Singleton"]["derive"] & Http["~Ephemeral"]["derive"];
 }>, "body" | "params" | "query" | "headers" | "cookie"> & Pick<HttpContext, "body" | "params" | "query" | "headers" | "cookie">;
-export type HttpRequestContextFactory<Http extends AnyElysia = Elysia, Value = unknown> = (request: Request, context: ApplicationHttpContext<Http>) => Value | Promise<Value>;
+export type HttpRequestContextFactory<Http extends AnyElysia = Elysia, Value = unknown> = (request: Request, context: ApplicationHttpContext<Http>, signal?: AbortSignal) => Value | Promise<Value>;
 export interface ApplicationOptions<Http extends AnyElysia = Elysia, RequestContext = unknown> {
     name?: string;
     /** false rejects extra schema properties instead of silently removing them. */
@@ -272,6 +273,11 @@ export interface ApplicationOptions<Http extends AnyElysia = Elysia, RequestCont
     onExecution?: ExecutionObserver;
     /** Optional read-only OpenAPI and GraphQL documentation endpoints. */
     documentation?: ApplicationDocumentationOptions;
+    /** Bounded lifecycle work accounting; registries remain owned by each host. */
+    pendingWork?: {
+        capacity?: number;
+        shutdownTimeoutMs?: number;
+    };
 }
 /** Lifecycle controls exposed by createApplication for explicit host startup/shutdown. */
 export interface ApplicationLifecycle {
@@ -279,6 +285,11 @@ export interface ApplicationLifecycle {
     readonly destroyed: boolean;
     initialize(): Promise<void>;
     destroy(): Promise<void>;
+    readonly pendingWork: PendingWorkRegistry;
+    waitForIdle(options?: {
+        timeoutMs?: number;
+        includeBackground?: boolean;
+    }): Promise<void>;
 }
 export interface JobInvocation {
     job: CompiledJob;
@@ -349,7 +360,7 @@ interface HttpContext {
  * and passed to the controller input as `scope`. Request-scoped controllers
  * are looked up on that scope, everything else on `services`.
  */
-export declare function createModulePlugin<const Services extends Record<string, unknown>, const Http extends AnyElysia = Elysia>(compiled: CompiledModule, services: Services, ctxFactory?: HttpRequestContextFactory<Http>, options?: Pick<ApplicationOptions<Http>, "http" | "httpPolicies" | "commandGovernance" | "commandExecutor" | "errorMapper" | "onExecution" | "normalize">, imported?: Record<string, Record<string, unknown>>): import("elysia/types").LocalHookReturn<"", "local", {
+export declare function createModulePlugin<const Services extends Record<string, unknown>, const Http extends AnyElysia = Elysia>(compiled: CompiledModule, services: Services, ctxFactory?: HttpRequestContextFactory<Http>, options?: Pick<ApplicationOptions<Http>, "http" | "httpPolicies" | "commandGovernance" | "commandExecutor" | "errorMapper" | "onExecution" | "normalize">, imported?: Record<string, Record<string, unknown>>, pendingWork?: PendingWorkRegistry): import("elysia/types").LocalHookReturn<"", "local", {
     decorator: {} & Http["~Singleton"]["decorator"];
     store: ({} & Http["~Singleton"]["store"] extends infer T_1 ? { [K_1 in keyof T_1]: T_1[K_1]; } : never) extends infer T ? { [K in keyof T]: T[K]; } : never;
     derive: {} & Http["~Singleton"]["derive"];

package/dist/index.js

@@ -1,5 +1,6 @@
 // src/index.ts
 import { Elysia as Elysia3, setupTypebox, Validator as Validator2 } from "elysia";
+import { PendingWorkRegistry as PendingWorkRegistry2, PendingWorkTimeoutError } from "@supacloud/app/runtime";
 import { decodeCommandPreview } from "@supacloud/contracts";
 
 // src/command-errors.ts
@@ -1426,6 +1427,7 @@ function cloneValue(value) {
   return structuredClone(value);
 }
 // src/worker.ts
+import { PendingWorkRegistry } from "@supacloud/app/runtime";
 function workerFailureMessage(error) {
   const message = error instanceof Error ? error.message : typeof error === "string" ? error : "Worker job failed";
   const normalized = message.replace(/[\u0000-\u001f\u007f]/g, " ").trim();
@@ -1558,6 +1560,11 @@ class SupaCloudWorker {
   workerId;
   concurrency;
   pollIntervalMs;
+  shutdownTimeoutMs;
+  work = new PendingWorkRegistry;
+  get pendingWork() {
+    return this.work;
+  }
   executor;
   observer;
   onError;
@@ -1588,6 +1595,7 @@ class SupaCloudWorker {
     }));
     this.concurrency = this.capturePositiveInteger(options.concurrency, 1, 1000, "concurrency");
     this.pollIntervalMs = this.captureNonNegativeInteger(options.pollIntervalMs, 1000, 300000, "pollIntervalMs");
+    this.shutdownTimeoutMs = this.captureNonNegativeInteger(options.shutdownTimeoutMs, 5000, 2147483647, "shutdownTimeoutMs");
     this.executor = options.executor;
     this.observer = options.onExecution;
     this.onError = options.onError;
@@ -1640,11 +1648,13 @@ class SupaCloudWorker {
       return;
     if (this.stateValue === "starting" && this.startPromise)
       return this.startPromise;
-    if (this.stateValue === "stopping" && this.stopPromise)
-      await this.stopPromise;
+    if (this.stateValue === "stopping")
+      await this.stop();
     this.stopRequested = false;
+    if (this.work.closed)
+      this.work = new PendingWorkRegistry;
     this.stateValue = "starting";
-    const startPromise = Promise.resolve().then(() => this.initialize()).then(async () => {
+    const startPromise = this.work.run({ name: "worker.startup", kind: "startup" }, () => Promise.resolve().then(() => this.initialize())).then(async () => {
       if (this.stopRequested || this.stateValue !== "starting") {
         await this.releaseServices();
         return;
@@ -1667,9 +1677,12 @@ class SupaCloudWorker {
       return this.stopPromise;
     this.stopRequested = true;
     this.stateValue = "stopping";
-    this.claimController?.abort(new DOMException("Worker stopped", "AbortError"));
+    this.work.close();
     const startPromise = this.startPromise;
-    this.stopPromise = (async () => {
+    this.stopPromise = Promise.resolve().then(async () => {
+      this.claimController?.abort(new DOMException("Worker stopped", "AbortError"));
+      this.work.dispose();
+      await this.work.waitForIdle({ timeoutMs: this.shutdownTimeoutMs });
       await startPromise?.catch(() => {
         return;
       });
@@ -1681,7 +1694,10 @@ class SupaCloudWorker {
       this.loopPromise = undefined;
       this.startPromise = undefined;
       this.stopPromise = undefined;
-    })();
+    }).catch((error) => {
+      this.stopPromise = undefined;
+      throw error;
+    });
     return this.stopPromise;
   }
   async runOnce() {
@@ -1692,20 +1708,22 @@ class SupaCloudWorker {
     if (!controller)
       throw new WorkerRegistrationError("WORKER_NOT_STARTED", "Worker claim lifecycle is unavailable");
     controller.signal.throwIfAborted();
-    const claim = await this.transport.claim(controller.signal);
-    if (claim === null)
-      return null;
-    return this.processClaim(claim);
+    return this.work.run({ name: "worker.claim", kind: "job" }, async (signal) => {
+      const claim = await this.transport.claim(controller.signal);
+      return claim === null ? null : this.executeClaim(claim, signal);
+    });
   }
   async processClaim(rawClaim) {
+    return this.work.run({ name: "worker.job", kind: "job" }, (signal) => this.executeClaim(rawClaim, signal));
+  }
+  async executeClaim(rawClaim, signal) {
     const claim = safeClaim(this.mapClaim(rawClaim));
     const entry = this.registry.get(claim.jobName);
-    const controller = new AbortController;
     const context = Object.freeze({
       jobId: claim.id,
       jobName: claim.jobName,
       attempt: claim.attempt ?? 1,
-      signal: controller.signal
+      signal: new AbortController().signal
     });
     if (!entry) {
       const receipt = await this.failClaim(rawClaim, claim, new WorkerRegistrationError("WORKER_INVALID_JOB", `Job "${claim.jobName}" is not registered`), context);
@@ -1716,7 +1734,7 @@ class SupaCloudWorker {
       if (this.stateValue !== "running" && this.stateValue !== "stopping") {
         throw new WorkerRegistrationError("WORKER_NOT_STARTED", "Worker is not active");
       }
-      const requestContext = claim.requestContext ?? await this.requestContextFactory(claim, controller.signal);
+      const requestContext = claim.requestContext ?? await this.requestContextFactory(claim, signal);
       const moduleServices = this.moduleServices.get(entry.module.name);
       if (!moduleServices)
         throw new WorkerRegistrationError("WORKER_NOT_STARTED", "Worker services are unavailable");
@@ -1776,10 +1794,12 @@ class SupaCloudWorker {
         await Promise.race(this.inFlight).catch((error) => this.reportError(error));
         continue;
       }
+      const complete = this.work.add({ name: "worker.claim", kind: "job" });
       let claim;
       try {
         claim = await this.transport.claim(signal);
       } catch (error) {
+        complete();
         if (signal.aborted)
           break;
         await this.reportError(error);
@@ -1789,12 +1809,13 @@ class SupaCloudWorker {
         continue;
       }
       if (claim === null) {
+        complete();
         await delay(this.pollIntervalMs, signal).catch(() => {
           return;
         });
         continue;
       }
-      const execution = this.processClaim(claim).catch((error) => this.reportError(error));
+      const execution = this.executeClaim(claim, this.work.signal).catch((error) => this.reportError(error)).finally(complete);
       this.inFlight.add(execution);
       execution.finally(() => this.inFlight.delete(execution));
     }
@@ -2293,7 +2314,7 @@ function assertDeclaredResponseStatus(route, value, configuredStatus) {
     return;
   throw new ApplicationError("Response validation failed", { status: 500, code: "RESPONSE_CONTRACT_UNDECLARED" });
 }
-function createModulePlugin(compiled, services, ctxFactory = defaultRequestContext, options = {}, imported = {}) {
+function createModulePlugin(compiled, services, ctxFactory = defaultRequestContext, options = {}, imported = {}, pendingWork) {
   const supportedMethods = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
   const supportedFields = new Set([
     "method",
@@ -2352,29 +2373,35 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
     }
   }
   const requestContexts = new WeakMap;
+  const requestCompletions = new WeakMap;
   const governanceExecutor = options.commandGovernance ? createCommandExecutor(options.commandGovernance, options.onExecution) : undefined;
   const commandExecutor = options.commandExecutor && governanceExecutor ? composeCommandExecutors(options.commandExecutor, governanceExecutor) : options.commandExecutor ?? governanceExecutor;
   const plugin = mountHttp(options.http, `supacloud:${compiled.name}`, options.normalize ?? true).derive(async (context) => {
-    const requestContext = await ctxFactory(context.request, context);
+    if (pendingWork?.closed)
+      throw new ApplicationError("Application is stopping", { status: 503, code: "APPLICATION_STOPPING" });
+    const complete = pendingWork?.add({ name: "http.request", kind: "request" });
+    if (complete)
+      requestCompletions.set(context.request, complete);
+    const signal = pendingWork ? AbortSignal.any([context.request.signal, pendingWork.signal]) : context.request.signal;
+    const requestContext = await ctxFactory(context.request, context, signal);
     requestContexts.set(context.request, requestContext);
     return { services, requestContext };
   });
   const createRequestScope = compiled.createRequestScope;
   const requestScopes = new WeakMap;
-  if (compiled.destroyRequestScope) {
-    const destroyRequestScope = compiled.destroyRequestScope;
-    plugin.afterResponse(async ({ request }) => {
-      const scope = requestScopes.get(request);
-      if (!scope)
-        return;
-      requestScopes.delete(request);
-      try {
-        await destroyRequestScope(scope);
-      } catch (error) {
-        console.error(`supacloud: request scope cleanup failed for "${compiled.name}"`, error);
-      }
-    });
-  }
+  plugin.afterResponse(async ({ request }) => {
+    const scope = requestScopes.get(request);
+    requestScopes.delete(request);
+    try {
+      if (scope)
+        await compiled.destroyRequestScope?.(scope);
+    } catch (error) {
+      console.error(`supacloud: request scope cleanup failed for "${compiled.name}"`, error);
+    } finally {
+      requestCompletions.get(request)?.();
+      requestCompletions.delete(request);
+    }
+  });
   plugin.error(async ({ error, request }) => {
     const code = error instanceof Error && "code" in error && typeof error.code === "string" ? error.code.toUpperCase().replaceAll("-", "_") : "UNKNOWN";
     const context = {
@@ -2682,16 +2709,17 @@ function isPublicApplicationError(error) {
   return error.expose === true && typeof error.status === "number" && Number.isInteger(error.status) && error.status >= 400 && error.status <= 599 && typeof error.code === "string" && error.code.length > 0;
 }
 function createApplication(options) {
+  const pendingWork = new PendingWorkRegistry2(options.pendingWork ? { capacity: options.pendingWork.capacity } : {});
   const app = new Elysia3({ name: options.name ?? "supacloud:app", normalize: options.normalize ?? true }).use(contextPlugin(options.http).as("global"));
   if (options.documentation)
     app.use(createDocumentationPlugin(options.documentation));
   const configuredContextFactory = options.requestContext ?? defaultRequestContext;
   const contextCache = new WeakMap;
-  const ctxFactory = (request, context) => {
+  const ctxFactory = (request, context, signal) => {
     const cached = contextCache.get(request);
     if (cached)
       return cached;
-    const pending = Promise.resolve(configuredContextFactory(request, context));
+    const pending = Promise.resolve().then(() => configuredContextFactory(request, context, signal));
     contextCache.set(request, pending);
     return pending;
   };
@@ -2701,7 +2729,7 @@ function createApplication(options) {
     const services = module.createServices(options.deps ?? {}, imported);
     imported[module.name] = services;
     moduleServices.push({ module, services });
-    app.use(createModulePlugin(module, services, ctxFactory, { ...options, http: undefined }, imported));
+    app.use(createModulePlugin(module, services, ctxFactory, { ...options, http: undefined }, imported, pendingWork));
   }
   let initialized = false;
   let destroyed = false;
@@ -2714,34 +2742,47 @@ function createApplication(options) {
     get destroyed() {
       return destroyed;
     },
+    pendingWork,
+    waitForIdle(options) {
+      return pendingWork.waitForIdle(options);
+    },
     initialize() {
       if (destroyed)
         return Promise.reject(new Error("Application has already been destroyed"));
       if (initializationPromise)
         return initializationPromise;
-      initializationPromise = (async () => {
+      const startup = pendingWork.run({ name: "application.startup", kind: "startup" }, () => Promise.resolve().then(async () => {
+        for (const { module, services } of moduleServices) {
+          await module.initializeServices?.(services);
+        }
+        initialized = !destroyed;
+      })).catch(async (error) => {
         try {
-          for (const { module, services } of moduleServices) {
-            await module.initializeServices?.(services);
-          }
-          initialized = true;
-        } catch (error) {
-          try {
-            await lifecycle.destroy();
-          } catch (cleanupError) {
-            throw new AggregateError([error, cleanupError], "Application initialization failed and cleanup failed");
-          }
-          throw error;
+          await lifecycle.destroy();
+        } catch (cleanupError) {
+          throw new AggregateError([error, cleanupError], "Application initialization failed and cleanup failed");
         }
-      })();
-      return initializationPromise;
+        throw error;
+      });
+      initializationPromise = startup;
+      return startup;
     },
     destroy() {
       if (destructionPromise)
         return destructionPromise;
       destroyed = true;
-      destructionPromise = (async () => {
+      pendingWork.close();
+      destructionPromise = Promise.resolve().then(async () => {
+        pendingWork.dispose();
         const errors = [];
+        try {
+          await pendingWork.waitForIdle({ timeoutMs: options.pendingWork?.shutdownTimeoutMs ?? 5000 });
+        } catch (error) {
+          if (error instanceof PendingWorkTimeoutError)
+            destructionPromise = undefined;
+          throw error;
+        }
+        pendingWork.dispose();
         for (const { module, services } of [...moduleServices].reverse()) {
           try {
             await module.destroyServices?.(services);
@@ -2752,13 +2793,15 @@ function createApplication(options) {
         if (errors.length > 0) {
           throw new AggregateError(errors, "Application destruction failed");
         }
-      })();
+      });
       return destructionPromise;
     }
   };
   Object.defineProperties(app, {
     initialized: { enumerable: true, configurable: false, get: () => lifecycle.initialized },
     destroyed: { enumerable: true, configurable: false, get: () => lifecycle.destroyed },
+    pendingWork: { enumerable: true, configurable: false, value: pendingWork },
+    waitForIdle: { enumerable: true, configurable: false, value: lifecycle.waitForIdle },
     initialize: { enumerable: true, configurable: false, value: lifecycle.initialize },
     destroy: { enumerable: true, configurable: false, value: lifecycle.destroy }
   });

package/dist/worker.d.ts

@@ -1,3 +1,4 @@
+import { PendingWorkRegistry } from "@supacloud/app/runtime";
 import { type CompiledJob, type CompiledModule, type ExecutionObserver, type JobExecutor } from "./index";
 export type WorkerState = "idle" | "starting" | "running" | "stopping" | "stopped";
 /** The transport-specific claim is mapped to this small execution contract. */
@@ -76,6 +77,8 @@ export interface WorkerOptions<TClaim = WorkerClaim, TReceipt = unknown> {
     workerId?: string;
     concurrency?: number;
     pollIntervalMs?: number;
+    /** Maximum drain observation; timeout keeps services owned until a later stop succeeds. */
+    shutdownTimeoutMs?: number;
     executor?: JobExecutor;
     onExecution?: ExecutionObserver;
     onError?: (error: unknown) => void | Promise<void>;
@@ -111,6 +114,9 @@ export declare class SupaCloudWorker<TClaim = WorkerClaim, TReceipt = unknown> {
     private readonly workerId;
     private readonly concurrency;
     private readonly pollIntervalMs;
+    private readonly shutdownTimeoutMs;
+    private work;
+    get pendingWork(): PendingWorkRegistry;
     private readonly executor;
     private readonly observer;
     private readonly onError;
@@ -139,6 +145,7 @@ export declare class SupaCloudWorker<TClaim = WorkerClaim, TReceipt = unknown> {
     runOnce(): Promise<WorkerRunResult<TReceipt> | null>;
     /** Process a host-provided claim without performing another claim operation. */
     processClaim(rawClaim: TClaim): Promise<WorkerRunResult<TReceipt>>;
+    private executeClaim;
     private failClaim;
     private initialize;
     private releaseServices;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/elysia",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Elysia runtime adapter for SupaCloud compiled modules: application/request scopes, route registration and validation",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,22 +49,22 @@
     "directory": "packages/elysia"
   },
   "dependencies": {
-    "@supacloud/app": "0.20.0",
-    "@supacloud/contracts": "0.7.0",
+    "@supacloud/app": "0.21.0",
+    "@supacloud/contracts": "0.8.0",
     "exact-mirror": "1.2.6",
     "jose": "^6.2.11",
     "typebox": "1.3.34"
   },
   "overrides": {
     "@supacloud/delivery": "0.4.0",
-    "@supacloud/contracts": "0.7.0",
+    "@supacloud/contracts": "0.8.0",
     "@supacloud/commands": "0.9.0"
   },
   "peerDependencies": {
     "elysia": "2.0.0-beta.19"
   },
   "devDependencies": {
-    "@supacloud/compiler": "0.29.0",
+    "@supacloud/compiler": "0.30.0",
     "@supacloud/delivery": "0.4.0",
     "@supacloud/commands": "0.9.0",
     "@supacloud/db": "0.11.0",