@bleedingdev/modern-js-server-core 3.2.0-ultramodern.0

package/dist/types/plugins/telemetry.d.ts

@@ -0,0 +1,309 @@
+import type { Metrics } from '@modern-js/types';
+import type { ServerTelemetryUserConfig } from '../types/config';
+import type { ServerPlugin } from '../types/plugins';
+export type TelemetrySignalType = 'log' | 'metric' | 'trace';
+export interface TelemetryEnvelope {
+    timestamp: number;
+    service: string;
+    module: string;
+    environment: string;
+    signalType: TelemetrySignalType;
+    name: string;
+    level?: string;
+    value?: number;
+    unit?: string;
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    tags?: Record<string, string>;
+    attributes?: Record<string, unknown>;
+    error?: {
+        name?: string;
+        message: string;
+        stack?: string;
+    };
+}
+export interface TelemetryExporter {
+    name: string;
+    init?: (context: {
+        service: string;
+        module: string;
+        environment: string;
+    }) => void | Promise<void>;
+    emit: (batch: TelemetryEnvelope[]) => void | Promise<void>;
+    flush?: () => void | Promise<void>;
+    shutdown?: () => void | Promise<void>;
+}
+export interface TelemetryRegistryOptions {
+    service: string;
+    module: string;
+    environment: string;
+    samplingRate?: number;
+    flushIntervalMs?: number;
+    maxBatchSize?: number;
+    maxQueueSize?: number;
+    redactionKeys?: string[];
+    slo?: {
+        queueUtilizationWarnThreshold?: number;
+        queueDroppedWarnThreshold?: number;
+        alertCooldownMs?: number;
+        onAlert?: (alert: TelemetrySloAlert) => void;
+    };
+}
+export type TelemetrySloAlertType = 'queue.utilization' | 'queue.drop';
+export interface TelemetrySloAlert {
+    timestamp: number;
+    service: string;
+    module: string;
+    environment: string;
+    type: TelemetrySloAlertType;
+    value: number;
+    threshold: number;
+    queueDepth: number;
+    queueCapacity: number;
+    queueUtilization: number;
+    totalDropped: number;
+}
+export interface TelemetryQueueStats {
+    depth: number;
+    capacity: number;
+    utilization: number;
+    pendingDropped: number;
+    totalDropped: number;
+}
+export type TelemetryCanaryState = 'canary' | 'promoted' | 'rolled_back';
+export type TelemetryCanaryAction = 'hold' | 'promote' | 'rollback';
+export type TelemetryCanaryFailureReason = 'queue_utilization' | 'queue_dropped' | 'unhealthy_exporter' | 'contract_gate_missing' | 'contract_gate_failed';
+export interface TelemetryCanaryFailure {
+    reason: TelemetryCanaryFailureReason;
+    gate?: string;
+    message?: string;
+    threshold?: number;
+    value?: number;
+}
+export interface TelemetryCanaryContractGateStatus {
+    name: string;
+    passed: boolean;
+    reason?: string;
+    updatedAt: number;
+}
+export interface TelemetryCanaryDecision {
+    timestamp: number;
+    action: TelemetryCanaryAction;
+    state: TelemetryCanaryState;
+    consecutiveHealthy: number;
+    consecutiveFailures: number;
+    failures: TelemetryCanaryFailure[];
+    queueStats: TelemetryQueueStats;
+    unhealthyExporterCount: number;
+    contractGates: TelemetryCanaryContractGateStatus[];
+}
+export interface TelemetryCanaryStatusSnapshot {
+    timestamp: number;
+    state: TelemetryCanaryState;
+    consecutiveHealthy: number;
+    consecutiveFailures: number;
+    queueStats: TelemetryQueueStats;
+    unhealthyExporterCount: number;
+    requiredContractGates: string[];
+    contractGates: TelemetryCanaryContractGateStatus[];
+    failurePreview: TelemetryCanaryFailure[];
+}
+export interface TelemetryCanaryOrchestratorOptions {
+    registry: TelemetryRegistry;
+    evaluationIntervalMs?: number;
+    minConsecutiveHealthyEvaluations?: number;
+    rollbackConsecutiveFailures?: number;
+    maxQueueUtilization?: number;
+    maxTotalDropped?: number;
+    maxUnhealthyExporters?: number;
+    requiredContractGates?: string[];
+    onEvaluate?: (decision: TelemetryCanaryDecision) => void;
+    onPromote?: (decision: TelemetryCanaryDecision) => void;
+    onRollback?: (decision: TelemetryCanaryDecision) => void;
+}
+export interface TelemetryExporterHealthStatus {
+    name: string;
+    healthy: boolean;
+    failures: number;
+    lastError?: string;
+    lastSuccessAt?: number;
+    lastFailureAt?: number;
+}
+export declare class TelemetryStartupHealthError extends Error {
+    readonly code = "TELEMETRY_EXPORTER_STARTUP_HEALTH_FAILED";
+    readonly failedExporters: TelemetryExporterHealthStatus[];
+    constructor(failedExporters: TelemetryExporterHealthStatus[]);
+}
+export interface OtlpExporterOptions {
+    endpoint?: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}
+export interface VictoriaMetricsExporterOptions extends OtlpExporterOptions {
+    metricPrefix?: string;
+}
+export declare const DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT = "/_modern/contract-gates/runtime-fallback";
+export declare const DEFAULT_RUNTIME_STATUS_ENDPOINT = "/_modern/runtime/status";
+export type RuntimeSignalErrorCode = 'PAYLOAD_TOO_LARGE' | 'INVALID_PAYLOAD' | 'RATE_LIMITED' | 'UNAUTHORIZED' | 'UNTRUSTED_SOURCE';
+export type RuntimeSignalError = Error & {
+    code?: RuntimeSignalErrorCode;
+};
+export type RuntimeFallbackSignalTrustPolicy = {
+    allowedApps: string[];
+    allowedEntryOrigins: string[];
+    expectedRuntimeDigests: Record<string, string>;
+    enforceRuntimeDigest: boolean;
+    maxSignalsPerWindow: number;
+    windowMs: number;
+    dedupeWindowMs: number;
+};
+type RuntimeFallbackSignalRateLimitState = {
+    count: number;
+    windowStartedAt: number;
+};
+export type RuntimeFallbackSignalAuthConfig = {
+    enabled: boolean;
+    headerName: string;
+    expectedValue?: string;
+};
+export type RuntimeFallbackSignalRuntimeState = {
+    rateLimitBySource: Map<string, RuntimeFallbackSignalRateLimitState>;
+    dedupeByFingerprint: Map<string, number>;
+};
+export type RuntimeFallbackSignalTrustContext = {
+    trustPolicy: RuntimeFallbackSignalTrustPolicy;
+    runtimeState: RuntimeFallbackSignalRuntimeState;
+};
+export declare function createOtlpTelemetryExporter(options?: OtlpExporterOptions): TelemetryExporter;
+export declare function createVictoriaMetricsTelemetryExporter(options?: VictoriaMetricsExporterOptions): TelemetryExporter;
+export declare class TelemetryRegistry {
+    private readonly exporters;
+    private readonly queue;
+    private readonly redactionKeys;
+    private readonly service;
+    private readonly module;
+    private readonly environment;
+    private readonly samplingRate;
+    private readonly maxBatchSize;
+    private readonly maxQueueSize;
+    private readonly flushIntervalMs;
+    private readonly flushTimer?;
+    private droppedCount;
+    private totalDroppedCount;
+    private flushing;
+    private readonly exporterHealth;
+    private readonly queueUtilizationWarnThreshold;
+    private readonly queueDroppedWarnThreshold;
+    private readonly alertCooldownMs;
+    private readonly onSloAlert?;
+    private readonly lastSloAlertAt;
+    constructor(options: TelemetryRegistryOptions);
+    register(exporter: TelemetryExporter): Promise<void>;
+    private getOrCreateExporterHealth;
+    private markExporterHealthy;
+    private markExporterFailure;
+    private maybeEmitSloAlert;
+    enqueue(envelope: TelemetryEnvelope): void;
+    enqueueMetric(input: {
+        name: string;
+        value: number;
+        unit?: string;
+        traceId?: string;
+        spanId?: string;
+        parentSpanId?: string;
+        tags?: Record<string, string>;
+        attributes?: Record<string, unknown>;
+    }): void;
+    enqueueLog(input: {
+        name: string;
+        level: string;
+        traceId?: string;
+        spanId?: string;
+        parentSpanId?: string;
+        tags?: Record<string, string>;
+        attributes?: Record<string, unknown>;
+        error?: TelemetryEnvelope['error'];
+    }): void;
+    enqueueTrace(input: {
+        name: string;
+        traceId?: string;
+        spanId?: string;
+        parentSpanId?: string;
+        tags?: Record<string, string>;
+        attributes?: Record<string, unknown>;
+    }): void;
+    private buildDroppedEnvelope;
+    private buildQueueDepthEnvelope;
+    private buildQueueUtilizationEnvelope;
+    private emitBatch;
+    private buildStartupProbeEnvelope;
+    startupHealthCheck(options?: {
+        failLoud?: boolean;
+    }): Promise<void>;
+    getExporterHealth(): TelemetryExporterHealthStatus[];
+    getQueueStats(): TelemetryQueueStats;
+    private flushInternal;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export declare class TelemetryCanaryOrchestrator {
+    private readonly registry;
+    private readonly evaluationIntervalMs;
+    private readonly minConsecutiveHealthyEvaluations;
+    private readonly rollbackConsecutiveFailures;
+    private readonly maxQueueUtilization;
+    private readonly maxTotalDropped;
+    private readonly maxUnhealthyExporters;
+    private requiredContractGates;
+    private readonly onEvaluate?;
+    private readonly onPromote?;
+    private readonly onRollback?;
+    private readonly contractGates;
+    private state;
+    private consecutiveHealthy;
+    private consecutiveFailures;
+    private evaluationTimer?;
+    constructor(options: TelemetryCanaryOrchestratorOptions);
+    setRequiredContractGates(gates: string[]): void;
+    addRequiredContractGate(name: string): void;
+    setContractGate(name: string, passed: boolean, reason?: string): void;
+    setContractGates(gates: Record<string, boolean | {
+        passed: boolean;
+        reason?: string;
+    }>): void;
+    resetToCanary(): void;
+    private collectFailures;
+    evaluate(): TelemetryCanaryDecision;
+    getStatusSnapshot(): TelemetryCanaryStatusSnapshot;
+    start(): void;
+    stop(): void;
+}
+export declare const createTelemetryAwareMetrics: <T extends Metrics>(baseMetrics: T, registry: TelemetryRegistry) => T;
+export declare function resolveRuntimeFallbackSignalEndpoint(configuredEndpoint?: string): string;
+export declare function createRuntimeSignalError(message: string, code: RuntimeSignalError['code']): RuntimeSignalError;
+export declare function normalizeRuntimeFallbackSignalAuthConfig(configured: {
+    enabled?: boolean;
+    headerName?: string;
+    expectedValue?: string;
+    expectedValueEnv?: string;
+} | undefined): RuntimeFallbackSignalAuthConfig;
+export declare function enforceRuntimeFallbackSignalAuthToken(token: string | undefined, authConfig: RuntimeFallbackSignalAuthConfig): void;
+export declare function normalizeRuntimeFallbackTrustPolicy(configured: {
+    allowedApps?: string[];
+    allowedEntryOrigins?: string[];
+    expectedRuntimeDigests?: Record<string, string>;
+    enforceRuntimeDigest?: boolean;
+    maxSignalsPerWindow?: number;
+    windowMs?: number;
+    dedupeWindowMs?: number;
+} | undefined): RuntimeFallbackSignalTrustPolicy;
+export declare function createRuntimeFallbackSignalRuntimeState(): RuntimeFallbackSignalRuntimeState;
+export declare function enforceRuntimeFallbackSignalTrustPolicy(payload: Record<string, unknown>, runtimeSignalContext: RuntimeFallbackSignalTrustContext): {
+    deduped: boolean;
+};
+export declare function parseRuntimeFallbackSignalPayloadFromRawBody(rawBody: string, maxBodyBytes: number): Record<string, unknown>;
+export declare function getRuntimeSignalErrorStatusCode(signalError: RuntimeSignalError): 400 | 401 | 403 | 413 | 429 | 500;
+export declare const hasEnabledTelemetryExporters: (config: ServerTelemetryUserConfig | undefined) => boolean;
+export declare const injectTelemetryPlugin: () => ServerPlugin;
+export {};

package/dist/types/serverBase.d.ts

@@ -0,0 +1,38 @@
+import { type ServerCreateOptions } from '@modern-js/plugin/server';
+import type { Env, ServerConfig, ServerPlugin, ServerPluginHooks } from './types';
+import type { CliConfig } from './types/config';
+export interface ServerBaseOptions extends ServerCreateOptions {
+    /** server working directory, and then also dist directory */
+    config: CliConfig;
+    serverConfig?: ServerConfig;
+    runMode?: 'apiOnly' | 'ssrOnly' | 'webOnly';
+}
+export declare class ServerBase<E extends Env = any> {
+    #private;
+    serverOptions: ServerBaseOptions;
+    private app;
+    private plugins;
+    private serverContext;
+    constructor(options: ServerBaseOptions);
+    /**
+     * Order
+     * - server runner
+     * - apply middlewares
+     */
+    init(): Promise<this>;
+    addPlugins(plugins: ServerPlugin[]): void;
+    get hooks(): ServerPluginHooks;
+    get all(): import("hono/types").HandlerInterface<E, "all", import("hono/types").BlankSchema, "/", "/">;
+    get use(): import("hono/types").MiddlewareHandlerInterface<E, import("hono/types").BlankSchema, "/">;
+    get get(): import("hono/types").HandlerInterface<E, "get", import("hono/types").BlankSchema, "/", "/">;
+    get options(): import("hono/types").HandlerInterface<E, "options", import("hono/types").BlankSchema, "/", "/">;
+    get post(): import("hono/types").HandlerInterface<E, "post", import("hono/types").BlankSchema, "/", "/">;
+    get put(): import("hono/types").HandlerInterface<E, "put", import("hono/types").BlankSchema, "/", "/">;
+    get delete(): import("hono/types").HandlerInterface<E, "delete", import("hono/types").BlankSchema, "/", "/">;
+    get patch(): import("hono/types").HandlerInterface<E, "patch", import("hono/types").BlankSchema, "/", "/">;
+    get handle(): (request: Request, Env?: {} | E["Bindings"] | undefined, executionCtx?: import("hono").ExecutionContext) => Response | Promise<Response>;
+    get request(): (input: Request | string | URL, requestInit?: RequestInit, Env?: {} | E["Bindings"] | undefined, executionCtx?: import("hono").ExecutionContext) => Response | Promise<Response>;
+    get notFound(): (handler: import("hono").NotFoundHandler<E>) => import("hono/hono-base").HonoBase<E, import("hono/types").BlankSchema, "/", "/">;
+    get onError(): (handler: import("hono").ErrorHandler<E>) => import("hono/hono-base").HonoBase<E, import("hono/types").BlankSchema, "/", "/">;
+}
+export declare function createServerBase<E extends Env>(options: ServerBaseOptions): ServerBase<E>;

package/dist/types/types/config/bff.d.ts

@@ -0,0 +1,142 @@
+import type { HttpMethodDecider } from '@modern-js/types';
+export type BffRuntimeFramework = 'hono' | 'effect';
+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 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;
+    openapi?: BffEffectOpenApiUserConfig;
+    dataPlatform?: BffEffectDataPlatformUserConfig;
+}
+export interface BffUserConfig {
+    prefix?: string | string[];
+    httpMethodDecider?: HttpMethodDecider;
+    enableHandleWeb?: boolean;
+    /**
+     * Enables cross-project BFF SDK generation for producer apps.
+     */
+    crossProject?: boolean;
+    /**
+     * Internal marker injected by generated cross-project SDK plugins.
+     */
+    isCrossProjectServer?: boolean;
+    /**
+     * Logical producer ID forwarded to generated clients and runtime contracts.
+     */
+    requestId?: string;
+    /**
+     * Legacy request runtime import path. Internal/compatibility usage.
+     */
+    runtimeCreateRequest?: string;
+    /**
+     * Custom request creator import path for generated BFF clients.
+     */
+    requestCreator?: string;
+    /**
+     * Legacy custom fetcher import path for generated BFF clients.
+     */
+    fetcher?: string;
+    /**
+     * Selects the BFF runtime implementation.
+     *
+     * - `effect`: only `api/effect/index` is served.
+     * - `hono`: only `api/lambda/**` handlers are served.
+     *
+     * @default 'effect'
+     */
+    runtimeFramework?: BffRuntimeFramework;
+    /**
+     * Effect runtime configuration. Only applies when `runtimeFramework: 'effect'`.
+     */
+    effect?: BffEffectUserConfig;
+    crossProjectPolicy?: BffCrossProjectPolicyUserConfig;
+}
+export type BffNormalizedConfig = BffUserConfig;

