Repository navigation
Commit a32e448
fix: make AI work again on hosted Void Cloud: publish AI logging policy to KV (#814)
Since 1.8.0 the proxy asked the API for each project's AI logging policy
on every AI call, and the API refused unless
PLATFORM_AUTH_DATABASE_UNCACHED
was set. Hosted Void Cloud never sets it, so every hosted AI call failed
with 503 ai_logging_policy_unavailable.
Now the API and the installer write the policy to ROUTING KV key
`ai-logging:<projectId>`, and the proxy reads it from there.
## How AI logging works
**The setting.** Each project gets one AI Gateway logging mode:
| Mode | What AI Gateway stores |
|---|---|
| `inherit` | Whatever the gateway is set to; Void sends nothing (same
as 1.7.0) |
| `off` | No log entry |
| `metadata` | A log entry without the request or response bodies |
| `full` | A log entry with the bodies |
**Which mode wins:** the project's own setting, then its plan's default,
then the gateway. An account on a plan that isn't in the catalog uses
the default plan's setting.
### Data flow
```
operator / CLI / dashboard
project ai-logging · plans set · user plan · transfer · create · delete
│
▼
┌──────────────────────┐ lock project row, read inputs ┌──────────────┐
│ API │ ──────── through a write ─────────▶ │ Postgres │ saved settings
│ works out the mode │◀─────────────────────────────────── │ │ (the truth)
└──────────┬───────────┘ └──────────────┘
│ write under the lock (retries a 429 after 1/2/4 s)
▼
ROUTING KV ai-logging:<projectId> = off | metadata | full (no key = inherit)
▲ metadata {mode, at}
│ read on every AI call, 30 s cache
┌──────────┴───────────┐
│ proxy │ ──▶ AI Gateway headers for /ai/run, /ai/toMarkdown, /ai/provider
└──────────────────────┘
```
The proxy no longer calls the API. That call was the 503 that broke AI
on hosted Void Cloud.
### Who writes the key
| Event | What happens |
|---|---|
| Operator sets a project mode | Stricter change (e.g. `full` → `off`):
one transaction, rolled back if KV fails. Looser change or `inherit`:
saved first, then published. |
| Plan default changes | Published 100 projects per call. `plans sync`
continues, and the CLI keeps syncing until done. |
| User's plan changes | One page per call; running the same change again
continues it |
| Project create / transfer / delete | Key written inside the create;
republished on transfer; removed only after the row is gone |
| Install / upgrade / repair | The installer copies every saved setting
to KV, before and after the Worker upload |
| Every hour | The sweep repairs keys that differ from Postgres (at most
400 KV operations per run) |
### Timing
KV reads are cached for 30 s at each Cloudflare location, so a change
can take a short while to reach every location. After a change, the CLI
prints "expected by HH:MM:SS (normally within 2 minutes)".
### Readback
`void platform project show` and `project ai-logging` report a state:
```
applied KV matches and the settle time has passed
pending just published; some locations may still use the old value
pending_plan_publish a plan or user-plan publish has not reached this project yet
drift KV differs from the saved setting (the hourly sweep fixes it)
unknown KV could not be read
```
### When something fails, the proxy refuses instead of guessing
- KV read error: `503 ai_logging_policy_unavailable`, with `Retry-After`
- Unknown value in KV: `503 ai_logging_policy_invalid` (the value itself
is never logged)
- Publish failure on a change: `ai_logging_publish_failed` (nothing
changed) or `ai_logging_publish_pending` (saved, KV catches up)
### Older proxies
Proxies still on 1.8.x keep calling `GET /internal/ai-logging/:id`. That
route still exists and now answers from the same KV key, so they work
during the upgrade.
## Changes
Shared (`@void/platform/ai-logging`)
- Key names, value and metadata shape, parsers, resolver and the 30 s
read cache time, used by the API, the installer and the proxy.
Proxy
- Reads the key (cacheTtl 30) in /ai/run, /ai/provider and
/ai/toMarkdown,
after body validation. Missing key: inherit (no logging option, as in
1.7.0). off / metadata / full: the 1.8.0 gateway mapping. KV error:
503 ai_logging_policy_unavailable. Bad value: 503
ai_logging_policy_invalid. Caller-supplied logging keys are still
stripped.
API
- publishProjectAiLogging locks the project row, reads every input
through
a write statement (cached Hyperdrive reads never feed a publish), and
writes KV before the lock is released.
- The operator POST orders the write by direction: a tighten writes in
the
same transaction; a loosen or inherit commits first and publishes in a
second locked step. Errors: ai_logging_publish_failed / _pending.
- Plan defaults in platform_settings 'plans:ai-logging', published in
pages of 100. A user plan change publishes one page per call; transfer,
create and delete keep the key in step.
- An unfinished plan publish follows its accounts through a catalog
change: a removed plan's scope moves to its replacement, and a run that
covered unknown plans also covers plans added to the catalog.
- Readback returns saved, plan, effective, source, published and a
state:
applied, pending, pending_plan_publish, drift or unknown.
- An hourly sweep repairs drifted keys within a 400 KV operation budget.
- The internal route 1.8.x proxies call is kept and answers from KV.
Installer and CLI
- Every install, upgrade and repair copies each project's setting from
Postgres to KV, before and after the Worker upload, under the same row
locks as the API.
- `void platform project ai-logging` and `project show` print the
source,
effective mode and state; plan files accept `aiLogging`.
Docs
- CLI reference, admin guides, upgrade note, design doc 0094, operations
notes for the hosted rollout.
Refs #793.
Replaces the stack #814–#817 (now one PR, so the proxy switch and the KV
writers land together).
## Verification
- Full suite (`vp test run`) before the test cleanup: 804 files, 17,022
tests passed, 35 skipped. After it: `vp run check`, `vp lint`, the
touched test files, and CI.
- The two PostgreSQL-only lock-wait tests (`VOID_TEST_DATABASE_URL`) run
in CI.
- `packages/md/test/integration/theme-layout.test.ts` also fails on
`main` (from #811); fixed in #819. Merge #819 first, then update this
branch from `main`.
- Not run: live checks A/B, done by hand on a scratch Cloudflare
account; see design doc 0094.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>1 parent 071f444 commit a32e448
84 files changed
Lines changed: 7150 additions & 389 deletions
File tree
- docs
- guide
- platform
- administration
- installation
- reference
- cli
- packages
- platform
- src
- test/unit
- void
- src/cli
- test/unit
- platform
- meta
- design-docs
- packages
- api
- src
- admin
- fate
- react/views
- routes
- auth
- db
- operator
- provisioning
- routes
- test
- integration
- unit
- proxy
- src
- test/unit
Some content is hidden
Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
142 | 142 | | |
143 | 143 | | |
144 | 144 | | |
145 | | - | |
| 145 | + | |
146 | 146 | | |
147 | 147 | | |
148 | 148 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
16 | 16 | | |
17 | 17 | | |
18 | 18 | | |
19 | | - | |
| 19 | + | |
20 | 20 | | |
21 | 21 | | |
22 | 22 | | |
| |||
89 | 89 | | |
90 | 90 | | |
91 | 91 | | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
92 | 125 | | |
93 | 126 | | |
94 | 127 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
34 | 34 | | |
35 | 35 | | |
36 | 36 | | |
37 | | - | |
| 37 | + | |
38 | 38 | | |
39 | | - | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
40 | 42 | | |
41 | 43 | | |
42 | 44 | | |
| |||
49 | 51 | | |
50 | 52 | | |
51 | 53 | | |
52 | | - | |
| 54 | + | |
53 | 55 | | |
54 | 56 | | |
55 | 57 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
114 | 114 | | |
115 | 115 | | |
116 | 116 | | |
| 117 | + | |
| 118 | + | |
117 | 119 | | |
118 | 120 | | |
119 | 121 | | |
| |||
144 | 146 | | |
145 | 147 | | |
146 | 148 | | |
| 149 | + | |
| 150 | + | |
147 | 151 | | |
148 | 152 | | |
149 | 153 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
34 | 34 | | |
35 | 35 | | |
36 | 36 | | |
37 | | - | |
| 37 | + | |
38 | 38 | | |
39 | 39 | | |
40 | 40 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
21 | 21 | | |
22 | 22 | | |
23 | 23 | | |
24 | | - | |
| 24 | + | |
25 | 25 | | |
26 | | - | |
| 26 | + | |
27 | 27 | | |
28 | | - | |
| 28 | + | |
29 | 29 | | |
30 | 30 | | |
31 | 31 | | |
| |||
0 commit comments