Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript
16.9 KB
Raw Blame
import { describe, it, expect } from 'vitest'
import {
  buildGroups,
  groupMatchesQuery,
  isGroupDepleted,
  isMemberDepleted,
  isMemberSplit,
  memberEndpointTitle,
  memberOverrideKey,
  memberProviderLabel,
  providerPinId,
  splitsWithoutMember,
  tightestRateLimit,
  type RateLimitUsageRow,
  type Row,
  clampRankToIndex,
} from './routing'

// Per-endpoint identity must be INVISIBLE until two endpoints actually serve the
// same model id (#651). The server sends `endpointScope` / `qualifiedModelId` on
// every custom row — including the only relay of a one-endpoint install — so any
// gate written against those fields alone leaks the user's own base URL. These
// cases pin the gate to the collision itself.

type R = {
  platform: string; modelId: string; source?: 'catalog' | 'custom'
  keyLabel?: string | null; endpointScope?: string | null; qualifiedModelId?: string | null
  displayName?: string
}

const soloRelay: R = {
  platform: 'custom', modelId: 'deepseek-v3.1', source: 'custom', keyLabel: 'Custom',
  endpointScope: 'http://192.168.1.50:11434/v1',
  qualifiedModelId: 'custom:deepseek-v3.1#192.168.1.50-11434-v1',
}
const relayA: R = {
  platform: 'custom', modelId: 'deepseek-v3.1', source: 'custom', keyLabel: 'Relay A',
  endpointScope: 'https://relay-a.example.com/v1',
  qualifiedModelId: 'custom:deepseek-v3.1#relay-a.example.com-v1',
}
const relayB: R = {
  platform: 'custom', modelId: 'deepseek-v3.1', source: 'custom', keyLabel: 'Relay B',
  endpointScope: 'https://relay-b.example.com/v1',
  qualifiedModelId: 'custom:deepseek-v3.1#relay-b.example.com-v1',
}
const catalog: R = { platform: 'groq', modelId: 'llama-3.3-70b', source: 'catalog' }

describe('single-endpoint install stays un-qualified', () => {
  it('labels the lone relay by its key label only', () => {
    expect(memberProviderLabel(soloRelay, [soloRelay])).toBe('Custom')
  })

  it('reveals no endpoint URL on hover', () => {
    expect(memberEndpointTitle(soloRelay, [soloRelay])).toBeUndefined()
  })

  it('offers the bare model id, never the qualified one', () => {
    expect(providerPinId(soloRelay, [soloRelay])).toBe('deepseek-v3.1')
  })

  it('leaves catalog rows entirely alone', () => {
    expect(memberProviderLabel(catalog, [catalog, soloRelay])).toBe('groq')
    expect(memberEndpointTitle(catalog, [catalog, soloRelay])).toBeUndefined()
  })
})

describe('two endpoints serving one model id', () => {
  const both = [relayA, relayB]

  it('appends the endpoint to each label', () => {
    expect(memberProviderLabel(relayA, both)).toBe('Relay A · relay-a.example.com/v1')
    expect(memberProviderLabel(relayB, both)).toBe('Relay B · relay-b.example.com/v1')
  })

  it('reveals the full endpoint URL on hover', () => {
    expect(memberEndpointTitle(relayA, both)).toBe('https://relay-a.example.com/v1')
    expect(memberEndpointTitle(relayB, both)).toBe('https://relay-b.example.com/v1')
  })

  it('offers the qualified id so a copy pins one relay', () => {
    expect(providerPinId(relayA, both)).toBe('custom:deepseek-v3.1#relay-a.example.com-v1')
    expect(providerPinId(relayB, both)).toBe('custom:deepseek-v3.1#relay-b.example.com-v1')
  })

  it('does not disambiguate a DIFFERENT model id that only one relay serves', () => {
    const soloOnA: R = { ...relayA, modelId: 'qwen-3' }
    const siblings = [soloOnA, relayA, relayB]
    expect(memberProviderLabel(soloOnA, siblings)).toBe('Relay A')
    expect(memberEndpointTitle(soloOnA, siblings)).toBeUndefined()
    expect(providerPinId(soloOnA, siblings)).toBe('qwen-3')
  })
})


