Files
canina/backend/src/hermes-management/hermes.adapter.ts
T

343 lines
10 KiB
TypeScript

export type Json =
| null
| boolean
| number
| string
| Json[]
| { [key: string]: Json };
export type Row = Record<string, Json>;
export type HermesErrorCode =
| 'CONFIGURATION'
| 'AUTH_REQUIRED'
| 'UNAVAILABLE'
| 'CONTRACT'
| 'LIMIT'
| 'FORBIDDEN'
| 'UNSUPPORTED';
export class HermesError extends Error {
constructor(readonly code: HermesErrorCode) {
super(`Hermes ${code.toLowerCase()}`);
}
}
export interface HermesConfig {
origin: string;
token: () => Promise<string>;
}
export interface Health {
ok: boolean;
version: string;
commit: string;
auth_required: boolean;
provenance?: Row;
}
function object(value: unknown): Record<string, unknown> {
if (!value || typeof value !== 'object' || Array.isArray(value))
throw new HermesError('CONTRACT');
return value as Record<string, unknown>;
}
function fields(
value: unknown,
schema: Record<string, 'string' | 'boolean' | 'number'>,
): Row {
const source = object(value);
const result: Row = {};
for (const [key, type] of Object.entries(schema)) {
if (
typeof source[key] !== type ||
(type === 'number' && !Number.isFinite(source[key]))
)
throw new HermesError('CONTRACT');
result[key] = source[key] as Json;
}
return result;
}
export class HermesAdapter {
private readonly origin: string;
private inflight = 0;
constructor(
private readonly config: HermesConfig,
private readonly fetcher: typeof fetch = fetch,
) {
if (
![
'http://canina-hermes:9119',
'http://canina-hermes-inventory:9119',
].includes(config.origin)
)
throw new HermesError('CONFIGURATION');
this.origin = config.origin;
}
private async request(
path: string,
profile?: string,
method = 'GET',
params: Record<string, string> = {},
): Promise<unknown> {
if (
profile !== undefined &&
!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(profile)
)
throw new HermesError('FORBIDDEN');
const url = new URL(path, this.origin);
if (profile) url.searchParams.set('profile', profile);
for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
if (this.inflight >= 4) throw new HermesError('LIMIT');
this.inflight++;
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 5000);
try {
const token = await Promise.race([
this.config.token(),
new Promise<never>((_, reject) =>
controller.signal.addEventListener(
'abort',
() => reject(new HermesError('UNAVAILABLE')),
{ once: true },
),
),
]);
if (!token || /[\r\n]/.test(token))
throw new HermesError('AUTH_REQUIRED');
const response = await this.fetcher(url, {
method,
headers: {
Authorization: `Bearer ${token}`,
Accept: 'application/json',
},
signal: controller.signal,
redirect: 'error',
});
if ([401, 403].includes(response.status))
throw new HermesError('AUTH_REQUIRED');
if (response.status === 404) throw new HermesError('UNSUPPORTED');
if (!response.ok) throw new HermesError('UNAVAILABLE');
if (Number(response.headers.get('content-length')) > 262144)
throw new HermesError('LIMIT');
const reader = response.body?.getReader();
if (!reader) throw new HermesError('CONTRACT');
let bytes = 0;
const chunks: Uint8Array[] = [];
try {
for (;;) {
const { done, value } = await reader.read();
if (done) break;
bytes += value.byteLength;
if (bytes > 262144) throw new HermesError('LIMIT');
chunks.push(value);
}
} finally {
await reader.cancel().catch(() => undefined);
}
const data: unknown = JSON.parse(Buffer.concat(chunks).toString('utf8'));
if (this.origin === 'http://canina-hermes-inventory:9119') {
const rows = Array.isArray(data) ? data : [data];
for (const row of rows) provenance(row, true);
}
return data;
} catch (error) {
if (error instanceof HermesError) throw error;
throw new HermesError('UNAVAILABLE');
} finally {
clearTimeout(timer);
this.inflight--;
}
}
async health(): Promise<Health> {
const raw = await this.request('/api/health');
const health = {
...fields(raw, {
ok: 'boolean',
version: 'string',
commit: 'string',
auth_required: 'boolean',
}),
...provenance(raw),
} as unknown as Health;
if (!health.auth_required) throw new HermesError('AUTH_REQUIRED');
return health;
}
async status(profile: string): Promise<Row> {
const raw = object(await this.request('/api/status', profile));
const row = fields(raw, {
version: 'string',
gateway_running: 'boolean',
overall: 'string',
active_agents: 'number',
});
if (raw.gateway_state !== null && typeof raw.gateway_state !== 'string')
throw new HermesError('CONTRACT');
return {
...row,
gateway_state: raw.gateway_state as Json,
...provenance(raw),
...(raw.provenance
? {
gateway_running: false,
active_agents: 0,
gateway_state: null,
overall: 'unknown',
liveGatewayState: 'unknown',
liveActiveAgents: null,
}
: {}),
};
}
async profiles(): Promise<Row[]> {
return list(object(await this.request('/api/profiles')).profiles).map(
(r) => ({
...fields(r, {
name: 'string',
is_default: 'boolean',
gateway_running: 'boolean',
}),
...provenance(r),
...(object(r).provenance
? { gateway_running: false, liveGatewayState: 'unknown' }
: {}),
}),
);
}
async modelInfo(profile: string): Promise<Row> {
const raw = await this.request('/api/model/info', profile);
return {
...fields(raw, {
model: 'string',
provider: 'string',
effective_context_length: 'number',
}),
...provenance(raw),
};
}
async modelOptions(profile: string): Promise<Row[]> {
return list(
object(await this.request('/api/model/options', profile)).providers,
).map((r) => {
const row = fields(r, { slug: 'string', name: 'string' });
const models = list(object(r).models);
if (models.some((m) => typeof m !== 'string'))
throw new HermesError('CONTRACT');
return { ...row, models: models as string[] };
});
}
async usage(profile: string, days = 30): Promise<Row> {
bound(days, 1, 365);
const raw = object(
await this.request('/api/analytics/usage', profile, 'GET', {
days: String(days),
}),
);
return {
...fields(raw, { period_days: 'number' }),
...provenance(raw),
totals: fields(raw.totals, {
total_input: 'number',
total_output: 'number',
total_sessions: 'number',
total_estimated_cost: 'number',
}),
};
}
async sessions(profile: string, limit = 20, offset = 0): Promise<Row> {
bound(limit, 1, 100);
bound(offset, 0, 10000);
const raw = object(
await this.request('/api/sessions', profile, 'GET', {
limit: String(limit),
offset: String(offset),
full: 'false',
order: 'recent',
}),
);
if (raw.storage && Object.keys(object(raw.storage)).length)
throw new HermesError('UNAVAILABLE');
const rows = list(raw.sessions).map((r) =>
scoped(r, profile, {
id: 'string',
profile: 'string',
source: 'string',
is_active: 'boolean',
}),
);
return {
...fields(raw, { total: 'number' }),
sessions: rows,
...provenance(raw),
};
}
async crons(profile: string): Promise<Row[]> {
return list(await this.request('/api/cron/jobs', profile)).map((r) =>
scoped(r, profile, {
id: 'string',
profile: 'string',
enabled: 'boolean',
}),
);
}
private async cron(
profile: string,
id: string,
action: 'pause' | 'resume',
): Promise<Row> {
if (!/^[a-zA-Z0-9_-]{1,128}$/.test(id)) throw new HermesError('FORBIDDEN');
return scoped(
await this.request(`/api/cron/jobs/${id}/${action}`, profile, 'POST'),
profile,
{ id: 'string', profile: 'string', enabled: 'boolean' },
);
}
pauseCron(profile: string, id: string): Promise<Row> {
return this.cron(profile, id, 'pause');
}
resumeCron(profile: string, id: string): Promise<Row> {
return this.cron(profile, id, 'resume');
}
}
function list(value: unknown): unknown[] {
if (!Array.isArray(value) || value.length > 1000)
throw new HermesError('CONTRACT');
return value;
}
function bound(value: number, min: number, max: number): void {
if (!Number.isInteger(value) || value < min || value > max)
throw new HermesError('LIMIT');
}
function scoped(
value: unknown,
profile: string,
schema: Record<string, 'string' | 'boolean' | 'number'>,
): Row {
const row = fields(value, schema);
if (row.profile !== profile) throw new HermesError('FORBIDDEN');
return { ...row, ...provenance(value) };
}
/** Snapshot provenance is mandatory on inventory origin; never synthesize a capture time. */
function provenance(value: unknown, required = false): Row {
const raw = object(value);
if (!raw.provenance && !required) return {};
const p = object(raw.provenance);
if (
p.source !== 'snapshot' ||
p.liveProcess !== 'unknown' ||
typeof p.capturedAt !== 'string' ||
!p.capturedAt.endsWith('Z') ||
!Number.isFinite(Date.parse(p.capturedAt)) ||
Date.parse(p.capturedAt) > Date.now() ||
typeof p.ageSeconds !== 'number' ||
!Number.isInteger(p.ageSeconds) ||
p.ageSeconds < 0 ||
!['fresh', 'stale'].includes(String(p.freshness))
)
throw new HermesError('CONTRACT');
return {
provenance: {
source: 'snapshot',
capturedAt: p.capturedAt,
ageSeconds: p.ageSeconds,
freshness: p.freshness as string,
liveProcess: 'unknown',
},
};
}