README.md (7694B)
1 # radroots_service_host 2 3 `radroots_service_host` is the unpublished, native host-mechanism crate for 4 Radroots services. It provides narrow, reusable building blocks for validated 5 service identity, deterministic configuration loading, injected time and 6 entropy, lifecycle supervision, permissioned local administration, and cached 7 operations surfaces. 8 9 The crate owns mechanisms only. Service-specific configuration, policy, 10 database schema, domain routes, readiness decisions, process CLI parsing, 11 runtime creation, global logging, and signal installation remain with the 12 consuming service or binary boundary. Authoritative tasks may not be detached, 13 and this crate must not become a broad lifecycle framework. 14 15 All service-host modules are private. Consumers use the deliberate crate-root 16 surface, including its re-exported [`ServiceId`](crate::ServiceId) and 17 [`InstanceId`](crate::InstanceId) identity types. 18 19 The host boundary is governed by the 20 [`services_hardening_host.v1` machine decision](../../contracts/architecture/decisions/services_hardening_host.v1.json). 21 The reviewed Rust surface is recorded in the 22 [public API baseline](../../contracts/api_baselines/radroots_service_host.txt). 23 24 ## Strict configuration values 25 26 Configuration parsing is inert except for the one explicitly selected file. 27 Schema identity is checked before service-owned typed deserialization, and 28 common leaves use strict canonical units: 29 30 ```rust 31 use radroots_service_host::{ 32 BoundedCount, ByteLimit, LoggingFormat, OptionalOperationsBind, 33 PositiveDuration, 34 }; 35 36 let grace: PositiveDuration = "30s".parse()?; 37 let response_limit: ByteLimit = "1MiB".parse()?; 38 let workers = BoundedCount::<64>::new(8)?; 39 let logging: LoggingFormat = "json".parse()?; 40 let operations: OptionalOperationsBind = "127.0.0.1:9100".parse()?; 41 42 assert_eq!(grace.to_string(), "30s"); 43 assert_eq!(response_limit.bytes(), 1_048_576); 44 assert_eq!(workers.value(), 8); 45 assert_eq!(logging.to_string(), "json"); 46 assert!(operations.is_enabled()); 47 # Ok::<(), Box<dyn std::error::Error>>(()) 48 ``` 49 50 An enabled non-loopback operations address does not authorize public binding; 51 conversion to [`OperationsListenerConfig`](crate::OperationsListenerConfig) 52 still requires [`OperationsBindPolicy::Public`](crate::OperationsBindPolicy::Public). 53 Configuration errors redact selected paths and raw parser input from ordinary 54 Display, Debug, and standard error chains. 55 56 ## Cached state and explicit cancellation 57 58 Status and operations reads consume the latest validated cached value. They do 59 not perform an active probe. Cancellation is explicit, cloneable, and 60 directional from parent to child: 61 62 ```rust 63 use radroots_service_host::{ 64 CachedServiceState, CancellationToken, Readiness, ReasonCodes, 65 ServiceOperationalState, ServicePhase, cached_service_state, 66 }; 67 68 let operational = ServiceOperationalState::new( 69 ServicePhase::Ready, 70 Readiness::READY, 71 ReasonCodes::empty(), 72 )?; 73 let (_publisher, reader) = cached_service_state(CachedServiceState::new(operational, ())); 74 assert_eq!(reader.snapshot().operational().phase(), ServicePhase::Ready); 75 76 let parent = CancellationToken::new(); 77 let child = parent.child_token(); 78 parent.cancel(); 79 assert!(child.is_cancelled()); 80 # Ok::<(), radroots_service_host::StatusContractError>(()) 81 ``` 82 83 ## Local administration and operations 84 85 Detailed status and mutations use the bounded HTTP/1.1 Unix administration 86 models and server. Linux admission requires peer credentials; macOS v1 relies 87 on the exact owner-only filesystem posture. The TCP operations server exposes 88 only cached `GET /livez`, `GET /readyz`, and `GET /metrics`; it has no route 89 extension point for detailed status or mutation authority. 90 91 Request and response bodies, headers, queries, connection concurrency, 92 deadlines, task names, metric snapshots, reason collections, and shutdown 93 phases have explicit bounds. Safe Display and ordinary Debug projections 94 exclude raw paths, SQL, credentials, payloads, and provider or relay errors. 95 Where a host error retains an original cause for trusted inspection, that cause 96 is not rendered by its safe projection or ordinary/pretty `Debug`. `HostError` 97 formatting does not invoke the retained cause's formatters; explicit trusted 98 `source()` inspection and downcasting retain the original cause. 99 100 Reason-code iterators and wire arrays stop at the first item beyond their fixed 101 maximum. Administration payloads are traversed directly from the bounded input 102 or streamed directly into the capped response writer; validation does not 103 materialize an intermediate `serde_json::Value` tree. Recursive null rejection 104 and duplicate or unknown field rejection remain fail closed. 105 106 Every bounded text constructor validates borrowed UTF-8 before it creates the 107 retained string. Bounded wire strings use validating Serde visitors, so the 108 host does not create a second prevalidation copy of identifiers, safe messages, 109 reason codes, task names, routes, or metric vocabulary. 110 111 Administration operation and correlation identifiers are closed ASCII values 112 of 1 through 128 bytes. Their first byte is alphanumeric; later bytes are 113 alphanumeric or `.`, `_`, `:`, or `-`. Ordinary `Debug` is redacted and no 114 `Display` implementation exposes the retained value. Trusted protocol code 115 uses the explicit borrowed `as_str` accessor for serialization. 116 117 ## Process and runtime ownership 118 119 The crate does not parse a CLI, read configuration from environment variables, 120 install an operating-system signal handler, initialize tracing, create a Tokio 121 runtime, call `process::exit`, choose service paths, open a service database, 122 or own service-domain policy. Process binaries inject clocks and entropy, 123 normalize signals through [`ProcessSignalAdapter`], register every authoritative 124 task with [`TaskSupervisor`], and execute [`GracefulShutdown`] explicitly. 125 126 Shutdown task cancellation is phase aware. Entering a phase cancels only tasks 127 assigned to that phase and does not advance until their joins are observed; 128 bounded one-shot work drains without cancellation during `DrainOperations`, 129 while a fatal task outcome still 130 cancels and joins the complete graph. `GracefulShutdown` retains one absolute 131 deadline plus the completed handler/drain boundary across cancellation and 132 retry, so no phase or cleanup attempt receives a fresh grace period. A caller- 133 cancelled incomplete handler may be entered again and must be idempotent and 134 cancellation safe. The first phase or task failure is retained while later 135 close phases continue as long as the original deadline remains. 136 137 Bulk and phase supervision retain already joined observations in the supervisor 138 when their wait is cancelled. Retrying bulk supervision includes that prefix 139 and keeps the first fatal outcome; switching to `join_next` returns retained 140 observations first in join order. A completed bulk call consumes its batch and 141 returns either the nonfatal exits or the first fatal failure; `join_next` 142 consumes one observation. Phased shutdown retains its fatal result while 143 continuing the remaining close phases. Forced abort-and-drain joins remaining tasks and 144 preserves unconsumed observations for a later explicit read. `task_count` and 145 `is_empty` describe tasks that have not yet been joined, so an empty supervisor 146 can still have retained observations. 147 148 ## Supported targets and publication 149 150 The generic host/config/status/lifecycle surfaces support the workspace's 151 qualified Rust targets. Unix administration and its client/server are exported 152 only on Linux and macOS. Linux peer credentials are required and fail closed; 153 macOS makes no peer-credential equivalence claim. 154 155 Publication is disabled. The package is not part of the public Radroots crate 156 release closure.