// Display name is presentation, never identity (#651). Renaming one relay's copy
// moves it into a different display-name group, but the two rows still share
// (platform, model_id) — so the disambiguation must key on that pair and nothing
// else, and the split/merge override must name ONE relay's row.
describe('two endpoints whose copies were renamed apart', () => {
  const renamedA: R = { ...relayA, displayName: 'DeepSeek via A' }
  const all = [renamedA, relayB]

  it('still labels each with its endpoint', () => {
    expect(memberProviderLabel(renamedA, all)).toBe('Relay A · relay-a.example.com/v1')
    expect(memberProviderLabel(relayB, all)).toBe('Relay B · relay-b.example.com/v1')
  })

  it('still hands out the qualified id to copy', () => {
    expect(providerPinId(renamedA, all)).toBe('custom:deepseek-v3.1#relay-a.example.com-v1')
    expect(providerPinId(relayB, all)).toBe('custom:deepseek-v3.1#relay-b.example.com-v1')
  })

  it('still reveals the endpoint on hover', () => {
    expect(memberEndpointTitle(renamedA, all)).toBe('https://relay-a.example.com/v1')
  })
})

describe('split / merge override key', () => {
  it('names one relay\'s row, not every custom row with that model id', () => {
    expect(memberOverrideKey(relayA)).toBe('custom:deepseek-v3.1#relay-a.example.com-v1')
    expect(memberOverrideKey(relayB)).toBe('custom:deepseek-v3.1#relay-b.example.com-v1')
    expect(memberOverrideKey(relayA)).not.toBe(memberOverrideKey(relayB))
  })

  it('keeps the plain member id for rows with no endpoint of their own', () => {
    expect(memberOverrideKey(catalog)).toBe('groq:llama-3.3-70b')
    expect(memberOverrideKey({ platform: 'custom', modelId: 'legacy' })).toBe('custom:legacy')
  })
})

describe('collision detection keys on (platform, model_id)', () => {
  it('ignores a same-id row on a different platform', () => {
    const sameIdOnCatalog: R = { platform: 'groq', modelId: 'deepseek-v3.1', source: 'catalog' }
    expect(memberProviderLabel(soloRelay, [soloRelay, sameIdOnCatalog])).toBe('Custom')
    expect(providerPinId(soloRelay, [soloRelay, sameIdOnCatalog])).toBe('deepseek-v3.1')
  })
})

// A split persisted BEFORE per-endpoint identity names the row in the plain
// "platform:modelId" form. The override key is qualified now, so a naive
// equality check stops recognising it: the row stays split with no control to
// merge it back. Rewriting the stored key would be a silent data migration for
// a cosmetic gain, so matching has to accept both forms instead.
describe('pre-#651 split overrides stay undoable', () => {
  const legacySplit = [{ member: 'custom:deepseek-v3.1' }]
  const qualifiedSplit = [{ member: 'custom:deepseek-v3.1#relay-a.example.com-v1' }]

  it('recognises a split stored in the plain form', () => {
    expect(isMemberSplit(legacySplit, relayA)).toBe(true)
  })

  it('recognises one stored in the qualified form', () => {
    expect(isMemberSplit(qualifiedSplit, relayA)).toBe(true)
  })

  it('removes the entry that is actually stored, whichever form it uses', () => {
    expect(splitsWithoutMember(legacySplit, relayA)).toEqual([])
    expect(splitsWithoutMember(qualifiedSplit, relayA)).toEqual([])
  })

  it('does not treat a sibling relay as split by the other one\'s entry', () => {
    expect(isMemberSplit(qualifiedSplit, relayB)).toBe(false)
    expect(splitsWithoutMember(qualifiedSplit, relayB)).toEqual(qualifiedSplit)
  })

  it('still matches a plain entry on a row that has no endpoint at all', () => {
    const legacyRow = { platform: 'custom', modelId: 'legacy', source: 'custom' as const }
    expect(isMemberSplit([{ member: 'custom:legacy' }], legacyRow)).toBe(true)
  })

  it('leaves catalog rows on the plain form only', () => {
    expect(isMemberSplit([{ member: 'groq:llama-3.3-70b' }], catalog)).toBe(true)
  })
})

