@layerall/core 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# @layerall/core
+
+The orchestration engine for LayerAll: routing strategies, provider router with retries/fallback and typed policies.
+
+## Install
+
+```bash
+npm install @layerall/core
+```
+
+## Usage
+
+```ts
+import { Router, type PolicyDocument, type Provider } from '@layerall/core';
+
+const providers: Record<string, Provider> = {
+  providerA: {
+    id: 'providerA', weight: 50, health: 0.96, baseLatency: 180, failRate: 0.06,
+    invoke: async ctx => upstreamCallA(ctx),
+  },
+  providerB: { id: 'providerB', /* ... */ invoke: async ctx => upstreamCallB(ctx) },
+};
+
+const policy: PolicyDocument = {
+  tenants: {
+    default: {
+      providers: ['providerA', 'providerB'],
+      operations: {
+        create: { strategy: 'round_robin', timeoutMs: 8000, retries: { max: 1, backoffMs: 300 }, failover: true },
+      },
+    },
+  },
+};
+
+const router = new Router({
+  policy,
+  providers,
+  observer: { onAttempt: l => console.log(l), onFinish: r => console.log(r) },
+});
+
+const res = await router.execute('create', { externalId: 'req_123', data: {} });
+```
+
+## Strategies
+
+| Strategy       | Behaviour                                          |
+| -------------- | -------------------------------------------------- |
+| `round_robin`  | Cycles through eligible providers in policy order. |
+| `load_balance` | Weighted random by `Provider.weight` / policy weights. |
+| `most_fast`    | Lowest score = `baseLatency + (1-health)*280 + failRate*420`. |
+| `failover`     | Tries eligible providers in order until one succeeds. |
+
+See the root [README](../../README.md) for the product overview.

package/dist/index.d.ts

