fa-model-catalog 0.0.0-stage → 0.1.1

package/src/client.js

@@ -0,0 +1,317 @@
+import { validateModel } from './catalog-schemas.js';
+import { nextRefreshTime } from './schedule.js';
+
+export function createCatalogClient({
+  baseUrl,
+  token,
+  models = [],
+  timezone = 'Europe/Moscow',
+  timeoutMs = 10000,
+  fetch: fetcher = globalThis.fetch,
+  now = Date.now,
+  random = Math.random,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+  onEvent = () => {},
+}) {
+  const url = new URL(baseUrl);
+  if (url.username || url.password || url.search || url.hash || !['http:', 'https:'].includes(url.protocol)) {
+    throw new Error('Invalid service URL.');
+  }
+  if (url.protocol !== 'https:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) {
+    throw new Error('HTTPS is required for a remote service.');
+  }
+  if (typeof token !== 'string' || !token || /[\r\n]/.test(token) || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error('Invalid client settings.');
+  }
+  new Intl.DateTimeFormat('en', { timeZone: timezone }).format();
+  const cache = new Map();
+  const wanted = new Set();
+  const pending = new Map();
+  const queued = new Set();
+  const controllers = new Set();
+  let active = false;
+  let stopped = false;
+  let flushQueued = false;
+  let serial = Promise.resolve();
+  let scheduleTimer;
+  let retryTimer;
+  let retryCount = 0;
+  let refreshPromise;
+  let lastWindow = null;
+  let nextScheduledAt = null;
+  const emit = (e) => {
+    try {
+      onEvent(e);
+    } catch {
+      /* Observer cannot change results. */
+    }
+  };
+  const checkNames = (names) => {
+    if (!Array.isArray(names) || names.some((n) => typeof n !== 'string' || !n.length || n.length > 512)) {
+      throw new Error('Expected an array of nonempty names, each up to 512 characters long.');
+    }
+  };
+  checkNames(models);
+  models.forEach((n) => wanted.add(n));
+  const result = (name) =>
+    structuredClone(
+      cache.get(name) ?? {
+        requestedName: name,
+        matchedName: null,
+        canonicalName: null,
+        status: 'unavailable',
+        model: null,
+        catalogVersion: null,
+        stale: false,
+        lastSuccessAt: null,
+        reason: 'Data has not been received yet.',
+      },
+    );
+  const planRetry = (waitMs = 0) => {
+    if (!active || retryTimer || retryCount >= 2) {
+      return;
+    }
+    const base = [300000, 1200000][retryCount++];
+    const delay = Math.max(waitMs, base * (0.8 + random() * 0.4));
+    retryTimer = setTimer(() => {
+      retryTimer = null;
+      return refreshInternal(false);
+    }, delay);
+    retryTimer.unref?.();
+  };
+  const request = async (names) => {
+    if (stopped) {
+      return;
+    }
+    const controller = new AbortController();
+    controllers.add(controller);
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    timeout.unref?.();
+    try {
+      const response = await fetcher(
+        new URL('v1/models/resolve', url.href.endsWith('/') ? url : new URL(`${url.href}/`)),
+        {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ models: names }),
+          signal: controller.signal,
+          redirect: 'error',
+        },
+      );
+      if (!response.ok) {
+        const retryAfter = response.headers.get('retry-after');
+        const retrySeconds =
+          retryAfter && /^\d+$/.test(retryAfter)
+            ? Number(retryAfter) * 1000
+            : retryAfter
+              ? Math.max(0, Date.parse(retryAfter) - now())
+              : 0;
+        throw Object.assign(new Error(), {
+          status: response.status,
+          retryAfter: Number.isFinite(retrySeconds) ? retrySeconds : 0,
+        });
+      }
+      const text = await readBounded(response, 8 * 1024 * 1024);
+      const data = JSON.parse(text);
+      if (
+        !Array.isArray(data) ||
+        data.length !== names.length ||
+        data.some((r, i) => !validRecord(r, names[i])) ||
+        new Set(data.map((r) => r.catalogVersion)).size > 1
+      ) {
+        throw Object.assign(new Error(), { status: 400, invalidResponse: true });
+      }
+      if (stopped) {
+        return;
+      }
+      const success = new Date(now()).toISOString();
+      data.forEach((r) => cache.set(r.requestedName, { ...r, stale: false, lastSuccessAt: success, reason: null }));
+      emit({ event: 'prices_received', count: data.length, catalogVersion: data[0]?.catalogVersion ?? null });
+    } catch (e) {
+      if (stopped) {
+        return;
+      }
+      const reason = e.invalidResponse
+        ? 'The service returned invalid data.'
+        : e.status === 401 || e.status === 403
+          ? 'The service denied access.'
+          : e.status
+            ? `Could not retrieve prices; response status ${e.status}.`
+            : 'The service is unavailable or the request timed out.';
+      names.forEach((name) => {
+        const old = result(name);
+        cache.set(name, { ...old, stale: old.lastSuccessAt !== null, reason });
+      });
+      emit({ event: 'prices_unavailable', count: names.length, reason });
+      if (!e.status || e.status === 429 || e.status >= 500) {
+        planRetry(e.retryAfter);
+      }
+    } finally {
+      clearTimeout(timeout);
+      controllers.delete(controller);
+    }
+  };
+  const enqueue = (names) => {
+    const promises = [];
+    for (const name of names) {
+      if (!pending.has(name)) {
+        let resolve;
+        const promise = new Promise((done) => {
+          resolve = done;
+        });
+        pending.set(name, { promise, resolve });
+        queued.add(name);
+      }
+      promises.push(pending.get(name).promise);
+    }
+    if (queued.size && !flushQueued) {
+      flushQueued = true;
+      queueMicrotask(() => {
+        flushQueued = false;
+        const batch = [...queued];
+        queued.clear();
+        serial = serial.then(async () => {
+          let group = [];
+          let bytes = 13;
+          for (const name of batch) {
+            const size = Buffer.byteLength(JSON.stringify(name)) + 1;
+            if (group.length >= 1000 || bytes + size > 250 * 1024) {
+              await request(group);
+              group = [];
+              bytes = 13;
+            }
+            group.push(name);
+            bytes += size;
+          }
+          if (group.length) {
+            await request(group);
+          }
+          for (const name of batch) {
+            pending.get(name)?.resolve();
+            pending.delete(name);
+          }
+        });
+      });
+    }
+    return Promise.all(promises);
+  };
+  const refreshInternal = async (reset) => {
+    if (stopped || !active) {
+      throw new Error('The client has not been started.');
+    }
+    if (refreshPromise) {
+      return refreshPromise;
+    }
+    if (reset) {
+      retryCount = 0;
+      clearTimer(retryTimer);
+      retryTimer = null;
+    }
+    refreshPromise = enqueue([...wanted]).finally(() => {
+      refreshPromise = null;
+    });
+    await refreshPromise;
+    return [...wanted].map(result);
+  };
+  const schedule = () => {
+    if (!active) {
+      return;
+    }
+    const next = nextRefreshTime({ now: now(), timezone, random, afterWindow: lastWindow });
+    nextScheduledAt = new Date(next.time).toISOString();
+    scheduleTimer = setTimer(async () => {
+      lastWindow = next.windowId;
+      try {
+        await refreshInternal(true);
+      } finally {
+        if (active) {
+          schedule();
+        }
+      }
+    }, next.time - now());
+    scheduleTimer.unref?.();
+  };
+  return {
+    async start() {
+      if (stopped) {
+        throw new Error('A stopped client cannot be restarted.');
+      }
+      if (active) {
+        return;
+      }
+      active = true;
+      schedule();
+      await refreshInternal(true);
+    },
+    async get(names) {
+      checkNames(names);
+      if (!active || stopped) {
+        throw new Error('The client has not been started.');
+      }
+      names.forEach((n) => wanted.add(n));
+      await enqueue([...new Set(names)].filter((n) => !cache.has(n)));
+      return names.map(result);
+    },
+    refresh() {
+      return refreshInternal(true);
+    },
+    get nextRefreshAt() {
+      return nextScheduledAt;
+    },
+    stop() {
+      active = false;
+      stopped = true;
+      clearTimer(scheduleTimer);
+      clearTimer(retryTimer);
+      nextScheduledAt = null;
+      controllers.forEach((c) => c.abort());
+    },
+  };
+}
+
+async function readBounded(response, limit) {
+  if (!response.body) {
+    throw new Error();
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) {
+        break;
+      }
+      size += value.byteLength;
+      if (size > limit) {
+        throw new Error();
+      }
+      chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+  } finally {
+    await reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+}
+
+function validRecord(r, name) {
+  if (
+    !r ||
+    r.requestedName !== name ||
+    typeof r.catalogVersion !== 'string' ||
+    !/^[a-f0-9]{64}$/.test(r.catalogVersion)
+  ) {
+    return false;
+  }
+  if (r.status === 'not_found') {
+    return r.matchedName === null && r.canonicalName === null && r.model === null;
+  }
+  return (
+    r.status === 'found' &&
+    typeof r.matchedName === 'string' &&
+    typeof r.canonicalName === 'string' &&
+    validateModel(r.model)
+  );
+}