// ── Group-level rate-limit badge (#876, #921 follow-up) ──────────────────────
// The badge means "how close is this logical model to being unusable". A model
// is unusable only when EVERY provider serving it is out of headroom, so the
// group number follows the BEST member. Taking the worst member painted a
// five-provider group red the moment one provider ran dry.

function usageRow(modelDbId: number, w: Partial<Pick<RateLimitUsageRow, 'rpm' | 'rpd' | 'tpm'>> = {}): RateLimitUsageRow {
  return {
    modelDbId,
    platform: 'p' + modelDbId,
    modelId: 'm' + modelDbId,
    rpm: w.rpm ?? null,
    rpd: w.rpd ?? null,
    tpm: w.tpm ?? null,
  }
}

describe('tightestRateLimit', () => {
  it('returns null with no rows at all', () => {
    expect(tightestRateLimit([])).toBeNull()
  })

  it('returns null when every window is idle (no badge for an unused model)', () => {
    expect(tightestRateLimit([usageRow(1, { rpm: { used: 0, limit: 30 } })])).toBeNull()
  })

  it('returns null when rows carry no windows at all (model has no limits)', () => {
    expect(tightestRateLimit([usageRow(1)])).toBeNull()
  })

  it('reports a single member as-is', () => {
    expect(tightestRateLimit([usageRow(1, { rpm: { used: 21, limit: 30 } })]))
      .toEqual({ kind: 'RPM', used: 21, limit: 30 })
  })

  it('within one member picks the TIGHTEST window (that member is blocked by it)', () => {
    const row = usageRow(1, {
      rpm: { used: 3, limit: 30 },     // 10%
      rpd: { used: 900, limit: 1000 }, // 90% ← binding
      tpm: { used: 100, limit: 1000 }, // 10%
    })
    expect(tightestRateLimit([row])).toEqual({ kind: 'RPD', used: 900, limit: 1000 })
  })

  it('across a group picks the member with the MOST headroom, not the exhausted one', () => {
    const exhausted = usageRow(1, { rpm: { used: 30, limit: 30 } })
    const easy = usageRow(2, { rpm: { used: 2, limit: 30 } })
    expect(tightestRateLimit([exhausted, easy])).toEqual({ kind: 'RPM', used: 2, limit: 30 })
  })

  it('one exhausted provider out of five does not decide the badge', () => {
    const rows = [
      usageRow(1, { rpd: { used: 1000, limit: 1000 } }),
      usageRow(2, { rpd: { used: 10, limit: 1000 } }),
      usageRow(3, { rpd: { used: 50, limit: 1000 } }),
      usageRow(4, { rpd: { used: 5, limit: 1000 } }),
      usageRow(5, { rpd: { used: 400, limit: 1000 } }),
    ]
    expect(tightestRateLimit(rows)).toEqual({ kind: 'RPD', used: 5, limit: 1000 })
  })

  it('goes red only when every member is exhausted', () => {
    const rows = [
      usageRow(1, { rpm: { used: 30, limit: 30 } }),
      usageRow(2, { rpm: { used: 60, limit: 60 } }),
    ]
    const tight = tightestRateLimit(rows)!
    expect(tight.used / tight.limit).toBe(1)
  })

  it('a fully idle member wins over a busy one and suppresses the badge', () => {
    const rows = [
      usageRow(1, { rpm: { used: 29, limit: 30 } }),
      usageRow(2, { rpm: { used: 0, limit: 30 } }),
    ]
    expect(tightestRateLimit(rows)).toBeNull()
  })

  it('ignores a zero limit rather than dividing by it', () => {
    const rows = [usageRow(1, { rpm: { used: 5, limit: 0 } })]
    expect(tightestRateLimit(rows)).toBeNull()
  })

  it('compares members by ratio, not by raw counts', () => {
    // 500/100000 (0.5%) has far more headroom than 8/10 (80%), despite the
    // bigger absolute number.
    const rows = [
      usageRow(1, { rpm: { used: 8, limit: 10 } }),
      usageRow(2, { tpm: { used: 500, limit: 100_000 } }),
    ]
    expect(tightestRateLimit(rows)).toEqual({ kind: 'TPM', used: 500, limit: 100_000 })
  })
})