@@ -0,0 +1,185 @@
+/** Canonical operations an orchestrator exposes to clients. */
+type OperationName = 'create' | 'send' | 'status' | 'cancel';
+/** Pluggable routing strategies. */
+type StrategyName = 'round_robin' | 'load_balance' | 'most_fast' | 'failover';
+/** A registered provider implementation. Adapters map domain calls to `invoke`. */
+interface Provider<TContext = unknown, TResult = unknown> {
+    id: string;
+    /** Optional weights used by `load_balance`. Higher weight = more traffic share. */
+    weight?: number;
+    /** Optional capacity hint used by `load_balance` when `weight` is absent. */
+    capacity?: number;
+    /** Whether the provider is currently eligible for routing (defaults to true). */
+    enabled?: boolean;
+    /** Optional current health score in [0, 1]; used by `most_fast` and failover scoring. */
+    health?: number;
+    /** Optional base latency in ms; used by `most_fast` as the expected response time. */
+    baseLatency?: number;
+    /** Optional transient failure rate in [0, 1]; used by `most_fast` as a penalty. */
+    failRate?: number;
+    /**
+     * Executes the operation against this provider. Implementations translate the
+     * provider-agnostic call into a concrete downstream API request.
+     */
+    invoke: (ctx: InvokeContext<TContext>) => Promise<TResult>;
+}
+/** Context passed to a provider on invocation. `payload` is domain-specific. */
+interface InvokeContext<TData = unknown> {
+    operation: OperationName;
+    requestId: string;
+    payload: OperationPayload<TData>;
+    signal?: AbortSignal;
+}
+/** Generic operation payload. `externalId` enables idempotency. */
+interface OperationPayload<TData = unknown> {
+    externalId?: string;
+    data: TData;
+}
+/** Outcome returned to the client, normalized across providers. */
+interface OperationResult<TResult = unknown> {
+    id: string;
+    requestId: string;
+    provider: string;
+    operation: OperationName;
+    status: 'succeeded' | 'failed';
+    result?: TResult;
+    error?: OperationError;
+    /** Latency observed for the successful/terminal call, in ms. */
+    latencyMs: number;
+    /** Number of provider attempts consumed (including the successful one). */
+    attempts: number;
+    /** Stable receipt for audit/storage; derived from provider + requestId. */
+    providerReceipt: string;
+}
+/** Normalized error surface. */
+interface OperationError {
+    code: string;
+    message: string;
+    /** Whether the error is likely transient (retryable). */
+    transient?: boolean;
+    provider: string;
+}
+/** Per-operation retry policy. */
+interface RetryPolicy {
+    max: number;
+    backoffMs: number;
+    /** Optional multiplier applied between successive backoffs (default 1, i.e. fixed). */
+    backoffMultiplier?: number;
+}
+/** Per-operation configuration entry in a tenant policy. */
+interface OperationPolicy {
+    strategy?: StrategyName;
+    timeoutMs?: number;
+    retries?: RetryPolicy;
+    failover?: boolean;
+    /** Explicit weights keyed by provider id (overrides `Provider.weight`). */
+    weights?: Record<string, number>;
+    /** Optional short cache TTL for idempotent reads such as `status`. */
+    cacheTtlMs?: number;
+}
+/** Flags set by the client on a per-request basis to override policy. */
+interface OperationRequestOptions {
+    strategy?: StrategyName;
+    timeoutMs?: number;
+    failover?: boolean;
+    signal?: AbortSignal;
+}
+/** A tenant routing policy. */
+interface TenantPolicy {
+    providers: string[];
+    operations: Partial<Record<OperationName, OperationPolicy>>;
+}
+/** Root policy document keyed by tenant id. */
+interface PolicyDocument {
+    tenants: Record<string, TenantPolicy>;
+}
+/** Metadata collected per attempt for observability. */
+interface AttemptLog {
+    /** Id of the request this attempt belongs to. */
+    requestId: string;
+    /** Operation being executed. */
+    operation: OperationName;
+    provider: string;
+    attempt: number;
+    ok: boolean;
+    latencyMs: number;
+    transient: boolean;
+    /** Human-readable error message when `ok === false`. */
+    error?: string;
+    /** Stable error code (e.g. `upstream_error`, `timeout`) when `ok === false`. */
+    errorCode?: string;
+}
+/** Sink receiving attempt logs and final outcomes for observability. */
+interface Observer {
+    onStart?(ev: {
+        requestId: string;
+        operation: OperationName;
+        strategy: StrategyName;
+    }): void;
+    onAttempt?(log: AttemptLog): void;
+    onFinish?(res: OperationResult): void;
+}
+
+/**
+ * Internal selection context shared by every strategy.
+ * Strategies MUST be pure given this state snapshot so they are trivially testable.
+ */
+interface SelectionContext {
+    strategy: StrategyName;
+    /** Eligible providers, in policy order. */
+    eligible: Provider[];
+    /** Provider id weights across all registered providers (policy or provider-weighted). */
+    weights: Record<string, number>;
+    roundRobinIndex: {
+        value: number;
+    };
+}
+type Strategy = (ctx: SelectionContext) => Provider | null;
+/** Round‑robin: cycles through eligible providers in order. */
+declare const roundRobin: Strategy;
+/** Weighted random selection by provider weight (capacity-aware when no weight). */
+declare const loadBalance: Strategy;
+/** Picks the provider with the lowest expected score = latency + health/failure penalty. */
+declare const mostFast: Strategy;
+/** Failover: returns the first eligible provider (the router tries them in order on failure). */
+declare const failover: Strategy;
+declare const strategies: Record<StrategyName, Strategy>;
+
+interface RouterOptions {
+    policy: PolicyDocument;
+    providers: Record<string, Provider>;
+    tenant?: string;
+    observer?: Observer;
+    defaultStrategy?: StrategyName;
+    defaultTimeoutMs?: number;
+}
+declare class Router {
+    private readonly providers;
+    private readonly policy;
+    private readonly observer?;
+    private readonly defaultStrategy;
+    private readonly defaultTimeoutMs;
+    private readonly rrIndex;
+    constructor(opts: RouterOptions);
+    execute<TData = unknown, TResult = unknown>(operation: OperationName, payload: OperationPayload<TData>, options?: OperationRequestOptions): Promise<OperationResult<TResult>>;
+    private eligibleProviders;
+    private resolveTenant;
+    private signal;
+    private success;
+    private fail;
+    private emitAttempt;
+}
+
+/** Generates a short unique id (timestamp + random). */
+declare function uid(prefix?: string): string;
+/** Clamps `n` between `min` and `max`. */
+declare function clamp(n: number, min: number, max: number): number;
+/** Sleep helper that respects an optional AbortSignal. */
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+declare class AbortedError extends Error {
+    constructor();
+}
+/** Builds a stable audit receipt from the provider id and requestId. */
+declare function buildReceipt(providerId: string, requestId: string): string;
+
+export { AbortedError, type AttemptLog, type InvokeContext, type Observer, type OperationError, type OperationName, type OperationPayload, type OperationPolicy, type OperationRequestOptions, type OperationResult, type PolicyDocument, type Provider, type RetryPolicy, Router, type RouterOptions, type SelectionContext, type Strategy, type StrategyName, type TenantPolicy, buildReceipt, clamp, failover, loadBalance, mostFast, roundRobin, sleep, strategies, uid };