package/dist/types/types/config/dev.d.ts

@@ -0,0 +1,4 @@
+export interface DevUserConfig {
+    assetPrefix?: string;
+}
+export type DevNormalizedConfig = DevUserConfig;

package/dist/types/types/config/html.d.ts

@@ -0,0 +1,15 @@
+export type CrossOrigin = 'anonymous' | 'use-credentials';
+export type ScriptLoading = 'defer' | 'module' | 'blocking';
+export interface HtmlUserConfig {
+    favicon?: string;
+    /**
+     * Set the [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) attribute
+     * of the `<script>` tag.
+     */
+    crossorigin?: boolean | CrossOrigin;
+    /**
+     * Set the loading mode of the `<script>` tag.
+     */
+    scriptLoading?: ScriptLoading;
+}
+export type HtmlNormalizedConfig = HtmlUserConfig;

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

@@ -0,0 +1,35 @@
+import type { BffNormalizedConfig, BffUserConfig } from './bff';
+import type { DevNormalizedConfig, DevUserConfig } from './dev';
+import type { HtmlNormalizedConfig, HtmlUserConfig } from './html';
+import type { OutputNormalizedConfig, OutputUserConfig } from './output';
+import type { SecurityNormalizedConfig, SecurityUserConfig } from './security';
+import type { ServerNormalizedConfig, ServerUserConfig } from './server';
+import type { SourceNormalizedConfig, SourceUserConfig } from './source';
+import type { ToolsNormalizedConfig, ToolsUserConfig } from './tools';
+export * from './bff';
+export * from './html';
+export * from './output';
+export * from './server';
+export * from './source';
+export * from './tools';
+export interface UserConfig {
+    output?: OutputUserConfig;
+    source?: SourceUserConfig;
+    tools?: ToolsUserConfig;
+    server?: ServerUserConfig;
+    html?: HtmlUserConfig;
+    bff?: BffUserConfig;
+    dev?: DevUserConfig;
+    security?: SecurityUserConfig;
+}
+export type ServerOptions = {
+    output: OutputNormalizedConfig;
+    source: SourceNormalizedConfig;
+    tools: ToolsNormalizedConfig;
+    server: ServerNormalizedConfig;
+    html: HtmlNormalizedConfig;
+    bff: BffNormalizedConfig;
+    dev?: DevNormalizedConfig;
+    security?: SecurityNormalizedConfig;
+};
+export type CliConfig = Required<UserConfig>;

package/dist/types/types/config/output.d.ts

@@ -0,0 +1,20 @@
+export interface OutputUserConfig {
+    distPath?: {
+        root?: string;
+        js?: string;
+        css?: string;
+        svg?: string;
+        font?: string;
+        html?: string;
+        image?: string;
+        media?: string;
+        server?: string;
+    };
+    enableInlineRouteManifests?: boolean;
+    disableInlineRouteManifests?: boolean;
+    assetPrefix?: string;
+    polyfill?: 'entry' | 'usage' | 'ua' | 'off';
+    inlineScripts?: boolean;
+    inlineStyles?: boolean;
+}
+export type OutputNormalizedConfig = OutputUserConfig;

package/dist/types/types/config/security.d.ts

@@ -0,0 +1,4 @@
+export interface SecurityUserConfig {
+    nonce?: string;
+}
+export type SecurityNormalizedConfig = SecurityUserConfig;