@bleedingdev/modern-js-runtime-extensions 3.9.0-ultramodern.4 → 3.9.0-ultramodern.5

package/dist/types/routerPrefetchPolicy.d.ts

@@ -0,0 +1,28 @@
+type PrefetchBehavior = 'intent' | 'render' | 'viewport' | 'none';
+type PrefetchState = {
+    code: boolean;
+    data: boolean;
+};
+/** Policy-only contract: native links supply elements, route inputs and loads. */
+export declare function createRouterPrefetchPolicy(): {
+    canWarmup: () => boolean;
+    allowData(route: unknown): boolean;
+    observe({ element, prefetch: inputPrefetch, preload: inputPreload, notify, }: {
+        element: HTMLAnchorElement | null;
+        prefetch?: PrefetchBehavior;
+        preload?: PrefetchBehavior | false;
+        notify: (state: PrefetchState) => void;
+    }): {
+        onIntent(): void;
+        onCancel(): void;
+        dispose(): void;
+    };
+    schedule({ runtimeContext, chunkLoader, publicPath, key: operationKey, run, }: {
+        runtimeContext: object;
+        chunkLoader: object;
+        publicPath: string;
+        key: string;
+        run: () => Promise<unknown>;
+    }): () => void;
+};
+export {};

package/dist/types/routerProvider.d.ts

@@ -0,0 +1,77 @@
+/** Structural plugin contract; the composing integration supplies native hooks. */
+export type RouterProviderPlugin = {
+    name?: string;
+    registryHooks?: Record<string, unknown>;
+    setup?: (api: any) => unknown;
+    [key: string]: unknown;
+};
+/**
+ * Guard for the wrapper plugin (`router/internal`): a resolved provider is
+ * only invoked through `setup`, so registry hooks outside the canonical
+ * router hook contract cannot be registered for it. Returns the offending
+ * hook names and warns once so they are surfaced instead of silently dropped.
+ */
+export declare function reportUnsupportedProviderRegistryHooks(providerPlugin: {
+    name?: string;
+    registryHooks?: Record<string, unknown>;
+}, routerProviderRegistryHooks: Record<string, unknown>): string[];
+export type RouterProviderFactory = (userConfig?: any) => RouterProviderPlugin;
+export type RouterProviderRegistration = {
+    name: string;
+    factory: RouterProviderFactory;
+    isDefault?: boolean;
+};
+/**
+ * App-owned provider catalog. Provider factories close over their module graph,
+ * so they must be resolved from the runtime wrapper that owns the app instead
+ * of from a page-global first-registration winner.
+ */
+export type RouterProviderRealm = Readonly<{
+    defaultProvider?: string;
+    get: (name: string) => RouterProviderFactory | undefined;
+    names: () => readonly string[];
+}>;
+export declare function createRouterProviderRealm(registrations: readonly RouterProviderRegistration[]): RouterProviderRealm;
+export declare function registerRouterProvider(name: string, factory: RouterProviderFactory, options?: {
+    isDefault?: boolean;
+}): void;
+export declare function resolveRouterProvider(framework?: string, options?: {
+    /**
+     * Provider factories owned by the resolving app/runtime wrapper. A realm
+     * is the exclusive provider source when supplied because its factories
+     * close over the correct app module graph.
+     */
+    realm?: RouterProviderRealm;
+    /**
+     * Legacy single-provider override retained for published wrappers. New
+     * integrations should pass an app-owned `realm`, which supports every
+     * provider rather than only the default.
+     */
+    localDefault?: {
+        name: string;
+        factory: RouterProviderFactory;
+    };
+}): RouterProviderFactory;
+/**
+ * Test-only escape hatch: compatibility registries live on `globalThis`, so
+ * unit tests need a way to restore a pristine state between cases.
+ */
+export declare function unsafe_resetRouterProvidersForTesting(): void;
+/** Compose app-owned providers without importing the native runtime graph. */
+export declare function createRouterPlugin<Hooks extends Record<string, unknown>>({ defaultProvider, registryHooks, localProviders, }: {
+    defaultProvider: {
+        name: string;
+        factory: RouterProviderFactory;
+    };
+    registryHooks: Hooks;
+    localProviders?: readonly Omit<RouterProviderRegistration, 'isDefault'>[];
+}): (userConfig?: Record<string, any>) => {
+    name: string;
+    registryHooks: Hooks;
+    setup(api: {
+        getRuntimeConfig: () => {
+            router?: Record<string, unknown>;
+        };
+        [key: string]: any;
+    }): void;
+};

