Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,10 @@ providers/transport → `deep-dive-providers.md`; reload/restart →
`wire/` protocol codecs, `routing/` + `accounts/` +
`catalog/` + `quota/` + `health/` selection, `model_router.rs` affinity,
`identity.rs` + `web_session.rs` + `user_budget.rs` + `instance_budget.rs` +
`model_policy.rs` on-prem user access, `providers/` transport,
`model_policy.rs` + `personal_upstream.rs` on-prem user access, `providers/` transport,
`runtime_lifecycle/` generations + `reload.rs` +
`task_supervisor.rs`, `operations/` local lifecycle, `db/` +
`rust/assets/db/migrations/` v1–v65 immutable.
`rust/assets/db/migrations/` v1–v66 immutable.
- Reusable policy crates: `rust/crates/eggpool-model-routing/` (neutral validation/compilation only; selector execution and affinity cache stay in `rust/src/`), `rust/crates/eggpool-client-config/` (portable Codex/OpenCode projection, profiles, `epc1` tokens, V1/V2 renderers, TOML/JSONC-preserving mutation; EggPool `Config`/catalog/DB/key/endpoint/CLI/file IO stays in `rust/src/operations/integrations.rs`), `rust/crates/eggpool-provider-profile/` (secret-free sans-I/O provider-profile contract plus the canonical bundled asset at `assets/_provider_profiles.toml`; `rust/src/provider_profile.rs` is the only EggPool reader), `rust/crates/eggpool-wire/` (neutral sans-I/O wire kernel; execution stays in `rust/src/`), `rust/crates/eggpool-connect/` (narrow `eggpool-connect` binary: plan/install/verify/backups/restore/remove with byte-exact backups, atomic writes, automatic rollback; no Axum/SQLite/Eggress, no proxy/agent/daemon).
- Tooling only (never a runtime fallback): repo-root `pyproject.toml`, `scripts/`, `tests/tooling/`. `scripts/qualification_sbc.py` is the sole physical-SBC runner (loopback-only, aggregate-only, non-CI). Native tests live in `rust/tests/` (serial; there is no `coordinator_c012`; streaming files are `coordinator.rs`, `execution.rs`, `terminal.rs`, `timeout.rs`, `types.rs`, `diagnostics.rs`).
- Config resolution: `--config` > `$EGGPOOL_CONFIG` > `~/.config/eggpool/config.toml` > `./config.toml`. Provider/upstream keys come from environment/`.env`, never committed; the server key lives under `[server]` (`api_key` via `eggpool newkey`, or `api_key_env`). Examples: `rust/config.example.toml`, `rust/config.local.example.toml`, `rust/config.sbc.example.toml`.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ Generated configs reference `EGGPOOL_API_KEY` without embedding the key. Set it

## Dashboard & LAN Access

By default EggPool binds `0.0.0.0:11300` and serves a public read-only dashboard at `http://<lan-ip>:11300/`. To share with desktops on your LAN, set `[integrations].advertise_base_url = "http://<lan-ip>:11300/v1"`, run `eggpool rehash` (advertised URL is live-reloadable profile output; it never changes the listen socket), then export a profile with `eggpool configremote codex`. Lock it down with `[server].host = "127.0.0.1"` (local only) or `eggpool dashboard public --off` (key required on the dashboard too). See [Firewall](https://github.com/eggstack/eggpool/blob/main/docs/firewall.md).
By default EggPool binds `0.0.0.0:11300`. After `eggpool onboard`, sign in at `http://<lan-ip>:11300/login` and export the one-time personal token as `EGGPOOL_API_KEY`. A database that is still `legacy_unmigrated` can serve a public read-only dashboard at `http://<lan-ip>:11300/`. To share with desktops on your LAN, set `[integrations].advertise_base_url = "http://<lan-ip>:11300/v1"`, run `eggpool rehash` (advertised URL is live-reloadable profile output; it never changes the listen socket), then export a profile with `eggpool configremote codex`. Lock a legacy dashboard down with `[server].host = "127.0.0.1"` (local only) or `eggpool dashboard public --off` (key required on that legacy dashboard too). See [Firewall](https://github.com/eggstack/eggpool/blob/main/docs/firewall.md).

Browser password sign-in is shown only over loopback or trusted HTTPS proxy
transport. A remote plaintext HTTP visit to `/login` receives an explanation
Expand Down
8 changes: 5 additions & 3 deletions architecture/deep-dive-dashboard.md
Original file line number Diff line number Diff line change
Expand Up @@ -154,9 +154,11 @@ page, not a fragment.
`/admin/audit`, `/my-account`, `/my-account/models`, and the one-shot
personal-token page) use `dashboard_standalone_page()`; the one-shot token
page keeps its bare shell but still resolves the theme.
- **Navigation chrome.** The shared navigation (`DASHBOARD_NAVIGATION`) is
rendered by the dashboard layout and by every standalone shell, so there is
always a route back to the overview. Its destinations are fixed.
- **Navigation chrome.** Operator pages render `DASHBOARD_NAVIGATION`, so
an administrator always has a route back to the overview. Member pages for
`/my-account`, `/my-account/models`, and `/usage` render the member set:
My account, My models, Usage, and Password. An administrator viewing those
same pages keeps the operator set.
- **Table chrome.** The stylesheet scopes the table chrome to `table.data`.
Every table the renderers emit is opened through `DASHBOARD_TABLE_OPEN` or
`DASHBOARD_TABLE_OPEN_COMPACT`, and a source-level guard fails if a table is
Expand Down
45 changes: 34 additions & 11 deletions architecture/deep-dive-on-prem-user-access.md
Original file line number Diff line number Diff line change
Expand Up @@ -220,24 +220,38 @@ from the measured lookup overhead.

`server/dashboard/admin.rs` owns the HTML surfaces and their form handlers.
Every handler is a thin adapter: it validates the CSRF form field, resolves
the actor, and delegates to `identity.rs` or `model_policy.rs`.
the actor, and delegates to `identity.rs`, `model_policy.rs`, or
`personal_upstream.rs`.

Admin surfaces: `/users`, `/profiles`, `/usage`, `/admin/audit`, and the
`/admin/users/*` action family (create, state, password, token, revoke
tokens, profile assignment, override add/remove, budget), the
tokens, profile assignment, override add/remove, budget, personal-upstream
grant and remove), the
`/admin/budget/instance*` family, and the `/admin/profiles/*` family (create,
default, update, delete, rule add/remove, preference).

