Commit 04e9315
feat(ocap-kernel): bound relay hints in OCAP URLs and relay pool size (#929)
## Summary
OCAP URLs embed relay multiaddrs as discovery hints. After #887
propagated these hints on redemption, the relay list in URLs (and in the
KV store) grows unboundedly as kernels encounter new relays through URL
exchange. This PR bounds both the URL hint count and the relay pool
size.
After investigating whether a gossip protocol was needed (#889), the
conclusion was that the problem is URL size, not relay discovery —
passive propagation via URL exchange is sufficient at current scale. A
gossip protocol can be added later if needed.
### Changes
- Add `RelayEntry` type with `addr`, `lastSeen`, `isBootstrap` metadata
for prioritized relay selection
- Cap relay hints embedded in OCAP URLs to `MAX_URL_RELAY_HINTS` (3),
selecting bootstrap relays first, then most recently seen
- Bound the relay pool to `MAX_KNOWN_RELAYS` (20) with eviction of
oldest non-bootstrap entries
- Mark bootstrap relays at kernel init; merge with (not overwrite)
existing learned relays
- Auto-migrate legacy `string[]` relay storage format to `RelayEntry[]`
- Update store API: `getRelayEntries()` / `setRelayEntries()` /
`getKnownRelayAddresses()` replace `getKnownRelays()` /
`setKnownRelays()`
## Testing
All changes are covered by unit tests. New tests verify URL hint
capping, bootstrap relay priority in selection, pool cap enforcement (in
both `addKnownRelays` and `initRemoteIdentity`), eviction of oldest
non-bootstrap entries, `lastSeen` timestamp updates on re-observation,
bootstrap flag clearing on re-init with a different set, and legacy
storage format auto-migration. Existing tests were updated for the new
store API. All 82 tests pass, lint and build are clean.
Closes #889
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> **Medium Risk**
> Changes relay persistence and selection logic used for OCAP URL
issuance, including an on-read KV migration and eviction behavior that
could affect connectivity if misconfigured or buggy.
>
> **Overview**
> OCAP URL issuance now **limits embedded relay hints** (default `3`) by
selecting relays from a prioritized pool (*bootstrap first, then most
recently seen*).
>
> Relay storage is refactored from a raw `string[]` to `RelayEntry[]`
(`addr`, `lastSeen`, `isBootstrap`), with a **bounded relay pool**
(default `20`) that evicts oldest non-bootstrap entries and
merges/updates bootstrap relays on init; legacy `knownRelays` data is
auto-migrated on read.
>
> `initRemoteComms`/RPC adds `maxUrlRelayHints` and `maxKnownRelays`,
strips undefined params via `ifDefined`, and avoids passing `mnemonic`
to platform services; tests are updated/expanded for capping, ordering,
eviction, and migration.
>
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
9bbc7e9. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>1 parent 8a1b6d0 commit 04e9315
11 files changed
Lines changed: 994 additions & 122 deletions
File tree
- packages/ocap-kernel
- src
- remotes
- kernel
- rpc/kernel-control
- store
- methods
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
7 | 7 | | |
8 | 8 | | |
9 | 9 | | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
10 | 14 | | |
11 | 15 | | |
12 | 16 | | |
| |||
0 commit comments