package/dist/types/routerState.d.ts

@@ -0,0 +1,12 @@
+import type { InternalRouterRuntimeState, InternalRouterServerSnapshot, RouterServerPrepareResult } from './routerStateTypes.js';
+export type { BuiltInRouterFramework, InternalRouterRuntimeState, InternalRouterServerSnapshot, RouterFramework, RouterLifecyclePhase, RouterRouteMatchSnapshot, RouterServerPrepareResult, } from './routerStateTypes.js';
+export declare function getRouterRuntimeState(runtimeContext: object): InternalRouterRuntimeState | undefined;
+export declare function getRouterServerSnapshot(runtimeContext: object): InternalRouterServerSnapshot | undefined;
+type RouterSnapshotLike = Partial<InternalRouterServerSnapshot>;
+export declare function createRouterServerSnapshot(state: RouterSnapshotLike): InternalRouterServerSnapshot;
+export declare function createRouterRuntimeState(state: InternalRouterRuntimeState): InternalRouterRuntimeState;
+export declare function applyRouterRuntimeState<Context extends object>(runtimeContext: Context, state: InternalRouterRuntimeState): Context;
+export declare function applyRouterServerPrepareResult<Context extends object>(runtimeContext: Context, result: RouterServerPrepareResult): Context;
+export declare function getRouterHydrationScripts(runtimeContext: object): string[];
+export declare function getRouterMatchedRouteIds(runtimeContext: object): string[] | undefined;
+export declare function cleanupRouterRuntimeState(runtimeContext: object): Promise<void>;

package/dist/types/routerStatePlugin.d.ts

@@ -0,0 +1,19 @@
+type RouterLifecycleEvent = {
+    framework: string;
+    phase: string;
+    runtimeContext: object;
+    basename?: string;
+    router?: unknown;
+};
+/** Install fork policy through lifecycle hooks supplied by the native owner. */
+export declare function createRouterStatePlugin<Hooks extends Record<string, unknown>>({ registryHooks, }: {
+    registryHooks: Hooks;
+}): {
+    name: string;
+    registryHooks: Hooks;
+    setup(api: {
+        onBeforeRender: (callback: (context: object) => void) => unknown;
+        onAfterCreateRouter: (callback: (event: RouterLifecycleEvent) => void) => unknown;
+    }): void;
+};
+export {};

package/dist/types/routerStateTypes.d.ts

@@ -0,0 +1,40 @@
+export type BuiltInRouterFramework = 'react-router' | 'tanstack';
+export type RouterFramework = BuiltInRouterFramework | (string & {});
+export interface RouterRouteMatchSnapshot {
+    routeId: string;
+    assetRouteId?: string;
+    pathname?: string;
+    params?: Record<string, string>;
+}
+export interface InternalRouterServerSnapshot {
+    framework?: RouterFramework;
+    basename?: string;
+    statusCode?: number;
+    errors?: Record<string, unknown>;
+    routerData?: {
+        loaderData?: Record<string, unknown>;
+        errors?: Record<string, unknown>;
+    };
+    hydrationScript?: string;
+    hydrationScripts?: string[];
+    matchedRouteIds?: string[];
+    matches?: RouterRouteMatchSnapshot[];
+}
+export interface InternalRouterRuntimeState {
+    framework: RouterFramework;
+    basename?: string;
+    instance?: unknown;
+    hydrationScript?: string;
+    hydrationScripts?: string[];
+    matchedRouteIds?: string[];
+    matches?: RouterRouteMatchSnapshot[];
+    serverSnapshot?: InternalRouterServerSnapshot;
+    cleanup?: () => void | Promise<void>;
+}
+export interface RouterServerPrepareResult {
+    state: InternalRouterRuntimeState;
+    snapshot?: InternalRouterServerSnapshot;
+    redirect?: Response;
+    cleanup?: () => void | Promise<void>;
+}
+export type RouterLifecyclePhase = 'ssr-prepare' | 'client-create' | 'hydrate';

package/dist/types/runtimeContextProjection.d.ts

@@ -0,0 +1,30 @@
+interface ProjectionContext {
+    isBrowser?: boolean;
+    ssrContext?: {
+        request: {
+            url?: unknown;
+            userAgent?: unknown;
+            cookie?: unknown;
+            pathname?: unknown;
+            query?: object;
+            params?: object;
+            headers?: object;
+            host?: unknown;
+            referer?: unknown;
+        };
+        response: {
+            locals?: unknown;
+        };
+    };
+}
+export declare function projectRuntimeContext<InternalContext extends ProjectionContext, PublicContext extends ProjectionContext>(projection: {
+    internalContext: InternalContext;
+    publicContext: PublicContext;
+}, options: {
+    context: InternalContext;
+    isRsc: boolean;
+}): {
+    internalContext: InternalContext;
+    publicContext: PublicContext;
+};
+export {};