// #1056: a relay added as a custom endpoint carries platform 'custom', so
// searching the provider's name ("unorouter") found nothing even though the
// table prints the endpoint host on the row.
describe('groupMatchesQuery (#1056)', () => {
  const member = (over: Record<string, unknown> = {}) => ({
    platform: 'custom', modelId: 'glm-5.1', displayName: 'GLM 5.1',
    source: 'custom' as const, keyLabel: null,
    endpointScope: 'https://api.unorouter.com/v1', ...over,
  })
  const group = (members: ReturnType<typeof member>[]) => ({ label: 'GLM 5.1', members })

  it('matches a custom endpoint host the table displays', () => {
    expect(groupMatchesQuery(group([member()]), 'unorouter')).toBe(true)
    expect(groupMatchesQuery(group([member()]), 'api.unorouter.com')).toBe(true)
  })

  it('matches the operator-given key label', () => {
    const g = group([member({ endpointScope: null, keyLabel: 'My UnoRouter key' })])
    expect(groupMatchesQuery(g, 'unorouter')).toBe(true)
  })

  it('matches when only ONE member of a multi-provider group is on that endpoint', () => {
    const g = group([
      member({ platform: 'zhipu', source: 'catalog' as const, endpointScope: null }),
      member(),
    ])
    expect(groupMatchesQuery(g, 'unorouter')).toBe(true)
    expect(groupMatchesQuery(g, 'zhipu')).toBe(true)
  })

  it('still matches names, ids and catalog platforms', () => {
    const g = group([member({ platform: 'groq', source: 'catalog' as const, endpointScope: null })])
    expect(groupMatchesQuery(g, 'glm')).toBe(true)
    expect(groupMatchesQuery(g, 'groq')).toBe(true)
    expect(groupMatchesQuery(g, 'mistral')).toBe(false)
  })
})

