@forgezero/providers 0.1.0

package/dist/pool.js

@@ -0,0 +1,376 @@
+// src/index.ts
+class ProviderError extends Error {
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "ProviderError";
+  }
+}
+function envCredentials(env) {
+  return {
+    name: "env",
+    async get(reference, field) {
+      const key = `${reference}_${field}`.replace(/[.-]/g, "_").toUpperCase();
+      const value = env[key];
+      if (value === undefined) {
+        throw new ProviderError("CREDENTIAL_MISSING", `Set ${key} in the environment.`);
+      }
+      return value;
+    }
+  };
+}
+function chainCredentials(...sources) {
+  return {
+    name: sources.map((source) => source.name).join("+"),
+    async get(reference, field) {
+      let last;
+      for (const source of sources) {
+        try {
+          return await source.get(reference, field);
+        } catch (error) {
+          last = error;
+        }
+      }
+      throw last instanceof Error ? last : new ProviderError("CREDENTIAL_MISSING", `No source held ${reference}.${field}.`);
+    }
+  };
+}
+function staticConfig(services) {
+  const health = new Map;
+  return {
+    name: "static",
+    async list(serviceKey) {
+      return (services[serviceKey] ?? []).map((provider) => ({
+        ...provider,
+        health: health.get(`${serviceKey}:${provider.providerId}`) ?? provider.health
+      }));
+    },
+    async recordHealth(serviceKey, providerId, next) {
+      health.set(`${serviceKey}:${providerId}`, next);
+    }
+  };
+}
+function defineProvider(spec) {
+  return spec;
+}
+var STRIKES_TO_OFFLINE = 3;
+function nextHealth(current, kind) {
+  if (kind === "success")
+    return { strikes: 0, status: "ok" };
+  if (kind === "backoff")
+    return current ?? { strikes: 0, status: "ok" };
+  const strikes = (current?.strikes ?? 0) + 1;
+  return {
+    strikes,
+    status: strikes >= STRIKES_TO_OFFLINE ? "offline" : "degraded",
+    lastFailureAtTs: Date.now()
+  };
+}
+function createRegistry(options) {
+  const byId = new Map(options.providers.map((provider) => [provider.id, provider]));
+  async function call(serviceKey, args) {
+    const configured = [...await options.config.list(serviceKey)].filter((provider) => provider.enabled).sort((a, b) => a.priority - b.priority);
+    const attempts = [];
+    for (const entry of configured) {
+      const spec = byId.get(entry.providerId);
+      if (!spec) {
+        attempts.push({ providerId: entry.providerId, outcome: "skipped", error: "not registered" });
+        continue;
+      }
+      if (entry.health?.status === "offline") {
+        attempts.push({ providerId: entry.providerId, outcome: "skipped", error: "offline" });
+        continue;
+      }
+      options.before?.({ service: serviceKey, provider: entry.providerId });
+      try {
+        const result = await spec.invoke({
+          config: entry.config,
+          secret: (field) => options.credentials.get(entry.secretRef, field)
+        }, args);
+        attempts.push({ providerId: entry.providerId, outcome: "sent" });
+        await options.config.recordHealth(serviceKey, entry.providerId, nextHealth(entry.health, "success"));
+        const sent = { ok: true, result, provider: entry.providerId, attempts };
+        options.after?.(sent);
+        return sent;
+      } catch (error) {
+        const kind = spec.classify(error);
+        attempts.push({
+          providerId: entry.providerId,
+          outcome: "failed",
+          kind,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        await options.config.recordHealth(serviceKey, entry.providerId, nextHealth(entry.health, kind));
+        if (kind === "terminal") {
+          const refused = {
+            ok: false,
+            attempts,
+            error: new ProviderError("PAYLOAD_REJECTED", "The request was refused as malformed; no provider will accept it.")
+          };
+          options.after?.(refused);
+          return refused;
+        }
+      }
+    }
+    const failed = {
+      ok: false,
+      attempts,
+      error: new ProviderError(attempts.length === 0 ? "NO_PROVIDER" : "ALL_PROVIDERS_FAILED", attempts.length === 0 ? `No provider is configured for "${serviceKey}".` : `Every provider for "${serviceKey}" failed or was skipped.`)
+    };
+    options.after?.(failed);
+    return failed;
+  }
+  return { call };
+}
+var VERSION = "0.1.0";
+
+// src/http.ts
+class BudgetExhausted extends ProviderError {
+  host;
+  retryAfterMs;
+  constructor(host, retryAfterMs) {
+    super("RATE_BUDGET_EXHAUSTED", `The ${host} budget is spent. Retry in ${retryAfterMs}ms.`);
+    this.host = host;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+var windows = new Map;
+function resetBudgets() {
+  windows.clear();
+}
+function spend(budget, cost, nowMs) {
+  const ceiling = Math.floor(budget.limit * (budget.headroom ?? 0.9));
+  const current = windows.get(budget.host);
+  if (!current || current.resetAtMs <= nowMs) {
+    windows.set(budget.host, { spent: cost, resetAtMs: nowMs + budget.windowMs });
+    return;
+  }
+  if (current.spent + cost > ceiling) {
+    throw new BudgetExhausted(budget.host, current.resetAtMs - nowMs);
+  }
+  current.spent += cost;
+}
+function settle(host, reserved, actual) {
+  const current = windows.get(host);
+  if (!current)
+    return;
+  current.spent = Math.max(0, current.spent - reserved + actual);
+}
+var budgetState = (host) => windows.get(host);
+function createHttpClient(config) {
+  const doFetch = config.fetch ?? globalThis.fetch;
+  const timeoutMs = config.timeoutMs ?? 1e4;
+  return {
+    async call(request) {
+      const reserved = request.weight ?? config.budget.defaultCost;
+      spend(config.budget, reserved, Date.now());
+      const url = new URL(config.baseUrl + request.path);
+      for (const [key, value] of Object.entries(request.query ?? {})) {
+        url.searchParams.set(key, String(value));
+      }
+      const controller = new AbortController;
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await doFetch(url.toString(), {
+          method: request.method ?? "GET",
+          signal: controller.signal,
+          headers: {
+            ...request.body === undefined ? {} : { "content-type": "application/json" },
+            ...request.headers
+          },
+          ...request.body === undefined ? {} : { body: JSON.stringify(request.body) }
+        });
+        const cost = config.costOf?.(response);
+        if (cost !== undefined)
+          settle(config.budget.host, reserved, cost);
+        const text = await response.text();
+        let body;
+        try {
+          body = text ? JSON.parse(text) : null;
+        } catch {
+          body = text;
+        }
+        if (!response.ok) {
+          throw Object.assign(new Error(`${config.budget.host} ${response.status}`), {
+            status: response.status,
+            body,
+            retryAfter: response.headers.get("retry-after")
+          });
+        }
+        return { status: response.status, body, cost };
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+    budget: () => budgetState(config.budget.host)
+  };
+}
+var http = defineProvider({
+  id: "http",
+  service: "http",
+  label: "HTTP",
+  multiInstance: true,
+  credentials: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      apiKey: { type: "string", title: "API key", writeOnly: true },
+      apiSecret: { type: "string", title: "API secret", writeOnly: true }
+    }
+  },
+  config: {
+    type: "object",
+    additionalProperties: false,
+    required: ["baseUrl"],
+    properties: {
+      baseUrl: { type: "string", title: "Base URL" },
+      limit: { type: "integer", default: 6000, title: "Units per window" },
+      windowMs: { type: "integer", default: 60000 },
+      headroom: {
+        type: "number",
+        default: 0.9,
+        description: "Stop at this fraction of the limit. The venue's window boundary is not ours, and the penalty for crossing is a ban rather than a rejection."
+      }
+    }
+  },
+  async invoke(context, request) {
+    const config = context.config;
+    const client = createHttpClient({
+      baseUrl: config.baseUrl,
+      fetch: config.fetch,
+      costOf: config.costOf,
+      budget: {
+        host: new URL(config.baseUrl).host,
+        limit: config.limit ?? 6000,
+        windowMs: config.windowMs ?? 60000,
+        defaultCost: 1,
+        headroom: config.headroom
+      }
+    });
+    return client.call(request);
+  },
+  classify(error) {
+    const status = error.status;
+    if (status === 418)
+      return "backoff";
+    if (status === 429)
+      return "backoff";
+    if (status === 400 || status === 422)
+      return "terminal";
+    if (status === 401 || status === 403)
+      return "retryable";
+    return "retryable";
+  }
+});
+var binanceWeight = (response) => {
+  const header = response.headers.get("x-mbx-used-weight-1m");
+  return header === null ? undefined : Number(header);
+};
+var httpProviders = [http];
+
+// src/pool.ts
+class PoolExhausted extends Error {
+  addresses;
+  retryAfterMs;
+  constructor(addresses, retryAfterMs) {
+    super(`Every one of the ${addresses} outbound addresses is at its limit. Retry in ${retryAfterMs}ms, or add an address.`);
+    this.addresses = addresses;
+    this.retryAfterMs = retryAfterMs;
+    this.name = "PoolExhausted";
+  }
+}
+
+class PoolEmpty extends Error {
+  constructor() {
+    super("The address pool is enabled with no addresses configured.");
+    this.name = "PoolEmpty";
+  }
+}
+function createAddressPool(options) {
+  const now = options.now ?? Date.now;
+  const enabled = options.enabled ?? true;
+  const budgets = new Map;
+  const budgetFor = (address) => {
+    const existing = budgets.get(address.id);
+    if (existing)
+      return existing;
+    const budget = {
+      host: `pool:${address.id}`,
+      limit: options.perAddress,
+      windowMs: options.windowMs,
+      defaultCost: 1,
+      headroom: options.headroom ?? 0.9
+    };
+    budgets.set(address.id, budget);
+    return budget;
+  };
+  const usable = (address) => address.enabled && (address.blockedUntilMs ?? 0) <= now();
+  function orderFor(key, candidates) {
+    if (candidates.length === 0)
+      return [];
+    if (!key)
+      return [...candidates];
+    let hash = 0;
+    for (let index = 0;index < key.length; index += 1) {
+      hash = hash * 31 + key.charCodeAt(index) >>> 0;
+    }
+    const start = hash % candidates.length;
+    return [...candidates.slice(start), ...candidates.slice(0, start)];
+  }
+  return {
+    take(args = {}) {
+      if (!enabled) {
+        return { address: null, settle: () => {} };
+      }
+      const candidates = options.addresses.filter(usable);
+      if (candidates.length === 0) {
+        if (options.addresses.length === 0)
+          throw new PoolEmpty;
+        throw new PoolExhausted(options.addresses.length, 60000);
+      }
+      const cost = args.cost ?? 1;
+      let soonest = Number.MAX_SAFE_INTEGER;
+      for (const address of orderFor(args.key, candidates)) {
+        const budget = budgetFor(address);
+        try {
+          spend(budget, cost, now());
+          return {
+            address,
+            settle: (actual) => settle(budget.host, cost, actual)
+          };
+        } catch (cause) {
+          if (cause instanceof BudgetExhausted) {
+            soonest = Math.min(soonest, cause.retryAfterMs);
+            continue;
+          }
+          throw cause;
+        }
+      }
+      throw new PoolExhausted(candidates.length, soonest === Number.MAX_SAFE_INTEGER ? 1000 : soonest);
+    },
+    block(id, forMs) {
+      const address = options.addresses.find((entry) => entry.id === id);
+      if (address)
+        address.blockedUntilMs = now() + forMs;
+    },
+    state() {
+      return options.addresses.map((address) => ({
+        id: address.id,
+        spent: budgetState(`pool:${address.id}`)?.spent ?? 0,
+        limit: options.perAddress,
+        blocked: (address.blockedUntilMs ?? 0) > now(),
+        enabled: address.enabled
+      }));
+    },
+    capacity: () => enabled ? options.addresses.filter(usable).length * Math.floor(options.perAddress * (options.headroom ?? 0.9)) : Number.POSITIVE_INFINITY,
+    enabled
+  };
+}
+export {
+  createAddressPool,
+  PoolExhausted,
+  PoolEmpty
+};

package/dist/storage.d.ts

@@ -0,0 +1,137 @@
+import { ProviderError } from './index';
+export declare class StorageError extends ProviderError {
+    readonly status?: number | undefined;
+    constructor(code: string, message: string, status?: number | undefined);
+}
+/** Single-PUT ceiling. Above this a real implementation needs multipart. */
+export declare const MAX_SINGLE_PUT_BYTES: number;
+export interface S3Config {
+    endpoint: string;
+    region: string;
+    bucket: string;
+    /**
+     * `path` → `host/bucket/key`, `virtual` → `bucket.host/key`.
+     *
+     * Defaults to `path` because that is what every S3-compatible store other
+     * than AWS expects, and getting it wrong presents as a 404 rather than as a
+     * configuration error.
+     */
+    addressing?: 'path' | 'virtual';
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+export interface S3Credentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** STS / temporary credentials. Carried in `x-amz-security-token` when present. */
+    sessionToken?: string;
+}
+/**
+ * Percent-encode a path segment per SigV4's rules.
+ *
+ * `encodeURIComponent` leaves `!'()*` alone and S3 does not, so a key containing
+ * any of them signs correctly on our side and is rejected as a signature
+ * mismatch by the vendor — an error that points at credentials rather than at
+ * the filename that actually caused it.
+ */
+export declare function encodeSegment(segment: string): string;
+/** `20260731T140233Z` and `20260731`, the two forms every part of SigV4 wants. */
+export declare function amzDate(at: Date): {
+    full: string;
+    short: string;
+};
+export interface SignedRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+}
+/**
+ * AWS Signature Version 4.
+ *
+ * `at` is a parameter rather than read from the clock so the test suite can
+ * check the signature against AWS's own published example vectors — the only
+ * way to know the implementation is correct rather than merely self-consistent.
+ */
+export declare function signRequest(args: {
+    method: string;
+    url: URL;
+    region: string;
+    service?: string;
+    credentials: S3Credentials;
+    payloadHash: string;
+    headers?: Record<string, string>;
+    at: Date;
+}): Promise<SignedRequest>;
+export interface PutObjectArgs {
+    key: string;
+    body: Uint8Array | string;
+    contentType?: string;
+    /** Written as `x-amz-meta-*`. Never a place for anything secret — see below. */
+    metadata?: Record<string, string>;
+}
+export interface ObjectSummary {
+    key: string;
+    size: number;
+    etag?: string;
+    lastModified?: string;
+}
+export declare function createS3Client(config: S3Config, credentials: S3Credentials): {
+    putObject(args: PutObjectArgs): Promise<{
+        etag?: string;
+    }>;
+    getObject(key: string): Promise<Uint8Array>;
+    headObject(key: string): Promise<ObjectSummary | null>;
+    deleteObject(key: string): Promise<void>;
+    /**
+     * List, following continuation tokens.
+     *
+     * S3 caps a response at 1000 keys and says so only by returning a token.
+     * A client that ignores it silently lists the first thousand — which is
+     * correct in every test and wrong in every production bucket.
+     */
+    listObjects(prefix?: string, limit?: number): Promise<ObjectSummary[]>;
+    /**
+     * A URL that works without our credentials, for a bounded time.
+     *
+     * The signature is in the query string, so anyone holding the URL can use
+     * it — it is a bearer token that survives a browser history, a referrer
+     * header and a support screenshot. Expiries are therefore short by default
+     * and the caller has to ask for longer.
+     */
+    presign(args: {
+        key: string;
+        expiresInSec?: number;
+        method?: "GET" | "PUT";
+    }): Promise<string>;
+    bucket: string;
+    endpoint: string;
+};
+export type S3Client = ReturnType<typeof createS3Client>;
+export declare function parseListXml(xml: string): ObjectSummary[];
+export type StorageRequest = {
+    op: 'put';
+    key: string;
+    body: Uint8Array | string;
+    contentType?: string;
+    metadata?: Record<string, string>;
+} | {
+    op: 'get';
+    key: string;
+} | {
+    op: 'head';
+    key: string;
+} | {
+    op: 'delete';
+    key: string;
+} | {
+    op: 'list';
+    prefix?: string;
+    limit?: number;
+} | {
+    op: 'presign';
+    key: string;
+    expiresInSec?: number;
+    method?: 'GET' | 'PUT';
+};
+export declare const s3: import("./index").ProviderSpec<StorageRequest, unknown>;
+export declare const storageProviders: readonly [import("./index").ProviderSpec<StorageRequest, unknown>];