package/src/pricing.js

@@ -0,0 +1,104 @@
+const fields = {
+  standard: ['inp', 'inpC', 'inpW', 'out'],
+  flex: ['inpF', 'inpCF', 'inpWF', 'outF'],
+  batch: ['inpB', null, null, 'outB'],
+  fast: ['inpFast', null, null, 'outFast'],
+};
+
+export function tariffSnapshot(record, { serviceTier = 'standard' } = {}) {
+  const model = record?.model;
+  if (record?.status !== 'found' || !model || !fields[serviceTier] || !model.modes.includes(serviceTier)) {
+    return null;
+  }
+  const [input, cachedInput, cacheWriteInput, output] = fields[serviceTier];
+  return structuredClone({
+    requestedName: record.requestedName,
+    matchedName: record.matchedName,
+    canonicalName: record.canonicalName,
+    catalogVersion: record.catalogVersion,
+    currency: 'USD',
+    serviceTier,
+    billing: model.billing,
+    evidence: model.evidence,
+    rates: {
+      input: model[input] ?? null,
+      cachedInput: cachedInput ? (model[cachedInput] ?? null) : null,
+      cacheWriteInput: cacheWriteInput ? (model[cacheWriteInput] ?? null) : null,
+      output: model[output] ?? null,
+    },
+    matrix: { low: model.low, medium: model.medium, high: model.high },
+    stale: record.stale ?? false,
+    lastSuccessAt: record.lastSuccessAt ?? null,
+    reason: record.reason ?? null,
+  });
+}
+
+export function calculatePrice(record, usage, { serviceTier = 'standard' } = {}) {
+  const snapshot = tariffSnapshot(record, { serviceTier });
+  const issues = [];
+  const quantities = structuredClone(usage);
+  const parts = {};
+  const add = (name, quantity, rate, per) => {
+    const valid =
+      typeof quantity === 'number' &&
+      Number.isFinite(quantity) &&
+      quantity >= 0 &&
+      (snapshot.billing.kind !== 'tokens' || Number.isSafeInteger(quantity));
+    const known = typeof rate === 'number' && Number.isFinite(rate) && rate >= 0;
+    const cost = valid && (known || quantity === 0) ? (quantity === 0 ? 0 : (quantity / per) * rate) : null;
+    parts[name] = { quantity: quantity ?? null, rate, per, costUsd: cost };
+    if (!valid) {
+      issues.push(`Invalid quantity: ${name}.`);
+    } else if (!known && quantity !== 0) {
+      issues.push(`Unknown rate: ${name}.`);
+    }
+    if (cost !== null && !Number.isFinite(cost)) {
+      parts[name].costUsd = null;
+      issues.push(`Cost overflow: ${name}.`);
+    }
+  };
+  if (!snapshot) {
+    issues.push(record?.status === 'found' ? 'The service tier is not supported.' : 'Pricing is unavailable.');
+  } else {
+    const { billing, rates } = snapshot;
+    if (snapshot.stale) {
+      issues.push(`Pricing is stale: ${snapshot.reason || 'The refresh has not been confirmed.'}`);
+    }
+    if (snapshot.evidence.status === 'insufficient') {
+      issues.push(snapshot.evidence.reason);
+    }
+    if (usage.unit !== billing.unit) {
+      issues.push('The usage unit does not match the billing unit.');
+    }
+    if (billing.kind === 'tokens') {
+      const { inputTokens, outputTokens, cachedInputTokens = 0, cacheWriteInputTokens = 0 } = usage;
+      const values = [inputTokens, cachedInputTokens, cacheWriteInputTokens];
+      const valid =
+        values.every((n) => Number.isSafeInteger(n) && n >= 0) &&
+        cachedInputTokens + cacheWriteInputTokens <= inputTokens;
+      if (!valid) {
+        issues.push('Input quantities are inconsistent or are not nonnegative integers.');
+      }
+      add('input', valid ? inputTokens - cachedInputTokens - cacheWriteInputTokens : null, rates.input, billing.per);
+      add('cachedInput', cachedInputTokens, rates.cachedInput, billing.per);
+      add('cacheWriteInput', cacheWriteInputTokens, rates.cacheWriteInput, billing.per);
+      add('output', outputTokens, rates.output, billing.per);
+    } else if (billing.kind === 'quantity') {
+      add('quantity', usage.quantity, rates.input, billing.per);
+    } else {
+      add('quantity', usage.quantity, snapshot.matrix[usage.quality]?.[usage.size] ?? null, billing.per);
+    }
+  }
+  const knownSubtotalUsd = Object.values(parts).reduce((sum, p) => sum + (p.costUsd ?? 0), 0);
+  const complete =
+    Boolean(snapshot) && usage.unit === snapshot.billing.unit && Object.values(parts).every((p) => p.costUsd !== null);
+  return {
+    usage: quantities,
+    snapshot,
+    parts,
+    knownSubtotalUsd,
+    priceUsd: complete ? knownSubtotalUsd : null,
+    status: !complete ? 'incomplete' : issues.length ? 'qualified' : 'complete',
+    issues,
+  };
+}

