hyprstream_discovery/lib.rs
1//! Service discovery and endpoint resolution for hyprstream.
2//!
3//! This crate provides the `DiscoveryService` — the authoritative source
4//! for service endpoint resolution in a hyprstream cluster. It wraps
5//! the `EndpointRegistry` from `hyprstream-rpc` and exposes it as both
6//! a local `Resolver` implementation and a Cap'n Proto RPC service.
7//!
8//! # Architecture
9//!
10//! ```text
11//! hyprstream-rpc trait Resolver + SocketKind + EndpointRegistry
12//! ↑
13//! hyprstream-discovery DiscoveryService (wraps registry, serves RPC)
14//! ↑
15//! hyprstream factory creates DiscoveryService, injects AuthorizationProvider
16//! ```
17
18extern crate self as hyprstream_discovery;
19
20// Re-export shared capnp modules so generated code's `crate::*_capnp` resolves
21pub use hyprstream_rpc::annotations_capnp;
22pub use hyprstream_rpc::common_capnp;
23
24// Canonical Cap'n Proto code is generated by the Apache-2.0 contract crate.
25
26// Generated RPC service code. The canonical contract crate owns all public
27// clients/data; this module exposes only AGPL server dispatch helpers.
28pub mod generated {
29 pub mod discovery_client {
30 #![allow(dead_code, unused_imports, unused_variables)]
31 #![allow(clippy::all)]
32 hyprstream_rpc_derive::generate_rpc_server!(
33 "discovery",
34 types_crate = hyprstream_rpc_std,
35 scope_handlers,
36 );
37 }
38}
39
40mod service;
41mod state_store;
42pub use state_store::{
43 DiscoveryState, DiscoveryStateBackend, DiscoveryStateConfig, MemoryStateConfig,
44 TieredStateConfig, ValkeyStateConfig,
45};
46// The checkpointed PDS store reads its accepted-state authority from the
47// local RocksDB store (`rocksdb` feature) or the networked RDS Postgres store
48// (`postgres` feature, selected by the resolved `[rds]` binding at bootstrap).
49// Both dependencies stay target-gated to non-wasm32.
50#[cfg(all(
51 any(feature = "rocksdb", feature = "postgres"),
52 not(target_arch = "wasm32")
53))]
54mod checkpointed_pds;
55
56/// Create the empty checkpoint store for an explicitly provisioned fresh
57/// node, or reuse a healthy retained one. Ordinary resolver startup never
58/// calls this, so missing history fails closed.
59///
60/// Reboot-idempotent: a retained store that opens and reads back cleanly is
61/// reported as [`DeploymentStoreInit::Reused`] without any write; invalid
62/// retained state (garbage, empty directory, unreadable store) fails closed.
63#[cfg(all(feature = "rocksdb", not(target_arch = "wasm32")))]
64pub fn initialize_deployment_checkpoint_store() -> anyhow::Result<DeploymentStoreInit> {
65 checkpointed_pds::initialize_deployment_store()
66}
67
68/// Outcome of [`initialize_deployment_checkpoint_store`]: whether the store
69/// was freshly created or a healthy retained store was reused.
70#[cfg(all(feature = "rocksdb", not(target_arch = "wasm32")))]
71pub use checkpointed_pds::DeploymentStoreInit;
72
73/// The first-boot provisioning marker RocksDB key, written by
74/// [`initialize_deployment_checkpoint_store`] and deleted by the registry in
75/// the same `WriteBatch` as its first accepted-state commit. Re-exported so
76/// the app crate's QUIC startup gate and registry writer can share the exact
77/// key.
78#[cfg(all(feature = "rocksdb", not(target_arch = "wasm32")))]
79pub use checkpointed_pds::FIRST_BOOT_KEY;
80
81/// #893 (at9p D1) — `did:at9p` capsule resolver: turns a GATE-verified capsule
82/// into a dialable `TransportConfig::iroh` (sibling to
83/// `hyprstream_rpc::service_entry::decode_iroh`). Injectable at the
84/// `Resolver::set_global` / network-profile resolver seam (#873).
85pub mod at9p_resolver;
86
87/// #1652 — derived native admission roster: deployment service identities
88/// (and their `local` tenant) resolved from the live accepted-state store at
89/// admission time, replacing the DID-valued `quic.moql_subject_tenants` map.
90pub mod admission_roster;
91
92/// #896 (at9p D4) — `did:web` / `did:key` → `did:at9p` aliasing resolver:
93/// resolves a classical DID to its authoritative `did:at9p` identity via mutual
94/// `alsoKnownAs` attestation + the GATE pipeline. Sibling to `at9p_resolver`.
95pub mod at9p_alias;
96
97/// #1136 — explicit DID-anchored deployment trust source. Resolves the public
98/// `(did:at9p, did:web)` pin pair without weakening the OS-owned-file source.
99#[cfg(not(target_arch = "wasm32"))]
100pub mod did_anchored;
101
102/// #1167 — canonical, append-only, hash-chained DID operation log.
103///
104/// Defines the genesis/rotation wire format and its pinned-Hybrid
105/// (Ed25519 + ML-DSA-65) fail-closed verifier. Kept separate from DID
106/// resolution and anchored-DID policy.
107pub mod did_op;
108
109/// #1342 A — operable Hybrid `did:plc` directory.
110///
111/// Adds authority-bound genesis registration and verified/live resolution
112/// without adding a write path to the federated PLC resolver.
113pub mod plc_directory;
114
115/// #524 P1 — placement directory record ingestion + in-process index.
116///
117/// Polls `RecordResolver::resolve_repo` for a bootstrap set of node DIDs,
118/// walks the returned CAR's MST, and decodes `ai.hyprstream.placement.*`
119/// records (node / workload / group / groupItem) into a queryable index:
120/// label-selector evaluation, resource matching, and bidirectional-consent
121/// group membership. Consumed by `handle_query_candidates`.
122pub mod placement_index;
123
124/// #523 P0 / #524 / #628 — Scheduling Substrate.
125///
126/// The shared `LabelSelector` / `ResourceRequest` / `PlacementCandidate`
127/// vocabulary + a small `filter → rank → select` helper + one `SelectionReport`
128/// explain shape + a `CapabilitySource` contract, so every scheduling surface
129/// (placement `queryCandidates`, the `SandboxPool` engine, `CellRouter` routing,
130/// backend `selection.rs`) composes without duplicating filter/rank/explain
131/// logic or capability truth.
132///
133/// **Not a framework**: free functions + plain types. See the module doc.
134pub mod scheduling;
135
136/// K4c (#787) — the placement→PodSpec vocabulary map (`k8s` feature).
137///
138/// Pure translation of a placement decision (in the [`scheduling`] substrate
139/// vocabulary) into the Kubernetes `PodSpec` scheduling fields — `nodeSelector`
140/// / `affinity` / `tolerations` / `resources` / `priorityClassName`. The
141/// two-level-scheduling seam: hyprstream decides *what runs with what
142/// constraints*, Kubernetes decides *which node*. No cluster, no kube client.
143#[cfg(feature = "k8s")]
144pub mod podspec;
145
146// Re-export key types
147#[cfg(not(target_arch = "wasm32"))]
148pub use did_anchored::{
149 verify_anchor_material, DeploymentTrustSource, DidAnchors, VerifiedAnchorMaterial,
150};
151pub use hyprstream_rpc::registry::SocketKind;
152pub use hyprstream_rpc::resolver::Resolver;
153pub use plc_directory::{
154 ConnectTimeDiscovery, DidOpSuccessorWitness, InMemoryPlcDirectoryStore, LivePlcDiscovery,
155 PlcDirectory, PlcDirectoryRecord, PlcDirectoryStore, ResolvedPlcIdentity,
156 SignedPlcDirectoryGenesis,
157};
158#[cfg(feature = "test-fixtures")]
159#[doc(hidden)]
160pub use service::test_fixtures::{
161 install_bootstrap_discovery_client_fixture, install_production_inference_fixture,
162 ProductionInferenceFixture,
163};
164pub use service::{
165 authenticate_local_deployment_registry, bootstrap_deployment_process,
166 bootstrap_deployment_process_with_ephemeral_client_transport,
167 delegation_capability_set_grants_enrollment, deployment_registry_verifier,
168 installed_bootstrap_discovery_client, native_network_required,
169 production_browser_currentness_verifier, production_browser_provisioning,
170 production_deployment_roster, production_inference_rpc_client_at_transport,
171 production_moq_event_target, production_moql_accepted_state_authority, production_rpc_client,
172 registry_mint_capability, resolve_and_authenticate_did_anchors,
173 service_key_enrollment_capability, validate_delegation_ucan, validate_registry_delegation,
174 verify_deployment_artifacts_with_authority_log, verify_deployment_public_ca,
175 verify_genesis_deployment_artifacts, verify_os_owned_service_key_enrollment,
176 verify_service_key_enrollment, AuthorizationProvider, DeploymentAuthorityCheckpoint,
177 DeploymentAuthorityLog, DiscoverySelfAnnouncer, DiscoveryService, RecordCarData,
178 RecordResolver, RegistryDelegationArtifact, RegistryDeploymentVerifier,
179 ServiceKeyEnrollmentArtifact, ServiceKeyEnrollmentSigningBody, ValidatedDelegation,
180 VerifiedDeploymentArtifacts, VerifiedServiceKeyEnrollment,
181 SERVICE_KEY_ENROLLMENT_ALLOWED_SERVICES,
182};
183
184/// Production client-construction adapter for the portable `rpc-std` clients.
185///
186/// The adapter lives in this AGPL implementation crate because resolver
187/// authority/evidence is deployment policy. Third-party applications can
188/// provide their own `RpcClientProvider` without depending on Discovery.
189#[derive(Clone, Copy, Debug, Default)]
190pub struct ProductionRpcClientProvider;
191
192impl hyprstream_rpc::RpcClientProvider for ProductionRpcClientProvider {
193 fn rpc_client(
194 &self,
195 service_name: &str,
196 signing_key: hyprstream_rpc::crypto::SigningKey,
197 token: Option<String>,
198 ) -> anyhow::Result<std::sync::Arc<dyn hyprstream_rpc::RpcClient>> {
199 service::production_rpc_client(service_name, signing_key, token)
200 }
201}
202
203#[cfg(test)]
204#[allow(clippy::expect_used, clippy::unwrap_used)]
205mod did_field_domain_type_tests {
206 use hyprstream_rpc::identity::Did;
207 use hyprstream_rpc::{serialize_message, FromCapnp, ToCapnp};
208 use hyprstream_rpc_std::discovery_capnp;
209 use hyprstream_rpc_std::discovery_client::{EnvelopeKeyset, RegisterEnvelopeKeysetRequest};
210
211 /// Field-level `$domainType("hyprstream_rpc::identity::Did")` on
212 /// `EnvelopeKeyset.serviceDid` must generate a `Did` newtype field (not `String`),
213 /// and the value must round-trip through the capnp wire (which stays `Text`).
214 #[test]
215 fn envelope_keyset_service_did_is_did_and_roundtrips() {
216 let original = EnvelopeKeyset {
217 service_did: Did::new("did:web:registry.example".to_owned()),
218 cose_keyset_cbor: vec![1, 2, 3, 4],
219 fetched_at: 1234,
220 };
221 // Type-level proof: the codegen emitted a `Did` field, not a `String`.
222 let _typecheck: &Did = &original.service_did;
223
224 let bytes = serialize_message(|msg| {
225 let mut b = msg.init_root::<discovery_capnp::envelope_keyset::Builder>();
226 original.write_to(&mut b);
227 })
228 .expect("serialize");
229
230 let reader =
231 capnp::serialize::read_message(&mut &bytes[..], capnp::message::ReaderOptions::new())
232 .expect("read message");
233 let root = reader
234 .get_root::<discovery_capnp::envelope_keyset::Reader>()
235 .expect("root reader");
236 let back = EnvelopeKeyset::read_from(root).expect("read_from");
237
238 assert_eq!(back.service_did, original.service_did);
239 assert_eq!(back.service_did.as_str(), "did:web:registry.example");
240 assert!(back.service_did.is_did_web());
241 assert_eq!(back.cose_keyset_cbor, vec![1, 2, 3, 4]);
242 assert_eq!(back.fetched_at, 1234);
243 }
244
245 /// Same for the request struct's `serviceDid` field.
246 #[test]
247 fn register_envelope_keyset_request_service_did_roundtrips() {
248 let original = RegisterEnvelopeKeysetRequest {
249 service_did: Did::new("did:key:z6Mkexample".to_owned()),
250 cose_keyset_cbor: vec![9, 9, 9],
251 };
252 let _typecheck: &Did = &original.service_did;
253
254 let bytes = serialize_message(|msg| {
255 let mut b =
256 msg.init_root::<discovery_capnp::register_envelope_keyset_request::Builder>();
257 original.write_to(&mut b);
258 })
259 .expect("serialize");
260
261 let reader =
262 capnp::serialize::read_message(&mut &bytes[..], capnp::message::ReaderOptions::new())
263 .expect("read message");
264 let root = reader
265 .get_root::<discovery_capnp::register_envelope_keyset_request::Reader>()
266 .expect("root reader");
267 let back = RegisterEnvelopeKeysetRequest::read_from(root).expect("read_from");
268
269 assert_eq!(back.service_did.as_str(), "did:key:z6Mkexample");
270 assert!(back.service_did.is_did_key());
271 }
272}