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

package/tests/telemetryCanaryOrchestrator.test.ts

@@ -0,0 +1,140 @@
+import {
+  TelemetryCanaryOrchestrator,
+  type TelemetryEnvelope,
+  TelemetryRegistry,
+} from '../src/telemetry';
+
+const createEnvelope = (
+  partial: Partial<TelemetryEnvelope> = {},
+): TelemetryEnvelope => ({
+  timestamp: Date.now(),
+  service: 'svc',
+  module: 'server',
+  environment: 'test',
+  signalType: 'metric',
+  name: 'server.handle.request',
+  value: 10,
+  unit: 'ms',
+  ...partial,
+});
+
+describe('telemetry canary orchestrator', () => {
+  test('supports dynamic required contract gate registration', async () => {
+    const registry = new TelemetryRegistry({
+      service: 'svc',
+      module: 'server',
+      environment: 'test',
+      flushIntervalMs: 60_000,
+    });
+
+    const orchestrator = new TelemetryCanaryOrchestrator({
+      registry,
+      rollbackConsecutiveFailures: 1,
+    });
+
+    orchestrator.addRequiredContractGate('runtime-contracts');
+    const missingDecision = orchestrator.evaluate();
+    expect(missingDecision.action).toBe('rollback');
+    expect(
+      missingDecision.failures.some(
+        item =>
+          item.reason === 'contract_gate_missing' &&
+          item.gate === 'runtime-contracts',
+      ),
+    ).toBe(true);
+
+    orchestrator.resetToCanary();
+    orchestrator.setContractGate('runtime-contracts', true);
+    const passingDecision = orchestrator.evaluate();
+    expect(passingDecision.failures).toHaveLength(0);
+
+    await registry.shutdown();
+  });
+
+  test('promotes when telemetry and contract gates stay healthy', async () => {
+    const registry = new TelemetryRegistry({
+      service: 'svc',
+      module: 'server',
+      environment: 'test',
+      flushIntervalMs: 60_000,
+    });
+    await registry.register({
+      name: 'memory',
+      async emit() {
+        // noop
+      },
+    });
+
+    const onPromote = rs.fn();
+    const orchestrator = new TelemetryCanaryOrchestrator({
+      registry,
+      minConsecutiveHealthyEvaluations: 2,
+      requiredContractGates: ['contracts'],
+      onPromote,
+    });
+    orchestrator.setContractGate('contracts', true);
+
+    expect(orchestrator.evaluate().action).toBe('hold');
+    const decision = orchestrator.evaluate();
+    expect(decision.action).toBe('promote');
+    expect(decision.state).toBe('promoted');
+    expect(onPromote).toHaveBeenCalledTimes(1);
+
+    await registry.shutdown();
+  });
+
+  test('rolls back after consecutive contract gate failures', async () => {
+    const registry = new TelemetryRegistry({
+      service: 'svc',
+      module: 'server',
+      environment: 'test',
+      flushIntervalMs: 60_000,
+    });
+
+    const onRollback = rs.fn();
+    const orchestrator = new TelemetryCanaryOrchestrator({
+      registry,
+      requiredContractGates: ['contracts'],
+      rollbackConsecutiveFailures: 2,
+      onRollback,
+    });
+    orchestrator.setContractGate('contracts', false, 'schema drift');
+
+    expect(orchestrator.evaluate().action).toBe('hold');
+    const decision = orchestrator.evaluate();
+    expect(decision.action).toBe('rollback');
+    expect(decision.state).toBe('rolled_back');
+    expect(
+      decision.failures.some(item => item.reason === 'contract_gate_failed'),
+    ).toBe(true);
+    expect(onRollback).toHaveBeenCalledTimes(1);
+
+    await registry.shutdown();
+  });
+
+  test('rolls back immediately when queue dropped budget is exceeded', async () => {
+    const registry = new TelemetryRegistry({
+      service: 'svc',
+      module: 'server',
+      environment: 'test',
+      maxQueueSize: 2,
+      flushIntervalMs: 60_000,
+    });
+    registry.enqueue(createEnvelope({ name: 'a' }));
+    registry.enqueue(createEnvelope({ name: 'b' }));
+    registry.enqueue(createEnvelope({ name: 'c' }));
+
+    const orchestrator = new TelemetryCanaryOrchestrator({
+      registry,
+      maxTotalDropped: 0,
+      rollbackConsecutiveFailures: 1,
+    });
+    const decision = orchestrator.evaluate();
+    expect(decision.action).toBe('rollback');
+    expect(
+      decision.failures.some(item => item.reason === 'queue_dropped'),
+    ).toBe(true);
+
+    await registry.shutdown();
+  });
+});

package/tests/telemetryLifecycle.test.ts