package/src/schedule.js

@@ -0,0 +1,59 @@
+function partsAt(time, timezone) {
+  return Object.fromEntries(
+    new Intl.DateTimeFormat('en-CA', {
+      timeZone: timezone,
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+      hourCycle: 'h23',
+    })
+      .formatToParts(time)
+      .filter((p) => p.type !== 'literal')
+      .map((p) => [p.type, Number(p.value)]),
+  );
+}
+
+function localTime(year, month, day, hour, timezone) {
+  const target = Date.UTC(year, month - 1, day, hour);
+  let time = target;
+  for (let i = 0; i < 4; i++) {
+    const p = partsAt(time, timezone);
+    const shift = target - Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second);
+    if (!shift) {
+      break;
+    }
+    time += shift;
+  }
+  return time;
+}
+
+export function nextRefreshTime({
+  now = Date.now(),
+  timezone = 'Europe/Moscow',
+  random = Math.random,
+  afterWindow = null,
+} = {}) {
+  const p = partsAt(now, timezone);
+  for (let offset = 0; offset < 3; offset++) {
+    const date = new Date(Date.UTC(p.year, p.month - 1, p.day + offset));
+    for (const hour of [1, 13]) {
+      const center = localTime(date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate(), hour, timezone);
+      const windowId = center;
+      if ((afterWindow !== null && windowId <= afterWindow) || center + 1200000 <= now) {
+        continue;
+      }
+      const draw = random();
+      if (!Number.isFinite(draw) || draw < 0 || draw >= 1) {
+        throw new Error('The random number source must return a number between zero and one.');
+      }
+      const time = center - 1200000 + Math.floor(draw * 2400001);
+      if (time > now) {
+        return { time, windowId };
+      }
+    }
+  }
+  throw new Error('Could not select a refresh time.');
+}

