@fluojs/runtime 1.0.0-beta.7 → 1.0.0-beta.9

package/README.ko.md

@@ -130,6 +130,8 @@ class UsersModule {}
 - `multi: true` provider token은 context cache에 memoize되지 않습니다. 각 `get()` 호출은 DI로 위임되어 컨테이너가 새로운 contribution 배열을 조립하며, 각 contribution 자체는 해당 provider scope에 따라 재사용됩니다.
 - `duplicateProviderPolicy`가 `warn` 또는 `ignore`일 때 context cache 적격성과 lifecycle hook 실행은 bootstrap이 선택한 effective winning provider를 기준으로 결정됩니다. stale losing provider는 cache entry나 lifecycle hook을 만들지 않습니다.
 - 애플리케이션 또는 컨텍스트 bootstrap이 런타임 리소스나 lifecycle instance 생성 이후 실패하면 fluo는 readiness를 초기화하고, 등록된 runtime cleanup callback을 실행하며, 그 시점까지 해석된 instance의 shutdown hook을 `bootstrap-failed`로 호출하고, 컨테이너를 dispose하고, cleanup 실패를 로그로 남긴 뒤 원래 bootstrap error를 다시 던집니다.
+- 연결된 microservice는 부모 `Application`이 소유하는 child입니다. `startAllMicroservices()`는 순차적으로 시작하며 이후 child 시작이 실패하면 이미 시작된 child를 `bootstrap-failed`로 rollback하고, `Application.close(signal)`은 부모 lifecycle hook, adapter 종료, container dispose보다 먼저 연결된 child를 닫습니다.
+- `FluoFactory.createMicroservice()`는 cleanup이 실패해도 원래 bootstrap/runtime 해석 오류를 보존하고 cleanup 실패는 별도로 로그로 남깁니다.
 - Bootstrap은 독립적인 singleton lifecycle provider를 병렬로 해석한 뒤 lifecycle hook은 결정적인 provider 순서대로 실행합니다.
 - 멀티파트 파싱은 누적 바디 크기가 설정된 `multipart.maxTotalSize`를 넘으면 즉시 거부되며, 런타임 어댑터는 별도 재정의가 없으면 이 한도를 `maxBodySize`와 동일하게 맞춥니다.
 - `createNodeHttpAdapter(...)`, `bootstrapNodeApplication(...)`, `runNodeApplication(...)`는 `maxBodySize`를 0 이상의 정수 바이트 수로만 받으며, 값이 잘못되면 어댑터 생성/부트스트랩 단계에서 즉시 실패합니다.
@@ -137,6 +139,7 @@ class UsersModule {}
 - 런타임 health 모듈은 bootstrap이 ready로 표시하기 전까지 `/ready`를 HTTP 503과 `starting`으로 보고하며, 애플리케이션/컨텍스트 종료가 시작되는 즉시, 종료 시도가 실패하더라도 다시 `starting`으로 내려갑니다.
 - 시그널 기반 종료 헬퍼는 bounded drain semantics를 유지하면서 timeout/실패 상황을 로그와 `process.exitCode`로 보고하지만, 최종 프로세스 종료 소유권은 주변 호스트 런타임에 남겨 둡니다.
 - 플랫폼 snapshot 생산은 런타임에 남아 있고, 그래프 보기와 Mermaid 렌더링은 CLI 및 자동화 호출자가 소비하는 Studio 소유 계약입니다.
+- 모듈 그래프 컴파일 결과 캐시는 `moduleGraphCache: true`를 통한 opt-in입니다. 캐시 항목은 root module identity, runtime provider, validation token, core metadata version, compile algorithm version으로 식별되며, 성공한 컴파일만 저장하고 호출자 mutation이 이후 bootstrap을 오염시키지 않도록 격리된 그래프 복사본을 반환합니다.
 
 ## 공개 API 개요
 

package/README.md

@@ -130,6 +130,8 @@ class UsersModule {}
 - `multi: true` provider tokens are not context-cache memoized: each `get()` call delegates to DI so the container can assemble a fresh contribution array while still reusing each contribution according to its own provider scope.
 - When `duplicateProviderPolicy` is `warn` or `ignore`, context-cache eligibility and lifecycle hook execution are based on the effective winning provider selected by bootstrap; stale losing providers do not seed cache entries or lifecycle hooks.
 - If application or context bootstrap fails after runtime resources or lifecycle instances have been created, fluo resets readiness, runs registered runtime cleanup callbacks, invokes shutdown hooks for instances resolved so far with `bootstrap-failed`, disposes the container, logs cleanup failures, and rethrows the original bootstrap error.
+- Connected microservices are owned children of their parent `Application`: `startAllMicroservices()` starts them sequentially and rolls back already-started children with `bootstrap-failed` if a later child fails, while `Application.close(signal)` closes connected children before parent lifecycle hooks, adapter shutdown, and container disposal.
+- `FluoFactory.createMicroservice()` preserves the original bootstrap/runtime-resolution error when cleanup fails and logs cleanup failures separately.
 - Bootstrap resolves independent singleton lifecycle providers concurrently, then runs lifecycle hooks in deterministic provider order.
 - Multipart parsing rejects payloads when the cumulative body size exceeds the configured `multipart.maxTotalSize`; runtime adapters default that limit to `maxBodySize` unless you override it.
 - `createNodeHttpAdapter(...)`, `bootstrapNodeApplication(...)`, and `runNodeApplication(...)` accept `maxBodySize` only as a non-negative integer byte count and fail fast during adapter creation/bootstrap when the value is invalid.
@@ -137,6 +139,7 @@ class UsersModule {}
 - Runtime health modules report `/ready` as `starting` with HTTP 503 until bootstrap marks them ready, and they return to `starting` as soon as application/context shutdown begins, including failed shutdown attempts.
 - Signal-driven shutdown helpers preserve bounded drain semantics, log timeout/failure conditions, and set `process.exitCode` when shutdown does not finish cleanly, but they leave final process termination ownership to the surrounding host runtime.
 - Platform snapshot production stays in runtime; graph viewing and Mermaid rendering are Studio-owned contracts consumed by CLI and automation callers.
