@oxy.so/core 1.0.1 → 1.1.2

package/src/mixins/__tests__/agency.test.ts

@@ -0,0 +1,120 @@
+import { OxyServices } from '../../OxyServices';
+
+function makeJwt(payload: Record<string, unknown>): string {
+  const encode = (value: Record<string, unknown>): string =>
+    Buffer.from(JSON.stringify(value)).toString('base64url');
+  return `${encode({ alg: 'none', typ: 'JWT' })}.${encode({ exp: Math.floor(Date.now() / 1000) + 3600, ...payload })}.sig`;
+}
+
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+describe('native agency authority', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    oxy.httpService.setTokens(makeJwt({ userId: 'owner' }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  it('loads account-scoped grants and audit events', async () => {
+    fetchMock
+      .mockResolvedValueOnce(jsonResponse({ grants: [] }))
+      .mockResolvedValueOnce(jsonResponse({ events: [] }));
+
+    await expect(oxy.listDelegationGrants('owner/account')).resolves.toEqual([]);
+    await expect(oxy.listCapabilityAuditEvents('owner/account')).resolves.toEqual([]);
+
+    expect(String(fetchMock.mock.calls[0]?.[0])).toBe(
+      'http://test.invalid/capabilities/grants?ownerAccountId=owner%2Faccount',
+    );
+    expect(String(fetchMock.mock.calls[1]?.[0])).toBe(
+      'http://test.invalid/capabilities/audit?accountId=owner%2Faccount',
+    );
+  });
+
+  it('invalidates the exact grant list after revocation', async () => {
+    const clear = jest.spyOn(oxy, 'clearCacheEntry');
+    fetchMock.mockResolvedValueOnce(jsonResponse(undefined));
+
+    await oxy.revokeDelegationGrant('grant/id', 'owner/account');
+
+    expect(String(fetchMock.mock.calls[0]?.[0])).toBe(
+      'http://test.invalid/capabilities/grants/grant%2Fid',
+    );
+    expect(fetchMock.mock.calls[0]?.[1]?.method).toBe('DELETE');
+    expect(clear).toHaveBeenCalledWith(
+      'GET:/capabilities/grants?ownerAccountId=owner%2Faccount',
+    );
+  });
+
+  it('updates only a grant authority envelope through its stable id', async () => {
+    const grant = { id: 'grant/id', catalog: null };
+    fetchMock.mockResolvedValueOnce(jsonResponse({ grant }));
+
+    await expect(oxy.updateDelegationGrant('grant/id', 'owner/account', {
+      capabilityPackages: ['read'],
+      capabilities: ['email.read'],
+      toolOverrides: [{ tool: 'sendEmail', decision: 'deny' }],
+      limits: [],
+      maximumAutonomy: 'read_only',
+      canRedelegate: false,
+      expiresAt: null,
+    })).resolves.toEqual(grant);
+
+    const [url, init] = fetchMock.mock.calls[0] ?? [];
+    expect(String(url)).toBe('http://test.invalid/capabilities/grants/grant%2Fid');
+    expect(init?.method).toBe('PUT');
+    expect(JSON.parse(String(init?.body))).toEqual({
+      capabilityPackages: ['read'],
+      capabilities: ['email.read'],
+      toolOverrides: [{ tool: 'sendEmail', decision: 'deny' }],
+      limits: [],
+      maximumAutonomy: 'read_only',
+      canRedelegate: false,
+      expiresAt: null,
+    });
+  });
+
+  it('writes the most restrictive account policy without leaking it across accounts', async () => {
+    const policy = {
+      id: 'policy-1',
+      accountId: 'account-a',
+      appSlug: 'mention',
+      maximumAutonomy: 'draft' as const,
+      deniedCapabilities: ['social.publish'],
+      createdAt: '2026-09-03T00:00:00.000Z',
+      updatedAt: '2026-09-03T00:00:00.000Z',
+    };
+    fetchMock.mockResolvedValueOnce(jsonResponse({ policy }));
+
+    await expect(oxy.putAccountCapabilityPolicy('mention', {
+      accountId: 'account-a',
+      maximumAutonomy: 'draft',
+      deniedCapabilities: ['social.publish'],
+    })).resolves.toEqual(policy);
+
+    const [url, init] = fetchMock.mock.calls[0] ?? [];
+    expect(String(url)).toBe('http://test.invalid/capabilities/account-policies/mention');
+    expect(init?.method).toBe('PUT');
+    expect(init?.body).toBe(JSON.stringify({
+      accountId: 'account-a',
+      maximumAutonomy: 'draft',
+      deniedCapabilities: ['social.publish'],
+    }));
+  });
+});

package/src/mixins/__tests__/connectedApps.test.ts

@@ -120,4 +120,27 @@ describe('connected apps (OAuth grants)', () => {
     expect(clearSpy).toHaveBeenCalledWith('GET:/auth/grants');
     clearSpy.mockRestore();
   });
+
+  it('lists and revokes resource-bound external MCP clients', async () => {
+    const grant = {
+      id: 'mcp-grant',
+      appSlug: 'noted',
+      resource: 'https://mcp.noted.oxy.so',
+      scopes: ['notes.read'],
+      clientId: 'client-public-id',
+      clientName: 'Research client',
+      createdAt: '2026-09-03T00:00:00.000Z',
+      lastUsedAt: '2026-09-03T01:00:00.000Z',
+    };
+    fetchMock
+      .mockResolvedValueOnce(jsonResponse({ grants: [grant] }))
+      .mockResolvedValueOnce(jsonResponse(undefined));
+
+    await expect(oxy.listConnectedMcpClients()).resolves.toEqual([grant]);
+    await expect(oxy.revokeConnectedMcpClient('mcp/grant')).resolves.toBeUndefined();
+
+    expect(String(fetchMock.mock.calls[0]?.[0])).toBe('http://test.invalid/auth/mcp/oauth/grants');
+    expect(String(fetchMock.mock.calls[1]?.[0])).toBe('http://test.invalid/auth/mcp/oauth/grants/mcp%2Fgrant');
+    expect(fetchMock.mock.calls[1]?.[1]?.method).toBe('DELETE');
+  });
 });