package/src/server.js

@@ -0,0 +1,124 @@
+import { createServer } from 'node:http';
+import { createAccessControl, AccessError } from 'fa-web-access';
+import { createCatalogStore, resolveModels } from './catalog.js';
+
+export function createCatalogServer({ catalogFile, accessFile, reloadIntervalMs = 5000, onEvent = () => {} }) {
+  if (!catalogFile || !accessFile || !Number.isFinite(reloadIntervalMs) || reloadIntervalMs < 10) {
+    throw new Error('Invalid server settings.');
+  }
+  const store = createCatalogStore({ file: catalogFile, reloadIntervalMs, onEvent });
+  const access = createAccessControl({ file: accessFile, reloadIntervalMs, onEvent });
+  const send = (res, status, value, headers = {}) => {
+    res.writeHead(status, {
+      'Content-Type': 'application/json; charset=utf-8',
+      'Cache-Control': 'no-store',
+      ...headers,
+    });
+    res.end(JSON.stringify(value));
+  };
+  const server = createServer(async (req, res) => {
+    if (req.method === 'GET' && req.url === '/health') {
+      send(res, store.snapshot ? 200 : 503, { status: store.error ? 'degraded' : 'ok' });
+      return;
+    }
+    try {
+      access.authenticate(req);
+    } catch (e) {
+      send(
+        res,
+        e instanceof AccessError ? e.status : 503,
+        { error: 'Access denied.' },
+        e instanceof AccessError ? e.headers : {},
+      );
+      req.resume();
+      return;
+    }
+    if (req.method !== 'POST' || req.url !== '/v1/models/resolve') {
+      send(res, 404, { error: 'Not found.' });
+      req.resume();
+      return;
+    }
+    try {
+      if (!/^application\/json(?:\s*;|$)/i.test(req.headers['content-type'] || '')) {
+        send(res, 400, { error: 'JSON is required.' });
+        req.resume();
+        return;
+      }
+      const chunks = [];
+      let size = 0;
+      for await (const chunk of req) {
+        size += chunk.length;
+        if (size > 256 * 1024) {
+          send(res, 413, { error: 'Request size limit exceeded.' });
+          req.resume();
+          return;
+        }
+        chunks.push(chunk);
+      }
+      const body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+      if (
+        !body ||
+        typeof body !== 'object' ||
+        Array.isArray(body) ||
+        Object.keys(body).some((k) => k !== 'models') ||
+        !Array.isArray(body.models) ||
+        body.models.length > 1000 ||
+        body.models.some((n) => typeof n !== 'string' || !n.length || n.length > 512)
+      ) {
+        send(res, 400, { error: 'Expected an array of at most 1000 nonempty names, each up to 512 characters long.' });
+        return;
+      }
+      send(res, 200, resolveModels(store.snapshot, body.models));
+    } catch {
+      if (!res.headersSent) {
+        send(res, 400, { error: 'Could not read the request.' });
+      }
+    }
+  });
+  server.requestTimeout = 10000;
+  server.headersTimeout = 10000;
+  let closed = false;
+  return {
+    server,
+    store,
+    access,
+    async listen({ port = 3000, host = '127.0.0.1' } = {}) {
+      if (closed) {
+        throw new Error('The server has been stopped.');
+      }
+      try {
+        await access.load();
+        await store.load();
+        await new Promise((resolve, reject) => {
+          const fail = (e) => {
+            server.off('listening', ready);
+            reject(e);
+          };
+          const ready = () => {
+            server.off('error', fail);
+            resolve();
+          };
+          server.once('error', fail);
+          server.once('listening', ready);
+          server.listen(port, host);
+        });
+        return server.address();
+      } catch (e) {
+        access.stop();
+        store.stop();
+        throw e;
+      }
+    },
+    async close() {
+      closed = true;
+      access.stop();
+      store.stop();
+      if (server.listening) {
+        await new Promise((resolve, reject) => {
+          server.close((e) => (e ? reject(e) : resolve()));
+          server.closeIdleConnections();
+        });
+      }
+    },
+  };
+}