+- Module graph compile-result caching is opt-in through `moduleGraphCache: true`; it keys entries by root module identity, runtime providers, validation tokens, core metadata versions, and the compile algorithm version, caches only successful compilations, and returns isolated graph copies so caller mutations cannot poison later bootstraps.
 
 ## Public API Overview
 

package/dist/bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EAEX,uBAAuB,EAGvB,2BAA2B,EAC3B,sBAAsB,EACtB,eAAe,EAGf,wBAAwB,EACxB,+BAA+B,EAC/B,yBAAyB,EAEzB,gBAAgB,EAChB,UAAU,EAKX,MAAM,YAAY,CAAC;AA2apB;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,gBAAgB,GAAG,CAAC,CAIjG;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,GAAE,sBAA2B,GAAG,eAAe,CA+B7G;AAmqBD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,WAAW,CAAC,CAqHrG;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB;;;;;;;OAOG;WACU,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,WAAW,CAAC;IAOzG;;;;;;;OAOG;WACU,wBAAwB,CACnC,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,kBAAkB,CAAC;IAoG9B;;;;;;;;OAQG;WACU,kBAAkB,CAC7B,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,uBAAuB,CAAC;CAuBpC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,oBAAc,CAAC"}
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EAEX,uBAAuB,EAGvB,2BAA2B,EAC3B,sBAAsB,EACtB,eAAe,EAGf,wBAAwB,EACxB,+BAA+B,EAC/B,yBAAyB,EAEzB,gBAAgB,EAChB,UAAU,EAKX,MAAM,YAAY,CAAC;AAubpB;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,gBAAgB,GAAG,CAAC,CAIjG;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,GAAE,sBAA2B,GAAG,eAAe,CA+B7G;AAkvBD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,WAAW,CAAC,CAsHrG;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB;;;;;;;OAOG;WACU,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,WAAW,CAAC;IAOzG;;;;;;;OAOG;WACU,wBAAwB,CACnC,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,kBAAkB,CAAC;IAqG9B;;;;;;;;OAQG;WACU,kBAAkB,CAC7B,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,uBAAuB,CAAC;CA+BpC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,oBAAc,CAAC"}

package/dist/bootstrap.js