package/src/mixins/index.ts

@@ -17,6 +17,7 @@ import { OxyServicesReputationMixin } from './OxyServices.reputation';
 import { OxyServicesAssetsMixin } from './OxyServices.assets';
 import { OxyServicesAccountsMixin } from './OxyServices.accounts';
 import { OxyServicesConnectedAppsMixin } from './OxyServices.connectedApps';
+import { OxyServicesAgencyMixin } from './OxyServices.agency';
 import { OxyServicesStoreMixin } from './OxyServices.store';
 import { OxyServicesLocationMixin } from './OxyServices.location';
 import { OxyServicesAnalyticsMixin } from './OxyServices.analytics';
@@ -31,7 +32,6 @@ import { OxyServicesAppDataMixin } from './OxyServices.appData';
 import { OxyServicesCivicMixin } from './OxyServices.civic';
 import { OxyServicesChainsMixin } from './OxyServices.chains';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
-import { OxyServicesLinksMixin } from './OxyServices.links';
 import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph';
 import { OxyServicesInferenceMixin } from './OxyServices.inference';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
@@ -58,6 +58,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesAgencyMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesStoreMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>>
@@ -71,7 +72,6 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesChainsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>>
-  & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesInferenceMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>>
@@ -129,6 +129,8 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     // OAuth-consent surface (public app identity + connected-app grants). Kept
     // separate from account ownership.
     OxyServicesConnectedAppsMixin,
+    // Oxy-owned delegated authority for Alia and digital-agent accounts.
+    OxyServicesAgencyMixin,
     // The app store: the public storefront, the reviews on it, and the listing a
     // publisher edits. A module OVER the platform — turn it off and OAuth still
     // works — so it is its own surface rather than more of `accounts`.
@@ -151,9 +153,6 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     // User nodes / decentralization (Fase 5): register/read/revoke/manage the
     // caller's personal data node + ingest hint.
     OxyServicesNodesMixin,
