@bleedingdev/modern-js-server-runtime-extensions 0.0.0-trusted-publisher-bootstrap

package/src/contractGateSnapshotStore.ts

@@ -0,0 +1,420 @@
+import { createRequire } from 'node:module';
+import { fs } from '@modern-js/utils';
+import { promises as nodeFs } from 'fs';
+import path from 'path';
+import { parseServerRuntimeExtensionsEnv } from './env';
+
+export const CONTRACT_GATE_SNAPSHOT_SCHEMA_VERSION = 1;
+export const DEFAULT_CONTRACT_GATE_SNAPSHOT_PATH =
+  '.modern/contract-gates.json';
+
+export type GateSnapshotGateValue =
+  | boolean
+  | {
+      passed?: boolean;
+      reason?: string;
+      updatedAt?: number;
+      expiresAt?: number;
+      [key: string]: unknown;
+    };
+
+export type GateSnapshot = {
+  schemaVersion?: number;
+  updatedAt?: number;
+  gates?: Record<string, GateSnapshotGateValue>;
+};
+
+type LoggerLike = {
+  info?: (message: string) => void;
+  warn?: (message: string) => void;
+};
+
+export type ContractGateSnapshotStore = {
+  name: string;
+  readSnapshot: () => Promise<GateSnapshot | undefined>;
+  writeSnapshot: (snapshot: GateSnapshot) => Promise<void>;
+};
+
+export type ContractGateSnapshotStoreFactoryContext = {
+  appDirectory: string;
+  gateSnapshotPath: string;
+  options?: Record<string, unknown>;
+  logger?: LoggerLike;
+};
+
+export type ContractGateSnapshotStoreFactory = (
+  context: ContractGateSnapshotStoreFactoryContext,
+) => Promise<ContractGateSnapshotStore> | ContractGateSnapshotStore;
+
+export type ContractGateSnapshotStoreModule = {
+  createContractGateSnapshotStore?: ContractGateSnapshotStoreFactory;
+  default?:
+    | ContractGateSnapshotStoreFactory
+    | {
+        createContractGateSnapshotStore?: ContractGateSnapshotStoreFactory;
+      };
+};
+
+export type ContractGateSnapshotStoreUserConfig = {
+  module: string;
+  options?: Record<string, unknown>;
+};
+
+export type ContractGateSnapshotHttpStoreOptions = {
+  endpoint: string;
+  readMethod?: string;
+  writeMethod?: string;
+  headers?: Record<string, string>;
+  timeoutMs?: number;
+};
+
+const DEFAULT_HTTP_STORE_TIMEOUT_MS = 5_000;
+const BUILTIN_HTTP_STATE_STORE_MODULES = new Set([
+  'http',
+  // historical aliases kept for config compatibility with the era when these
+  // modules lived inside @modern-js/server-core.
+  '@modern-js/server-core/http',
+  '@modern-js/server-core/contract-gate-http-store',
+  '@modern-js/server-runtime-extensions/http',
+  '@modern-js/server-runtime-extensions/contract-gate-http-store',
+]);
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const normalizeSnapshot = (snapshot: unknown): GateSnapshot | undefined => {
+  if (!isRecord(snapshot)) {
+    return undefined;
+  }
+
+  const schemaVersion =
+    typeof snapshot.schemaVersion === 'number'
+      ? snapshot.schemaVersion
+      : CONTRACT_GATE_SNAPSHOT_SCHEMA_VERSION;
+  const updatedAt =
+    typeof snapshot.updatedAt === 'number' ? snapshot.updatedAt : Date.now();
+  const gates = isRecord(snapshot.gates)
+    ? (snapshot.gates as Record<string, GateSnapshotGateValue>)
+    : {};
+
+  return {
+    schemaVersion,
+    updatedAt,
+    gates,
+  };
+};
+
+const normalizeHttpStoreOptions = (
+  options: Record<string, unknown> | undefined,
+): ContractGateSnapshotHttpStoreOptions => {
+  const endpoint =
+    typeof options?.endpoint === 'string' ? options.endpoint.trim() : '';
+  if (!endpoint) {
+    throw new Error(
+      '[telemetry.canary.autopilot] HTTP stateStore requires options.endpoint',
+    );
+  }
+
+  const readMethod =
+    typeof options?.readMethod === 'string' && options.readMethod.trim()
+      ? options.readMethod.trim().toUpperCase()
+      : 'GET';
+  const writeMethod =
+    typeof options?.writeMethod === 'string' && options.writeMethod.trim()
+      ? options.writeMethod.trim().toUpperCase()
+      : 'PUT';
+
+  const timeoutMsRaw = Number(options?.timeoutMs);
+  const timeoutMs =
+    Number.isFinite(timeoutMsRaw) && timeoutMsRaw > 0
+      ? Math.floor(timeoutMsRaw)
+      : DEFAULT_HTTP_STORE_TIMEOUT_MS;
+
+  const headersRaw = options?.headers;
+  const headers: Record<string, string> = {};
+  if (
+    headersRaw &&
+    typeof headersRaw === 'object' &&
+    !Array.isArray(headersRaw)
+  ) {
+    Object.entries(headersRaw).forEach(([key, value]) => {
+      if (typeof key === 'string' && key.trim().length > 0 && value != null) {
+        headers[key] = String(value);
+      }
+    });
+  }
+
+  return {
+    endpoint,
+    readMethod,
+    writeMethod,
+    headers,
+    timeoutMs,
+  };
+};
+
+const withTimeoutAbort = (timeoutMs: number) => {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  return {
+    signal: controller.signal,
+    clear: () => clearTimeout(timer),
+  };
+};
+
+export const createHttpContractGateSnapshotStore = (
+  options: ContractGateSnapshotHttpStoreOptions,
+): ContractGateSnapshotStore => {
+  const normalized = normalizeHttpStoreOptions(
+    options as unknown as Record<string, unknown>,
+  );
+  const endpoint = normalized.endpoint;
+
+  return {
+    name: `http:${endpoint}`,
+    async readSnapshot() {
+      const { signal, clear } = withTimeoutAbort(normalized.timeoutMs || 5_000);
+      try {
+        const response = await fetch(endpoint, {
+          method: normalized.readMethod || 'GET',
+          headers: {
+            accept: 'application/json',
+            ...(normalized.headers || {}),
+          },
+          signal,
+        });
+
+        if (response.status === 404) {
+          return undefined;
+        }
+
+        if (!response.ok) {
+          throw new Error(
+            `HTTP stateStore read failed with status ${String(response.status)}`,
+          );
+        }
+
+        const payload = await response.json();
+        return normalizeSnapshot(payload);
+      } finally {
+        clear();
+      }
+    },
+    async writeSnapshot(snapshot) {
+      const body = JSON.stringify(
+        normalizeSnapshot(snapshot) || {
+          schemaVersion: CONTRACT_GATE_SNAPSHOT_SCHEMA_VERSION,
+          updatedAt: Date.now(),
+          gates: {},
+        },
+      );
+      const { signal, clear } = withTimeoutAbort(normalized.timeoutMs || 5_000);
+      try {
+        const response = await fetch(endpoint, {
+          method: normalized.writeMethod || 'PUT',
+          headers: {
+            'content-type': 'application/json',
+            ...(normalized.headers || {}),
+          },
+          body,
+          signal,
+        });
+        if (!response.ok) {
+          throw new Error(
+            `HTTP stateStore write failed with status ${String(response.status)}`,
+          );
+        }
+      } finally {
+        clear();
+      }
+    },
+  };
+};
+
+const tryResolveBuiltinSnapshotStore = (input: {
+  stateStore: ContractGateSnapshotStoreUserConfig;
+}): ContractGateSnapshotStore | undefined => {
+  const moduleName = input.stateStore.module.trim();
+  if (!BUILTIN_HTTP_STATE_STORE_MODULES.has(moduleName)) {
+    return undefined;
+  }
+
+  return createHttpContractGateSnapshotStore(
+    (input.stateStore.options || {}) as ContractGateSnapshotHttpStoreOptions,
+  );
+};
+
+const pickStoreFactory = (
+  mod: ContractGateSnapshotStoreModule,
+): ContractGateSnapshotStoreFactory | undefined => {
+  if (typeof mod === 'function') {
+    return mod as unknown as ContractGateSnapshotStoreFactory;
+  }
+
+  if (typeof mod.createContractGateSnapshotStore === 'function') {
+    return mod.createContractGateSnapshotStore;
+  }
+
+  if (typeof mod.default === 'function') {
+    return mod.default;
+  }
+
+  if (
+    mod.default &&
+    typeof mod.default === 'object' &&
+    typeof mod.default.createContractGateSnapshotStore === 'function'
+  ) {
+    return mod.default.createContractGateSnapshotStore;
+  }
+
+  return undefined;
+};
+
+const ensureStoreShape = (
+  store: ContractGateSnapshotStore,
+  modulePath: string,
+) => {
+  if (
+    !store ||
+    typeof store !== 'object' ||
+    typeof store.readSnapshot !== 'function' ||
+    typeof store.writeSnapshot !== 'function'
+  ) {
+    throw new Error(
+      `Invalid contract gate snapshot store from "${modulePath}". Expected { readSnapshot(), writeSnapshot() }.`,
+    );
+  }
+};
+
+/**
+ * Resolves a user-configured stateStore module specifier from the app, not
+ * from this framework package: relative paths resolve against appDirectory,
+ * and bare package specifiers resolve through the app's own module graph
+ * (`createRequire` anchored at the app package.json). Resolving from the
+ * framework package breaks app-installed stores under pnpm's strict
+ * node_modules layout. Bare specifiers fall back to framework-local
+ * resolution for stores installed alongside the framework.
+ */
+const resolveStoreModulePath = (appDirectory: string, modulePath: string) => {
+  const normalized = modulePath.trim();
+  if (!normalized) {
+    throw new Error(
+      'Contract gate snapshot stateStore.module must be non-empty',
+    );
+  }
+
+  if (path.isAbsolute(normalized)) {
+    return normalized;
+  }
+
+  if (normalized.startsWith('.')) {
+    return path.resolve(appDirectory, normalized);
+  }
+
+  const appRequire = createRequire(path.join(appDirectory, 'package.json'));
+  try {
+    return appRequire.resolve(normalized);
+  } catch (_error) {
+    // Fall back to this package's own resolution so stores installed next to
+    // the framework keep working.
+    return normalized;
+  }
+};
+
+export const resolveContractGateSnapshotPath = (
+  appDirectory: string,
+  configuredPath: string | undefined,
+) => {
+  const rawPath =
+    configuredPath ||
+    parseServerRuntimeExtensionsEnv().contractGatesFile ||
+    DEFAULT_CONTRACT_GATE_SNAPSHOT_PATH;
+  if (path.isAbsolute(rawPath)) {
+    return rawPath;
+  }
+  return path.resolve(appDirectory, rawPath);
+};
+
+export const createFileContractGateSnapshotStore = (
+  gateSnapshotPath: string,
+): ContractGateSnapshotStore => {
+  const resolvedPath = path.resolve(gateSnapshotPath);
+  return {
+    name: `file:${resolvedPath}`,
+    async readSnapshot() {
+      if (!(await fs.pathExists(resolvedPath))) {
+        return undefined;
+      }
+
+      try {
+        const raw = await nodeFs.readFile(resolvedPath, 'utf8');
+        return normalizeSnapshot(JSON.parse(raw));
+      } catch (_error) {
+        return undefined;
+      }
+    },
+    async writeSnapshot(snapshot) {
+      const normalized = normalizeSnapshot(snapshot) || {
+        schemaVersion: CONTRACT_GATE_SNAPSHOT_SCHEMA_VERSION,
+        updatedAt: Date.now(),
+        gates: {},
+      };
+      await nodeFs.mkdir(path.dirname(resolvedPath), { recursive: true });
+      await nodeFs.writeFile(
+        resolvedPath,
+        `${JSON.stringify(normalized, null, 2)}\n`,
+      );
+    },
+  };
+};
+
+export const resolveContractGateSnapshotStore = async (input: {
+  appDirectory: string;
+  gateSnapshotPath: string;
+  stateStore?: ContractGateSnapshotStoreUserConfig;
+  logger?: LoggerLike;
+}): Promise<ContractGateSnapshotStore> => {
+  const { appDirectory, gateSnapshotPath, stateStore, logger } = input;
+
+  if (!stateStore?.module) {
+    return createFileContractGateSnapshotStore(gateSnapshotPath);
+  }
+
+  const builtinStore = tryResolveBuiltinSnapshotStore({ stateStore });
+  if (builtinStore) {
+    logger?.info?.(
+      `[telemetry.canary.autopilot] using built-in contract gate snapshot store "${builtinStore.name}"`,
+    );
+    return builtinStore;
+  }
+
+  const modulePath = resolveStoreModulePath(appDirectory, stateStore.module);
+  let mod: ContractGateSnapshotStoreModule;
+  try {
+    // eslint-disable-next-line import/no-dynamic-require,global-require
+    mod = require(modulePath) as ContractGateSnapshotStoreModule;
+  } catch (error) {
+    throw new Error(
+      `[telemetry.canary.autopilot] Failed to load stateStore.module "${stateStore.module}" (${modulePath}): ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  const factory = pickStoreFactory(mod);
+  if (!factory) {
+    throw new Error(
+      `[telemetry.canary.autopilot] stateStore.module "${stateStore.module}" does not export createContractGateSnapshotStore()`,
+    );
+  }
+
+  const store = await factory({
+    appDirectory,
+    gateSnapshotPath,
+    options: stateStore.options,
+    logger,
+  });
+  ensureStoreShape(store, modulePath);
+  logger?.info?.(
+    `[telemetry.canary.autopilot] using contract gate snapshot store "${store.name || modulePath}"`,
+  );
+  return store;
+};

package/src/env.ts

@@ -0,0 +1,63 @@
+/**
+ * Single typed pass over the statically-known environment variables consumed
+ * by the ultramodern.js server runtime extensions (telemetry pipeline and
+ * contract-gate canary autopilot).
+ *
+ * Modules in this package read this environment state through
+ * `parseServerRuntimeExtensionsEnv()` so the surface is documented and
+ * testable in one place, with one documented exception: the telemetry
+ * runtime-fallback-signal auth config can name an arbitrary token variable
+ * via `auth.expectedValueEnv`, which is necessarily read dynamically from
+ * `process.env` when that config is normalized. See the package README for
+ * per-variable docs.
+ */
+
+export const DEFAULT_ENVIRONMENT_NAME = 'development';
+
+export interface ServerRuntimeExtensionsEnv {
+  /**
+   * `MODERN_ENV` — deployment environment name loaded by the Modern.js env
+   * bootstrap (`.env.{MODERN_ENV}`). Undefined when unset or blank.
+   */
+  modernEnv?: string;
+  /** `NODE_ENV` — standard Node.js environment name. Undefined when unset or blank. */
+  nodeEnv?: string;
+  /**
+   * Effective telemetry environment label:
+   * `MODERN_ENV` || `NODE_ENV` || `"development"`.
+   */
+  environmentName: string;
+  /**
+   * `MODERN_CONTRACT_GATES_FILE` — path of the contract-gate snapshot file
+   * (absolute, or relative to the app directory). Undefined when unset.
+   */
+  contractGatesFile?: string;
+}
+
+const readString = (value: string | undefined): string | undefined => {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+};
+
+/**
+ * Parse the statically-known environment variables consumed by this package
+ * in one typed, documented pass. Defaults are applied here so consumers never
+ * touch `process.env` directly (except the documented `expectedValueEnv`
+ * indirection above).
+ */
+export const parseServerRuntimeExtensionsEnv = (
+  env: Record<string, string | undefined> = process.env,
+): ServerRuntimeExtensionsEnv => {
+  const modernEnv = readString(env.MODERN_ENV);
+  const nodeEnv = readString(env.NODE_ENV);
+
+  return {
+    modernEnv,
+    nodeEnv,
+    environmentName: modernEnv || nodeEnv || DEFAULT_ENVIRONMENT_NAME,
+    contractGatesFile: readString(env.MODERN_CONTRACT_GATES_FILE),
+  };
+};

package/src/index.ts

@@ -0,0 +1,84 @@
+export {
+  ContractGateAutopilot,
+  type ContractGateAutopilotOptions,
+} from './contractGateAutopilot';
+export {
+  CONTRACT_GATE_SNAPSHOT_SCHEMA_VERSION,
+  type ContractGateSnapshotHttpStoreOptions,
+  type ContractGateSnapshotStore,
+  type ContractGateSnapshotStoreFactory,
+  type ContractGateSnapshotStoreFactoryContext,
+  type ContractGateSnapshotStoreModule,
+  type ContractGateSnapshotStoreUserConfig,
+  createFileContractGateSnapshotStore,
+  createHttpContractGateSnapshotStore,
+  DEFAULT_CONTRACT_GATE_SNAPSHOT_PATH,
+  type GateSnapshot,
+  type GateSnapshotGateValue,
+  resolveContractGateSnapshotPath,
+  resolveContractGateSnapshotStore,
+} from './contractGateSnapshotStore';
+export {
+  DEFAULT_ENVIRONMENT_NAME,
+  parseServerRuntimeExtensionsEnv,
+  type ServerRuntimeExtensionsEnv,
+} from './env';
+export {
+  getRequestPathname,
+  injectMfAssetCacheHeadersPlugin,
+  isMfManifestAsset,
+  isMfRemoteEntryAsset,
+  resolveMfAssetCacheHeaders,
+} from './mfCache';
+export {
+  type CollectDirectRemoteModuleFederationCssOptions,
+  collectDirectRemoteModuleFederationCss,
+  collectDirectRemoteModuleFederationCssWithMeta,
+  collectModuleFederationManifestCss,
+  createModuleFederationCssCollector,
+  injectModuleFederationCssPlugin,
+  type ModuleFederationCssCollectorOptions,
+  type ModuleFederationCssPluginOptions,
+  type ModuleFederationManifest,
+  type RemoteModuleFederationCssCollection,
+} from './moduleFederationCss';
+export {
+  createOtlpTelemetryExporter,
+  createRuntimeFallbackSignalRuntimeState,
+  createRuntimeSignalError,
+  createTelemetryAwareMetrics,
+  createVictoriaMetricsTelemetryExporter,
+  DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT,
+  DEFAULT_RUNTIME_STATUS_ENDPOINT,
+  enforceRuntimeFallbackSignalAuthToken,
+  enforceRuntimeFallbackSignalTrustPolicy,
+  getRuntimeSignalErrorStatusCode,
+  hasEnabledTelemetryExporters,
+  injectTelemetryPlugin,
+  normalizeRequiredRuntimeFallbackSignalAuthConfig,
+  normalizeRuntimeFallbackSignalAuthConfig,
+  normalizeRuntimeFallbackTrustPolicy,
+  type OtlpExporterOptions,
+  parseRuntimeFallbackSignalPayloadFromRawBody,
+  type RuntimeFallbackSignalAuthConfig,
+  type RuntimeFallbackSignalRuntimeState,
+  type RuntimeFallbackSignalSource,
+  type RuntimeFallbackSignalTrustContext,
+  type RuntimeFallbackSignalTrustPolicy,
+  type RuntimeSignalError,
+  type RuntimeSignalErrorCode,
+  resolveRuntimeFallbackSignalEndpoint,
+  resolveTelemetrySloOptions,
+  type TelemetryCanaryDecision,
+  TelemetryCanaryOrchestrator,
+  type TelemetryCanaryStatusSnapshot,
+  type TelemetryEnvelope,
+  type TelemetryExporter,
+  type TelemetryQueueStats,
+  TelemetryRegistry,
+  type TelemetryRegistryOptions,
+  type TelemetrySignalType,
+  type TelemetrySloAlert,
+  TelemetryStartupHealthError,
+  type VictoriaMetricsExporterOptions,
+} from './telemetry';

package/src/mfCache.ts

@@ -0,0 +1,119 @@
+import type {
+  Middleware,
+  ServerEnv,
+  ServerPlugin,
+} from '@modern-js/server-core';
+
+const REMOTE_ENTRY_REGEXP = /(^|\/)remoteEntry(?:\.[a-zA-Z0-9_-]+)?\.js$/;
+
+function firstQueryValue(value: unknown): string | undefined {
+  if (Array.isArray(value)) {
+    return value.find(item => typeof item === 'string' && item.length > 0);
+  }
+  if (typeof value === 'string' && value.length > 0) {
+    return value;
+  }
+  return undefined;
+}
+
+export function getRequestPathname(url: string) {
+  try {
+    return new URL(url, 'http://modernjs.local').pathname;
+  } catch (_error) {
+    return url.split('?')[0] || '/';
+  }
+}
+
+export function isMfManifestAsset(pathname: string) {
+  return (
+    pathname.endsWith('/mf-manifest.json') ||
+    pathname.endsWith('/mf-stats.json')
+  );
+}
+
+export function isMfRemoteEntryAsset(pathname: string) {
+  return REMOTE_ENTRY_REGEXP.test(pathname);
+}
+
+function hasRemoteVersionPin(query: Record<string, unknown> = {}) {
+  return Boolean(
+    firstQueryValue(query.mfv) ||
+      firstQueryValue(query.v) ||
+      firstQueryValue(query.version),
+  );
+}
+
+export function resolveMfAssetCacheHeaders(
+  url: string,
+  query: Record<string, unknown> = {},
+) {
+  const pathname = getRequestPathname(url);
+
+  if (isMfManifestAsset(pathname)) {
+    return {
+      'cache-control': 'no-cache, no-store, must-revalidate',
+      pragma: 'no-cache',
+      expires: '0',
+    };
+  }
+
+  if (isMfRemoteEntryAsset(pathname)) {
+    return hasRemoteVersionPin(query)
+      ? {
+          'cache-control': 'public, max-age=31536000, immutable',
+        }
+      : {
+          'cache-control': 'public, max-age=0, must-revalidate',
+        };
+  }
+
+  return undefined;
+}
+
+/**
+ * Applies the documented MF asset cache-header policy (ADR-0002) to responses
+ * for module federation manifest/remoteEntry endpoints:
+ *
+ * - `mf-manifest.json` / `mf-stats.json` are never cached (`no-store`), so
+ *   hosts always observe remote redeploys;
+ * - `remoteEntry*.js` revalidates unless explicitly version-pinned via a
+ *   `mfv`/`v`/`version` query parameter, in which case it is immutable.
+ *
+ * Registered by @modern-js/prod-server next to the other fork plugins; the
+ * middleware runs in the `pre` phase so it wraps the static-file middleware
+ * that actually serves these assets.
+ */
+export const injectMfAssetCacheHeadersPlugin = (): ServerPlugin => ({
+  name: '@modern-js/inject-mf-asset-cache-headers',
+
+  setup(api) {
+    api.onPrepare(() => {
+      const { middlewares } = api.getServerContext();
+
+      const handler: Middleware<ServerEnv> = async (c, next) => {
+        await next();
+
+        // Never attach cache policies to error responses: an `immutable`
+        // 404 remoteEntry could otherwise be cached for a year.
+        if (!c.res || c.res.status >= 400) {
+          return;
+        }
+
+        const headers = resolveMfAssetCacheHeaders(c.req.path, c.req.query());
+        if (!headers) {
+          return;
+        }
+
+        for (const [name, value] of Object.entries(headers)) {
+          c.res.headers.set(name, value);
+        }
+      };
+
+      middlewares.push({
+        name: 'mf-asset-cache-headers',
+        handler,
+        order: 'pre',
+      });
+    });
+  },
+});