@bleedingdev/modern-js-runtime-extensions 3.9.0-ultramodern.2 → 3.9.0-ultramodern.21

package/src/server-config/bffRuntime.ts

@@ -0,0 +1,136 @@
+export type BffRuntimeFramework = 'hono' | 'effect';
+
+/** Fork BFF options, independent of any native server config interface. */
+export interface BffRuntimeUserConfig {
+  runtimeFramework?: BffRuntimeFramework;
+  effect?: BffEffectUserConfig;
+  crossProjectPolicy?: BffCrossProjectPolicyUserConfig;
+}
+
+export interface BffCrossProjectPolicyUserConfig {
+  /**
+   * Enable cross-project envelope and operation-context policy checks.
+   *
+   * @default false
+   */
+  enabled?: boolean;
+  /**
+   * Require cross-project envelope header when policy is enabled.
+   *
+   * @default true
+   */
+  requireEnvelope?: boolean;
+  /**
+   * Require operation-context header when policy is enabled.
+   *
+   * @default true
+   */
+  requireOperationContext?: boolean;
+  /**
+   * Require operation-context detail header carrying schema/version metadata.
+   *
+   * @default true
+   */
+  requireOperationContextDetails?: boolean;
+  /**
+   * Require operation schema hash in operation-context details.
+   *
+   * @default true
+   */
+  requireOperationSchemaHash?: boolean;
+  /**
+   * Require operation version in operation-context details.
+   *
+   * @default true
+   */
+  requireOperationVersion?: boolean;
+  /**
+   * Optional allowlist of producer namespaces derived from requestId.
+   */
+  allowedNamespaces?: string[];
+  /**
+   * Optional hook deriving a verified producer identity (namespace) from
+   * request headers, e.g. an mTLS subject or gateway-verified JWT claim.
+   * When provided, namespace checks bind to this verified value instead of
+   * the client-asserted requestId namespace; returning `undefined` denies
+   * the request. Without it the namespace checks are advisory only.
+   */
+  verifyProducerIdentity?: (
+    headers: Record<string, unknown>,
+  ) => string | undefined;
+  /**
+   * Optional operation-contract map keyed by:
+   * - `${METHOD}:${routePath}`
+   * - `operation:${requestId}:${operationId}`
+   */
+  expectedOperationContracts?: Record<
+    string,
+    {
+      schemaHash?: string;
+      operationVersion?: number;
+    }
+  >;
+  /**
+   * Allow operations missing from expectedOperationContracts.
+   *
+   * @default false
+   */
+  allowUnknownOperations?: boolean;
+  /**
+   * HTTP status code used for denied requests.
+   *
+   * @default 403
+   */
+  denyStatus?: number;
+}
+
+export type BffEffectOpenApiUserConfig =
+  | boolean
+  | {
+      path?: string;
+    };
+
+export interface BffEffectDataPlatformSelectionUserConfig {
+  maxDepth?: number;
+  maxFields?: number;
+  allowedLeafPaths?: string[];
+}
+
+export interface BffEffectDataPlatformBatchUserConfig {
+  enabled?: boolean;
+  endpoint?: `/${string}`;
+  maxBatchSize?: number;
+  maxBatchBytes?: number;
+  flushIntervalMs?: number;
+  maxConcurrency?: number;
+  requestTimeoutMs?: number;
+  allowedMethods?: string[];
+}
+
+export interface BffEffectDataPlatformUserConfig {
+  enabled?: boolean;
+  requireEnvelope?: boolean;
+  envelopeHeader?: string;
+  expectedNamespace?: string;
+  validateOrigin?: boolean;
+  requireTraceContext?: boolean;
+  selection?: BffEffectDataPlatformSelectionUserConfig;
+  batch?: BffEffectDataPlatformBatchUserConfig;
+}
+
+export interface BffEffectUserConfig {
+  entry?: string;
+  /**
+   * Enforce Effect-native API/runtime modules instead of raw request handlers.
+   *
+   * Effect API entries must export a `defineEffectBff(...)`
+   * definition or a `{ api, layer }` HttpApi module. Raw `handler` exports,
+   * default request handlers, and unbranded custom `createHandler` factories
+   * are rejected.
+   *
+   * @default true
+   */
+  strictEffectApproach?: true;
+  openapi?: BffEffectOpenApiUserConfig;
+  dataPlatform?: BffEffectDataPlatformUserConfig;
+}

