@starci/ai-router 0.2.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +11 -0
- package/README.md +256 -14
- package/dist/ai-router-gateway.listen.d.ts +30 -0
- package/dist/ai-router-gateway.listen.js +67 -0
- package/dist/ai-router-gateway.module-definition.d.ts +21 -0
- package/dist/ai-router-gateway.module-definition.js +6 -0
- package/dist/ai-router-gateway.module.d.ts +19 -0
- package/dist/ai-router-gateway.module.js +75 -0
- package/dist/ai-router.service.d.ts +3 -1
- package/dist/ai-router.service.js +4 -0
- package/dist/config.d.ts +3 -1
- package/dist/config.js +41 -0
- package/dist/gateway/cli.d.ts +13 -0
- package/dist/gateway/cli.js +241 -0
- package/dist/gateway/config-file.d.ts +37 -0
- package/dist/gateway/config-file.js +238 -0
- package/dist/gateway/gateway.d.ts +34 -0
- package/dist/gateway/gateway.js +527 -0
- package/dist/gateway/index.d.ts +14 -0
- package/dist/gateway/index.js +7 -0
- package/dist/gateway/keys.d.ts +166 -0
- package/dist/gateway/keys.js +268 -0
- package/dist/gateway/run.d.ts +1 -0
- package/dist/gateway/run.js +14 -0
- package/dist/gateway/serve.d.ts +25 -0
- package/dist/gateway/serve.js +38 -0
- package/dist/gateway/sqlite-key-store.d.ts +8 -0
- package/dist/gateway/sqlite-key-store.js +167 -0
- package/dist/index.d.ts +4 -4
- package/dist/index.js +2 -1
- package/dist/router.js +3 -1
- package/dist/types.d.ts +28 -0
- package/package.json +29 -3
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
import type { MaybePromise, RouterCatalog } from "../types.js";
|
|
2
|
+
/** The limits of one virtual key; an absent field is no limit. Days and months are UTC. */
|
|
3
|
+
export interface KeyQuota {
|
|
4
|
+
readonly requestsPerMinute?: number;
|
|
5
|
+
/** Prompt plus completion tokens the provider reported. */
|
|
6
|
+
readonly tokensPerDay?: number;
|
|
7
|
+
/** Estimated cost, from usage and the model's configured cost; a model without a cost counts 0. */
|
|
8
|
+
readonly costPerDay?: number;
|
|
9
|
+
readonly costPerMonth?: number;
|
|
10
|
+
}
|
|
11
|
+
/** A virtual key as every surface shows it: its bindings and state, never its secret or hash. */
|
|
12
|
+
export interface VirtualKey {
|
|
13
|
+
/** The public id admin operations name it by (`key_<hex>`). */
|
|
14
|
+
readonly id: string;
|
|
15
|
+
readonly label: string;
|
|
16
|
+
readonly owner: string | null;
|
|
17
|
+
/** The key's prefix and last four characters, enough to recognise it: `sk-starci-<label>-...abcd`. */
|
|
18
|
+
readonly hint: string;
|
|
19
|
+
/** Profile names the key may call, or `*` for every profile. */
|
|
20
|
+
readonly profiles: readonly string[];
|
|
21
|
+
/** Model ids or aliases the key may call directly, or `*` for every model. */
|
|
22
|
+
readonly models: readonly string[];
|
|
23
|
+
/** False pins every call to the profile's or the named model; no fallback model is tried. */
|
|
24
|
+
readonly allowFallback: boolean;
|
|
25
|
+
readonly quota: KeyQuota;
|
|
26
|
+
readonly enabled: boolean;
|
|
27
|
+
/** Epoch milliseconds. */
|
|
28
|
+
readonly createdAt: number;
|
|
29
|
+
readonly rotatedAt: number | null;
|
|
30
|
+
readonly revokedAt: number | null;
|
|
31
|
+
}
|
|
32
|
+
/** A virtual key as a store holds it: the public record plus the SHA-256 of its secret. */
|
|
33
|
+
export interface StoredKey extends VirtualKey {
|
|
34
|
+
readonly hash: string;
|
|
35
|
+
}
|
|
36
|
+
/** What a new key is bound to. */
|
|
37
|
+
export interface KeySpec {
|
|
38
|
+
/** Lowercase letters, digits and underscores, 1 to 32 characters; it becomes part of the secret. */
|
|
39
|
+
readonly label: string;
|
|
40
|
+
readonly owner?: string;
|
|
41
|
+
readonly profiles?: readonly string[];
|
|
42
|
+
readonly models?: readonly string[];
|
|
43
|
+
/** Default true. */
|
|
44
|
+
readonly allowFallback?: boolean;
|
|
45
|
+
readonly quota?: KeyQuota;
|
|
46
|
+
/** Default true. */
|
|
47
|
+
readonly enabled?: boolean;
|
|
48
|
+
}
|
|
49
|
+
/** The bindings of a key an update may change; the label and the secret stay. */
|
|
50
|
+
export type KeyPatch = Omit<KeySpec, "label">;
|
|
51
|
+
/** One settled request of a key: how it ended and what it consumed. No prompt, no end-user identifier. */
|
|
52
|
+
export interface UsageDelta {
|
|
53
|
+
/** `success`, `error:<class>` for a pool failure, `rejected:<reason>` for a request the gateway refused. */
|
|
54
|
+
readonly outcome: string;
|
|
55
|
+
readonly promptTokens: number;
|
|
56
|
+
readonly completionTokens: number;
|
|
57
|
+
readonly cost: number;
|
|
58
|
+
readonly latencyMs: number;
|
|
59
|
+
}
|
|
60
|
+
/** A key's usage over one UTC day. */
|
|
61
|
+
export interface UsageRow {
|
|
62
|
+
readonly keyId: string;
|
|
63
|
+
/** `YYYY-MM-DD`. */
|
|
64
|
+
readonly day: string;
|
|
65
|
+
readonly requests: number;
|
|
66
|
+
readonly succeeded: number;
|
|
67
|
+
readonly failed: number;
|
|
68
|
+
readonly promptTokens: number;
|
|
69
|
+
readonly completionTokens: number;
|
|
70
|
+
readonly cost: number;
|
|
71
|
+
/** The sum of every request's latency; divide by `requests` for the mean. */
|
|
72
|
+
readonly latencyMs: number;
|
|
73
|
+
readonly outcomes: Readonly<Record<string, number>>;
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Where virtual keys and their usage live. The in-memory store is the default; `openSqliteKeyStore` is the durable
|
|
77
|
+
* one, and an adapter over another database implements the same methods (the SQLite schema is its reference).
|
|
78
|
+
*/
|
|
79
|
+
export interface KeyStore {
|
|
80
|
+
/** Inserts or replaces a key by id. */
|
|
81
|
+
put(key: StoredKey): MaybePromise<void>;
|
|
82
|
+
get(id: string): MaybePromise<StoredKey | undefined>;
|
|
83
|
+
byHash(hash: string): MaybePromise<StoredKey | undefined>;
|
|
84
|
+
list(): MaybePromise<readonly StoredKey[]>;
|
|
85
|
+
/** Counts one request in the key's minute (epoch minutes) and returns the minute's count; a new minute starts at 1. Atomic. */
|
|
86
|
+
hit(id: string, minute: number): MaybePromise<number>;
|
|
87
|
+
/** Adds one settled request to the key's day. Atomic. */
|
|
88
|
+
record(id: string, day: string, delta: UsageDelta): MaybePromise<void>;
|
|
89
|
+
/** The key's days from `from` to `to`, both inclusive, oldest first. */
|
|
90
|
+
usage(id: string, from: string, to: string): MaybePromise<readonly UsageRow[]>;
|
|
91
|
+
close?(): MaybePromise<void>;
|
|
92
|
+
}
|
|
93
|
+
/** Adds a request to a day row; the stores share it so a row means the same everywhere. */
|
|
94
|
+
export declare function addToRow(row: UsageRow | undefined, keyId: string, day: string, delta: UsageDelta): UsageRow;
|
|
95
|
+
/** The default key store: one process's memory, lost on restart. */
|
|
96
|
+
export declare class MemoryKeyStore implements KeyStore {
|
|
97
|
+
#private;
|
|
98
|
+
/** Inserts or replaces a key. */
|
|
99
|
+
put(key: StoredKey): void;
|
|
100
|
+
/** Reads a key by id. */
|
|
101
|
+
get(id: string): StoredKey | undefined;
|
|
102
|
+
/** Reads a key by the hash of its secret. */
|
|
103
|
+
byHash(hash: string): StoredKey | undefined;
|
|
104
|
+
/** Lists every key. */
|
|
105
|
+
list(): readonly StoredKey[];
|
|
106
|
+
/** Counts a request in the key's minute. */
|
|
107
|
+
hit(id: string, minute: number): number;
|
|
108
|
+
/** Adds a settled request to the key's day. */
|
|
109
|
+
record(id: string, day: string, delta: UsageDelta): void;
|
|
110
|
+
/** The key's day rows in a range. */
|
|
111
|
+
usage(id: string, from: string, to: string): readonly UsageRow[];
|
|
112
|
+
}
|
|
113
|
+
/** Why an admin operation was refused: an unknown id, an invalid spec, or a change to a revoked key. */
|
|
114
|
+
export declare class KeyAdminError extends Error {
|
|
115
|
+
readonly code: "not_found" | "invalid" | "revoked";
|
|
116
|
+
/** Builds the error. */
|
|
117
|
+
constructor(code: KeyAdminError["code"], message: string);
|
|
118
|
+
}
|
|
119
|
+
/** A newly issued or rotated key: the record, and the secret shown this once. */
|
|
120
|
+
export interface IssuedKey {
|
|
121
|
+
readonly key: VirtualKey;
|
|
122
|
+
readonly secret: string;
|
|
123
|
+
}
|
|
124
|
+
/** A key's usage over a range of days, with the totals of the range. */
|
|
125
|
+
export interface KeyUsage {
|
|
126
|
+
readonly key: VirtualKey;
|
|
127
|
+
readonly from: string;
|
|
128
|
+
readonly to: string;
|
|
129
|
+
readonly rows: readonly UsageRow[];
|
|
130
|
+
readonly totals: Omit<UsageRow, "keyId" | "day">;
|
|
131
|
+
}
|
|
132
|
+
/** The SHA-256 hex of a secret: what a store keeps instead of it. Keys are 192 random bits, so a fast hash is enough. */
|
|
133
|
+
export declare function hashSecret(secret: string): string;
|
|
134
|
+
/** The UTC day of an epoch time, `YYYY-MM-DD`. */
|
|
135
|
+
export declare function dayOf(time: number): string;
|
|
136
|
+
/** The public view of a stored key. */
|
|
137
|
+
export declare function publicKey(key: StoredKey): VirtualKey;
|
|
138
|
+
/** Issues, lists, revokes, rotates and updates virtual keys over a store, and reports their usage. */
|
|
139
|
+
export declare class KeyAdmin {
|
|
140
|
+
#private;
|
|
141
|
+
readonly store: KeyStore;
|
|
142
|
+
/** Binds the admin to a store; with a catalog, a key may only name the pool's profiles and models. */
|
|
143
|
+
constructor(store: KeyStore, options?: {
|
|
144
|
+
readonly catalog?: RouterCatalog;
|
|
145
|
+
readonly clock?: () => number;
|
|
146
|
+
});
|
|
147
|
+
/** Issues a key; the secret is returned now and never again. */
|
|
148
|
+
create(spec: KeySpec): Promise<IssuedKey>;
|
|
149
|
+
/** Lists every key, oldest first. */
|
|
150
|
+
list(): Promise<VirtualKey[]>;
|
|
151
|
+
/** Reads one key. */
|
|
152
|
+
get(id: string): Promise<VirtualKey>;
|
|
153
|
+
/** Revokes a key for good: its secret answers 401 from now on. Revoking twice is a no-op. */
|
|
154
|
+
revoke(id: string): Promise<VirtualKey>;
|
|
155
|
+
/** Replaces a key's secret, keeping its id, bindings and usage; the old secret answers 401 from now on. */
|
|
156
|
+
rotate(id: string): Promise<IssuedKey>;
|
|
157
|
+
/** Changes a key's bindings; a field left out keeps its value. */
|
|
158
|
+
update(id: string, patch: KeyPatch): Promise<VirtualKey>;
|
|
159
|
+
/** A key's usage per UTC day from `from` to `to` (default: the current month), with the totals. */
|
|
160
|
+
usage(id: string, range?: {
|
|
161
|
+
readonly from?: string;
|
|
162
|
+
readonly to?: string;
|
|
163
|
+
}): Promise<KeyUsage>;
|
|
164
|
+
/** The stored key a secret names, or undefined; the caller decides what a revoked or disabled key means. */
|
|
165
|
+
authenticate(secret: string): Promise<StoredKey | undefined>;
|
|
166
|
+
}
|
|
@@ -0,0 +1,268 @@
|
|
|
1
|
+
import { createHash, randomBytes } from "node:crypto";
|
|
2
|
+
/** Adds a request to a day row; the stores share it so a row means the same everywhere. */
|
|
3
|
+
export function addToRow(row, keyId, day, delta) {
|
|
4
|
+
const success = delta.outcome === "success";
|
|
5
|
+
return {
|
|
6
|
+
keyId,
|
|
7
|
+
day,
|
|
8
|
+
requests: (row?.requests ?? 0) + 1,
|
|
9
|
+
succeeded: (row?.succeeded ?? 0) + (success ? 1 : 0),
|
|
10
|
+
failed: (row?.failed ?? 0) + (success ? 0 : 1),
|
|
11
|
+
promptTokens: (row?.promptTokens ?? 0) + delta.promptTokens,
|
|
12
|
+
completionTokens: (row?.completionTokens ?? 0) + delta.completionTokens,
|
|
13
|
+
cost: (row?.cost ?? 0) + delta.cost,
|
|
14
|
+
latencyMs: (row?.latencyMs ?? 0) + delta.latencyMs,
|
|
15
|
+
outcomes: { ...row?.outcomes, [delta.outcome]: (row?.outcomes[delta.outcome] ?? 0) + 1 },
|
|
16
|
+
};
|
|
17
|
+
}
|
|
18
|
+
/** The default key store: one process's memory, lost on restart. */
|
|
19
|
+
export class MemoryKeyStore {
|
|
20
|
+
#keys = new Map();
|
|
21
|
+
#rate = new Map();
|
|
22
|
+
#usage = new Map();
|
|
23
|
+
/** Inserts or replaces a key. */
|
|
24
|
+
put(key) {
|
|
25
|
+
this.#keys.set(key.id, key);
|
|
26
|
+
}
|
|
27
|
+
/** Reads a key by id. */
|
|
28
|
+
get(id) {
|
|
29
|
+
return this.#keys.get(id);
|
|
30
|
+
}
|
|
31
|
+
/** Reads a key by the hash of its secret. */
|
|
32
|
+
byHash(hash) {
|
|
33
|
+
for (const key of this.#keys.values())
|
|
34
|
+
if (key.hash === hash)
|
|
35
|
+
return key;
|
|
36
|
+
return undefined;
|
|
37
|
+
}
|
|
38
|
+
/** Lists every key. */
|
|
39
|
+
list() {
|
|
40
|
+
return [...this.#keys.values()];
|
|
41
|
+
}
|
|
42
|
+
/** Counts a request in the key's minute. */
|
|
43
|
+
hit(id, minute) {
|
|
44
|
+
const held = this.#rate.get(id);
|
|
45
|
+
const count = held?.minute === minute ? held.count + 1 : 1;
|
|
46
|
+
this.#rate.set(id, { minute, count });
|
|
47
|
+
return count;
|
|
48
|
+
}
|
|
49
|
+
/** Adds a settled request to the key's day. */
|
|
50
|
+
record(id, day, delta) {
|
|
51
|
+
const name = `${id}/${day}`;
|
|
52
|
+
this.#usage.set(name, addToRow(this.#usage.get(name), id, day, delta));
|
|
53
|
+
}
|
|
54
|
+
/** The key's day rows in a range. */
|
|
55
|
+
usage(id, from, to) {
|
|
56
|
+
return [...this.#usage.values()].filter((row) => row.keyId === id && row.day >= from && row.day <= to).sort((a, b) => a.day.localeCompare(b.day));
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
/** Why an admin operation was refused: an unknown id, an invalid spec, or a change to a revoked key. */
|
|
60
|
+
export class KeyAdminError extends Error {
|
|
61
|
+
code;
|
|
62
|
+
/** Builds the error. */
|
|
63
|
+
constructor(code, message) {
|
|
64
|
+
super(message);
|
|
65
|
+
this.name = "KeyAdminError";
|
|
66
|
+
this.code = code;
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
const LABEL = /^[a-z0-9_]{1,32}$/;
|
|
70
|
+
const DAY = /^\d{4}-\d{2}-\d{2}$/;
|
|
71
|
+
/** The SHA-256 hex of a secret: what a store keeps instead of it. Keys are 192 random bits, so a fast hash is enough. */
|
|
72
|
+
export function hashSecret(secret) {
|
|
73
|
+
return createHash("sha256").update(secret, "utf8").digest("hex");
|
|
74
|
+
}
|
|
75
|
+
/** The UTC day of an epoch time, `YYYY-MM-DD`. */
|
|
76
|
+
export function dayOf(time) {
|
|
77
|
+
return new Date(time).toISOString().slice(0, 10);
|
|
78
|
+
}
|
|
79
|
+
/** The public view of a stored key. */
|
|
80
|
+
export function publicKey(key) {
|
|
81
|
+
return {
|
|
82
|
+
id: key.id,
|
|
83
|
+
label: key.label,
|
|
84
|
+
owner: key.owner,
|
|
85
|
+
hint: key.hint,
|
|
86
|
+
profiles: key.profiles,
|
|
87
|
+
models: key.models,
|
|
88
|
+
allowFallback: key.allowFallback,
|
|
89
|
+
quota: key.quota,
|
|
90
|
+
enabled: key.enabled,
|
|
91
|
+
createdAt: key.createdAt,
|
|
92
|
+
rotatedAt: key.rotatedAt,
|
|
93
|
+
revokedAt: key.revokedAt,
|
|
94
|
+
};
|
|
95
|
+
}
|
|
96
|
+
function invalid(message) {
|
|
97
|
+
return new KeyAdminError("invalid", message);
|
|
98
|
+
}
|
|
99
|
+
function names(value, field, known) {
|
|
100
|
+
// A spec arrives as JSON from the admin API, so its types are checked, not trusted.
|
|
101
|
+
const raw = value ?? [];
|
|
102
|
+
if (!Array.isArray(raw))
|
|
103
|
+
throw invalid(`${field} must be a list of names`);
|
|
104
|
+
const list = raw.filter((name) => typeof name === "string" && name !== "");
|
|
105
|
+
if (list.length !== raw.length)
|
|
106
|
+
throw invalid(`${field} must be a list of names`);
|
|
107
|
+
for (const name of list) {
|
|
108
|
+
if (name !== "*" && known !== null && !known.has(name))
|
|
109
|
+
throw invalid(`${field} names "${name}", which the pool does not serve`);
|
|
110
|
+
}
|
|
111
|
+
return [...new Set(list)];
|
|
112
|
+
}
|
|
113
|
+
function quotaOf(value) {
|
|
114
|
+
const quota = value ?? {};
|
|
115
|
+
const out = {};
|
|
116
|
+
for (const [field, integer] of [
|
|
117
|
+
["requestsPerMinute", true],
|
|
118
|
+
["tokensPerDay", true],
|
|
119
|
+
["costPerDay", false],
|
|
120
|
+
["costPerMonth", false],
|
|
121
|
+
]) {
|
|
122
|
+
const limit = quota[field];
|
|
123
|
+
if (limit === undefined)
|
|
124
|
+
continue;
|
|
125
|
+
if (typeof limit !== "number" || !Number.isFinite(limit) || limit <= 0 || (integer && !Number.isInteger(limit))) {
|
|
126
|
+
throw invalid(`quota.${field} must be a positive ${integer ? "integer" : "number"}`);
|
|
127
|
+
}
|
|
128
|
+
out[field] = limit;
|
|
129
|
+
}
|
|
130
|
+
const unknown = Object.keys(quota).filter((field) => !(field in out) && quota[field] !== undefined);
|
|
131
|
+
if (unknown.length > 0)
|
|
132
|
+
throw invalid(`quota has unknown fields: ${unknown.join(", ")}`);
|
|
133
|
+
return out;
|
|
134
|
+
}
|
|
135
|
+
function bool(value, field, fallback) {
|
|
136
|
+
if (value === undefined)
|
|
137
|
+
return fallback;
|
|
138
|
+
if (typeof value !== "boolean")
|
|
139
|
+
throw invalid(`${field} must be true or false`);
|
|
140
|
+
return value;
|
|
141
|
+
}
|
|
142
|
+
/** Issues, lists, revokes, rotates and updates virtual keys over a store, and reports their usage. */
|
|
143
|
+
export class KeyAdmin {
|
|
144
|
+
store;
|
|
145
|
+
#clock;
|
|
146
|
+
#profiles;
|
|
147
|
+
#models;
|
|
148
|
+
/** Binds the admin to a store; with a catalog, a key may only name the pool's profiles and models. */
|
|
149
|
+
constructor(store, options = {}) {
|
|
150
|
+
this.store = store;
|
|
151
|
+
this.#clock = options.clock ?? Date.now;
|
|
152
|
+
const catalog = options.catalog;
|
|
153
|
+
this.#profiles = catalog === undefined ? null : new Set(catalog.profiles.map((profile) => profile.name));
|
|
154
|
+
this.#models = catalog === undefined ? null : new Set(catalog.models.flatMap((model) => [model.id, ...model.aliases]));
|
|
155
|
+
}
|
|
156
|
+
#issue(label) {
|
|
157
|
+
const secret = `sk-starci-${label}-${randomBytes(24).toString("hex")}`;
|
|
158
|
+
return { secret, hash: hashSecret(secret), hint: `sk-starci-${label}-...${secret.slice(-4)}` };
|
|
159
|
+
}
|
|
160
|
+
#bindings(spec, base) {
|
|
161
|
+
const owner = spec.owner ?? base?.owner ?? null;
|
|
162
|
+
if (owner !== null && (typeof owner !== "string" || owner.length > 200))
|
|
163
|
+
throw invalid("owner must be a string of at most 200 characters");
|
|
164
|
+
const profiles = spec.profiles === undefined && base !== null ? base.profiles : names(spec.profiles, "profiles", this.#profiles);
|
|
165
|
+
const models = spec.models === undefined && base !== null ? base.models : names(spec.models, "models", this.#models);
|
|
166
|
+
if (profiles.length === 0 && models.length === 0)
|
|
167
|
+
throw invalid("a key needs at least one profile or model it may call");
|
|
168
|
+
return {
|
|
169
|
+
owner,
|
|
170
|
+
profiles,
|
|
171
|
+
models,
|
|
172
|
+
allowFallback: bool(spec.allowFallback, "allowFallback", base?.allowFallback ?? true),
|
|
173
|
+
quota: spec.quota === undefined && base !== null ? base.quota : quotaOf(spec.quota),
|
|
174
|
+
enabled: bool(spec.enabled, "enabled", base?.enabled ?? true),
|
|
175
|
+
};
|
|
176
|
+
}
|
|
177
|
+
async #find(id) {
|
|
178
|
+
const key = await this.store.get(id);
|
|
179
|
+
if (key === undefined)
|
|
180
|
+
throw new KeyAdminError("not_found", `no key has id "${id}"`);
|
|
181
|
+
return key;
|
|
182
|
+
}
|
|
183
|
+
/** Issues a key; the secret is returned now and never again. */
|
|
184
|
+
async create(spec) {
|
|
185
|
+
if (typeof spec.label !== "string" || !LABEL.test(spec.label))
|
|
186
|
+
throw invalid("label must be 1 to 32 lowercase letters, digits or underscores");
|
|
187
|
+
const issued = this.#issue(spec.label);
|
|
188
|
+
const key = {
|
|
189
|
+
id: `key_${randomBytes(8).toString("hex")}`,
|
|
190
|
+
label: spec.label,
|
|
191
|
+
hint: issued.hint,
|
|
192
|
+
...this.#bindings(spec, null),
|
|
193
|
+
createdAt: this.#clock(),
|
|
194
|
+
rotatedAt: null,
|
|
195
|
+
revokedAt: null,
|
|
196
|
+
hash: issued.hash,
|
|
197
|
+
};
|
|
198
|
+
await this.store.put(key);
|
|
199
|
+
return { key: publicKey(key), secret: issued.secret };
|
|
200
|
+
}
|
|
201
|
+
/** Lists every key, oldest first. */
|
|
202
|
+
async list() {
|
|
203
|
+
const keys = await this.store.list();
|
|
204
|
+
return [...keys].sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id)).map(publicKey);
|
|
205
|
+
}
|
|
206
|
+
/** Reads one key. */
|
|
207
|
+
async get(id) {
|
|
208
|
+
return publicKey(await this.#find(id));
|
|
209
|
+
}
|
|
210
|
+
/** Revokes a key for good: its secret answers 401 from now on. Revoking twice is a no-op. */
|
|
211
|
+
async revoke(id) {
|
|
212
|
+
const key = await this.#find(id);
|
|
213
|
+
if (key.revokedAt !== null)
|
|
214
|
+
return publicKey(key);
|
|
215
|
+
const revoked = { ...key, enabled: false, revokedAt: this.#clock() };
|
|
216
|
+
await this.store.put(revoked);
|
|
217
|
+
return publicKey(revoked);
|
|
218
|
+
}
|
|
219
|
+
/** Replaces a key's secret, keeping its id, bindings and usage; the old secret answers 401 from now on. */
|
|
220
|
+
async rotate(id) {
|
|
221
|
+
const key = await this.#find(id);
|
|
222
|
+
if (key.revokedAt !== null)
|
|
223
|
+
throw new KeyAdminError("revoked", `key "${id}" is revoked`);
|
|
224
|
+
const issued = this.#issue(key.label);
|
|
225
|
+
const rotated = { ...key, hash: issued.hash, hint: issued.hint, rotatedAt: this.#clock() };
|
|
226
|
+
await this.store.put(rotated);
|
|
227
|
+
return { key: publicKey(rotated), secret: issued.secret };
|
|
228
|
+
}
|
|
229
|
+
/** Changes a key's bindings; a field left out keeps its value. */
|
|
230
|
+
async update(id, patch) {
|
|
231
|
+
const key = await this.#find(id);
|
|
232
|
+
if (key.revokedAt !== null)
|
|
233
|
+
throw new KeyAdminError("revoked", `key "${id}" is revoked`);
|
|
234
|
+
const updated = { ...key, ...this.#bindings(patch, key) };
|
|
235
|
+
await this.store.put(updated);
|
|
236
|
+
return publicKey(updated);
|
|
237
|
+
}
|
|
238
|
+
/** A key's usage per UTC day from `from` to `to` (default: the current month), with the totals. */
|
|
239
|
+
async usage(id, range = {}) {
|
|
240
|
+
const key = await this.#find(id);
|
|
241
|
+
const today = dayOf(this.#clock());
|
|
242
|
+
const from = range.from ?? `${today.slice(0, 8)}01`;
|
|
243
|
+
const to = range.to ?? today;
|
|
244
|
+
if (!DAY.test(from) || !DAY.test(to))
|
|
245
|
+
throw invalid("from and to must be days, YYYY-MM-DD");
|
|
246
|
+
const rows = await this.store.usage(id, from, to);
|
|
247
|
+
const outcomes = {};
|
|
248
|
+
const totals = { requests: 0, succeeded: 0, failed: 0, promptTokens: 0, completionTokens: 0, cost: 0, latencyMs: 0 };
|
|
249
|
+
for (const row of rows) {
|
|
250
|
+
totals.requests += row.requests;
|
|
251
|
+
totals.succeeded += row.succeeded;
|
|
252
|
+
totals.failed += row.failed;
|
|
253
|
+
totals.promptTokens += row.promptTokens;
|
|
254
|
+
totals.completionTokens += row.completionTokens;
|
|
255
|
+
totals.cost += row.cost;
|
|
256
|
+
totals.latencyMs += row.latencyMs;
|
|
257
|
+
for (const [outcome, count] of Object.entries(row.outcomes))
|
|
258
|
+
outcomes[outcome] = (outcomes[outcome] ?? 0) + count;
|
|
259
|
+
}
|
|
260
|
+
return { key: publicKey(key), from, to, rows, totals: { ...totals, outcomes } };
|
|
261
|
+
}
|
|
262
|
+
/** The stored key a secret names, or undefined; the caller decides what a revoked or disabled key means. */
|
|
263
|
+
async authenticate(secret) {
|
|
264
|
+
if (!secret.startsWith("sk-starci-"))
|
|
265
|
+
return undefined;
|
|
266
|
+
return this.store.byHash(hashSecret(secret));
|
|
267
|
+
}
|
|
268
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/** The process entry of the gateway and its key commands: `node <package>/dist/gateway/run.js <command>`; it stops on SIGINT and SIGTERM. */
|
|
2
|
+
import { main } from "./cli.js";
|
|
3
|
+
const stop = new AbortController();
|
|
4
|
+
for (const signal of ["SIGINT", "SIGTERM"]) {
|
|
5
|
+
process.once(signal, () => {
|
|
6
|
+
stop.abort();
|
|
7
|
+
});
|
|
8
|
+
}
|
|
9
|
+
process.exitCode = await main(process.argv.slice(2), {
|
|
10
|
+
out: (text) => process.stdout.write(text),
|
|
11
|
+
err: (text) => process.stderr.write(text),
|
|
12
|
+
env: process.env,
|
|
13
|
+
signal: stop.signal,
|
|
14
|
+
});
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import type { FetchLike } from "../types.js";
|
|
2
|
+
import type { KeyStoreConfig } from "./config-file.js";
|
|
3
|
+
import type { AiRouterGateway } from "./gateway.js";
|
|
4
|
+
import type { KeyStore } from "./keys.js";
|
|
5
|
+
/** Opens the key store a config file names. */
|
|
6
|
+
export declare function openKeyStore(config: KeyStoreConfig): Promise<KeyStore>;
|
|
7
|
+
/** What `serveGateway` takes: the config file, and overrides of its address (and, for tests, of `fetch`). */
|
|
8
|
+
export interface ServeOptions {
|
|
9
|
+
readonly config: string;
|
|
10
|
+
readonly port?: number;
|
|
11
|
+
readonly host?: string;
|
|
12
|
+
readonly fetch?: FetchLike;
|
|
13
|
+
/** Where secret references are read from. Default `process.env`. */
|
|
14
|
+
readonly env?: NodeJS.ProcessEnv;
|
|
15
|
+
readonly onError?: (error: unknown) => void;
|
|
16
|
+
}
|
|
17
|
+
/** A running gateway process: the gateway, where it listens, and how to stop it. */
|
|
18
|
+
export interface ServingGateway {
|
|
19
|
+
readonly gateway: AiRouterGateway;
|
|
20
|
+
readonly url: string;
|
|
21
|
+
/** Stops listening and closes the key store. */
|
|
22
|
+
close(): Promise<void>;
|
|
23
|
+
}
|
|
24
|
+
/** Loads a config file, builds the router and the key store, and listens: the whole `ai-router serve`. */
|
|
25
|
+
export declare function serveGateway(options: ServeOptions): Promise<ServingGateway>;
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import { createRouter } from "../router.js";
|
|
2
|
+
import { loadGatewayConfig, readSecret } from "./config-file.js";
|
|
3
|
+
import { createGateway } from "./gateway.js";
|
|
4
|
+
import { MemoryKeyStore } from "./keys.js";
|
|
5
|
+
import { openSqliteKeyStore } from "./sqlite-key-store.js";
|
|
6
|
+
/** Opens the key store a config file names. */
|
|
7
|
+
export async function openKeyStore(config) {
|
|
8
|
+
return config.type === "sqlite" ? openSqliteKeyStore(config.path) : new MemoryKeyStore();
|
|
9
|
+
}
|
|
10
|
+
/** Loads a config file, builds the router and the key store, and listens: the whole `ai-router serve`. */
|
|
11
|
+
export async function serveGateway(options) {
|
|
12
|
+
const file = await loadGatewayConfig(options.config);
|
|
13
|
+
const router = createRouter(options.fetch === undefined ? file.pool : { ...file.pool, fetch: options.fetch });
|
|
14
|
+
const keys = await openKeyStore(file.gateway.keyStore);
|
|
15
|
+
const admin = file.gateway.adminToken;
|
|
16
|
+
const gateway = createGateway(router, {
|
|
17
|
+
keys,
|
|
18
|
+
maxBodyBytes: file.gateway.maxBodyBytes,
|
|
19
|
+
...(admin === null ? {} : { adminToken: () => readSecret(admin, options.env) }),
|
|
20
|
+
...(options.onError === undefined ? {} : { onError: options.onError }),
|
|
21
|
+
});
|
|
22
|
+
try {
|
|
23
|
+
const address = await gateway.listen(options.port ?? file.gateway.port, options.host ?? file.gateway.host);
|
|
24
|
+
return {
|
|
25
|
+
gateway,
|
|
26
|
+
url: address.url,
|
|
27
|
+
async close() {
|
|
28
|
+
await gateway.close();
|
|
29
|
+
await keys.close?.();
|
|
30
|
+
},
|
|
31
|
+
};
|
|
32
|
+
}
|
|
33
|
+
catch (error) {
|
|
34
|
+
await gateway.close();
|
|
35
|
+
await keys.close?.();
|
|
36
|
+
throw error;
|
|
37
|
+
}
|
|
38
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { KeyStore } from "./keys.js";
|
|
2
|
+
/**
|
|
3
|
+
* The schema of the durable key store. It is plain SQL (SQLite here; the same tables carry over to Postgres with
|
|
4
|
+
* `BIGINT` times, `DOUBLE PRECISION` cost and `JSONB` lists), so an adapter for another database starts from it.
|
|
5
|
+
*/
|
|
6
|
+
export declare const KEY_STORE_SCHEMA = "\nCREATE TABLE IF NOT EXISTS ai_router_keys (\n id TEXT PRIMARY KEY,\n hash TEXT NOT NULL UNIQUE,\n label TEXT NOT NULL,\n owner TEXT,\n hint TEXT NOT NULL,\n profiles TEXT NOT NULL,\n models TEXT NOT NULL,\n allow_fallback INTEGER NOT NULL,\n quota TEXT NOT NULL,\n enabled INTEGER NOT NULL,\n created_at INTEGER NOT NULL,\n rotated_at INTEGER,\n revoked_at INTEGER\n);\nCREATE TABLE IF NOT EXISTS ai_router_key_rate (\n key_id TEXT PRIMARY KEY,\n minute INTEGER NOT NULL,\n count INTEGER NOT NULL\n);\nCREATE TABLE IF NOT EXISTS ai_router_key_usage (\n key_id TEXT NOT NULL,\n day TEXT NOT NULL,\n requests INTEGER NOT NULL,\n succeeded INTEGER NOT NULL,\n failed INTEGER NOT NULL,\n prompt_tokens INTEGER NOT NULL,\n completion_tokens INTEGER NOT NULL,\n cost REAL NOT NULL,\n latency_ms INTEGER NOT NULL,\n outcomes TEXT NOT NULL,\n PRIMARY KEY (key_id, day)\n);\n";
|
|
7
|
+
/** Opens (and creates) the durable key store at a SQLite file path; `:memory:` gives a throwaway database. */
|
|
8
|
+
export declare function openSqliteKeyStore(path: string): Promise<KeyStore>;
|