-    // Link previews / unfurls: SDK-owned link-metadata resolution via oxy-api,
-    // so apps stop scraping link metadata locally.
-    OxyServicesLinksMixin,
     // The user-owned follow graph (#809). One relationship per user and target,
     // shared across applications, with per-application context on top.
     OxyServicesFollowGraphMixin,

package/src/models/interfaces.ts

@@ -596,6 +596,33 @@ export interface AssetUpdateVisibilityResponse {
  * deleted ids are omitted from the response (never error the whole batch),
  * so the result may be shorter than the requested id list.
  */
+/**
+ * A short-lived direct download URL for a file the calling application's own
+ * user attached to it, from `POST /assets/service/linked-url`.
+ *
+ * `url` is BEARER AUTHORITY over the bytes for `expiresIn` seconds: whoever
+ * holds the string is the reader, and nothing about the calling service's
+ * entitlement is re-evaluated when it is used. Hand it only to a caller the
+ * service has itself authorized, and never log it.
+ *
+ * `expiresIn` bounds when a transfer may START, not how long one may take. A
+ * large file downloads fine on a slow link; a RESUMED range request after the
+ * deadline does not, and needs a fresh URL.
+ *
+ * Unlike {@link ServiceAssetMetadata}, the absence of an id from the response is
+ * an AUTHORIZATION answer as often as an existence one — see
+ * `getServiceLinkedDownloadUrls`.
+ */
+export interface ServiceLinkedDownloadUrl {
+  id: string;
+  url: string;
+  /** Seconds from issue until `url` stops being accepted. */
+  expiresIn: number;
+  mime: string;
+  size: number;
+  sha256: string;
+}
+
 export interface ServiceAssetMetadata {
   id: string;
   sha256: string;

package/src/server/__tests__/traffic.test.ts

@@ -0,0 +1,49 @@
+import { createEcosystemTraffic } from '../traffic';
+
+jest.mock('../../OxyServices', () => ({ OxyServices: jest.fn(() => ({})) }));
+
+it('publishes independently of viewers and waits for registration before removing a stopped instance', async () => {
+  const originalFetch = globalThis.fetch;
+  const bodies: Array<Record<string, unknown> | unknown[]> = [];
+  let releaseRegistration!: () => void;
+  const registration = new Promise<void>(resolve => { releaseRegistration = resolve; });
+  let registered!: () => void;
+  const registrationStarted = new Promise<void>(resolve => { registered = resolve; });
+  globalThis.fetch = jest.fn(async (_input, init) => {
+    const body = JSON.parse(String(init?.body));
+    bodies.push(body);
+    if (!Array.isArray(body) && !body.removed) {
+      registered();
+      await registration;
+    }
+    return new Response(null, { status: 204 });
+  }) as unknown as typeof fetch;
+  const traffic = createEcosystemTraffic({ service: 'mention', region: 'us-west-2', credential: async () => 'test-service-token', ready: () => true });
+  try {
+    await registrationStarted;
+    traffic.record({ scope: 'internal', direction: 'outbound', activityType: 'communication', sourceRegion: 'us-west-2', targetRegion: 'us-west-2', targetService: 'oxy-api' });
+    const stopped = traffic.stop();
+    expect(bodies.some(body => !Array.isArray(body) && body.removed === true)).toBe(false);
+    releaseRegistration();
+    await stopped;
+    expect(bodies[bodies.length - 1]).toMatchObject({ removed: true, service: 'mention', status: 'online' });
+    expect(bodies.find(Array.isArray)).toEqual([expect.objectContaining({ service: 'mention', scope: 'internal', direction: 'outbound', requests: 1 })]);
+  } finally {
+    releaseRegistration();
+    await traffic.stop();
+    globalThis.fetch = originalFetch;
+  }
+});
+
+it('rejects a partial activity credential instead of mixing it with service credentials', () => {
+  const previous = { ...process.env };
+  try {
+    process.env.OXY_ACTIVITY_API_KEY = 'activity-key';
+    delete process.env.OXY_ACTIVITY_API_SECRET;
+    process.env.OXY_SERVICE_API_KEY = 'service-key';
+    process.env.OXY_SERVICE_API_SECRET = 'service-secret';
+    expect(() => createEcosystemTraffic({ service: 'homiio', region: 'us-west-2' })).toThrow('complete OXY_ACTIVITY');
+  } finally {
+    process.env = previous;
+  }
+});

package/src/server/__tests__/trafficNodeHttp.test.ts

@@ -0,0 +1,38 @@
+import http from 'node:http';
+import { once } from 'node:events';
+import { observeNodeHttp, withoutNodeHttpObservation } from '../trafficNodeHttp';
+import type { TrafficFlow } from '@oxy.so/telemetry/collector';
+
+it('observes real HTTP clients, preserves behavior and restores the HTTP facade', async () => {
+  const events: TrafficFlow[] = [];
+  const original = http.request;
+  const server = http.createServer((_req, res) => { res.setHeader('X-Oxy-Region', 'eu-west-1'); res.end('ok'); });
+  server.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  const port = (server.address() as { port: number }).port;
+  const stop = observeNodeHttp({ record: flow => events.push(flow) }, 'website', 'us-west-2', () => ({ service: 'oxy-api', region: 'unknown' }));
+  const request = (path: string) => new Promise<void>((resolve, reject) => {
+    const outgoing = http.get(`http://127.0.0.1:${port}${path}`, response => { response.resume(); response.on('end', resolve); });
+    // The observer must not swallow an unhandled request error.
+    expect(outgoing.listenerCount('error')).toBe(0);
+    outgoing.once('error', reject);
+  });
+  try {
+    // Bun leaves Host implicit: its ClientRequest.host is the available authority.
+    const getHeader = http.ClientRequest.prototype.getHeader;
+    http.ClientRequest.prototype.getHeader = function (name: string) { return name === 'host' ? undefined : getHeader.call(this, name); };
+    try { await request('/files/private-id'); } finally { http.ClientRequest.prototype.getHeader = getHeader; }
+    expect(events).toEqual([
+      expect.objectContaining({ scope: 'internal', direction: 'outbound', activityType: 'media', sourceRegion: 'us-west-2', targetRegion: 'eu-west-1' }),
+      expect.objectContaining({ scope: 'internal', direction: 'inbound', sourceRegion: 'eu-west-1', targetRegion: 'us-west-2' }),
+    ]);
+    expect(JSON.stringify(events)).not.toContain('private-id');
+    await withoutNodeHttpObservation(() => request('/files/no-double-count'));
+    await request('/internal/activity');
+    expect(events).toHaveLength(2);
+    stop();
+    expect(http.request).toBe(original);
+    await request('/files/after-stop');
+    expect(events).toHaveLength(2);
+  } finally { stop(); await new Promise<void>(resolve => server.close(() => resolve())); }
+});

package/src/server/index.ts

@@ -134,3 +134,8 @@ export type { OxyIdentityCacheEvictor } from '../utils/identityCacheSweep';
 // lets `@oxy.so/api` derive `auth.<apex>` without duplicating PSL logic.
 export { registrableApex } from '../utils/registrableApex';
 export { isOfficialWebOrigin } from '../utils/officialOrigins';
+
+export { createEcosystemTraffic } from './traffic';
+export type { EcosystemTrafficOptions } from './traffic';
+
+export { observeNodeHttp, withoutNodeHttpObservation } from './trafficNodeHttp';

package/src/server/traffic.ts

@@ -0,0 +1,116 @@
+import { observeNodeHttp, withoutNodeHttpObservation } from './trafficNodeHttp';
+import { observeTrafficSocket, observeTrafficWebSocket, type TrafficWebSocket, type TrafficSocket } from '@oxy.so/telemetry/socket';
+import { randomUUID } from 'node:crypto';
+import type { RequestHandler } from 'express';
+import { OxyServices } from '../OxyServices';
+import { createTrafficCollector, instrumentTrafficFetch, trafficMiddleware, type TrafficFlow, type ServiceEndpoint, resolveOxyServiceEndpoint, infrastructureLocation } from '@oxy.so/telemetry/collector';
+
+export interface EcosystemTrafficOptions {
+  service: string;
+  region?: string;
+  baseURL?: string;
+  credential?: () => Promise<string>;
+  resolveEndpoint?: (url: URL) => ServiceEndpoint | undefined;
+  onError?: () => void;
+  ready?: () => boolean;
+  location?: { label: string; coordinates: [number, number] };
+}
+
+/** Install once per service process, before registering HTTP routes. */
+export function createEcosystemTraffic(options: EcosystemTrafficOptions): {
+  middleware: RequestHandler;
+  record(flow: Omit<TrafficFlow, 'service' | 'region'>): void;
+  wrapFetch(fetcher: typeof fetch): typeof fetch;
+  installFetch(): void;
+  observeHttp: ReturnType<typeof trafficMiddleware>;
+  observeSocket(socket: TrafficSocket, options?: Parameters<typeof observeTrafficSocket>[4]): () => void;
+  observeWebSocket(socket: TrafficWebSocket, options?: Parameters<typeof observeTrafficWebSocket>[4]): () => void;
+  stop(): Promise<void>;
+} {
+  const region = options.region ?? process.env.AWS_REGION ?? 'unknown';
+  const baseURL = options.baseURL ?? process.env.OXY_API_URL ?? 'https://api.oxy.so';
+  const activityKey = process.env.OXY_ACTIVITY_API_KEY;
+  const activitySecret = process.env.OXY_ACTIVITY_API_SECRET;
+  if (!options.credential && Boolean(activityKey) !== Boolean(activitySecret)) {
+    throw new Error('Ecosystem activity requires a complete OXY_ACTIVITY_API_KEY and OXY_ACTIVITY_API_SECRET pair');
+  }
+  const apiKey = activityKey || process.env.OXY_SERVICE_API_KEY;
+  const apiSecret = activitySecret || process.env.OXY_SERVICE_API_SECRET;
+  if (!options.credential && (!apiKey || !apiSecret)) throw new Error('Ecosystem activity requires OXY_SERVICE_API_KEY and OXY_SERVICE_API_SECRET');
+  const oxy = new OxyServices({ baseURL });
+  if (apiKey && apiSecret) oxy.configureServiceAuth(apiKey, apiSecret);
+  const credential = options.credential ?? (() => oxy.getServiceToken());
+  const fetcher = globalThis.fetch.bind(globalThis);
+  const instanceId = randomUUID();
+  const location = options.location ?? infrastructureLocation(region);
+  if (!location) throw new Error('Ecosystem activity requires a known infrastructure region or explicit location');
+  const post = async (path: string, data: unknown) => {
+    const token = await credential();
+    const response = await fetcher(new URL(path, baseURL), {
+      method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify(data), signal: AbortSignal.timeout(4_000),
+    });
+    if (!response.ok) throw new Error('Activity collection failed');
+  };
+  const collector = createTrafficCollector(events => post('/internal/activity', events));
+  let stopped = false;
+  let heartbeatWork = Promise.resolve();
+  let heartbeatPending = false;
+  const reportError = options.onError ?? (() => console.warn('Ecosystem activity publisher unavailable'));
+  const heartbeat = (removed = false) => {
+    if (!removed && (stopped || heartbeatPending)) return heartbeatWork;
+    heartbeatPending = true;
+    heartbeatWork = heartbeatWork.then(() => post('/internal/activity/infrastructure', { instanceId, service: options.service, region, ...location, status: options.ready?.() ? 'online' : 'unknown', removed })).catch(reportError).finally(() => { heartbeatPending = false; });
+    return heartbeatWork;
+  };
+  const flush = () => collector.flush().catch(reportError);
+  const cleanups = new Set<() => void>();
+  const sockets = new WeakMap<object, () => void>();
+  let fetchInstalled = false;
+  const wrapFetch = (fetcher: typeof fetch): typeof fetch => {
+    const wrapped = instrumentTrafficFetch(fetcher, collector, options.service, region, options.resolveEndpoint ?? resolveOxyServiceEndpoint);
+    return Object.assign((...args: Parameters<typeof fetch>) => withoutNodeHttpObservation(() => wrapped(...args)), fetcher) as typeof fetch;
+  };
+  const observeHttp = trafficMiddleware(collector, options.service, region);
+  const timer = setInterval(() => { void flush(); }, 2_000);
+  timer.unref?.();
+  void heartbeat();
+  const heartbeatTimer = setInterval(() => { void heartbeat(); }, 10_000);
+  heartbeatTimer.unref?.();
+  return {
+    record: flow => collector.record({ ...flow, service: options.service, region }),
+    middleware: observeHttp as RequestHandler,
+    observeHttp,
+    wrapFetch,
+    installFetch() {
+      if (fetchInstalled || stopped) return;
+      fetchInstalled = true;
+      const original = globalThis.fetch;
+      const wrapped = wrapFetch(original);
+      globalThis.fetch = wrapped;
+      cleanups.add(() => { if (globalThis.fetch === wrapped) globalThis.fetch = original; });
+      cleanups.add(observeNodeHttp(collector, options.service, region, options.resolveEndpoint ?? resolveOxyServiceEndpoint));
+    },
+    observeWebSocket(socket, socketOptions) {
+      const existing = sockets.get(socket);
+      if (existing) return existing;
+      const unobserve = observeTrafficWebSocket(socket, collector, options.service, region, socketOptions);
+      const cleanup = () => { unobserve(); socket.off('close', cleanup); cleanups.delete(cleanup); sockets.delete(socket); };
+      sockets.set(socket, cleanup);
+      socket.once('close', cleanup);
+      cleanups.add(cleanup);
+      return cleanup;
+    },
+    observeSocket(socket, socketOptions) {
+      const existing = sockets.get(socket);
+      if (existing) return existing;
+      const unobserve = observeTrafficSocket(socket, collector, options.service, region, socketOptions);
+      const cleanup = () => { unobserve(); socket.off('disconnect', cleanup); cleanups.delete(cleanup); sockets.delete(socket); };
+      sockets.set(socket, cleanup);
+      socket.once('disconnect', cleanup);
+      cleanups.add(cleanup);
+      return cleanup;
+    },
+    async stop() { if (stopped) return; stopped = true; cleanups.forEach(cleanup => cleanup()); cleanups.clear(); clearInterval(timer); clearInterval(heartbeatTimer); await flush(); await heartbeat(true); },
+  };
+}

package/src/server/trafficNodeHttp.ts

@@ -0,0 +1,69 @@
+import http from 'node:http';
+import https from 'node:https';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { syncBuiltinESMExports } from 'node:module';
+import { normalizeInfrastructureRegion, trafficType, type TrafficFlow, type ServiceEndpoint } from '@oxy.so/telemetry/collector';
+
+const suppressed = new AsyncLocalStorage<boolean>();
+export function withoutNodeHttpObservation<T>(callback: () => T): T { return suppressed.run(true, callback); }
+
+/** Node and Bun share the HTTP facade; Bun does not emit Node's HTTP diagnostic channels. */
+export function observeNodeHttp(
+  collector: { record(flow: TrafficFlow): void }, service: string, region: string,
+  resolveEndpoint: (url: URL) => ServiceEndpoint | undefined,
+): () => void {
+  const seen = new WeakSet<http.ClientRequest>();
+  const restoreRequests = new Set<() => void>();
+  const observe = (request: http.ClientRequest) => {
+    if (seen.has(request) || suppressed.getStore()) return request;
+    seen.add(request);
+    const host = request.getHeader('host') ?? request.host;
+    if (typeof host !== 'string') return request;
+    const url = new URL(request.path || '/', `${request.protocol || 'http:'}//${host}`);
+    if (/^\/(?:internal\/activity|auth\/service-token|platform-infrastructure)(?:\/|$)/.test(url.pathname)) return request;
+    const peer = resolveEndpoint(url);
+    if (peer && !request.headersSent) request.setHeader('X-Oxy-Source-Region', region);
+    const flow: TrafficFlow = { service, region, activityType: trafficType(url.pathname), scope: peer ? 'internal' : 'external', direction: 'outbound', sourceRegion: region, sourceService: service, targetService: peer?.service };
+    const emit = request.emit;
+    let recorded = false;
+    const restore = () => { if (request.emit === observedEmit) request.emit = emit; restoreRequests.delete(restore); };
+    // Intercept notifications without adding an 'error' listener: observation
+    // must not turn an unhandled application error into a swallowed error.
+    const observedEmit: typeof request.emit = function (this: http.ClientRequest, event: string | symbol, ...args: unknown[]) {
+      try {
+        if (!recorded && event === 'response') {
+          recorded = true;
+          const response = args[0] as http.IncomingMessage;
+          const targetRegion = peer ? normalizeInfrastructureRegion(response.headers['x-oxy-region']) : undefined;
+          collector.record({ ...flow, targetRegion });
+          collector.record({ ...flow, direction: 'inbound', sourceRegion: targetRegion, targetRegion: region, sourceService: peer?.service, targetService: service });
+        } else if (!recorded && (event === 'error' || event === 'close')) {
+          recorded = true;
+          collector.record(flow);
+        }
+      } catch { /* A metrics failure cannot change a request's behavior. */ }
+      if (event === 'close') restore();
+      return emit.call(this, event, ...args);
+    };
+    request.emit = observedEmit;
+    restoreRequests.add(restore);
+    return request;
+  };
+  const safelyObserve = (request: http.ClientRequest) => {
+    try { return observe(request); } catch { return request; }
+  };
+  const patches = [http, https].map(module => {
+    const request = module.request;
+    const get = module.get;
+    const wrappedRequest = function (...args: Parameters<typeof request>) { return safelyObserve(request.apply(module, args)); } as typeof request;
+    const wrappedGet = function (...args: Parameters<typeof get>) { return safelyObserve(get.apply(module, args)); } as typeof get;
+    module.request = wrappedRequest;
+    module.get = wrappedGet;
+    return () => {
+      if (module.request === wrappedRequest) module.request = request;
+      if (module.get === wrappedGet) module.get = get;
+    };
+  });
+  syncBuiltinESMExports();
+  return () => { patches.forEach(restore => restore()); restoreRequests.forEach(restore => restore()); syncBuiltinESMExports(); };
+}

package/src/utils/__tests__/cacheLifecycle.test.ts

@@ -0,0 +1,65 @@
+import { TTLCache, registerCacheForCleanup, unregisterCacheFromCleanup, stopAllCleanupIntervals } from '../cache';
+
+afterEach(() => { stopAllCleanupIntervals(); jest.useRealTimers(); });
+
+test('empty registration is inert and first data starts one shared cleanup timer', () => {
+  jest.useFakeTimers();
+  const a = new TTLCache<string>(10);
+  const b = new TTLCache<string>(10);
+  registerCacheForCleanup(a);
+  registerCacheForCleanup(b);
+  expect(jest.getTimerCount()).toBe(0);
+  a.set('a', 'value');
+  b.set('b', 'value');
+  expect(jest.getTimerCount()).toBe(1);
+  jest.advanceTimersByTime(11);
+  expect(a.get('a')).toBeNull();
+  expect(b.has('b')).toBe(false);
+  jest.advanceTimersByTime(60_000);
+  expect(jest.getTimerCount()).toBe(0);
+});
+test('periodic cleanup expires unread entries and clear restarts lazily without losing registration', () => {
+  jest.useFakeTimers();
+  const a = new TTLCache<string>(10);
+  registerCacheForCleanup(a);
+  a.set('expired', 'value');
+  jest.advanceTimersByTime(60_000);
+  expect(a.size()).toBe(0);
+  expect(jest.getTimerCount()).toBe(0);
+  a.set('again', 'value');
+  expect(jest.getTimerCount()).toBe(1);
+  a.clear();
+  expect(jest.getTimerCount()).toBe(0);
+  a.set('after-clear', 'value');
+  expect(jest.getTimerCount()).toBe(1);
+});
+test('unregister and stop preserve entries but prevent writes restarting automatic cleanup', () => {
+  jest.useFakeTimers();
+  const a = new TTLCache<string>(100_000);
+  const b = new TTLCache<string>(100_000);
+  a.set('a', 'value');
+  registerCacheForCleanup(a);
+  registerCacheForCleanup(b);
+  b.set('b', 'value');
+  unregisterCacheFromCleanup(a);
+  expect(jest.getTimerCount()).toBe(1);
+  b.delete('b');
+  expect(jest.getTimerCount()).toBe(0);
+  a.set('unregistered', 'value');
+  expect(jest.getTimerCount()).toBe(0);
+  registerCacheForCleanup(a);
+  expect(jest.getTimerCount()).toBe(1);
+  stopAllCleanupIntervals();
+  a.set('stopped', 'value');
+  expect(jest.getTimerCount()).toBe(0);
+  expect(a.get('a')).toBe('value');
+});
+test('server barrel imports and client construction start no background timers', () => {
+  jest.useFakeTimers();
+  jest.isolateModules(() => {
+    const server = require('../../server');
+    expect(typeof server.createEcosystemTraffic).toBe('function');
+    expect(jest.getTimerCount()).toBe(0);
+    require('../cache').stopAllCleanupIntervals();
+  });
+});

package/src/utils/cache.ts

@@ -104,6 +104,7 @@ export class TTLCache<T> {
     const effectiveTTL = ttl === undefined ? this.defaultTTL : ttl;
     const expiresAt = now + effectiveTTL;
     this.cache.set(key, { data, timestamp: now, expiresAt });
+    if (!cleanupInterval && activeCaches.has(this)) updateCleanupInterval();
   }
 
   /**
@@ -112,7 +113,9 @@ export class TTLCache<T> {
    * @returns true if entry was deleted, false if not found
    */
   delete(key: string): boolean {
-    return this.cache.delete(key);
+    const deleted = this.cache.delete(key);
+    if (activeCaches.has(this)) updateCleanupInterval();
+    return deleted;
   }
 
   /**
@@ -122,6 +125,7 @@ export class TTLCache<T> {
     this.cache.clear();
     this.hits = 0;
     this.misses = 0;
+    if (activeCaches.has(this)) updateCleanupInterval();
   }
 
   /**
@@ -232,31 +236,29 @@ const activeCaches = new Set<TTLCache<any>>();
  */
 export function registerCacheForCleanup(cache: TTLCache<any>): void {
   activeCaches.add(cache);
+  updateCleanupInterval();
+}
 
-  // Start cleanup interval if not already running
-  if (!cleanupInterval) {
-    cleanupInterval = setInterval(() => {
-      for (const cache of activeCaches) {
-        cache.cleanup();
-      }
-    }, 60000); // Every minute
-    // Never block process/worker exit on a housekeeping timer.
-    cleanupInterval.unref?.();
+/** Empty registered caches need no timer; importing a client must stay inert. */
+function updateCleanupInterval(): void {
+  const hasEntries = [...activeCaches].some(cache => cache.size() > 0);
+  if (!hasEntries) {
+    if (cleanupInterval) clearInterval(cleanupInterval);
+    cleanupInterval = null;
+    return;
   }
+  if (cleanupInterval) return;
+  cleanupInterval = setInterval(() => {
+    for (const cache of activeCaches) cache.cleanup();
+    updateCleanupInterval();
+  }, 60_000);
+  cleanupInterval.unref?.();
 }
 
-/**
- * Unregister a cache from automatic cleanup
- * @param cache Cache instance to unregister
- */
+/** Unregister a cache without changing its entries or TTL behavior. */
 export function unregisterCacheFromCleanup(cache: TTLCache<any>): void {
   activeCaches.delete(cache);
-
-  // Stop cleanup interval if no caches are registered
-  if (activeCaches.size === 0 && cleanupInterval) {
-    clearInterval(cleanupInterval);
-    cleanupInterval = null;
-  }
+  updateCleanupInterval();
 }
 
 /**