Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

12.0 KB
Raw Blame
/**
 * Provider allowlist filter for the published catalog.
 *
 * A provider is the raw id prefix before the first `/` (for example `cc`
 * in `cc/claude-sonnet-4-6`), read BEFORE the enrichment overlay renames
 * anything. Ids without a `/` carry no provider claim and always pass.
 *
 * Unknown names in the allowlist warn once and filter nothing for that
 * name (fail-open, the inverse of the capacity-subset options which are
 * fail-closed). Only a filter that matches nothing publishes an empty
 * catalog, with an explicit warning (fail-explicit, never a silent
 * fallback to the full catalog).
 *
 * Alias design: the same alias pass as the usable-prefix filter resolves
 * short aliases (`cc`) to canonical provider ids (`claude`), so `["claude"]`
 * matches `cc/...` rows.
 */

import type { OmniRouteRawCombo } from "./shared/combos-map.js";
import type { OmniRouteEnrichmentMap } from "./shared/enrich.js";
import type { Logger } from "./shared/logger.js";

/** Compiled allowlist. `undefined` means inactive (empty/absent = full catalog). */
export interface ProviderFilter {
  /** Normalized (trimmed, lowercased, deduplicated) allowlist entries. */
  allow: Set<string>;
  /** Operator-facing spellings, same order, for diagnostics. */
  originals: string[];
}

/** Alias/canonical resolution tables, normalized lowercase at build time. */
export interface ProviderResolve {
  /** Every known name: enrichment aliases, provider canonicals, canonicals of aliases. */
  known: Set<string>;
  /** alias -> canonical (for example `cc` -> `claude`). */
  aliasToCanonical: Map<string, string>;
  /** canonical -> aliases (for example `claude` -> {`cc`}). */
  canonicalToAliases: Map<string, Set<string>>;
}

/** Normalize one operator entry; empty after trim means "no opinion". */
function normalizeName(value: string): string | undefined {
  if (typeof value !== "string") return undefined;
  const trimmed = value.trim().toLowerCase();
  return trimmed.length > 0 ? trimmed : undefined;
}

/**
 * Compile the operator allowlist. Empty/absent/blank-only input returns
 * `undefined` (filter inactive, full catalog, no warning).
 */
export function compileProviderFilter(allow?: string[]): ProviderFilter | undefined {
  if (!allow || allow.length === 0) return undefined;
  const seen = new Set<string>();
  const originals: string[] = [];
  for (const raw of allow) {
    const normalized = normalizeName(raw);
    if (normalized === undefined || seen.has(normalized)) continue;
    seen.add(normalized);
    originals.push(typeof raw === "string" ? raw.trim() : String(raw));
  }
  if (seen.size === 0) return undefined;
  return { allow: seen, originals };
}

/**
 * Provider prefix of a raw catalog id (lowercased). `undefined` for bare
 * ids without a `/` — those carry no provider claim and always pass.
 */
export function providerOf(id: string): string | undefined {
  if (typeof id !== "string") return undefined;
  const slash = id.indexOf("/");
  if (slash <= 0) return undefined;
  const prefix = id.slice(0, slash).trim().toLowerCase();
  return prefix.length > 0 ? prefix : undefined;
}

/**
 * Build the resolution tables from raw enrichment alias/canonical pairs
 * plus usable canonicals. All keys normalized lowercase once here, never
 * per comparison.
 */