package/src/server-config/index.ts

@@ -0,0 +1,2 @@
+export type * from './bffRuntime';
+export type * from './serverTelemetry';

package/src/server-config/serverTelemetry.ts

@@ -0,0 +1,337 @@
+export interface ServerTelemetryExporterOptions {
+  enabled?: boolean;
+  endpoint?: string;
+  headers?: Record<string, string>;
+  timeoutMs?: number;
+}
+
+export interface ServerTelemetryVictoriaMetricsOptions
+  extends ServerTelemetryExporterOptions {
+  metricPrefix?: string;
+}
+
+export interface ServerTelemetrySloUserConfig {
+  /**
+   * Queue utilization ratio threshold that emits SLO degradation alerts.
+   *
+   * @default 0.8
+   */
+  queueUtilizationWarnThreshold?: number;
+  /**
+   * Total dropped-envelope threshold that emits SLO degradation alerts.
+   *
+   * @default 1
+   */
+  queueDroppedWarnThreshold?: number;
+  /**
+   * Cooldown between SLO alert emissions for the same alert type.
+   *
+   * @default 60000
+   */
+  alertCooldownMs?: number;
+}
+
+export interface ServerTelemetryHealthContractGateUserConfig {
+  /**
+   * Whether this contract gate currently passes.
+   */
+  passed: boolean;
+  /**
+   * Optional failure reason used for health diagnostics.
+   */
+  reason?: string;
+}
+
+export interface ServerTelemetrySnapshotObservationUserConfig {
+  /**
+   * Enable automatic contract gate synchronization from a gate snapshot file.
+   *
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Path to contract gate snapshot JSON file.
+   *
+   * @default ".modern/contract-gates.json"
+   */
+  gateSnapshotPath?: string;
+  /**
+   * Poll interval for reading gate snapshot changes.
+   *
+   * @default 15000
+   */
+  pollIntervalMs?: number;
+  /**
+   * Marks gate entries as failed when they are older than this threshold.
+   *
+   * @default 600000
+   */
+  gateStaleAfterMs?: number;
+  /**
+   * Runtime MF fallback signal ingestion.
+   */
+  runtimeFallbackSignal?: ServerTelemetryHealthRuntimeFallbackSignalUserConfig;
+  /**
+   * Optional pluggable state store backend for contract gate snapshots.
+   * When omitted, snapshots are read/written from gateSnapshotPath on local disk.
+   */
+  stateStore?: ServerTelemetrySnapshotObservationStateStoreUserConfig;
+}
+
+export interface ServerTelemetrySnapshotObservationStateStoreUserConfig {
+  /**
+   * Path or package name of a module that exports
+   * `createContractGateSnapshotStore(context)`.
+   */
+  module: string;
+  /**
+   * Optional adapter-specific configuration.
+   */
+  options?: Record<string, unknown>;
+}
+
+export interface ServerTelemetryHealthRuntimeFallbackSignalUserConfig {
+  /**
+   * Enable runtime MF fallback signal ingestion endpoint.
+   *
+   * Opt-in: when enabled, `auth` must be configured with a token
+   * (`expectedValue` or `expectedValueEnv`) or server setup throws.
+   *
+   * @default false
+   */
+  enabled?: boolean;
+  /**
+   * HTTP endpoint path for runtime fallback events.
+   *
+   * @default "/_modern/contract-gates/runtime-fallback"
+   */
+  endpoint?: string;
+  /**
+   * Contract gate name updated by runtime fallback events.
+   *
+   * @default "runtime-mf-fallback-health"
+   */
+  gateName?: string;
+  /**
+   * How long a runtime fallback signal should hold gate failure status.
+   *
+   * @default 300000
+   */
+  failureHoldMs?: number;
+  /**
+   * Maximum accepted request body size in bytes.
+   *
+   * @default 16384
+   */
+  maxBodyBytes?: number;
+  /**
+   * Optional runtime trust policy for fallback signal ingestion.
+   * Use this to restrict who can mutate health contract gates.
+   */
+  trustPolicy?: ServerTelemetryHealthRuntimeFallbackSignalTrustPolicyUserConfig;
+  /**
+   * Optional request authentication for runtime fallback signal endpoint.
+   */
+  auth?: ServerTelemetryHealthRuntimeFallbackSignalAuthUserConfig;
+}
+
+export interface ServerTelemetryHealthRuntimeFallbackSignalAuthUserConfig {
+  /**
+   * Enable auth guard for runtime fallback signal endpoint.
+   *
+   * @default false
+   */
+  enabled?: boolean;
+  /**
+   * Header name carrying runtime fallback auth token.
+   *
+   * @default "x-modernjs-runtime-signal-token"
+   */
+  headerName?: string;
+  /**
+   * Expected token value. Prefer using expectedValueEnv in production.
+   */
+  expectedValue?: string;
+  /**
+   * Name of environment variable that stores expected token value.
+   */
+  expectedValueEnv?: string;
+}
+
+export interface ServerTelemetryHealthRuntimeFallbackSignalTrustPolicyUserConfig {
+  /**
+   * Allowlist of app names accepted by runtime fallback signal endpoint.
+   * Empty means no app-name allowlist check.
+   */
+  allowedApps?: string[];
+  /**
+   * Allowlist of entry origins accepted by runtime fallback signal endpoint.
+   * Values should be URL origins (for example https://erp.example.com).
+   * Empty means no entry-origin allowlist check.
+   */
+  allowedEntryOrigins?: string[];
+  /**
+   * Expected runtime digest per appName.
+   */
+  expectedRuntimeDigests?: Record<string, string>;
+  /**
+   * Require runtimeDigest to be present in signal payload metadata.
+   *
+   * @default false
+   */
+  enforceRuntimeDigest?: boolean;
+  /**
+   * Maximum accepted signals per app+origin window.
+   *
+   * @default 30
+   */
+  maxSignalsPerWindow?: number;
+  /**
+   * Sliding window size in milliseconds for maxSignalsPerWindow.
+   *
+   * @default 60000
+   */
+  windowMs?: number;
+  /**
+   * Drop duplicate fallback events with the same fingerprint during this window.
+   *
+   * @default 10000
+   */
+  dedupeWindowMs?: number;
+}
+
+export interface ServerTelemetryHealthUserConfig {
+  /**
+   * Enable telemetry health observation.
+   *
+   * @default false
+   */
+  enabled?: boolean;
+  /**
+   * Periodic health evaluation interval in milliseconds.
+   *
+   * @default 15000
+   */
+  evaluationIntervalMs?: number;
+  /**
+   * Required consecutive healthy evaluations before reporting healthy.
+   *
+   * @default 3
+   */
+  minConsecutiveHealthyEvaluations?: number;
+  /**
+   * Consecutive failing evaluations before reporting unhealthy.
+   *
+   * @default 2
+   */
+  minConsecutiveFailedEvaluations?: number;
+  /**
+   * Maximum queue utilization ratio allowed for healthy telemetry.
+   *
+   * @default 0.8
+   */
+  maxQueueUtilization?: number;
+  /**
+   * Maximum allowed total dropped envelopes for healthy telemetry.
+   *
+   * @default 0
+   */
+  maxTotalDropped?: number;
+  /**
+   * Maximum allowed unhealthy exporters for healthy telemetry.
+   *
+   * @default 0
+   */
+  maxUnhealthyExporters?: number;
+  /**
+   * Contract gate map used in health evaluations.
+   * `true` means passing, `false` means failing.
+   */
+  contractGates?: Record<
+    string,
+    boolean | ServerTelemetryHealthContractGateUserConfig
+  >;
+  /**
+   * Contract-gate snapshot observation settings.
+   */
+  snapshotObservation?: ServerTelemetrySnapshotObservationUserConfig;
+}
+
+export interface ServerTelemetryConfigExtension {
+  telemetry?: ServerTelemetryUserConfig;
+}
+
+export interface ServerTelemetryUserConfig {
+  /**
+   * Enable framework telemetry envelope emission.
+   * @default false
+   */
+  enabled?: boolean;
+  /**
+   * Logical service name attached to every telemetry envelope.
+   * @default server.metaName
+   */
+  service?: string;
+  /**
+   * Logical module name attached to every telemetry envelope.
+   * @default "server"
+   */
+  module?: string;
+  /**
+   * Environment attached to every telemetry envelope.
+   * @default process.env.NODE_ENV || "development"
+   */
+  environment?: string;
+  /**
+   * Sampling rate for monitor events.
+   * @default 1
+   */
+  samplingRate?: number;
+  /**
+   * Flush window in milliseconds for exporter batches.
+   * @default 1000
+   */
+  flushIntervalMs?: number;
+  /**
+   * Maximum envelopes in one emitted batch.
+   * @default 50
+   */
+  maxBatchSize?: number;
+  /**
+   * Maximum envelopes buffered before backpressure drops oldest.
+   * @default 1000
+   */
+  maxQueueSize?: number;
+  /**
+   * Envelope attribute keys that should be redacted.
+   */
+  redactionKeys?: string[];
+  /**
+   * Control startup exporter health probe behavior.
+   * When enabled (default), server initialization emits a startup probe and
+   * marks exporters healthy/unhealthy before serving traffic.
+   * When fail-loud mode is enabled (default), initialization throws if at
+   * least one configured exporter is unhealthy.
+   *
+   * @default true
+   */
+  failLoudStartup?: boolean;
+  /**
+   * Queue backpressure/degradation SLO alert thresholds.
+   */
+  slo?: ServerTelemetrySloUserConfig;
+  /**
+   * Telemetry health observation policy.
+   */
+  health?: ServerTelemetryHealthUserConfig;
+  exporters?: {
+    /**
+     * OpenTelemetry HTTP exporter.
+     */
+    otlp?: ServerTelemetryExporterOptions;
+    /**
+     * VictoriaMetrics Prometheus import exporter.
+     */
+    victoriaMetrics?: ServerTelemetryVictoriaMetricsOptions;
+  };
+}