Member surfaces: `/login`, `/logout`, `/account`, `/account/landing`,
`/account/password`, `/my-account`, `/my-account/models`, `/account/tokens`,
`/account/tokens/revoke`, `/usage`, and `/api/user-budget`.
`/account/password`, `/my-account`, `/my-account/models`, `/my-account/upstreams`,
`/my-account/upstreams/remove`, `/account/tokens`,
`/account/tokens/revoke`, `/usage`, and `/api/user-budget`. The personal
upstream form lives on My account. It is not a navigation item. The key field
is rendered only when that member's effective grant is allow, and a personal
API token cannot post it.

A member who signs in lands on `/account/landing`, which links the member
destinations (`/my-account`, `/my-account/models`, `/usage`) and exposes no
administrative route and no administrative datum, so the member surface is
reachable without knowing a URL. An administrator who signs in lands on
reachable without knowing a URL. The same member destinations are the only
links in the navigation of `/my-account`, `/my-account/models`, and `/usage`.
An administrator keeps the operator navigation on those pages. An administrator who signs in lands on
`/account`, which links back to the dashboard overview.

Usage projections stay inside one window kind. The administrator usage page
shows the current UTC day and the current UTC month as separate tables.
A member sees their own rows labeled day or month, the remaining allowance
on their own current windows, and the configured instance ceilings. Instance
usage totals stay on the administrator `/api/user-budget` response.

The route-role gate lives in `server/middleware.rs`, not here. A non-administrator
browser principal is confined to the member surfaces; an administrator-only
path answers `403` with a page that names the refusal and points at the member
Expand All @@ -249,12 +263,13 @@ never a password, a token, or any other secret.

The local CLI surface is `eggpool users`, whose subcommands are `bootstrap`,
`add`, `disable`, `enable`, `show`, `list`, `reset-password`, `token`,
`revoke`, `enable-managed`, `policy`, `budget`, `global-budget`, and
`defaults`.
`revoke`, `enable-managed`, `policy`, `budget`, `global-budget`,
`defaults`, and `upstream`. `upstream add` reads the key from a TTY or
`--secret-stdin` and writes it only to the config-adjacent `.env`.

## Durable tables

The subsystem's tables are migrations 55–63 of the embedded chain:
The subsystem's tables are migrations 55–63 and 66 of the embedded chain:

| Migration | Tables |
|---|---|
Expand All @@ -267,6 +282,7 @@ The subsystem's tables are migrations 55–63 of the embedded chain:
| 61 `user_budget_enforcement` | enforcement column and worst-case hold/price-provenance columns on the budget tables |
| 62 `instance_budgets` | `instance_budget_rules`, `instance_budget_reservations`, `instance_budget_usage`, `instance_budget_rule_audit` |
| 63 `default_member_profile` | `policy_state.default_member_profile_id` |
| 66 `personal_upstream` | `personal_upstream_grants`, `personal_upstream_bindings` |

`requests.user_id` is a nullable column without a foreign key, so disabling
or removing a local user cannot erase request attribution. Internal semantic
Expand All @@ -275,9 +291,11 @@ user-history queries; `identity::recent_user_requests` uses the
`(user_id, started_at DESC, id DESC)` index, clamps reads to 500 rows, and
returns content-free request facts.