export function buildProviderResolve(
  pairs: Array<{ alias?: string; canonical?: string }>,
  usableCanonicals?: Iterable<string>
): ProviderResolve {
  const known = new Set<string>();
  const aliasToCanonical = new Map<string, string>();
  const canonicalToAliases = new Map<string, Set<string>>();
  const addAlias = (alias: string, canonical: string): void => {
    aliasToCanonical.set(alias, canonical);
    let bucket = canonicalToAliases.get(canonical);
    if (!bucket) {
      bucket = new Set<string>();
      canonicalToAliases.set(canonical, bucket);
    }
    bucket.add(alias);
  };
  for (const pair of pairs) {
    const alias = normalizeName(pair.alias ?? "");
    const canonical = normalizeName(pair.canonical ?? "");
    if (alias !== undefined) known.add(alias);
    if (canonical !== undefined) known.add(canonical);
    if (alias !== undefined && canonical !== undefined && alias !== canonical) {
      if (!aliasToCanonical.has(alias)) addAlias(alias, canonical);
      else {
        const existing = aliasToCanonical.get(alias);
        if (existing !== undefined && existing !== canonical) {
          let bucket = canonicalToAliases.get(canonical);
          if (!bucket) {
            bucket = new Set<string>();
            canonicalToAliases.set(canonical, bucket);
          }
          bucket.add(alias);
        }
      }
      known.add(alias);
      known.add(canonical);
    }
  }
  if (usableCanonicals) {
    for (const raw of usableCanonicals) {
      const canonical = normalizeName(raw);
      if (canonical === undefined) continue;
      known.add(canonical);
    }
  }
  return { known, aliasToCanonical, canonicalToAliases };
}

/**
 * Whether one provider prefix matches the allowlist. Without a resolve
 * table this is a direct prefix comparison; with one, aliases resolve both
 * ways: prefix in allow, canonical(prefix) in allow, or prefix is an alias
 * of an allowed canonical.
 */
export function matchesAllow(
  prefix: string | undefined,
  filter: ProviderFilter | undefined,
  resolve?: ProviderResolve
): boolean {
  if (!filter) return true;
  if (prefix === undefined) return true;
  if (filter.allow.has(prefix)) return true;
  if (!resolve) return false;
  const canonPrefix = resolve.aliasToCanonical.get(prefix) ?? prefix;
  for (const allowed of filter.allow) {
    if (canonPrefix === allowed) return true;
    const canonAllowed = resolve.aliasToCanonical.get(allowed) ?? allowed;
    if (prefix === canonAllowed || canonPrefix === canonAllowed) return true;
    const aliases = resolve.canonicalToAliases.get(allowed);
    if (aliases !== undefined && aliases.has(prefix)) return true;
    const aliasesOfPrefix = resolve.canonicalToAliases.get(canonPrefix);
    if (aliasesOfPrefix !== undefined && aliasesOfPrefix.has(allowed)) return true;
  }
  return false;
}

/** Whether a raw model/combo id passes the provider filter. */
export function passesProviderFilter(
  id: string,
  filter: ProviderFilter | undefined,
  resolve?: ProviderResolve,
  allUnknown?: boolean
): boolean {
  if (!filter) return true;
  const prefix = providerOf(id);
  if (prefix === undefined) return true;
  if (matchesAllow(prefix, filter, resolve)) return true;
  // Fail-open on prefixes unknown to the vocabulary tables: an unknown
  // prefix proves nothing about the provider, so it cannot exclude.
  if (resolve && !resolve.known.has(prefix)) return true;
  // Fail-open on allow entries unknown to the vocabulary: when EVERY allow
  // name is outside the vocabulary, the whole filter stays inert (warned
  // once at publish time). A mix of known + unknown still lets the known
  // names restrict. The flag is precomputed once per publish; without a
  // resolve table it is false and only the direct comparison above decides.
  if (resolve && (allUnknown ?? filterAllUnknown(filter, resolve))) return true;
  return false;
}

/** Whether every allow entry sits outside the vocabulary (filter inert). */
export function filterAllUnknown(filter: ProviderFilter, resolve: ProviderResolve): boolean {
  for (const allowed of filter.allow) {
    if (resolve.known.has(allowed)) return false;
  }
  return true;
}

/** Read one combo member model id, skipping `combo-ref` steps. */
function comboMemberIds(combo: OmniRouteRawCombo): string[] {
  const steps = Array.isArray(combo.models) ? combo.models : [];
  const out: string[] = [];
  for (const step of steps) {
    if (step?.kind === "combo-ref") continue;
    const modelId = typeof step?.model === "string" ? step.model : "";
    if (modelId.length === 0) continue;
    out.push(modelId);
  }
  return out;
}

/**
 * Whether a combo passes: at least one member passes, `combo-ref` steps
 * skipped, zero resolvable members keep (mirrors the usableOnly combo rule).
 */