package/dist/types/server-config/bffRuntime.d.ts

@@ -0,0 +1,122 @@
+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.
+     *
+     * When enabled, 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 treated as legacy escape hatches.
+     *
+     * @default true
+     */
+    strictEffectApproach?: true;
+    openapi?: BffEffectOpenApiUserConfig;
+    dataPlatform?: BffEffectDataPlatformUserConfig;
+}

package/dist/types/server-config/index.d.ts

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

package/dist/types/server-config/serverTelemetry.d.ts

@@ -0,0 +1,322 @@
+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 ServerTelemetryCanaryContractGateUserConfig {
+    /**
+     * Whether this contract gate currently passes.
+     */
+    passed: boolean;
+    /**
+     * Optional failure reason used for rollback diagnostics.
+     */
+    reason?: string;
+}
+export interface ServerTelemetryCanaryAutopilotUserConfig {
+    /**
+     * 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?: ServerTelemetryCanaryRuntimeFallbackSignalUserConfig;
+    /**
+     * Optional pluggable state store backend for contract gate snapshots.
+     * When omitted, snapshots are read/written from gateSnapshotPath on local disk.
+     */
+    stateStore?: ServerTelemetryCanaryAutopilotStateStoreUserConfig;
+}
+export interface ServerTelemetryCanaryAutopilotStateStoreUserConfig {
+    /**
+     * Path or package name of a module that exports
+     * `createContractGateSnapshotStore(context)`.
+     */
+    module: string;
+    /**
+     * Optional adapter-specific configuration.
+     */
+    options?: Record<string, unknown>;
+}
+export interface ServerTelemetryCanaryRuntimeFallbackSignalUserConfig {
+    /**
+     * 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 canary contract gates.
+     */
+    trustPolicy?: ServerTelemetryCanaryRuntimeFallbackSignalTrustPolicyUserConfig;
+    /**
+     * Optional request authentication for runtime fallback signal endpoint.
+     */
+    auth?: ServerTelemetryCanaryRuntimeFallbackSignalAuthUserConfig;
+}
+export interface ServerTelemetryCanaryRuntimeFallbackSignalAuthUserConfig {
+    /**
+     * 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 ServerTelemetryCanaryRuntimeFallbackSignalTrustPolicyUserConfig {
+    /**
+     * 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 ServerTelemetryCanaryUserConfig {
+    /**
+     * Enable canary rollout/rollback orchestration.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Periodic canary evaluation interval in milliseconds.
+     *
+     * @default 15000
+     */
+    evaluationIntervalMs?: number;
+    /**
+     * Required consecutive healthy evaluations before promotion.
+     *
+     * @default 3
+     */
+    minConsecutiveHealthyEvaluations?: number;
+    /**
+     * Consecutive failing evaluations before automated rollback.
+     *
+     * @default 2
+     */
+    rollbackConsecutiveFailures?: number;
+    /**
+     * Maximum queue utilization ratio allowed during canary.
+     *
+     * @default 0.8
+     */
+    maxQueueUtilization?: number;
+    /**
+     * Maximum allowed total dropped envelopes during canary.
+     *
+     * @default 0
+     */
+    maxTotalDropped?: number;
+    /**
+     * Maximum allowed unhealthy exporters during canary.
+     *
+     * @default 0
+     */
+    maxUnhealthyExporters?: number;
+    /**
+     * Contract gate map used in rollout decisions.
+     * `true` means passing, `false` means failing.
+     */
+    contractGates?: Record<string, boolean | ServerTelemetryCanaryContractGateUserConfig>;
+    /**
+     * Contract-gate autopilot settings.
+     */
+    autopilot?: ServerTelemetryCanaryAutopilotUserConfig;
+}
+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;
+    /**
+     * Canary rollout and automated rollback orchestration policy.
+     */
+    canary?: ServerTelemetryCanaryUserConfig;
+    exporters?: {
+        /**
+         * OpenTelemetry HTTP exporter.
+         */
+        otlp?: ServerTelemetryExporterOptions;
+        /**
+         * VictoriaMetrics Prometheus import exporter.
+         */
+        victoriaMetrics?: ServerTelemetryVictoriaMetricsOptions;
+    };
+}