Expand description
Service discovery and endpoint resolution for hyprstream.
This crate provides the DiscoveryService — the authoritative source
for service endpoint resolution in a hyprstream cluster. It wraps
the EndpointRegistry from hyprstream-rpc and exposes it as both
a local Resolver implementation and a Cap’n Proto RPC service.
§Architecture
hyprstream-rpc trait Resolver + SocketKind + EndpointRegistry
↑
hyprstream-discovery DiscoveryService (wraps registry, serves RPC)
↑
hyprstream factory creates DiscoveryService, injects AuthorizationProviderRe-exports§
pub use did_anchored::verify_anchor_material;pub use did_anchored::DeploymentTrustSource;pub use did_anchored::DidAnchors;pub use did_anchored::VerifiedAnchorMaterial;pub use plc_directory::ConnectTimeDiscovery;pub use plc_directory::DidOpSuccessorWitness;pub use plc_directory::InMemoryPlcDirectoryStore;pub use plc_directory::LivePlcDiscovery;pub use plc_directory::PlcDirectory;pub use plc_directory::PlcDirectoryRecord;pub use plc_directory::PlcDirectoryStore;pub use plc_directory::ResolvedPlcIdentity;pub use plc_directory::SignedPlcDirectoryGenesis;
Modules§
- admission_
roster - #1652 — derived native admission roster: deployment service identities
(and their
localtenant) resolved from the live accepted-state store at admission time, replacing the DID-valuedquic.moql_subject_tenantsmap. Derived native admission roster (#1652): deployment service identities resolved from the live accepted-state store at admission time, not from DID-valued process configuration. - annotations_
capnp - at9p_
alias - #896 (at9p D4) —
did:web/did:key→did:at9paliasing resolver: resolves a classical DID to its authoritativedid:at9pidentity via mutualalsoKnownAsattestation + the GATE pipeline. Sibling toat9p_resolver.did:web/did:key→did:at9paliasing resolver (#896 / D4; design #879 Q4, #905 §2/§6). - at9p_
resolver - #893 (at9p D1) —
did:at9pcapsule resolver: turns a GATE-verified capsule into a dialableTransportConfig::iroh(sibling tohyprstream_rpc::service_entry::decode_iroh). Injectable at theResolver::set_global/ network-profile resolver seam (#873).did:at9pcapsule resolver — GATE-verified reach as aTransportConfig(#893, design #879 §9; epic #880 Track D / D1). - common_
capnp - did_
anchored - #1136 — explicit DID-anchored deployment trust source. Resolves the public
(did:at9p, did:web)pin pair without weakening the OS-owned-file source. DID-anchored deployment trust bootstrap (#1136). - did_op
- #1167 — canonical, append-only, hash-chained DID operation log.
- generated
- placement_
index - #524 P1 — placement directory record ingestion + in-process index.
- plc_
directory - #1342 A — operable Hybrid
did:plcdirectory. - scheduling
- #523 P0 / #524 / #628 — Scheduling Substrate.
Structs§
- Deployment
Authority Checkpoint - Independently provisioned expected head of the deployment authority log.
- Deployment
Authority Log - Signed DidOp authority history embedded in a registry delegation.
- Discovery
Self Announcer - Owned publisher sharing Discovery’s actual state and verification sources.
- Discovery
Service - Discovery service that exposes EndpointRegistry over RPC.
- Discovery
State - Constructed backend handle accepted by
crate::DiscoveryService. - Discovery
State Config - Memory
State Config - Production
RpcClient Provider - Production client-construction adapter for the portable
rpc-stdclients. - Record
CarData - A record returned as a CARv1 proof (the in-memory form of
RecordCar). - Registry
Delegation Artifact - Root/current-authority UCAN delegation embedded in delegated registry JWTs.
- Registry
Deployment Verifier - Opaque verification-only view of the authenticated deployment registry. It exposes neither raw root material nor an authority replacement operation. Retaining the authenticated hybrid CA prevents this capability from being represented as provenance from a classical-only root.
- Service
KeyEnrollment Artifact - Chain-signed attestation binding a discovery/policy service’s live hybrid
public key (the exact 1984-byte
bootstrap-pubkeysentry) to the deployment authority, minted at activation by the delegated signer (hyprstream#1562). Public trust material: installed mode 0644, per-service. - Service
KeyEnrollment Signing Body - The signed body of a
ServiceKeyEnrollmentArtifact: every field except the signature, serialized with fixed struct-field order so the mint and the production verifier derive identical bytes. - Tiered
State Config - Validated
Delegation - Outcome of validating a root-authorized delegation: whether it may enroll service keys, and the delegation expiry that caps anything it mints.
- Valkey
State Config - Verified
Deployment Artifacts - Result of verifying the enrolled deployment artifact set consumed at production bootstrap. This exposes no authority material and cannot install or replace process trust.
- Verified
Service KeyEnrollment - Result of verifying a service-key enrollment attestation: the authenticated hybrid public key for one allowlisted service. This exposes no authority or signing material.
Enums§
- Deployment
Store Init - Outcome of
initialize_deployment_checkpoint_store: whether the store was freshly created or a healthy retained store was reused. Outcome of an explicit deployment checkpoint-store initialization. - Discovery
State Backend - Socket
Kind - Socket type identifier for endpoint registration.
Constants§
- FIRST_
BOOT_ KEY - The first-boot provisioning marker RocksDB key, written by
initialize_deployment_checkpoint_storeand deleted by the registry in the sameWriteBatchas its first accepted-state commit. Re-exported so the app crate’s QUIC startup gate and registry writer can share the exact key. RocksDB key for the first-boot provisioning marker. - SERVICE_
KEY_ ENROLLMENT_ ALLOWED_ SERVICES - Fixed allowlist per hyprstream#1562: registry stays JWT-enrolled and policy-CA/authority keys are out of scope, so exactly these services may be enrolled by a delegated signer.
Traits§
- Authorization
Provider - Trait for pluggable authorization checks.
- Record
Resolver - Trait for resolving atproto records/repos from the node’s local PDS.
- Resolver
- Async endpoint resolver.
Functions§
- authenticate_
local_ deployment_ registry - Authenticate the fixed, OS-owned deployment artifacts for an offline registry provisioning operation using the same role-specific trusted-file loader as startup. Returns verification-only evidence, not a raw-key authority constructor, and does not install a process resolver.
- bootstrap_
deployment_ process - Atomically consume the explicitly selected deployment witness and install the process Discovery resolver. Selection never falls back between the OS-owned and DID-anchored providers.
- bootstrap_
deployment_ process_ with_ ephemeral_ client_ transport - Bootstrap a one-shot client using the same authenticated service identity but a fresh outbound Iroh carrier identity. N0 may publish transient reach for this random carrier, but it cannot overwrite the live service’s stable carrier record. Intended for short-lived diagnostics, never normal services.
- delegation_
capability_ set_ grants_ enrollment - Exact-set capability validation (hyprstream#1562): a delegation is either the legacy registry-only scope minted before enrollment existed, or exactly the registry + enrollment pair. Anything narrower, wider, or reordered is rejected. Returns true when the enrollment capability is present.
- deployment_
registry_ verifier - Read the verification-only identity installed by trusted startup.
- initialize_
deployment_ checkpoint_ store - Create the empty checkpoint store for an explicitly provisioned fresh node, or reuse a healthy retained one. Ordinary resolver startup never calls this, so missing history fails closed.
- installed_
bootstrap_ discovery_ client - The authenticated Discovery client this process’s own bootstrap installed, when bootstrap installed one.
- native_
network_ required - Transport profile selected by authenticated process bootstrap.
- production_
browser_ currentness_ verifier - Return the verifier backed by the same opaque production resolver used for projection. It is installed at the server dispatch boundary; no caller can inject accepted state or a fallback trust source.
- production_
browser_ provisioning - Project a browser/WebTransport provisioning document from the installed checkpoint-backed production resolver. No caller can inject candidates, accepted state, keys, reach, or a fallback resolver through this seam.
- production_
deployment_ roster - The process’s deployment-roster source for #1652 derived admission: enumerates every verified accepted state (with DIDs) so grant derivation can enforce cross-store uniqueness — the one property a per-DID read cannot see. Sourced from the same pinned checkpoint store as the per-DID authority; a read failure yields an empty roster, which denies. Served through a TTL cache: the live-session recheck runs every 100 ms per session and must not re-verify the whole store each time.
- production_
inference_ rpc_ client_ at_ transport - Construct a production RPC client pinned to one router-selected advertised reach while retaining Discovery’s opaque identity/currentness authority.
- production_
moq_ event_ target - Resolve native Event reach and its accepted-current server witness together.
- production_
moql_ accepted_ state_ authority - Project only bounded, valid checkpoint state into the MoQL authority. Every admission and live-session recheck rereads the pinned source.
- production_
rpc_ client - Construct an ordinary production RPC client. Production authority cannot be implemented, injected, or replaced by a downstream caller.
- registry_
mint_ capability - The exact registry-mint capability every delegation must carry.
- resolve_
and_ authenticate_ did_ anchors - Resolve the configured DID anchors and authenticate the fetched registry
deployment credential against the DID-derived deployment CA. This is the
full DID-anchored trust decision — GATE (canon → hash → sig), mutual
alsoKnownAs attestation, credential fetch, and the exact credential profile
(CA-bound kid/iss/domain, one-hour freshness) — WITHOUT the process-global
one-shot seal and resolver install performed by
bootstrap_deployment_process. Exposed so integration tests can exercise the trust decision (and its failure modes) more than once per process. Any failure is terminal for the caller; nothing here retries or downgrades. - service_
key_ enrollment_ capability - The exact service-key-enrollment capability (hyprstream#1562): a fixed allowlist, hybrid-only key type, and a one-hour attestation TTL ceiling.
- validate_
delegation_ ucan - Validate one root-authorized delegation UCAN (hyprstream#1562): a single authority-to-signer link (no proofs), signed by an active authority, addressed to the delegated signer, carrying exactly the registry-mint or the registry + service-key-enrollment capability set, and expiring.
- validate_
registry_ delegation - Validate a delegation artifact against the pinned production root and the installed/current authority log with its independently trusted head (hyprstream#1562 H3).
- verify_
deployment_ artifacts_ with_ authority_ log - Verify any enrolled deployment credential against the public root, the installed/current authority log, and its independently trusted head.
- verify_
deployment_ public_ ca - Parse the exact production public-root pin and return its stable deployment
domain. This is the mint-time half of
verify_deployment_artifacts_with_authority_log. - verify_
genesis_ deployment_ artifacts - Explicitly verify a direct-root credential during one-time genesis before authority-log enrollment. Production startup never calls this function and never infers genesis mode from a missing file.
- verify_
os_ owned_ service_ key_ enrollment - Verify a
hyprstream.service-key-enrollment.v1attestation against this node’s OS-owned deployment trust chain (hyprstream#1562 H3). - verify_
service_ key_ enrollment - Verify a
hyprstream.service-key-enrollment.v1attestation against the public root, the installed/current authority log, and its independently trusted head (hyprstream#1562).