package/dist/index.js

@@ -0,0 +1,266 @@
+// src/strategies.ts
+var roundRobin = (ctx) => {
+  const { eligible, roundRobinIndex } = ctx;
+  if (eligible.length === 0) return null;
+  const chosen = eligible[roundRobinIndex.value % eligible.length];
+  roundRobinIndex.value = (roundRobinIndex.value + 1) % Number.MAX_SAFE_INTEGER;
+  return chosen;
+};
+var loadBalance = (ctx) => {
+  const { eligible, weights } = ctx;
+  if (eligible.length === 0) return null;
+  const total = eligible.reduce(
+    (sum, p) => sum + (resolveWeight(p, weights) || 0),
+    0
+  );
+  if (total <= 0) return eligible[0];
+  let r = Math.random() * total;
+  for (const p of eligible) {
+    r -= resolveWeight(p, weights) || 0;
+    if (r <= 0) return p;
+  }
+  return eligible[eligible.length - 1];
+};
+var mostFast = (ctx) => {
+  const { eligible } = ctx;
+  if (eligible.length === 0) return null;
+  let best = null;
+  let bestScore = Infinity;
+  for (const p of eligible) {
+    const noise = Math.random() * 28 - 14;
+    const latency = (p.baseLatency ?? 200) + noise;
+    const penalty = (1 - (p.health ?? 1)) * 280 + (p.failRate ?? 0) * 420;
+    const score = latency + penalty;
+    if (score < bestScore) {
+      bestScore = score;
+      best = p;
+    }
+  }
+  return best;
+};
+var failover = (ctx) => {
+  const { eligible } = ctx;
+  return eligible[0] ?? null;
+};
+var strategies = {
+  round_robin: roundRobin,
+  load_balance: loadBalance,
+  most_fast: mostFast,
+  failover
+};
+function resolveWeight(p, weights) {
+  const explicit = weights[p.id];
+  if (typeof explicit === "number") return explicit;
+  if (typeof p.weight === "number") return p.weight;
+  if (typeof p.capacity === "number") return p.capacity;
+  return 1;
+}
+
+// src/utils.ts
+function uid(prefix = "") {
+  const ts = Date.now().toString(36);
+  const rand = Math.random().toString(36).slice(2, 10);
+  return `${prefix}${prefix ? "_" : ""}${ts}${rand}`;
+}
+function clamp(n, min, max) {
+  return Math.max(min, Math.min(max, n));
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new AbortedError());
+    const t = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, Math.max(0, ms));
+    const onAbort = () => {
+      clearTimeout(t);
+      reject(new AbortedError());
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+var AbortedError = class extends Error {
+  constructor() {
+    super("aborted");
+    this.name = "AbortedError";
+  }
+};
+function buildReceipt(providerId, requestId) {
+  const h = simpleHash(`${providerId}:${requestId}`);
+  return `${providerId}:${requestId}:${h.toString(36)}`;
+}
+function simpleHash(input) {
+  let h = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+
+// src/router.ts
+var DEFAULT_TENANT = "default";
+var Router = class {
+  constructor(opts) {
+    this.rrIndex = { value: 0 };
+    this.providers = opts.providers;
+    this.policy = opts.policy;
+    this.observer = opts.observer;
+    this.defaultStrategy = opts.defaultStrategy ?? "round_robin";
+    this.defaultTimeoutMs = opts.defaultTimeoutMs ?? 8e3;
+  }
+  async execute(operation, payload, options = {}) {
+    const tenant = this.resolveTenant();
+    const opPolicy = tenant.operations[operation] ?? {};
+    const strategy = options.strategy ?? opPolicy.strategy ?? this.defaultStrategy;
+    const timeoutMs = options.timeoutMs ?? opPolicy.timeoutMs ?? this.defaultTimeoutMs;
+    const failover2 = options.failover ?? opPolicy.failover ?? strategy === "failover";
+    const retries = opPolicy.retries ?? { max: 0, backoffMs: 300 };
+    const requestId = payload.externalId ?? uid("req");
+    this.observer?.onStart?.({ requestId, operation, strategy });
+    const eligible = this.eligibleProviders(tenant);
+    if (eligible.length === 0) {
+      return this.fail(requestId, operation, "no_providers", "Nenhum provedor ativo.", 0, 0);
+    }
+    const weights = opPolicy.weights ?? {};
+    const selectionCtx = {
+      strategy,
+      eligible,
+      weights,
+      roundRobinIndex: this.rrIndex
+    };
+    const startedAt = performance.now();
+    const order = failover2 ? eligible : [strategies[strategy](selectionCtx)].filter(
+      (p) => p !== null
+    );
+    const targets = order.length > 0 ? order : eligible;
+    let attempts = 0;
+    let lastError = null;
+    for (const provider of targets) {
+      const maxAttempts = 1 + (failover2 ? 0 : clamp(retries.max, 0, 5));
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        attempts++;
+        const attemptStart = performance.now();
+        try {
+          const signal = this.signal(timeoutMs, options.signal);
+          const result = await provider.invoke({
+            operation,
+            requestId,
+            payload,
+            signal
+          });
+          const latencyMs = Math.round(performance.now() - attemptStart);
+          this.emitAttempt(provider.id, attempt, true, latencyMs, false, void 0, void 0, requestId, operation);
+          const res = this.success(requestId, provider.id, operation, result, latencyMs, attempts);
+          this.observer?.onFinish?.(res);
+          return res;
+        } catch (err) {
+          const latencyMs = Math.round(performance.now() - attemptStart);
+          const transient = isTransient(err);
+          this.emitAttempt(provider.id, attempt, false, latencyMs, transient, errMsg(err), errCode(err), requestId, operation);
+          if (err instanceof AbortedError || options.signal?.aborted) {
+            const out2 = this.fail(requestId, operation, "aborted", "opera\xE7\xE3o abortada", latencyMs, attempts, provider.id);
+            this.observer?.onFinish?.(out2);
+            return out2;
+          }
+          if (attempt < maxAttempts && transient) {
+            const backoff = retries.backoffMs * Math.pow(retries.backoffMultiplier ?? 1, attempt - 1);
+            await sleep(clamp(backoff, 0, 5e3), options.signal).catch(() => {
+            });
+            continue;
+          }
+          lastError = this.fail(requestId, operation, errCode(err), errMsg(err), latencyMs, attempts, provider.id);
+          break;
+        }
+      }
+    }
+    const totalMs = Math.round(performance.now() - startedAt);
+    const out = lastError ?? this.fail(requestId, operation, "all_failed", "todos os provedores falharam", totalMs, attempts);
+    this.observer?.onFinish?.(out);
+    return out;
+  }
+  eligibleProviders(tenant) {
+    return tenant.providers.map((id) => this.providers[id]).filter((p) => p !== void 0 && p.enabled !== false);
+  }
+  resolveTenant() {
+    return this.policy.tenants[DEFAULT_TENANT] ?? { providers: [], operations: {} };
+  }
+  signal(timeoutMs, parent) {
+    if (timeoutMs <= 0 && !parent) return void 0;
+    const ctrl = new AbortController();
+    const t = timeoutMs > 0 ? setTimeout(() => ctrl.abort(), timeoutMs) : void 0;
+    const onParentAbort = () => ctrl.abort();
+    parent?.addEventListener("abort", onParentAbort, { once: true });
+    ctrl.signal.addEventListener("abort", () => {
+      if (t) clearTimeout(t);
+      parent?.removeEventListener("abort", onParentAbort);
+    });
+    return ctrl.signal;
+  }
+  success(requestId, providerId, operation, result, latencyMs, attempts) {
+    return {
+      id: uid("op"),
+      requestId,
+      provider: providerId,
+      operation,
+      status: "succeeded",
+      result,
+      latencyMs,
+      attempts,
+      providerReceipt: buildReceipt(providerId, requestId)
+    };
+  }
+  // Using overload: caller casts to TResult for ergonomics
+  fail(requestId, operation, code, message, latencyMs, attempts, provider) {
+    return {
+      id: uid("op"),
+      requestId,
+      provider: provider ?? "\u2014",
+      operation,
+      status: "failed",
+      latencyMs,
+      attempts,
+      providerReceipt: buildReceipt(provider ?? "none", requestId),
+      error: { code, message, transient: false, provider: provider ?? "\u2014" }
+    };
+  }
+  emitAttempt(provider, attempt, ok, latencyMs, transient, error, errorCode, requestId, operation) {
+    this.observer?.onAttempt?.({ provider, attempt, ok, latencyMs, transient, error, errorCode, requestId, operation });
+  }
+};
+function isTransient(err) {
+  if (!err) return false;
+  if (typeof err === "object" && err !== null) {
+    return err.transient === true;
+  }
+  return false;
+}
+function errCode(err) {
+  if (typeof err === "object" && err !== null) {
+    const code = err.code;
+    if (typeof code === "string") return code;
+  }
+  return "error";
+}
+function errMsg(err) {
+  if (typeof err === "string") return err;
+  if (err instanceof Error) return err.message;
+  if (typeof err === "object" && err !== null) {
+    const message = err.message;
+    if (typeof message === "string") return message;
+  }
+  return "unknown error";
+}
+export {
+  AbortedError,
+  Router,
+  buildReceipt,
+  clamp,
+  failover,
+  loadBalance,
+  mostFast,
+  roundRobin,
+  sleep,
+  strategies,
+  uid
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@layerall/core",
+  "version": "0.1.0",
+  "description": "Orchestration engine for LayerAll — types, routing strategies and provider router with retries and fallback",
+  "keywords": [
+    "orchestration",
+    "abstraction-layer",
+    "router",
+    "failover",
+    "round-robin",
+    "load-balance",
+    "strategies",
+    "typescript"
+  ],
+  "author": "Sidarta Veloso <sidartaveloso@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sidartaveloso/layerall.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/sidartaveloso/layerall/issues"
+  },
+  "homepage": "https://github.com/sidartaveloso/layerall#readme",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "clean": "rm -rf dist",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "test:no-coverage": "vitest run",
+    "prepublishOnly": "pnpm build"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}