@@ -0,0 +1,168 @@
+import { EventEmitter } from 'node:events';
+import {
+  createDefaultPlugins,
+  createServerBase,
+  type ServerPlugin,
+} from '@modern-js/server-core';
+import { logger } from '@modern-js/utils';
+import { injectTelemetryPlugin } from '../src/telemetry';
+import { getDefaultAppContext, getDefaultConfig } from './helpers';
+
+const emitMonitorEventsPlugin = (input: {
+  path: string;
+  message: string;
+  count: number;
+}): ServerPlugin => ({
+  name: 'emit-monitor-events',
+  setup(api) {
+    api.onPrepare(() => {
+      const { middlewares } = api.getServerContext();
+      middlewares.push({
+        name: 'emit-monitor-events',
+        path: input.path,
+        handler: async (c: any) => {
+          const monitors = c.get('monitors');
+          for (let index = 0; index < input.count; index++) {
+            monitors?.info(`${input.message}-${index}`);
+          }
+          return c.json({ ok: true });
+        },
+      });
+    });
+  },
+});
+
+const waitFor = async (predicate: () => boolean, timeoutMs = 2_000) => {
+  const startedAt = Date.now();
+  while (!predicate()) {
+    if (Date.now() - startedAt > timeoutMs) {
+      throw new Error('waitFor timed out');
+    }
+    await new Promise(resolve => setTimeout(resolve, 10));
+  }
+};
+
+describe('telemetry plugin lifecycle', () => {
+  test('wires server.telemetry.slo through to alert emission', async () => {
+    const warnSpy = rs.spyOn(logger, 'warn').mockImplementation(() => {});
+
+    try {
+      const config = getDefaultConfig();
+      config.server = {
+        telemetry: {
+          enabled: true,
+          maxQueueSize: 2,
+          maxBatchSize: 500,
+          flushIntervalMs: 60_000,
+          slo: {
+            queueUtilizationWarnThreshold: 0.5,
+            queueDroppedWarnThreshold: 1,
+            alertCooldownMs: 0,
+          },
+        },
+      } as any;
+
+      const server = createServerBase({
+        config,
+        pwd: process.cwd(),
+        appContext: getDefaultAppContext(),
+      });
+      server.addPlugins([
+        ...createDefaultPlugins({ logger: false }),
+        injectTelemetryPlugin(),
+        emitMonitorEventsPlugin({
+          path: '/emit',
+          message: 'slo-probe',
+          count: 6,
+        }),
+      ]);
+      await server.init();
+
+      const response = await server.request('/emit', {}, {});
+      expect(response.status).toBe(200);
+
+      const sloWarnings = warnSpy.mock.calls.filter(call =>
+        String(call[0]).includes('[telemetry.slo]'),
+      );
+      expect(sloWarnings.length).toBeGreaterThan(0);
+      expect(
+        sloWarnings.some(call => String(call[0]).includes('queue.drop')),
+      ).toBe(true);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  test('flushes pending envelopes when the node server closes', async () => {
+    const fetchCalls: Array<{ url: string; body: string }> = [];
+    const fetchMock = rs.fn(async (url: any, init?: any) => {
+      fetchCalls.push({ url: String(url), body: String(init?.body ?? '') });
+      return new Response('{}', { status: 200 });
+    });
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = fetchMock as any;
+
+    const nodeServerStub = new EventEmitter();
+    const stubNodeServerPlugin: ServerPlugin = {
+      name: 'stub-node-server',
+      setup(api) {
+        api.updateServerContext({ nodeServer: nodeServerStub } as any);
+      },
+    };
+
+    try {
+      const config = getDefaultConfig();
+      config.server = {
+        telemetry: {
+          enabled: true,
+          // make sure nothing flushes before the close event:
+          flushIntervalMs: 60_000,
+          maxBatchSize: 500,
+          exporters: {
+            otlp: {
+              enabled: true,
+              endpoint: 'http://127.0.0.1:9/v1/logs',
+            },
+          },
+        },
+      } as any;
+
+      const server = createServerBase({
+        config,
+        pwd: process.cwd(),
+        appContext: getDefaultAppContext(),
+      });
+      server.addPlugins([
+        ...createDefaultPlugins({ logger: false }),
+        stubNodeServerPlugin,
+        injectTelemetryPlugin(),
+        emitMonitorEventsPlugin({
+          path: '/emit',
+          message: 'close-flush-probe',
+          count: 1,
+        }),
+      ]);
+      await server.init();
+
+      // init performed the startup health probe only.
+      const callsAfterInit = fetchCalls.length;
+      expect(callsAfterInit).toBeGreaterThan(0);
+
+      const response = await server.request('/emit', {}, {});
+      expect(response.status).toBe(200);
+
+      // The envelope is queued but not flushed (long flush interval).
+      expect(
+        fetchCalls.some(call => call.body.includes('close-flush-probe')),
+      ).toBe(false);
+
+      nodeServerStub.emit('close');
+
+      await waitFor(() =>
+        fetchCalls.some(call => call.body.includes('close-flush-probe')),
+      );
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});

package/tests/telemetryTraceparent.test.ts

@@ -0,0 +1,167 @@
+import {
+  createDefaultPlugins,
+  createServerBase,
+  type ServerPlugin,
+} from '@modern-js/server-core';
+import { createServer } from 'http';
+import type { AddressInfo } from 'net';
+import { injectTelemetryPlugin } from '../src/telemetry';
+import { getDefaultAppContext, getDefaultConfig } from './helpers';
+
+type CapturedEnvelope = {
+  name?: string;
+  traceId?: string;
+  spanId?: string;
+};
+
+const createCaptureServer = async () => {
+  const envelopes: CapturedEnvelope[] = [];
+
+  const server = createServer((req, res) => {
+    const chunks: string[] = [];
+    req.on('data', chunk => {
+      chunks.push(String(chunk));
+    });
+    req.on('end', () => {
+      try {
+        const body = JSON.parse(chunks.join('')) as {
+          events?: CapturedEnvelope[];
+        };
+        envelopes.push(...(body.events || []));
+      } catch {
+        // ignore malformed payloads
+      }
+      res.statusCode = 200;
+      res.end('ok');
+    });
+  });
+
+  await new Promise<void>(resolve => server.listen(0, resolve));
+  const { port } = server.address() as AddressInfo;
+
+  return {
+    endpoint: `http://127.0.0.1:${port}/v1/logs`,
+    envelopes,
+    close: () =>
+      new Promise<void>(resolve => {
+        server.close(() => resolve());
+      }),
+  };
+};
+
+const waitForEnvelope = async (
+  envelopes: CapturedEnvelope[],
+  name: string,
+  timeoutMs = 5_000,
+) => {
+  const startedAt = Date.now();
+  for (;;) {
+    const found = envelopes.find(item => item.name === name);
+    if (found) {
+      return found;
+    }
+    if (Date.now() - startedAt > timeoutMs) {
+      throw new Error(`Timed out waiting for telemetry envelope "${name}"`);
+    }
+    await new Promise(resolve => setTimeout(resolve, 25));
+  }
+};
+
+describe('telemetry envelope traceparent tagging (W3C strict)', () => {
+  test('propagates valid traceparent ids and drops all-zero ids', async () => {
+    const capture = await createCaptureServer();
+
+    try {
+      const config = getDefaultConfig();
+      (config as Record<string, any>).server = {
+        telemetry: {
+          enabled: true,
+          // flush on every enqueue so the capture server sees envelopes
+          // without waiting for the interval timer
+          maxBatchSize: 1,
+          flushIntervalMs: 60_000,
+          exporters: {
+            otlp: {
+              enabled: true,
+              endpoint: capture.endpoint,
+            },
+          },
+        },
+      };
+
+      const probePlugin: ServerPlugin = {
+        name: 'emit-traceparent-probe',
+        setup(api) {
+          api.onPrepare(() => {
+            const { middlewares } = api.getServerContext();
+            middlewares.push({
+              name: 'emit-traceparent-probe',
+              handler: async (c: any) => {
+                const probeName = c.req.header('x-probe-name') || 'probe';
+                c.get('monitors')?.info(probeName);
+                return c.json({ ok: true });
+              },
+            });
+          });
+        },
+      };
+
+      const server = createServerBase({
+        config,
+        pwd: process.cwd(),
+        appContext: getDefaultAppContext(),
+      });
+      server.addPlugins([
+        ...createDefaultPlugins({ logger: false }),
+        injectTelemetryPlugin(),
+        probePlugin,
+      ]);
+      await server.init();
+
+      const validResponse = await server.request(
+        '/',
+        {
+          headers: new Headers({
+            'x-probe-name': 'probe-valid',
+            traceparent:
+              '00-0AF7651916CD43DD8448EB211C80319C-B7AD6B7169203331-01',
+          }),
+        },
+        {},
+      );
+      expect(validResponse.status).toBe(200);
+
+      const allZeroResponse = await server.request(
+        '/',
+        {
+          headers: new Headers({
+            'x-probe-name': 'probe-all-zero',
+            traceparent:
+              '00-00000000000000000000000000000000-0000000000000000-01',
+          }),
+        },
+        {},
+      );
+      expect(allZeroResponse.status).toBe(200);
+
+      const validEnvelope = await waitForEnvelope(
+        capture.envelopes,
+        'probe-valid',
+      );
+      // valid traceparent ids propagate (normalized to lowercase)
+      expect(validEnvelope.traceId).toBe('0af7651916cd43dd8448eb211c80319c');
+      expect(validEnvelope.spanId).toBe('b7ad6b7169203331');
+
+      const allZeroEnvelope = await waitForEnvelope(
+        capture.envelopes,
+        'probe-all-zero',
+      );
+      // all-zero trace/span ids are invalid per the W3C trace-context spec
+      // and must not be tagged onto envelopes
+      expect(allZeroEnvelope.traceId).toBeUndefined();
+      expect(allZeroEnvelope.spanId).toBeUndefined();
+    } finally {
+      await capture.close();
+    }
+  });
+});

package/tests/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@modern-js/tsconfig/base",
+  "compilerOptions": {
+    "declaration": false,
+    "jsx": "preserve",
+    "isolatedModules": true,
+    "types": ["node", "@rstest/core/globals"],
+    "rootDir": "..",
+    "outDir": "./dist"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "@modern-js/tsconfig/base",
+  "compilerOptions": {
+    "declaration": false,
+    "jsx": "preserve",
+    "isolatedModules": true,
+    "rootDir": "./src"
+  },
+  "include": ["src"]
+}