194 lines
13 KiB
Markdown
Executable File
194 lines
13 KiB
Markdown
Executable File
# Data Model Reference
|
|
|
|
This document summarizes the durable and in-memory data shapes that define
|
|
Frosty Deno's configuration, governance, caching, logging, and operator
|
|
surfaces.
|
|
|
|
## Durable storage model
|
|
|
|
### PostgreSQL state store
|
|
|
|
`packages/config/src/store_postgres.ts` defines two generic durable tables:
|
|
|
|
| Object | Shape | Purpose |
|
|
| ----------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
|
|
| `frosty.state` | `key_text text primary key`, `key_path text[]`, `value jsonb`, `updated_at timestamptz` | Durable JSON document store for config, hierarchy, settings, logs, and related state |
|
|
| `frosty.counters` | `key_text text primary key`, `key_path text[]`, `value bigint`, `updated_at timestamptz` | Durable atomic counters for usage, cost, budgets, and shared rate-limit windows |
|
|
|
|
State and counter namespaces are intentionally separate so additive counters
|
|
never masquerade as ordinary JSON documents.
|
|
|
|
### Cache and vector tables
|
|
|
|
| Object | Purpose | Source |
|
|
| ------------------------------------------------ | --------------------------------------------- | ----------------------------------------------------------- |
|
|
| `frosty.response_cache` | Cached response payloads with TTL support | `packages/cache/src/pg_cache.ts` |
|
|
| `FROSTY_PG_TABLE` defaulting to `frosty_vectors` | pgvector embeddings for semantic cache lookup | `apps/gateway/context.ts`, `packages/cache/src/pgvector.ts` |
|
|
|
|
## Key-path conventions in `frosty.state`
|
|
|
|
The durable store is key-path driven. Important observed prefixes include:
|
|
|
|
| Prefix | Stored object family |
|
|
| ------------------------------- | ------------------------------------------------------------- |
|
|
| `['config', 'providers', <id>]` | Provider account configuration |
|
|
| `['config', 'settings']` | Gateway config-level settings data |
|
|
| `['virtual_keys', ...]` | Virtual-key state |
|
|
| `['teams', ...]` | Team hierarchy data |
|
|
| `['customers', ...]` | Customer hierarchy data |
|
|
| `['settings', <group>]` | Per-group operator override fragments |
|
|
| `['logs', ...]` | Durable log entries when log storage is enabled |
|
|
| `['config', 'crypto', 'dek']` | Wrapped data-encryption key record for encrypted config state |
|
|
|
|
## Configuration entities
|
|
|
|
### `ProviderAccountConfig`
|
|
|
|
Defined in `packages/contracts/src/config.ts`.
|
|
|
|
Major fields:
|
|
|
|
| Field | Type | Purpose |
|
|
| --------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------- |
|
|
| `id` | `string` | Stable provider account id |
|
|
| `type` | enum | Provider family such as `openai`, `anthropic`, `azure`, `bedrock`, `vertex`, `openai-compatible`, or `lmstudio` |
|
|
| `apiKey` | `string?` | Provider API key when that provider uses one |
|
|
| `baseUrl` | `string?` | Upstream base URL |
|
|
| `endpoint`, `apiVersion` | `string?` | Azure-specific routing values |
|
|
| `enabled` | `boolean` | Provider account enablement |
|
|
| `models` | `string[]` | Advertised model catalog |
|
|
| `priority`, `weight` | `number` | Fallback and weighted balancing hints |
|
|
| `retry` | object | Provider retry policy |
|
|
| `aws*` | strings | Bedrock and S3 integration fields |
|
|
| `projectId`, `location`, `serviceAccountJson` | strings | Vertex AI configuration |
|
|
| `proxyUrl` | `string?` | Per-provider proxy endpoint |
|
|
| `network`, `proxy`, `performance`, `governance`, `betaHeaders`, `debugging` | objects | Six grouped provider-control panels |
|
|
|
|
Redacted browser-safe view:
|
|
|
|
- `ProviderAccountPublic` replaces secrets with presence markers such as
|
|
`hasApiKey`, `hasCloudCredentials`, `hasProxy`, `hasProxyPassword`, and
|
|
`hasCaCert`.
|
|
- Header values, proxy passwords, bypass rules, certificate PEM data, raw
|
|
provider secrets, and stored cloud credentials do not reach the browser.
|
|
|
|
### `GatewayConfig` and `ConfigExport`
|
|
|
|
| Type | Purpose |
|
|
| --------------- | ------------------------------------------------------------------------- |
|
|
| `GatewayConfig` | Strict object with `defaultProvider` and `providers[]` |
|
|
| `ConfigExport` | Versioned export payload containing `version`, `exportedAt`, and `config` |
|
|
|
|
## Governance entities
|
|
|
|
### `Budget`
|
|
|
|
Defined in `packages/governance/src/virtual_keys.ts`.
|
|
|
|
| Field | Purpose |
|
|
| ----------------- | ------------------------------------------ |
|
|
| `maxRequests` | Request-count budget ceiling |
|
|
| `maxCostUsd` | Dollar-cost budget ceiling |
|
|
| `resetIntervalMs` | Optional server-timed fixed reset interval |
|
|
|
|
### `VirtualKey`
|
|
|
|
Defined in `packages/governance/src/virtual_keys.ts`.
|
|
|
|
| Field | Purpose |
|
|
| ----------------------------------- | --------------------------------------------------------------------- |
|
|
| `id`, `name`, `description` | Stable identifier and operator label |
|
|
| `token` | Raw bearer token accepted transiently on creation or legacy migration |
|
|
| `tokenHash` | Persisted SHA-256 hex token hash |
|
|
| `tokenHint` | Non-secret last-four-character hint for UI display |
|
|
| `enabled` | Key enablement |
|
|
| `rateLimit` | Request-based fixed window |
|
|
| `tokenLimit` | Token-metered fixed window |
|
|
| `budget` | Request and/or cost budget |
|
|
| `allowedProviders`, `allowedModels` | Admission scope restrictions |
|
|
| `usedRequests`, `usedCostMicroUsd` | Accrued metering data |
|
|
| `teamId` | Optional team membership |
|
|
|
|
Public browser-safe projections drop the raw token and its hash and add a
|
|
derived `usedCostUsd` field.
|
|
|
|
### `Team` and `Customer`
|
|
|
|
Defined in `packages/governance/src/hierarchy.ts`.
|
|
|
|
| Type | Key fields | Purpose |
|
|
| ---------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------- |
|
|
| `Team` | `id`, `name`, `enabled`, `customerId`, `budget`, `usedRequests`, `usedCostMicroUsd` | Mid-level hierarchy node collecting usage from virtual keys |
|
|
| `Customer` | `id`, `name`, `enabled`, `budget`, `usedRequests`, `usedCostMicroUsd` | Top-level hierarchy node collecting usage from teams |
|
|
|
|
Unknown references fail closed during chain validation.
|
|
|
|
## Settings model
|
|
|
|
Defined in `packages/contracts/src/settings.ts` and
|
|
`apps/gateway/routes/settings.ts`.
|
|
|
|
Settings groups:
|
|
|
|
| Group | Purpose |
|
|
| --------------- | ------------------------------------------------------ |
|
|
| `security` | Auth and route-protection-related operator settings |
|
|
| `compatibility` | Request translation and unsupported-parameter handling |
|
|
| `performance` | Request-body and pool-size tuning |
|
|
| `caching` | Cache enablement and tuning |
|
|
| `mcp` | MCP tool and external-client settings |
|
|
|
|
Important settings response characteristics:
|
|
|
|
- `GET /api/settings` returns effective values plus per-field provenance in
|
|
`sources`.
|
|
- Provenance values are `default`, `env`, or `override`.
|
|
- Persisted overrides are stored by group under `['settings', <group>]`.
|
|
- `security.hasPassword` is derived metadata; the password itself is not
|
|
returned.
|
|
- Runtime enforcement is exposed separately through an `enforcement` map because
|
|
not every persisted setting is wired live.
|
|
|
|
## MCP data shapes
|
|
|
|
Observed browser-facing MCP view types in `apps/control-ui/src/api.ts`:
|
|
|
|
| Type | Purpose |
|
|
| ---------------- | ----------------------------------------------------------------------------------------------------- |
|
|
| `MCPClientView` | Browser-safe MCP client record with `headerNames`, `hasCommand`, `hasUrlCredentials`, and `toolCount` |
|
|
| `MCPClientInput` | UI write shape for MCP client creation and updates |
|
|
| `MCPToolView` | Aggregated tool metadata including `clientId` and optional annotations |
|
|
| `MCPHealthView` | Per-client health summary |
|
|
|
|
## Telemetry and log model
|
|
|
|
### `LogEntry`
|
|
|
|
Defined in `packages/telemetry/src/logbus.ts`.
|
|
|
|
| Field family | Purpose |
|
|
| ----------------------------------------------------- | ----------------------------------------------------- |
|
|
| `ts`, `level`, `message` | Base log metadata |
|
|
| `requestId`, `method`, `path`, `status`, `durationMs` | HTTP request identification and timing |
|
|
| `provider`, `model` | Resolved inference target |
|
|
| `promptTokens`, `completionTokens`, `totalTokens` | Usage accounting |
|
|
| `costMicroUsd` | Cost in the repo-wide integer micro-USD unit |
|
|
| `content` | Opt-in captured request/response content when enabled |
|
|
|
|
Request and response content capture is disabled by default and redacts
|
|
secret-looking keys before persistence.
|
|
|
|
## UI-facing transport shapes
|
|
|
|
The control UI imports shared contracts directly and adds view-specific wrapper
|
|
shapes in `apps/control-ui/src/api.ts`, including:
|
|
|
|
- `GatewayConfigView`
|
|
- `VersionInfo`
|
|
- `AnalyticsRollup`, `AnalyticsTotals`, `AnalyticsBucket`, `AnalyticsModelRow`,
|
|
`AnalyticsProviderRow`
|
|
- `StoredLogsResult`
|
|
|
|
Those client-side view types are projections over gateway responses, not
|
|
independent persistence models.
|