feat(netlayer): Phase 6 — cleanup + docs (relay → location hint, netlayer guide)#974
Draft
rekmarks wants to merge 9 commits into
Draft
feat(netlayer): Phase 6 — cleanup + docs (relay → location hint, netlayer guide)#974rekmarks wants to merge 9 commits into
rekmarks wants to merge 9 commits into
Conversation
…rface Rename the libp2p-flavored term "relay" to the netlayer-neutral term "location hint" across the kernel-generic surfaces where the concept is no longer libp2p-specific: the persisted hint pool, its entry type, the store methods, the kernel-level config options, and the RemoteIdentity accessor. - `store/methods/relay.ts` -> `location-hints.ts`; `getRelayMethods` -> `getLocationHintMethods`, `getRelayEntries`/`setRelayEntries`/ `getKnownRelayAddresses` -> their `LocationHint` equivalents; persisted KV key `knownRelays` -> `knownLocationHints`; drop the legacy `string[]` migration path. - `RelayEntry`/`RelayEntryStruct` -> `LocationHintEntry`/`LocationHintEntryStruct`. - `RemoteIdentity.addKnownRelays` -> `addKnownLocationHints`; `RemoteCommsOptions.maxUrlRelayHints`/`maxKnownRelays` -> `maxUrlLocationHints`/`maxKnownLocationHints` (also in the kernel-control RPC struct and the browser worker comms query string). The libp2p netlayer's own config key `config.knownRelays` is deliberately left as-is: it is the seam with `@metamask/netlayer-libp2p`'s `Libp2pNetlayerConfig`, which keeps the "relay" name. Persisted state is not migrated (breaking, per the netlayer plan's compatibility decision). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ibp2p references - Add `docs/writing-a-netlayer.md`: the `Netlayer`/`ChannelProvider` contracts, delivery semantics, incarnation handshake, identity requirements, error mapping, config/registration, testing guidance, a worked example, and an iroh next-netlayer note (issue #968). - Add a `## Networking` glossary section: netlayer, location hint, neutral peer id, loopback netlayer, hub-and-spoke, incarnation handshake, ocap URL. - Generalize `ken-protocol-assessment.md`'s FIFO/transport claims from "TCP/libp2p" to the netlayer per-connection ordering contract. - Update `usage.md` and `identity-backup-recovery.md` remote-comms examples to the `NetlayerSpecifier` shape and neutral (`z…`) peer ids. - Fix stale `packages/nodejs/` paths in `platform-specific.md` to `packages/kernel-node-runtime/`, and note netlayer injection. - Move the SES/libp2p patch guidance off the (now libp2p-free) ocap-kernel README onto `@metamask/netlayer-libp2p`; link the new guide from the netlayer package READMEs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…l stack - master.md: add the Phase 6 "Landed decisions" block (the executed rename, the `config.knownRelays` seam kept, the docs shipped, coverage) and an "Effort complete" summary of what shipped across Phases 1–4+6 and what remains (Phase 5 deferred, the endoify relocation review item, the browser getListenAddresses gap, iroh as future work). - phase-5.md: update the deferral banner to record that Phase 6 has landed and reconcile the plan against it — the relay→location-hint rename touched the kernel surface but not the `config.knownRelays` netlayer-config seam, so the plan's use of that key for `wss://` hub URLs still holds; point at the new writing-a-netlayer guide and glossary. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Document the README/test-helper touches in the packages Phase 6 modified incidentally (the three netlayer package READMEs and the libp2p e2e test helper), so the changelog check passes for every changed published package. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
Coverage Report
File Coverage
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Brings in 961d968: the reworded endoify follow-up note in master.md and the new phase-6.md §1a 'Follow-ups carried from Phase 4' section. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…rule, libp2pComms) - Add a packaging section to the writing-a-netlayer guide documenting the load-bearing tsconfig.packages.json subpath→src mapping rule for netlayer-libp2p (§1a.4): a missing mapping makes vitest resolve to dist and initialize a second post-lockdown @libp2p/webrtc, crashing SES. - Record the libp2pComms test-helper retirement (§1a.3) as tracked future work in master.md's effort-complete summary. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Add the user-requested draft plan for @metamask/netlayer-iroh (proposed to supersede the deferred WebSocket phase as the second real ChannelProvider, plus a provider-conformance test kit). Reconcile it with landed Phase 6: add the kernel's config.knownRelays convention key to its config sketch, link the writing-a-netlayer guide + glossary and the guide's packaging/tsconfig section. Cross-link the draft (marked DRAFT/unscheduled) from master.md's effort-complete iroh bullet and the guide's iroh note, and add one banner sentence to phase-5.md noting the draft exists (Phase 5 remains an independent future option). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Final phase of the pluggable-netlayer effort (issue #968), stacked on #973 (
rekm/netlayer-4). Phase 5 (@metamask/netlayer-websocket) is deferred by user decision — the effort goes Phase 4 → Phase 6 directly.Phase 6 is cleanup + docs. It contains no functional changes beyond a terminology rename.
Rename: relay → location hint (kernel-generic surface)
The libp2p-flavored term "relay" is renamed to the netlayer-neutral "location hint" everywhere it is the kernel's own vocabulary:
store/methods/relay.ts→location-hints.ts;getRelayMethods→getLocationHintMethods,get/setRelayEntries→get/setLocationHintEntries,getKnownRelayAddresses→getKnownLocationHintAddresses; persisted KV keyknownRelays→knownLocationHints; the legacystring[]migration path is deleted (fresh-storage only, per the effort's break-freely decision).RelayEntry/RelayEntryStruct→LocationHintEntry/LocationHintEntryStruct(theaddrfield name kept).RemoteIdentity.addKnownRelays→addKnownLocationHints;RemoteCommsOptions.maxUrlRelayHints/maxKnownRelays→maxUrlLocationHints/maxKnownLocationHints(also in the kernel-control RPC struct andkernel-browser-runtime'scomms-query-string).config.knownRelaysis deliberately NOT renamed — it is the netlayer-config seam with@metamask/netlayer-libp2p'sLibp2pNetlayerConfig.knownRelays(the one config key the kernel injects by convention), and phase-6 explicitly excludes the libp2p package. Renaming only the kernel side would break the contract.Docs
docs/writing-a-netlayer.md: theNetlayer/ChannelProvidercontracts, delivery semantics, incarnation handshake, identity requirements, error mapping, config/registration, testing guidance, a worked example, and an "iroh is the next (Node-only) netlayer" note.## Networkingglossary section (netlayer, location hint, neutral peer id, loopback netlayer, hub-and-spoke, incarnation handshake, ocap URL).ken-protocol-assessment.md(FIFO/transport → netlayer per-connection ordering),usage.md+identity-backup-recovery.md(NetlayerSpecifier shape, neutralz…peer ids),platform-specific.md(packages/nodejs/→packages/kernel-node-runtime/+ netlayer-injection note). The stale SES/@chainsafe/libp2p-yamuxpatch guidance moved off the now-libp2p-free ocap-kernel README onto@metamask/netlayer-libp2p.master.mdmarks Phase 6 done with a landed-decisions block and an effort-complete summary;phase-5.mdis re-reconciled against the final stack.Coverage
Both touched packages meet/exceed their pre-phase baselines on two clean runs:
Deleting the fully-covered migration path caused a ~0.02–0.07% arithmetic dip on ocap-kernel (no source regressed — uncovered-line count unchanged); it was closed above baseline with two behavior-asserting tests (bootstrap-hint sort order;
remoteForhint-registration failure).Left for humans
@libp2p/webrtcendoify relocation (kernel-shimsendoify-node.js) remains deferred and review-gated — a pre-lockdown import whose relocation touches ~7 packages with a silent-lockdown-failure risk. Not performed here.🤖 Generated with Claude Code