// #1015: models whose time-window quota is used up gray out and sink to the
// bottom of the table, so operators see healthy capacity first. The fold is
// score-mode-only: manual mode is the operator's drag-arranged ladder.
describe('depleted rows (#1015)', () => {
  function chainRow(modelDbId: number, over: Partial<Row> = {}): Row {
    return {
      modelDbId,
      priority: modelDbId,
      effectivePriority: modelDbId,
      penalty: 0,
      rateLimitHits: 0,
      enabled: true,
      platform: 'groq',
      modelId: 'm' + modelDbId,
      displayName: 'M' + modelDbId,
      intelligenceRank: 50,
      speedRank: 50,
      sizeLabel: '',
      monthlyTokenBudget: '',
      supportsVision: false,
      supportsTools: false,
      keyCount: 1,
      ...over,
    } as Row
  }

  const exhaustedUsage = (modelDbId: number) => usageRow(modelDbId, { rpm: { used: 30, limit: 30 } })
  const healthyUsage = (modelDbId: number) => usageRow(modelDbId, { rpm: { used: 3, limit: 30 } })

  it('isMemberDepleted: used-up tightest window is depleted', () => {
    expect(isMemberDepleted(exhaustedUsage(1))).toBe(true)
    expect(isMemberDepleted(healthyUsage(1))).toBe(false)
  })

  it('isMemberDepleted: no usage data or a fully idle member is not depleted', () => {
    expect(isMemberDepleted(undefined)).toBe(false)
    expect(isMemberDepleted(usageRow(1, { rpm: { used: 0, limit: 30 } }))).toBe(false)
    expect(isMemberDepleted(usageRow(1, { rpm: { used: 5, limit: 0 } }))).toBe(false)
  })

  it('isGroupDepleted: only when every member is out of headroom', () => {
    const members = [chainRow(1), chainRow(2)]
    expect(isGroupDepleted(members, new Map([
      [1, exhaustedUsage(1)],
      [2, exhaustedUsage(2)],
    ]))).toBe(true)
    // One healthy provider keeps the group routable — same rule as the badge.
    expect(isGroupDepleted(members, new Map([
      [1, exhaustedUsage(1)],
      [2, healthyUsage(2)],
    ]))).toBe(false)
    // A member we have never polled is not proven exhausted either.
    expect(isGroupDepleted(members, new Map([[1, exhaustedUsage(1)]]))).toBe(false)
  })

  it('buildGroups sinks a depleted group below healthy ones, score order intact', () => {
    const rows = [
      chainRow(1, { score: 0.5 }),
      // Depleted despite the best score: it cannot serve right now.
      chainRow(2, { score: 0.9 }),
      chainRow(3, { score: 0.7 }),
    ]
    const usage = new Map([[2, exhaustedUsage(2)]])
    const groups = buildGroups(rows, false, usage)
    // Healthy groups keep their score order (3 → 1); the depleted 2 sinks.
    expect(groups.map(g => g.members[0].modelDbId)).toEqual([3, 1, 2])
  })

  it('buildGroups sinks depleted members within a group in score mode', () => {
    const rows = [
      chainRow(1, { score: 0.9, groupKey: 'g1', displayName: 'Shared' }),
      chainRow(2, { score: 0.5, groupKey: 'g1', displayName: 'Shared' }),
    ]
    const usage = new Map([[1, exhaustedUsage(1)]])
    const [group] = buildGroups(rows, false, usage)
    expect(group.members.map(m => m.modelDbId)).toEqual([2, 1])
  })

  it('buildGroups leaves the manual ladder alone even with usage data', () => {
    const rows = [
      chainRow(1, { priority: 1, score: 0.1 }),
      chainRow(2, { priority: 2, score: 0.9 }),
    ]
    const usage = new Map([[1, exhaustedUsage(1)]])
    const groups = buildGroups(rows, true, usage)
    expect(groups.map(g => g.members[0].modelDbId)).toEqual([1, 2])
  })

  it('buildGroups without usage data keeps the plain score order', () => {
    const rows = [
      chainRow(1, { score: 0.5 }),
      chainRow(2, { score: 0.9 }),
    ]
    const groups = buildGroups(rows, false)
    expect(groups.map(g => g.members[0].modelDbId)).toEqual([2, 1])
  })
})

describe('clampRankToIndex (#1317)', () => {
  const N = 10
  it('maps a typed 1-based rank to the 0-based index', () => {
    expect(clampRankToIndex(1, N)).toBe(0)
    expect(clampRankToIndex(5, N)).toBe(4)
    expect(clampRankToIndex(N, N)).toBe(N - 1)
  })
  it('clamps instead of erroring: below 1 goes to the front, past the end goes last', () => {
    expect(clampRankToIndex(-3, N)).toBe(0)
    expect(clampRankToIndex(0, N)).toBe(0)
    expect(clampRankToIndex(999, N)).toBe(N - 1)
  })
  it('truncates fractional ranks', () => {
    expect(clampRankToIndex(3.9, N)).toBe(2)
  })
  it('rejects unparseable values so the row stays put', () => {
    expect(clampRankToIndex(Number.NaN, N)).toBe(-1)
    expect(clampRankToIndex(Infinity, N)).toBe(-1)
  })
})