No table stores a plaintext password, a plaintext token, a prompt, a raw
body, or a cache key. Backups therefore carry identity records and
non-recoverable credential digests only.
No table stores a plaintext password, a plaintext token, a provider key, a
prompt, a raw body, or a cache key. A personal upstream binding names the
provider, account, and user. The key stays in the operator environment file.
Backups therefore carry identity records and non-recoverable credential
digests only, plus the environment file when the backup includes it.

## Invariants

Expand All @@ -289,6 +307,11 @@ non-recoverable credential digests only.
disablement fails closed at commit time.
- A policy snapshot is immutable for the request that admitted it.
- Downstream user budgets and upstream provider quota remain independent.
- A personal upstream account is selectable only by its owner. No binding
means the account stays shared. The instance grant defaults to deny and
does not change routing. Disabling a user withdraws that user's active
bindings in the same transaction; enabling the user does not restore them.
Changing a grant does not withdraw a binding.
- The single SQLite connection/gate/worker, WAL/NORMAL, the generation lease
model, and the publication/finalization ownership are unchanged by this
subsystem.
6 changes: 6 additions & 0 deletions architecture/deep-dive-routing.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,12 @@ derives it from `RoutingConfig` (`local_quota_mode`, `fairness_mode`, `fairness_
`capability_policy`). `RoutingRequestFacts::from_model_id` splits an optional
`provider/model` suffix with `ModelCatalogCache::parse_model_provider`.

Before that per-account scoring, a generation snapshot of personal upstream
bindings drops an account that is withdrawn, ambiguously owned, or bound to
someone other than the request principal (`personal_upstream`). A missing
binding leaves the account shared. The legacy shared-key principal has no user
id and cannot select a bound account.

Per account, `candidate_for_account` checks, in order: enabled, usable credentials,
requested provider (`no_provider` when the account has no provider vs `wrong_provider`),
request surface (`RequestSurface`), requested/transcodable protocol,
Expand Down
16 changes: 11 additions & 5 deletions architecture/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,8 @@ operation, not a Responses alias); discovery and health at `/v1/models`,
`/api/stats/canonical-request-segmentation`, `/api/stats/cache-stability`,
`/api/stats/request-shaping`, `/api/timeseries`, `/api/timeseries/grouped`);
managed-user at `/login`, `/logout`, `/account`, `/account/landing`,
`/account/password`, `/my-account`, `/my-account/models`, `/account/tokens`,
`/account/password`, `/my-account`, `/my-account/models`,
`/my-account/upstreams`, `/my-account/upstreams/remove`, `/account/tokens`,
`/account/tokens/revoke`, `/usage`, `/api/user-budget`; dashboard pages at
`/`, `/accounts`, `/models`, `/models/{*model_id}`, `/latency`, `/events`,
`/timeseries`, `/bandwidth`, `/pings`, `/reliability`, `/routing`,
Expand All @@ -165,6 +166,8 @@ admin actions at `/admin/users/create`, `/admin/users/state`,
`/admin/users/password`, `/admin/users/token`, `/admin/users/revoke-tokens`,
`/admin/users/profile`, `/admin/users/override`,
`/admin/users/override/remove`, `/admin/users/budget`,
`/admin/users/upstream/default`, `/admin/users/upstream/grant`,
`/admin/users/upstream/remove`,
`/admin/budget/instance`, `/admin/budget/instance/remove`,
`/admin/profiles/create`, `/admin/profiles/default`,
`/admin/profiles/update`, `/admin/profiles/delete`, `/admin/profiles/rule`,
Expand Down Expand Up @@ -353,7 +356,7 @@ is the only persistence boundary. `db/` owns only the `backup_to` snapshot
primitive; backup orchestration lives in `operations/backup.rs` and crash
repair in `runtime_lifecycle/recovery.rs` plus coordinator reconciliation.
Migrations (`rust/assets/db/migrations/`,
currently v1–v65 with `checksums.json`) are embedded and immutable; commit or
currently v1–v66 with `checksums.json`) are embedded and immutable; commit or
ownership ambiguity fails closed; startup reconciliation repairs only covered
states. Repositories accept no unbounded diagnostic content and never store
credentials, prompts, raw bodies, or cache keys.
Expand Down Expand Up @@ -481,8 +484,11 @@ scopes: daily and monthly rules with explicit `estimated`/`hard` enforcement,
worst-case holds for `hard`, checks and holds in the same publication
transaction as the request reservation, and settlement of one daily and one
monthly bucket at terminalization. `rust/src/server/dashboard/admin.rs` owns
the admin and member HTML surfaces as thin CSRF-validated adapters. The
subsystem owns no router, no upstream dispatch, and no second database
the admin and member HTML surfaces as thin CSRF-validated adapters.
`rust/src/personal_upstream.rs` owns personal upstream grants and bindings.
The plaintext secret stays in the config-adjacent environment file, and
routing eligibility excludes a bound account from every principal except its
owner. The subsystem owns no router, no upstream dispatch, and no second database
writer; `server/middleware.rs` keeps the route-role gate, `coordinator/`
keeps publication and settlement, and `routing/`, `quota/`, and `health/`
keep owning upstream accounts, provider quota, and provider health.
Expand Down Expand Up @@ -591,7 +597,7 @@ Deep dives: [Core](deep-dive-core.md), [Deployment](deep-dive-deployment.md).
| Operations CLI surface | `rust/src/runtime.rs`, `rust/src/cli.rs`, `rust/src/operations/` (local operator commands; `runtime.rs` dispatches and renders, `operations/` owns the local services) | [Core](deep-dive-core.md), [Control](deep-dive-control.md), [Metrics](deep-dive-metrics.md) |
| Config, reload policy, reload | `rust/src/config.rs`, `rust/src/config_reload_policy.rs`, `rust/src/reload.rs`, `rust/build.rs`, `rust/build_support.rs` | [Core](deep-dive-core.md), [Control](deep-dive-control.md), [Runtime](deep-dive-runtime.md) |
| HTTP adapters | `rust/src/server/` | [Request lifecycle](deep-dive-request-lifecycle.md), [Dashboard](deep-dive-dashboard.md), [Runtime](deep-dive-runtime.md) |
| On-prem user access | `rust/src/identity.rs`, `rust/src/web_session.rs`, `rust/src/model_policy.rs`, `rust/src/user_budget.rs`, `rust/src/instance_budget.rs`, `rust/src/server/auth.rs`, `rust/src/server/dashboard/admin.rs` | [On-prem user access](deep-dive-on-prem-user-access.md) |
| On-prem user access | `rust/src/identity.rs`, `rust/src/web_session.rs`, `rust/src/model_policy.rs`, `rust/src/user_budget.rs`, `rust/src/instance_budget.rs`, `rust/src/personal_upstream.rs`, `rust/src/server/auth.rs`, `rust/src/server/dashboard/admin.rs` | [On-prem user access](deep-dive-on-prem-user-access.md) |
| Admission | `rust/src/request/` | [Request lifecycle](deep-dive-request-lifecycle.md), [Transcoder](deep-dive-transcoder.md) |
| Coordinator finite/streaming | `rust/src/coordinator/`, `rust/src/coordinator/streaming/` | [Request lifecycle](deep-dive-request-lifecycle.md), [Retry](deep-dive-retry.md) |
| Publication/finalization/failure | `rust/src/coordinator/publication.rs`, `rust/src/coordinator/finalization.rs`, `rust/src/coordinator/failure.rs`, `rust/src/coordinator/attempt.rs`, `rust/src/coordinator/wire_resolver.rs` | [Request lifecycle](deep-dive-request-lifecycle.md), [Retry](deep-dive-retry.md) |
Expand Down
12 changes: 7 additions & 5 deletions docs/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -200,11 +200,13 @@ Requests denied because a hard rule cannot be bounded return HTTP 429 with
machine code `hard_budget_not_enforceable` before any upstream submission.
The response gives corrective guidance for an explicit output cap and, when
applicable, an operator tariff. Exhausted rules use the code
`budget_exceeded`. Administrator responses additionally include
`instance_rules` and `instance_usage`: the single instance-wide ceiling
intersected with every per-user rule. Members never receive instance fields,
so one member cannot observe the shared ceiling or infer other users'
consumption from it.
`budget_exceeded`. `remaining` reports, for the target user's own current
UTC day and month rules, each ceiling minus settled usage minus active holds.
A dimension with no ceiling has `remaining: null`. Both member and
administrator responses include `instance_rules`, the configured shared
ceilings. Administrator responses additionally include `instance_usage`.
Members do not receive instance usage or another user's rows, so they cannot
infer who else consumed the shared ceiling.

An optional `[admission_fairness]` policy can add process-local short-window
request throttles before request-body collection. A throttle returns HTTP 429
Expand Down
4 changes: 3 additions & 1 deletion docs/backup-restore.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,9 @@ and the SQLite database (plus `-wal`/`-shm` if present) into a single
timestamped `.zip` archive.

The database snapshot includes local users, budget rules and audit records,
active budget holds, and settled user/model usage. Restoring the snapshot
active budget holds, settled user/model usage, and secret-free personal
upstream bindings. The provider key for a personal account lives in `.env`,
which this backup includes when `include_env` is true. Restoring the snapshot
preserves the remaining budget state; crash reconciliation settles unknown
in-flight use conservatively before new requests resume.

Expand Down
Loading
Loading