@@ -140,6 +140,15 @@ function hasReadinessStateMethods(value) {
 function isMicroserviceRuntime(value) {
   return hasMethod(value, 'listen');
 }
+function hasMicroserviceRuntimeClose(value) {
+  return typeof value.close === 'function';
+}
+async function closeMicroserviceRuntime(runtime, signal) {
+  if (!hasMicroserviceRuntimeClose(runtime)) {
+    return;
+  }
+  await runtime.close(signal);
+}
 function resetReadinessState(modules) {
   for (const compiledModule of modules) {
     if (hasReadinessStateMethods(compiledModule.type)) {
@@ -391,12 +400,43 @@ class FluoApplication {
     if (!isMicroserviceRuntime(runtime)) {
       throw new InvariantError('Resolved microservice token does not implement listen().');
     }
-    const microservice = new FluoMicroserviceApplication(this, this.logger, runtime);
+    const microservice = new FluoMicroserviceApplication(this, this.logger, runtime, false);
     this.connectedMicroservices.push(microservice);
     return microservice;
   }
   async startAllMicroservices() {
-    await Promise.all(this.connectedMicroservices.map(async microservice => microservice.listen()));
+    const startedMicroservices = [];
+    for (const microservice of this.connectedMicroservices) {
+      try {
+        await microservice.listen();
+        startedMicroservices.push(microservice);
+      } catch (error) {
+        await this.rollbackStartedMicroservices(startedMicroservices);
+        throw error;
+      }
+    }
+  }
+  async rollbackStartedMicroservices(startedMicroservices) {
+    for (const microservice of [...startedMicroservices].reverse()) {
+      try {
+        await microservice.close('bootstrap-failed');
+      } catch (rollbackError) {
+        this.logger.error('Failed to roll back a started microservice after startup failure.', rollbackError, 'FluoApplication');
+      }
+    }
+  }
+  async closeConnectedMicroservices(signal) {
+    const errors = [];
+    for (const microservice of [...this.connectedMicroservices].reverse()) {
+      try {
+        await microservice.close(signal);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (errors.length > 0) {
+      throw createLifecycleCloseError(errors);
+    }
   }
 
   /**
@@ -438,14 +478,27 @@ class FluoApplication {
       return;
     }
     this.closingPromise = (async () => {
-      await closeRuntimeResources({
-        adapter: this.adapter,
-        container: this.container,
-        lifecycleInstances: this.lifecycleInstances,
-        modules: this.modules,
-        runtimeCleanup: this.runtimeCleanup,
-        signal
-      });
+      const errors = [];
+      try {
+        await this.closeConnectedMicroservices(signal);
+      } catch (error) {
+        errors.push(error);
+      }
+      try {
+        await closeRuntimeResources({
+          adapter: this.adapter,
+          container: this.container,
+          lifecycleInstances: this.lifecycleInstances,
+          modules: this.modules,
+          runtimeCleanup: this.runtimeCleanup,
+          signal
+        });
+      } catch (error) {
+        errors.push(error);
+      }
+      if (errors.length > 0) {
+        throw createLifecycleCloseError(errors);
+      }
       this.closed = true;
       this.applicationState = 'closed';
     })();
@@ -507,10 +560,11 @@ class FluoMicroserviceApplication {
   closed = false;
   closingPromise;
   microserviceState = 'bootstrapped';
-  constructor(context, logger, runtime) {
+  constructor(context, logger, runtime, closeContextOnClose) {
     this.context = context;
     this.logger = logger;
     this.runtime = runtime;
+    this.closeContextOnClose = closeContextOnClose;
   }
   get container() {
     return this.context.container;
@@ -559,7 +613,24 @@ class FluoMicroserviceApplication {
       return;
     }
     this.closingPromise = (async () => {
-      await this.context.close(signal);
+      if (this.closeContextOnClose) {
+        const errors = [];
+        try {
+          await closeMicroserviceRuntime(this.runtime, signal);
+        } catch (error) {
+          errors.push(error);
+        }
+        try {
+          await this.context.close(signal);
+        } catch (error) {
+          errors.push(error);
+        }
+        if (errors.length > 0) {
+          throw createLifecycleCloseError(errors);
+        }
+      } else {
+        await closeMicroserviceRuntime(this.runtime, signal);
+      }
       this.closed = true;
       this.microserviceState = 'closed';
     })();
@@ -856,6 +927,7 @@ export async function bootstrapApplication(options) {
     const bootstrapped = bootstrapModule(options.rootModule, {
       duplicateProviderPolicy: options.duplicateProviderPolicy,
       logger,
+      moduleGraphCache: options.moduleGraphCache,
       providers: runtimeProviders,
       validationTokens: [RUNTIME_CONTAINER, COMPILED_MODULES, HTTP_APPLICATION_ADAPTER]
     });
@@ -964,6 +1036,7 @@ export class FluoFactory {
       const bootstrapped = bootstrapModule(rootModule, {
         duplicateProviderPolicy: options.duplicateProviderPolicy,
         logger,
+        moduleGraphCache: options.moduleGraphCache,
         providers: runtimeProviders,
         validationTokens: [RUNTIME_CONTAINER, COMPILED_MODULES]
       });
@@ -1038,9 +1111,13 @@ export class FluoFactory {
       if (!isMicroserviceRuntime(runtime)) {
         throw new InvariantError('Resolved microservice token does not implement listen().');
       }
-      return new FluoMicroserviceApplication(context, logger, runtime);
+      return new FluoMicroserviceApplication(context, logger, runtime, true);
     } catch (error) {
-      await context.close('bootstrap-failed');
+      try {
+        await context.close('bootstrap-failed');
+      } catch (cleanupError) {
+        logger.error('Failed to clean up after microservice bootstrap failure.', cleanupError, 'FluoFactory');
+      }
       logger.error('Failed to bootstrap microservice context. Check the error below for what failed and how to fix it.', error, 'FluoFactory');
       throw error;
     }

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './abort.js';
 export * from './bootstrap.js';
-export * from './health/diagnostics.js';
+export { createBootstrapTimingDiagnostics, createRuntimeDiagnosticsGraph, } from './health/diagnostics.js';
+export type { BootstrapTimingDiagnostics, BootstrapTimingPhase, RuntimeDiagnosticsGraph, RuntimeDiagnosticsModule, RuntimeDiagnosticsProvider, RuntimeDiagnosticsRelationships, } from './health/diagnostics.js';
 export * from './errors.js';
 export * from './health/health.js';
 export type { MultipartOptions, MultipartRequestLike, MultipartResult, UploadedFile, } from './multipart.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC;AACxC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,iCAAiC,EACjC,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,EAC7B,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,EACb,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACjE,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EACL,gCAAgC,EAChC,6BAA6B,GAC9B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,0BAA0B,EAC1B,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,EAC1B,+BAA+B,GAChC,MAAM,yBAAyB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,iCAAiC,EACjC,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,EAC7B,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,EACb,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACjE,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 export * from './abort.js';
 export * from './bootstrap.js';
-export * from './health/diagnostics.js';
+export { createBootstrapTimingDiagnostics, createRuntimeDiagnosticsGraph } from './health/diagnostics.js';
 export * from './errors.js';
 export * from './health/health.js';
 export * from './request-transaction.js';

package/dist/module-graph.d.ts

@@ -8,6 +8,22 @@ import type { BootstrapModuleOptions, CompiledModule, ModuleType } from './types
  * @returns The token that should be registered and resolved for the provider.
  */
 export declare function providerToken(provider: Provider): Token;
+/** Clears the process-local module graph compile cache for isolated regression tests. */
+export declare function clearModuleGraphCompileCacheForTesting(): void;
+/**
+ * Reads the current process-local module graph compile cache size for tests.
+ *
+ * @returns Number of successful compile snapshots currently retained in the cache.
+ */
+export declare function getModuleGraphCompileCacheSizeForTesting(): number;
+/**
+ * Builds the key used for opt-in module graph compile caching.
+ *
+ * @param rootModule Root module that would be compiled.
+ * @param options Bootstrap options that influence graph validation.
+ * @returns Process-local key that changes when metadata or runtime validation inputs change.
+ */
+export declare function createModuleGraphCacheKey(rootModule: ModuleType, options?: BootstrapModuleOptions): string;
 /**
  * Collects runtime provider tokens into a set for visibility and validation checks.
  *

package/dist/module-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module-graph.d.ts","sourceRoot":"","sources":["../src/module-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAK1C,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAoB,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvG;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,KAAK,CAMvD;AAyDD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,GAAE,QAAQ,EAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAE5E;AA8UD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,GAAE,sBAA2B,GAAG,cAAc,EAAE,CASjH"}
+{"version":3,"file":"module-graph.d.ts","sourceRoot":"","sources":["../src/module-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAW1C,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAoB,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvG;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,KAAK,CAMvD;AAiBD,yFAAyF;AACzF,wBAAgB,sCAAsC,IAAI,IAAI,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,wCAAwC,IAAI,MAAM,CAEjE;AAgFD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,GAAE,sBAA2B,GAAG,MAAM,CAY9G;AAiRD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,GAAE,QAAQ,EAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAE5E;AA8UD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,GAAE,sBAA2B,GAAG,cAAc,EAAE,CA4BjH"}

package/dist/module-graph.js

@@ -1,4 +1,4 @@
-import { getClassDiMetadata, getModuleMetadata, getOwnClassDiMetadata } from '@fluojs/core/internal';
+import { getClassDiMetadata, getClassDiMetadataVersion, getModuleMetadata, getModuleMetadataVersion, getOwnClassDiMetadata } from '@fluojs/core/internal';
 import { ModuleGraphError, ModuleInjectionMetadataError, ModuleVisibilityError } from './errors.js';
 /**
  * Returns the public token represented by a provider declaration.
@@ -12,6 +12,280 @@ export function providerToken(provider) {
   }
   return provider.provide;
 }
+const objectTokenIds = new WeakMap();
+const symbolTokenIds = new Map();
+let nextTokenId = 0;
+const MODULE_GRAPH_COMPILE_ALGORITHM_VERSION = 1;
+const moduleGraphCompileCache = new Map();
+
+/** Clears the process-local module graph compile cache for isolated regression tests. */
+export function clearModuleGraphCompileCacheForTesting() {
+  moduleGraphCompileCache.clear();
+}
+
+/**
+ * Reads the current process-local module graph compile cache size for tests.
+ *
+ * @returns Number of successful compile snapshots currently retained in the cache.
+ */
+export function getModuleGraphCompileCacheSizeForTesting() {
+  return moduleGraphCompileCache.size;
+}
+function getFunctionTokenId(token) {
+  const existing = objectTokenIds.get(token);
+  if (existing !== undefined) {
+    return existing;
+  }
+  nextTokenId += 1;
+  objectTokenIds.set(token, nextTokenId);
+  return nextTokenId;
+}
+function getSymbolTokenId(token) {
+  const existing = symbolTokenIds.get(token);
+  if (existing !== undefined) {
+    return existing;
+  }
+  nextTokenId += 1;
+  symbolTokenIds.set(token, nextTokenId);
+  return nextTokenId;
+}
+function describeTokenForCacheKey(token) {
+  if (typeof token === 'function') {
+    return `fn:${getFunctionTokenId(token)}`;
+  }
+  if (typeof token === 'symbol') {
+    return `sym:${getSymbolTokenId(token)}`;
+  }
+  return `str:${JSON.stringify(token)}`;
+}
+function describeInjectionTokenForCacheKey(token) {
+  if (isForwardRef(token)) {
+    return `forward:${describeTokenForCacheKey(token.forwardRef())}`;
+  }
+  if (isOptionalToken(token)) {
+    return `optional:${describeTokenForCacheKey(token.token)}`;
+  }
+  return describeTokenForCacheKey(token);
+}
+function describeProviderForCacheKey(provider) {
+  if (typeof provider === 'function') {
+    return `class:${describeTokenForCacheKey(provider)}`;
+  }
+  const provide = describeTokenForCacheKey(provider.provide);
+  const multi = 'multi' in provider && provider.multi === true ? 'multi' : 'single';
+  if ('useClass' in provider) {
+    const inject = provider.inject?.map(describeInjectionTokenForCacheKey).join(',') ?? '';
+    return `useClass:${provide}:${describeTokenForCacheKey(provider.useClass)}:${provider.scope ?? ''}:${multi}:${inject}`;
+  }
+  if ('useFactory' in provider) {
+    const inject = provider.inject?.map(describeInjectionTokenForCacheKey).join(',') ?? '';
+    const resolverClass = provider.resolverClass ? describeTokenForCacheKey(provider.resolverClass) : '';
+    return `useFactory:${provide}:${getFunctionTokenId(provider.useFactory)}:${resolverClass}:${provider.scope ?? ''}:${multi}:${inject}`;
+  }
+  if ('useExisting' in provider) {
+    return `useExisting:${provide}:${describeTokenForCacheKey(provider.useExisting)}`;
+  }
+  return `useValue:${provide}:${multi}`;
+}
+
+/**
+ * Builds the key used for opt-in module graph compile caching.
+ *
+ * @param rootModule Root module that would be compiled.
+ * @param options Bootstrap options that influence graph validation.
+ * @returns Process-local key that changes when metadata or runtime validation inputs change.
+ */
+export function createModuleGraphCacheKey(rootModule, options = {}) {
+  const runtimeProviders = (options.providers ?? []).map(describeProviderForCacheKey).join('|');
+  const validationTokens = (options.validationTokens ?? []).map(describeTokenForCacheKey).join('|');
+  return [`root:${describeTokenForCacheKey(rootModule)}`, `module:${getModuleMetadataVersion()}`, `class-di:${getClassDiMetadataVersion()}`, `algorithm:${MODULE_GRAPH_COMPILE_ALGORITHM_VERSION}`, `runtime:${runtimeProviders}`, `validation:${validationTokens}`].join(';');
+}
+function cloneModuleDefinition(definition) {
+  return {
+    global: definition.global,
+    imports: definition.imports ? [...definition.imports] : undefined,
+    providers: definition.providers ? definition.providers.map(provider => cloneProvider(provider)) : undefined,
+    controllers: definition.controllers ? [...definition.controllers] : undefined,
+    exports: definition.exports ? [...definition.exports] : undefined,
+    middleware: definition.middleware ? definition.middleware.map(middleware => cloneMutableValue(middleware)) : undefined
+  };
+}
+function cloneMutableValue(value, clones = new WeakMap()) {
+  if (typeof value !== 'object' || value === null) {
+    return value;
+  }
+  const existing = clones.get(value);
+  if (existing !== undefined) {
+    return existing;
+  }
+  if (value instanceof Date) {
+    return new Date(value);
+  }
+  if (value instanceof RegExp) {
+    return new RegExp(value);
+  }
+  if (Array.isArray(value)) {
+    const clonedArray = [];
+    clones.set(value, clonedArray);
+    for (const item of value) {
+      clonedArray.push(cloneMutableValue(item, clones));
+    }
+    return clonedArray;
+  }
+  if (value instanceof Map) {
+    const clonedMap = new Map();
+    clones.set(value, clonedMap);
+    for (const [key, entryValue] of value) {
+      clonedMap.set(cloneMutableValue(key, clones), cloneMutableValue(entryValue, clones));
+    }
+    return clonedMap;
+  }
+  if (value instanceof Set) {
+    const clonedSet = new Set();
+    clones.set(value, clonedSet);
+    for (const entryValue of value) {
+      clonedSet.add(cloneMutableValue(entryValue, clones));
+    }
+    return clonedSet;
+  }
+  const source = value;
+  const prototype = Object.getPrototypeOf(value);
+  const clonedObject = Object.create(prototype);
+  clones.set(value, clonedObject);
+  for (const key of Reflect.ownKeys(source)) {
+    clonedObject[key] = cloneMutableValue(source[key], clones);
+  }
+  return clonedObject;
+}
+function cloneInjectionToken(token) {
+  if (isForwardRef(token)) {
+    return {
+      __forwardRef__: true,
+      forwardRef: token.forwardRef
+    };
+  }
+  if (isOptionalToken(token)) {
+    return {
+      __optional__: true,
+      token: token.token
+    };
+  }
+  return token;
+}
+function cloneProvider(provider) {
+  if (typeof provider === 'function') {
+    return provider;
+  }
+  if ('useClass' in provider) {
+    return {
+      ...provider,
+      ...(provider.inject ? {
+        inject: provider.inject.map(token => cloneInjectionToken(token))
+      } : {})
+    };
+  }
+  if ('useFactory' in provider) {
+    return {
+      ...provider,
+      ...(provider.inject ? {
+        inject: provider.inject.map(token => cloneInjectionToken(token))
+      } : {})
+    };
+  }
+  if ('useValue' in provider) {
+    return {
+      ...provider,
+      useValue: cloneMutableValue(provider.useValue)
+    };
+  }
+  return {
+    ...provider
+  };
+}
+function cloneCompiledModule(compiledModule) {
+  return {
+    type: compiledModule.type,
+    definition: cloneModuleDefinition(compiledModule.definition),
+    accessibleTokens: new Set(compiledModule.accessibleTokens),
+    exportedTokens: new Set(compiledModule.exportedTokens),
+    importedExportedTokens: new Set(compiledModule.importedExportedTokens),
+    providerTokens: new Set(compiledModule.providerTokens)
+  };
+}
+function cloneCompiledModules(modules) {
+  return modules.map(compiledModule => cloneCompiledModule(compiledModule));
+}
+function freezeInjectionToken(token) {
+  if (isForwardRef(token) || isOptionalToken(token)) {
+    Object.freeze(token);
+  }
+  return token;
+}
+function freezeMutableValue(value, frozen = new WeakSet()) {
+  if (typeof value !== 'object' || value === null || frozen.has(value)) {
+    return value;
+  }
+  frozen.add(value);
+  if (value instanceof Map) {
+    for (const [key, entryValue] of value) {
+      freezeMutableValue(key, frozen);
+      freezeMutableValue(entryValue, frozen);
+    }
+  } else if (value instanceof Set) {
+    for (const entryValue of value) {
+      freezeMutableValue(entryValue, frozen);
+    }
+  } else {
+    const source = value;
+    for (const key of Reflect.ownKeys(source)) {
+      freezeMutableValue(source[key], frozen);
+    }
+  }
+  Object.freeze(value);
+  return value;
+}
+function freezeProvider(provider) {
+  if (typeof provider === 'function') {
+    return provider;
+  }
+  if ('inject' in provider && provider.inject) {
+    for (const token of provider.inject) {
+      freezeInjectionToken(token);
+    }
+    Object.freeze(provider.inject);
+  }
+  if ('useValue' in provider) {
+    freezeMutableValue(provider.useValue);
+  }
+  return Object.freeze(provider);
+}
+function freezeMiddleware(middleware) {
+  if (typeof middleware === 'object' && middleware !== null) {
+    freezeMutableValue(middleware);
+  }
+  return middleware;
+}
+function freezeModuleDefinition(definition) {
+  definition.imports && Object.freeze(definition.imports);
+  for (const provider of definition.providers ?? []) {
+    freezeProvider(provider);
+  }
+  definition.providers && Object.freeze(definition.providers);
+  definition.controllers && Object.freeze(definition.controllers);
+  definition.exports && Object.freeze(definition.exports);
+  for (const middleware of definition.middleware ?? []) {
+    freezeMiddleware(middleware);
+  }
+  definition.middleware && Object.freeze(definition.middleware);
+  return Object.freeze(definition);
+}
+function freezeCompiledModule(compiledModule) {
+  freezeModuleDefinition(compiledModule.definition);
+  return Object.freeze(compiledModule);
+}
+function createModuleGraphCacheSnapshot(modules) {
+  return Object.freeze(cloneCompiledModules(modules).map(compiledModule => freezeCompiledModule(compiledModule)));
+}
 function getEffectiveClassDiMetadata(target) {
   const metadata = getClassDiMetadata(target);
   if (!metadata) {
@@ -249,10 +523,22 @@ function validateCompiledModules(modules, runtimeProviders, runtimeProviderToken
  * @returns Compiled modules in dependency order after visibility and injection validation succeed.
  */
 export function compileModuleGraph(rootModule, options = {}) {
+  const cacheKey = options.moduleGraphCache === true ? createModuleGraphCacheKey(rootModule, options) : undefined;
+  if (cacheKey !== undefined) {
+    const cachedModules = moduleGraphCompileCache.get(cacheKey);
+    if (cachedModules !== undefined) {
+      return cloneCompiledModules(cachedModules);
+    }
+  }
   const ordered = [];
   const runtimeProviders = options.providers ?? [];
   const runtimeProviderTokens = mergeRuntimeTokenSets(runtimeProviders, options.validationTokens ?? []);
   compileModule(rootModule, runtimeProviderTokens, new Map(), new Set(), ordered);
   validateCompiledModules(ordered, runtimeProviders, runtimeProviderTokens);
+  if (cacheKey !== undefined) {
+    const cacheSnapshot = createModuleGraphCacheSnapshot(ordered);
+    moduleGraphCompileCache.set(cacheKey, cacheSnapshot);
+    return cloneCompiledModules(cacheSnapshot);
+  }
   return ordered;
 }

package/dist/node/internal-node-request.d.ts

@@ -16,7 +16,8 @@ export interface DeferredFrameworkRequestShellOptions<RawRequest> {
     query?: QueryRecord;
     queryFactory?: () => QueryRecord;
     raw: RawRequest;
-    signal: AbortSignal;
+    requestId?: string;
+    signal: AbortSignal | (() => AbortSignal);
     url: string;
 }
 /**
@@ -55,7 +56,7 @@ export declare function createDeferredFrameworkRequest(request: IncomingMessage,
  * @param options - Raw request, metadata factories, and deferred body materialization hooks.
  * @returns A framework request with lazy headers, cookies, query values, and optional body materialization.
  */
-export declare function createDeferredFrameworkRequestShell<RawRequest>({ cookieHeader, headers, headersFactory, materializeBody, method, path, query, queryFactory, raw, signal, url, }: DeferredFrameworkRequestShellOptions<RawRequest>): FrameworkRequest;
+export declare function createDeferredFrameworkRequestShell<RawRequest>({ cookieHeader, headers, headersFactory, materializeBody, method, path, query, queryFactory, raw, requestId, signal, url, }: DeferredFrameworkRequestShellOptions<RawRequest>): FrameworkRequest;
 /**
  * Materializes a deferred Node framework request body exactly once.
  *

package/dist/node/internal-node-request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal-node-request.d.ts","sourceRoot":"","sources":["../../src/node/internal-node-request.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"internal-node-request.d.ts","sourceRoot":"","sources":["../../src/node/internal-node-request.ts"],"names":[],"mappings":"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"}

package/dist/node/internal-node-request.js

@@ -94,6 +94,7 @@ export function createDeferredFrameworkRequest(request, signal, multipartOptions
     path: urlParts.path,
     queryFactory: () => parseQueryParamsFromSearch(urlParts.search),
     raw: request,
+    requestId: resolvePrimaryRequestIdFromHeaders(headers),
     signal,
     url: urlParts.path + urlParts.search
   });
@@ -116,12 +117,15 @@ export function createDeferredFrameworkRequestShell({
   query,
   queryFactory,
   raw,
+  requestId,
   signal,
   url
 }) {
+  const hasQuerySnapshot = query !== undefined;
+  const hasLazySignal = typeof signal === 'function';
   const resolveHeaders = headersFactory ? createMemoizedValue(headersFactory) : () => headers ?? {};
   const resolveCookies = createMemoizedValue(() => parseCookieHeader(cookieHeader ?? resolveHeaders().cookie));
-  const resolveQuery = createMemoizedValue(() => query ?? queryFactory?.() ?? {});
+  const resolveQuery = hasQuerySnapshot ? undefined : createMemoizedValue(() => queryFactory?.() ?? {});
   const frameworkRequest = {
     get cookies() {
       return resolveCookies();
@@ -132,13 +136,32 @@ export function createDeferredFrameworkRequestShell({
     method: method ?? 'GET',
     params: {},
     path,
-    get query() {
-      return resolveQuery();
-    },
+    requestId,
     raw,
-    signal,
     url
   };
+  if (hasLazySignal) {
+    Object.defineProperty(frameworkRequest, 'signal', {
+      configurable: true,
+      enumerable: true,
+      get() {
+        return signal();
+      }
+    });
+  } else {
+    frameworkRequest.signal = signal;
+  }
+  if (hasQuerySnapshot) {
+    frameworkRequest.query = query;
+  } else {
+    Object.defineProperty(frameworkRequest, 'query', {
+      configurable: true,
+      enumerable: true,
+      get() {
+        return resolveQuery();
+      }
+    });
+  }
   if (materializeBody) {
     frameworkRequest.materializeBody = materializeBody;
   }
@@ -232,6 +255,10 @@ export function resolveRequestIdFromHeaders(headers) {
   const requestId = headers['x-request-id'] ?? headers['x-correlation-id'];
   return Array.isArray(requestId) ? requestId[0] : requestId;
 }
+function resolvePrimaryRequestIdFromHeaders(headers) {
+  const requestId = headers['x-request-id'];
+  return Array.isArray(requestId) ? requestId[0] : requestId;
+}
 
 /**
  * Parses a raw URL search string into the framework query shape.

package/dist/types.d.ts

@@ -22,6 +22,15 @@ export interface ModuleDefinition {
 export interface BootstrapModuleOptions {
     duplicateProviderPolicy?: 'warn' | 'throw' | 'ignore';
     logger?: ApplicationLogger;
+    /**
+     * Opts this bootstrap into the process-local module graph compile result cache.
+     *
+     * The cache is disabled by default. When enabled, successful graph compiles are
+     * keyed by root module identity, runtime provider inputs, validation tokens,
+     * core metadata write versions, and the runtime compile algorithm version.
+     * Failed compilations are never cached.
+     */
+    moduleGraphCache?: boolean;
     providers?: Provider[];
     validationTokens?: Token[];
 }
@@ -91,6 +100,12 @@ export interface ExceptionFilterHandler {
 /** High-level bootstrap options for creating an HTTP application shell. */
 export interface BootstrapApplicationOptions {
     adapter?: HttpApplicationAdapter;
+    /**
+     * Enables the opt-in process-local module graph compile result cache for this
+     * bootstrap. The default is `false`, so each bootstrap compiles a fresh graph
+     * unless callers explicitly request cache reuse.
+     */
+    moduleGraphCache?: boolean;
     /**
      * Policy for duplicate provider tokens across modules.
      *
@@ -127,8 +142,13 @@ export interface CreateApplicationContextOptions extends Omit<BootstrapApplicati
 }
 /** Runtime transport contract used by microservice application shells. */
 export interface MicroserviceRuntime {
+    /** Release transport resources owned by the microservice runtime during shutdown. */
+    close?(signal?: string): MaybePromise<void>;
+    /** Emit a fire-and-forget message for the given transport pattern. */
     emit?(pattern: string, payload: unknown): MaybePromise<void>;
+    /** Start listening for transport messages. */
     listen(): MaybePromise<void>;
+    /** Send a request/response message for the given transport pattern. */
     send?(pattern: string, payload: unknown, signal?: AbortSignal): MaybePromise<unknown>;
 }
 /** Options accepted by `Application.connectMicroservice(...)`. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/web.d.ts

@@ -11,8 +11,10 @@ declare module '@fluojs/http' {
  * Configures Web request parsing, multipart handling, and raw body preservation.
  */
 export interface CreateWebRequestResponseFactoryOptions {
+    consumeOriginalBody?: boolean;
     maxBodySize?: number;
     multipart?: MultipartOptions;
+    preferNativeJsonBodyReader?: boolean;
     rawBody?: boolean;
 }
 /**

package/dist/web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,cAAc,CAAC;AAMtB,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,wCAAwC,CAAC;AAEhD,OAAO,QAAQ,cAAc,CAAC;IAC5B,UAAU,gBAAgB;QACxB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;QACvB,OAAO,CAAC,EAAE,UAAU,CAAC;KACtB;CACF;AAOD;;GAEG;AACH,MAAM,WAAW,sCAAsC;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,yBAA0B,SAAQ,sCAAsC;IACvF,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,sBAAsB,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,EAAE,oBAAoB,CAAC,CAAC;IACzF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,UAAU,IAAI,QAAQ,CAAC;CACxB;AAED,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAgNhD;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,GAAE,sCAA2C,GACnD,sBAAsB,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,EAAE,oBAAoB,CAAC,CA6BhF;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,UAAU,EACV,yBAAiG,EACjG,OAAO,EACP,OAAO,EACP,GAAG,OAAO,EACX,EAAE,yBAAyB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAU/C;AAED;;;;;;;;;GASG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,WAAW,EACnB,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,WAAW,SAAwB,EACnC,eAAe,UAAQ,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAW3B"}
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,cAAc,CAAC;AAMtB,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,wCAAwC,CAAC;AAEhD,OAAO,QAAQ,cAAc,CAAC;IAC5B,UAAU,gBAAgB;QACxB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;QACvB,OAAO,CAAC,EAAE,UAAU,CAAC;KACtB;CACF;AAOD;;GAEG;AACH,MAAM,WAAW,sCAAsC;IACrD,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,yBAA0B,SAAQ,sCAAsC;IACvF,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,sBAAsB,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,EAAE,oBAAoB,CAAC,CAAC;IACzF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,UAAU,IAAI,QAAQ,CAAC;CACxB;AAED,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAgNhD;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,GAAE,sCAA2C,GACnD,sBAAsB,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,EAAE,oBAAoB,CAAC,CA+BhF;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,UAAU,EACV,yBAAiG,EACjG,OAAO,EACP,OAAO,EACP,GAAG,OAAO,EACX,EAAE,yBAAyB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAU/C;AAED;;;;;;;;;GASG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,WAAW,EACnB,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,WAAW,SAAwB,EACnC,eAAe,UAAQ,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAW3B"}

package/dist/web.js

@@ -170,7 +170,7 @@ class MutableWebFrameworkResponse {
 export function createWebRequestResponseFactory(options = {}) {
   return {
     async createRequest(request, signal) {
-      return createDeferredWebFrameworkRequest(request, signal, options.multipart, options.maxBodySize ?? DEFAULT_MAX_BODY_SIZE, options.rawBody ?? false);
+      return createDeferredWebFrameworkRequest(request, signal, options.multipart, options.maxBodySize ?? DEFAULT_MAX_BODY_SIZE, options.rawBody ?? false, options.preferNativeJsonBodyReader ?? false, options.consumeOriginalBody ?? false);
     },
     materializeRequest(request) {
       return materializeWebFrameworkRequestBody(request);
@@ -241,7 +241,7 @@ export async function createWebFrameworkRequest(request, signal, multipartOption
  * @param preserveRawBody - Whether materialization should retain raw request body bytes.
  * @returns The framework request shell with metadata snapshotted and body materialization deferred.
  */
-function createDeferredWebFrameworkRequest(request, signal, multipartOptions, maxBodySize = DEFAULT_MAX_BODY_SIZE, preserveRawBody = false) {
+function createDeferredWebFrameworkRequest(request, signal, multipartOptions, maxBodySize = DEFAULT_MAX_BODY_SIZE, preserveRawBody = false, preferNativeJsonBodyReader = false, consumeOriginalBody = false) {
   const url = new URL(request.url);
   const requestHeaders = new Headers(request.headers);
   const method = request.method;
@@ -250,15 +250,11 @@ function createDeferredWebFrameworkRequest(request, signal, multipartOptions, ma
   const query = createMemoizedValue(() => parseQueryString(url.search));
   const contentType = requestHeaders.get('content-type') ?? undefined;
   const isMultipart = typeof contentType === 'string' && contentType.includes('multipart/form-data');
-  const materializeBody = createMemoizedAsyncValue(async () => {
+  const hasRequestBody = request.body !== null;
+  const materializeBody = hasRequestBody ? createMemoizedAsyncValue(async () => {
     if (isMultipart) {
       const materializedRequest = request.clone();
-      const result = await parseMultipart({
-        body: materializedRequest.body,
-        headers: requestHeaders,
-        method,
-        url: request.url
-      }, {
+      const result = await parseMultipart(createRequestWithSnapshotMetadata(materializedRequest, request.url, method, requestHeaders), {
         ...multipartOptions,
         maxTotalSize: multipartOptions?.maxTotalSize ?? maxBodySize
       });
@@ -271,12 +267,13 @@ function createDeferredWebFrameworkRequest(request, signal, multipartOptions, ma
       frameworkRequest.body = undefined;
       return;
     }
-    const bodyResult = await readWebRequestBody(request.clone(), contentType, maxBodySize, preserveRawBody);
+    const requestToRead = consumeOriginalBody ? request : request.clone();
+    const bodyResult = await readWebRequestBody(requestToRead, contentType, maxBodySize, preserveRawBody, preferNativeJsonBodyReader);
     frameworkRequest.body = bodyResult.body;
     if (bodyResult.rawBody) {
       frameworkRequest.rawBody = bodyResult.rawBody;
     }
-  });
+  }) : undefined;
   const frameworkRequest = {
     get cookies() {
       return cookies();
@@ -291,13 +288,28 @@ function createDeferredWebFrameworkRequest(request, signal, multipartOptions, ma
       return query();
     },
     raw: request,
+    requestId: requestHeaders.get('x-request-id') ?? undefined,
     signal,
     url: url.pathname + url.search,
     materializeBody
   };
+  if (!hasRequestBody) {
+    frameworkRequest.body = undefined;
+  }
   const nativeRouteHandoff = consumeRawRequestNativeRouteHandoff(request);
   return nativeRouteHandoff ? attachFrameworkRequestNativeRouteHandoff(frameworkRequest, nativeRouteHandoff) : frameworkRequest;
 }
+function createRequestWithSnapshotMetadata(request, url, method, headers) {
+  const init = {
+    headers: new Headers(headers),
+    method
+  };
+  if (request.body) {
+    init.body = request.body;
+    init.duplex = 'half';
+  }
+  return new Request(url, init);
+}
 function validateWebRequestContentLength(request, maxBodySize) {
   const contentLength = request.headers.get('content-length');
   if (contentLength === null) {
@@ -410,14 +422,23 @@ function parseCookieHeader(cookieHeader) {
     return [pair.slice(0, index).trim(), decodeCookieValue(pair.slice(index + 1).trim())];
   }));
 }
-async function readWebRequestBody(request, contentType, maxBodySize = DEFAULT_MAX_BODY_SIZE, preserveRawBody = false) {
+async function readWebRequestBody(request, contentType, maxBodySize = DEFAULT_MAX_BODY_SIZE, preserveRawBody = false, preferNativeJsonBodyReader = false) {
   validateWebRequestContentLength(request, maxBodySize);
   if (!request.body) {
     return {
       body: undefined
     };
   }
-  const rawBody = await readByteLimitedStream(request.body, maxBodySize);
+  if (!preserveRawBody && isJsonContentType(contentType) && (preferNativeJsonBodyReader || isContentLengthWithinLimit(request, maxBodySize))) {
+    const rawBody = new Uint8Array(await request.arrayBuffer());
+    if (rawBody.byteLength > maxBodySize) {
+      throw new PayloadTooLargeException(REQUEST_BODY_LIMIT_MESSAGE);
+    }
+    return parseWebRequestRawBody(rawBody, contentType, preserveRawBody);
+  }
+  return parseWebRequestRawBody(await readByteLimitedStream(request.body, maxBodySize), contentType, preserveRawBody);
+}
+function parseWebRequestRawBody(rawBody, contentType, preserveRawBody) {
   if (rawBody.byteLength === 0) {
     return {
       body: undefined
@@ -430,7 +451,7 @@ async function readWebRequestBody(request, contentType, maxBodySize = DEFAULT_MA
       rawBody: preserveRawBody ? rawBody : undefined
     };
   }
-  if (typeof contentType === 'string' && contentType.includes('application/json')) {
+  if (isJsonContentType(contentType)) {
     try {
       return {
         body: JSON.parse(bodyText),
@@ -445,6 +466,14 @@ async function readWebRequestBody(request, contentType, maxBodySize = DEFAULT_MA
     rawBody: preserveRawBody ? rawBody : undefined
   };
 }
+function isContentLengthWithinLimit(request, maxBodySize) {
+  const contentLength = request.headers.get('content-length');
+  if (contentLength === null) {
+    return false;
+  }
+  const parsedContentLength = Number(contentLength);
+  return Number.isFinite(parsedContentLength) && parsedContentLength > 0 && parsedContentLength <= maxBodySize;
+}
 async function readByteLimitedStream(stream, maxBodySize) {
   const reader = stream.getReader();
   const chunks = [];

package/package.json

@@ -9,7 +9,7 @@
     "module-graph",
     "orchestration"
   ],
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.9",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -67,14 +67,14 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/config": "^1.0.0-beta.3",
-    "@fluojs/core": "^1.0.0-beta.2",
-    "@fluojs/di": "^1.0.0-beta.5",
-    "@fluojs/http": "^1.0.0-beta.5"
+    "@fluojs/core": "^1.0.0-beta.3",
+    "@fluojs/config": "^1.0.0-beta.5",
+    "@fluojs/di": "^1.0.0-beta.6",
+    "@fluojs/http": "^1.0.0-beta.9"
   },
   "devDependencies": {
     "vitest": "^3.2.4",
-    "@fluojs/serialization": "^1.0.0-beta.3"
+    "@fluojs/serialization": "^1.0.0-beta.4"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",