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

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.
+     *
+     * 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/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 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/dist/types/workspaceEvents.d.ts

@@ -0,0 +1,62 @@
+export type UltramodernPerformanceReadinessSignalId = 'bfcache' | 'core-web-vitals-rum' | 'duplicate-prefetch-warmup' | 'cache-policy-sanity' | 'save-data-behavior' | 'cloudflare-ssr-cache-hints';
+export type UltramodernWorkspaceLocale = 'en' | 'cs';
+export type UltramodernPerformanceReadinessSignalStatus = 'pass' | 'warn' | 'fail';
+export declare const ultramodernWorkspaceEventNames: {
+    readonly navigate: 'ultramodern:navigate';
+    readonly performanceSignal: 'ultramodern:performance-signal';
+    readonly remoteReady: 'ultramodern:remote-ready';
+    readonly routeSettled: 'ultramodern:route-settled';
+};
+export type UltramodernWorkspaceEventName = (typeof ultramodernWorkspaceEventNames)[keyof typeof ultramodernWorkspaceEventNames];
+export interface UltramodernNavigatePayload {
+    to: string;
+    replace?: boolean;
+    state?: Record<string, unknown>;
+}
+export interface UltramodernRouteSettledPayload {
+    pathname: string;
+    locale?: UltramodernWorkspaceLocale;
+    title?: string;
+}
+export interface UltramodernRemoteReadyPayload {
+    appId: string;
+    build?: string;
+    surface?: string;
+    version?: string;
+}
+export interface UltramodernPerformanceSignalPayload {
+    signalId: UltramodernPerformanceReadinessSignalId;
+    status: UltramodernPerformanceReadinessSignalStatus;
+    durationMs?: number;
+    detail?: Record<string, unknown>;
+}
+export interface UltramodernWorkspaceEventPayloadMap {
+    'ultramodern:navigate': UltramodernNavigatePayload;
+    'ultramodern:performance-signal': UltramodernPerformanceSignalPayload;
+    'ultramodern:remote-ready': UltramodernRemoteReadyPayload;
+    'ultramodern:route-settled': UltramodernRouteSettledPayload;
+}
+export declare class UltramodernWorkspaceEventValidationError {
+    readonly message: string;
+    readonly name = "UltramodernWorkspaceEventValidationError";
+    readonly eventName: UltramodernWorkspaceEventName;
+    readonly payload: unknown;
+    constructor(eventName: UltramodernWorkspaceEventName, payload: unknown);
+}
+export declare const isUltramodernNavigatePayload: (payload: unknown) => payload is UltramodernNavigatePayload;
+export declare const isUltramodernRouteSettledPayload: (payload: unknown) => payload is UltramodernRouteSettledPayload;
+export declare const isUltramodernRemoteReadyPayload: (payload: unknown) => payload is UltramodernRemoteReadyPayload;
+export declare const isUltramodernPerformanceSignalPayload: (payload: unknown) => payload is UltramodernPerformanceSignalPayload;
+export declare const isUltramodernWorkspaceEventPayload: <Name extends UltramodernWorkspaceEventName>(eventName: Name, payload: unknown) => payload is UltramodernWorkspaceEventPayloadMap[Name];
+export declare const assertUltramodernWorkspaceEventPayload: <Name extends UltramodernWorkspaceEventName>(eventName: Name, payload: unknown) => UltramodernWorkspaceEventPayloadMap[Name];
+export declare const createUltramodernWorkspaceEvent: <Name extends UltramodernWorkspaceEventName>(eventName: Name, payload: UltramodernWorkspaceEventPayloadMap[Name]) => CustomEvent<UltramodernWorkspaceEventPayloadMap[Name]>;
+export declare const dispatchUltramodernWorkspaceEvent: <Name extends UltramodernWorkspaceEventName>(target: EventTarget, eventName: Name, payload: UltramodernWorkspaceEventPayloadMap[Name]) => boolean;
+export declare const onUltramodernWorkspaceEvent: <Name extends UltramodernWorkspaceEventName>(target: EventTarget, eventName: Name, handler: (payload: UltramodernWorkspaceEventPayloadMap[Name], event: CustomEvent<UltramodernWorkspaceEventPayloadMap[Name]>) => void) => () => void;
+export declare const dispatchUltramodernNavigate: (target: EventTarget, payload: UltramodernNavigatePayload) => boolean;
+export declare const dispatchUltramodernRouteSettled: (target: EventTarget, payload: UltramodernRouteSettledPayload) => boolean;
+export declare const dispatchUltramodernRemoteReady: (target: EventTarget, payload: UltramodernRemoteReadyPayload) => boolean;
+export declare const dispatchUltramodernPerformanceSignal: (target: EventTarget, payload: UltramodernPerformanceSignalPayload) => boolean;
+export declare const onUltramodernNavigate: (target: EventTarget, handler: (payload: UltramodernNavigatePayload, event: CustomEvent<UltramodernNavigatePayload>) => void) => () => void;
+export declare const onUltramodernRouteSettled: (target: EventTarget, handler: (payload: UltramodernRouteSettledPayload, event: CustomEvent<UltramodernRouteSettledPayload>) => void) => () => void;
+export declare const onUltramodernRemoteReady: (target: EventTarget, handler: (payload: UltramodernRemoteReadyPayload, event: CustomEvent<UltramodernRemoteReadyPayload>) => void) => () => void;
+export declare const onUltramodernPerformanceSignal: (target: EventTarget, handler: (payload: UltramodernPerformanceSignalPayload, event: CustomEvent<UltramodernPerformanceSignalPayload>) => void) => () => void;