package/src/types/client.d.ts

@@ -0,0 +1,22 @@
+import type { ModelRecord } from './types.js';
+export interface ClientOptions {
+  baseUrl: string;
+  token: string;
+  models?: string[];
+  timezone?: string;
+  timeoutMs?: number;
+  fetch?: typeof globalThis.fetch;
+  now?: () => number;
+  random?: () => number;
+  setTimer?: typeof setTimeout;
+  clearTimer?: typeof clearTimeout;
+  onEvent?: (event: object) => void;
+}
+export interface CatalogClient {
+  start(): Promise<void>;
+  get(names: string[]): Promise<ModelRecord[]>;
+  refresh(): Promise<ModelRecord[] | undefined>;
+  stop(): void;
+  readonly nextRefreshAt: string | null;
+}
+export function createCatalogClient(options: ClientOptions): CatalogClient;

package/src/types/pricing.d.ts

@@ -0,0 +1,15 @@
+import type { ModelRecord, Usage, ServiceTier, TariffSnapshot } from './types.js';
+export function tariffSnapshot(record: ModelRecord, options?: { serviceTier?: ServiceTier }): TariffSnapshot | null;
+export function calculatePrice(
+  record: ModelRecord,
+  usage: Usage,
+  options?: { serviceTier?: ServiceTier },
+): {
+  usage: Usage;
+  snapshot: TariffSnapshot | null;
+  parts: Record<string, { quantity: number | null; rate: number | null; per: number; costUsd: number | null }>;
+  knownSubtotalUsd: number;
+  priceUsd: number | null;
+  status: 'incomplete' | 'qualified' | 'complete';
+  issues: string[];
+};

package/src/types/server.d.ts

@@ -0,0 +1,21 @@
+import type { AddressInfo } from 'node:net';
+import type { Server as HttpServer } from 'node:http';
+export interface ServerOptions {
+  catalogFile: string;
+  accessFile: string;
+  reloadIntervalMs?: number;
+  onEvent?: (event: object) => void;
+}
+export function createCatalogServer(options: ServerOptions): {
+  server: HttpServer;
+  store: {
+    load(): Promise<void>;
+    reload(): Promise<boolean>;
+    readonly error: string | null;
+    readonly snapshot: object | undefined;
+    stop(): void;
+  };
+  access: { reload(): Promise<unknown>; stop(): void };
+  listen(options?: { port?: number; host?: string }): Promise<AddressInfo | string | null>;
+  close(): Promise<void>;
+};