export function passesProviderCombo(
  combo: OmniRouteRawCombo,
  filter: ProviderFilter | undefined,
  resolve?: ProviderResolve,
  allUnknown?: boolean
): boolean {
  if (!filter) return true;
  const members = comboMemberIds(combo);
  if (members.length === 0) return true;
  for (const member of members) {
    if (passesProviderFilter(member, filter, resolve, allUnknown)) return true;
  }
  return false;
}

/** Allow entries unknown to the vocabulary tables (operator spellings back). */
export function unknownProviders(filter: ProviderFilter | undefined, known: Set<string>): string[] {
  if (!filter) return [];
  const out: string[] = [];
  for (const original of filter.originals) {
    const normalized = normalizeName(original);
    if (normalized === undefined) continue;
    if (!known.has(normalized)) out.push(original);
  }
  return out;
}

/**
 * Warn once about unknown allow entries. Callers pass the publish-wide
 * warning set (`opts.collisionWarned`, shared across publishes) so a repeat
 * publish warns once per key.
 */
export function warnUnknownProviders(
  filter: ProviderFilter | undefined,
  known: Set<string>,
  warned: Set<string>,
  log: Pick<Logger, "warn">
): void {
  if (!filter) return;
  const unknown = unknownProviders(filter, known);
  if (unknown.length === 0) return;
  const key = `provider-unknown::${[...filter.allow].sort().join(",")}`;
  if (warned.has(key)) return;
  warned.add(key);
  log.warn(
    `[omniroute-v2] unknown provider(s) in providersAllow: ${unknown.join(",")} — ` +
      `no catalog entry matches these names, they filter nothing.`
  );
}

/**
 * Provider-allowlist preamble: build the filter/resolve tables from the
 * same alias pairs the collection passes use, and warn on an active
 * filter with no vocabulary or unknown names. Returns the three values
 * both collection points read, so the preamble cannot drift from them.
 */
export function resolveProviderFilter(
  providersAllow: string[] | undefined,
  enrichment: OmniRouteEnrichmentMap,
  canonicalToAlias: ReadonlyMap<string, string>,
  usableCanonicals: Iterable<string> | undefined,
  warned: Set<string>,
  log: Pick<Logger, "warn">
): {
  providerFilter: ProviderFilter | undefined;
  providerResolve: ProviderResolve | undefined;
  providerAllUnknown: boolean;
} {
  const providerFilter = compileProviderFilter(providersAllow);
  let providerResolve: ProviderResolve | undefined;
  let providerAllUnknown = false;
  if (providerFilter) {
    const pairs: Array<{ alias?: string; canonical?: string }> = [];
    for (const entry of enrichment.values()) {
      pairs.push({ alias: entry.providerAlias, canonical: entry.providerCanonical });
    }
    for (const [canonical, alias] of canonicalToAlias) {
      pairs.push({ alias, canonical });
    }
    providerResolve = buildProviderResolve(pairs, usableCanonicals);
    providerAllUnknown = filterAllUnknown(providerFilter, providerResolve);
    if (providerResolve.known.size === 0)
      warnNoVocabulary(providerFilter, providerResolve.known, warned, log);
    else warnUnknownProviders(providerFilter, providerResolve.known, warned, log);
  }
  return { providerFilter, providerResolve, providerAllUnknown };
}

/** Warn once when the filter is active but no vocabulary exists. */
export function warnNoVocabulary(
  filter: ProviderFilter | undefined,
  known: Set<string>,
  warned: Set<string>,
  log: Pick<Logger, "warn">
): void {
  if (!filter) return;
  if (known.size > 0) return;
  const key = "provider-no-vocabulary";
  if (warned.has(key)) return;
  warned.add(key);
  log.warn(
    `[omniroute-v2] provider filter active but no provider vocabulary available, ` +
      `keeping the full catalog.`
  );
}

/** Warn once when the provider filter drops the whole catalog. */
export function warnProviderMatchedNothing(
  filter: ProviderFilter | undefined,
  warned: Set<string>,
  log: Pick<Logger, "warn">
): void {
  if (!filter) return;
  const key = `provider-matched-nothing::${[...filter.allow].sort().join(",")}`;
  if (warned.has(key)) return;
  warned.add(key);
  log.warn(
    `[omniroute-v2] providersAllow [${filter.originals.join(", ")}] matched nothing, publishing empty catalog.`
  );
}