package/src/shellStream.ts

@@ -24,30 +24,60 @@ export const createConservingWebShellStream = (
     markerCarry = markerFound ? '' : candidate.slice(-(marker.length - 1));
   };
 
-  return source.pipeThrough(
-    new TransformStream<Uint8Array, Uint8Array>({
-      transform(chunk, controller) {
-        const decoded = decoder.decode(chunk, { stream: true });
-        observeMarker(decoded);
-        const output = headProcessor.push(decoded);
-        if (output) {
-          controller.enqueue(encoder.encode(output));
+  const transform = new TransformStream<Uint8Array, Uint8Array>({
+    transform(chunk, controller) {
+      const decoded = decoder.decode(chunk, { stream: true });
+      observeMarker(decoded);
+      const output = headProcessor.push(decoded);
+      if (output) {
+        controller.enqueue(encoder.encode(output));
+      }
+    },
+    flush(controller) {
+      const decoded = decoder.decode();
+      observeMarker(decoded);
+      if (!markerFound) {
+        abortHeadRender(context);
+        const error = new Error(MISSING_SHELL_MARKER_ERROR);
+        onMissingMarker?.(error);
+        throw error;
+      }
+      const output = headProcessor.finish(decoded);
+      if (output) {
+        controller.enqueue(encoder.encode(output));
+      }
+    },
+  });
+  const piping = source.pipeTo(transform.writable);
+  piping.catch(() => {});
+  const reader = transform.readable.getReader();
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const result = await reader.read();
+        if (result.done) {
+          await piping;
+          controller.close();
+          reader.releaseLock();
+        } else controller.enqueue(result.value);
+      } catch (error) {
+        await piping.catch(() => {});
+        controller.error(error);
+        reader.releaseLock();
+      }
+    },
+    async cancel(reason) {
+      try {
+        await reader.cancel(reason);
+      } finally {
+        try {
+          await piping.catch(error => {
+            if (error !== reason) throw error;
+          });
+        } finally {
+          reader.releaseLock();
         }
-      },
-      flush(controller) {
-        const decoded = decoder.decode();
-        observeMarker(decoded);
-        if (!markerFound) {
-          abortHeadRender(context);
-          const error = new Error(MISSING_SHELL_MARKER_ERROR);
-          onMissingMarker?.(error);
-          throw error;
-        }
-        const output = headProcessor.finish(decoded);
-        if (output) {
-          controller.enqueue(encoder.encode(output));
-        }
-      },
-    }),
-  );
+      }
+    },
+  });
 };