feat(core): deliver request-lifecycle P0 scaffolding (#227)

Thread a single RequestContext end-to-end through dispatch_pipeline
(forwarded from all 5 ingress shells, dropping the per-target throwaway
context) and add a type-keyed ContextBag scratch space. Introduce a
read-only PluginKernel aggregating the Hook/Vendor/Protocol registries.

Also add the lifecycle and observability design RFCs. Behaviour unchanged;
check/clippy/test all green.

Author: shuaijinchao

crates/nyro-core/src/lib.rs

@@ -5,6 +5,7 @@ pub mod db;
 pub mod error;
 pub mod integrations;
 pub mod logging;
+pub mod plugin;
 pub mod protocol;
 pub mod provider;
 pub mod proxy;

crates/nyro-core/src/plugin/mod.rs

@@ -0,0 +1,151 @@
+//! Unified extension kernel (P0 scaffolding for the request-lifecycle RFC).
+//!
+//! Nyro already has several compile-time, `inventory`-based registries that act
+//! as implicit plugin systems:
+//!
+//! - [`HookRegistry`] — request/response integration hooks.
+//! - [`VendorRegistry`] — provider vendor presets / adapters.
+//! - [`ProtocolRegistry`] — protocol endpoint handlers.
+//!
+//! [`PluginKernel`] is a thin, **read-only** façade that aggregates those
+//! registries behind one entry point. It does not own or replace them; it only
+//! offers a single place for future phases (`PhaseHook`, capabilities) and admin
+//! tooling to enumerate "what is loaded". Introducing it now is purely additive
+//! and changes no runtime behaviour.
+//!
+//! See `docs/design/lifecycle.md` for the full framework design.
+
+use std::sync::OnceLock;
+
+use crate::integrations::HookRegistry;
+use crate::protocol::registry::ProtocolRegistry;
+use crate::provider::VendorRegistry;
+
+/// The kind of extension capability a manifest entry represents.
+///
+/// Mirrors the capability taxonomy in the lifecycle RFC. Only the
+/// already-existing capabilities are surfaced today; `PhaseHook` /
+/// `TelemetryExporter` slots are reserved for later phases.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CapabilityKind {
+    /// A request-phase integration hook ([`crate::integrations::RequestHook`]).
+    RequestHook,
+    /// A response-phase integration hook ([`crate::integrations::ResponseHook`]).
+    ResponseHook,
+    /// A provider vendor preset/adapter.
+    ProviderVendor,
+    /// A protocol endpoint handler.
+    ProtocolEndpoint,
+}
+
+impl CapabilityKind {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            CapabilityKind::RequestHook => "request_hook",
+            CapabilityKind::ResponseHook => "response_hook",
+            CapabilityKind::ProviderVendor => "provider_vendor",
+            CapabilityKind::ProtocolEndpoint => "protocol_endpoint",
+        }
+    }
+}
+
+/// A read-only description of one loaded extension.
+#[derive(Debug, Clone)]
+pub struct PluginManifest {
+    /// Stable identifier of the extension (hook name / vendor id / protocol id).
+    pub id: String,
+    /// Which capability slot this extension occupies.
+    pub capability: CapabilityKind,
+}
+
+/// Aggregated, read-only view over Nyro's compile-time extension registries.
+///
+/// Cheap to build (it only borrows the global registries) and cached as a
+/// process-wide singleton via [`PluginKernel::global`].
+pub struct PluginKernel {
+    hooks: &'static HookRegistry,
+    vendors: &'static VendorRegistry,
+    protocols: &'static ProtocolRegistry,
+}
+
+impl PluginKernel {
+    /// Process-wide kernel singleton.
+    pub fn global() -> &'static PluginKernel {
+        static KERNEL: OnceLock<PluginKernel> = OnceLock::new();
+        KERNEL.get_or_init(|| PluginKernel {
+            hooks: HookRegistry::global(),
+            vendors: VendorRegistry::global(),
+            protocols: ProtocolRegistry::global(),
+        })
+    }
+
+    /// Enumerate every loaded extension across all registries.
+    pub fn manifests(&self) -> Vec<PluginManifest> {
+        let mut out = Vec::new();
+
+        for hook in self.hooks.request_hooks() {
+            out.push(PluginManifest {
+                id: hook.name().to_string(),
+                capability: CapabilityKind::RequestHook,
+            });
+        }
+        for hook in self.hooks.response_hooks() {
+            out.push(PluginManifest {
+                id: hook.name().to_string(),
+                capability: CapabilityKind::ResponseHook,
+            });
+        }
+        for vendor in self.vendors.list_metadata() {
+            out.push(PluginManifest {
+                id: vendor.id.to_string(),
+                capability: CapabilityKind::ProviderVendor,
+            });
+        }
+        for handler in self.protocols.list() {
+            out.push(PluginManifest {
+                id: handler.id().to_string(),
+                capability: CapabilityKind::ProtocolEndpoint,
+            });
+        }
+
+        out
+    }
+
+    /// Manifests filtered to a single capability kind.
+    pub fn manifests_of(&self, kind: CapabilityKind) -> Vec<PluginManifest> {
+        self.manifests()
+            .into_iter()
+            .filter(|m| m.capability == kind)
+            .collect()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn kernel_aggregates_builtin_extensions() {
+        let kernel = PluginKernel::global();
+        let manifests = kernel.manifests();
+
+        // Built-in protocol endpoints and vendor presets are always registered,
+        // so the aggregated view must never be empty.
+        assert!(
+            !manifests.is_empty(),
+            "expected built-in extensions to be registered"
+        );
+        assert!(
+            !kernel
+                .manifests_of(CapabilityKind::ProtocolEndpoint)
+                .is_empty(),
+            "expected at least one protocol endpoint"
+        );
+        assert!(
+            !kernel
+                .manifests_of(CapabilityKind::ProviderVendor)
+                .is_empty(),
+            "expected at least one provider vendor"
+        );
+    }
+}

crates/nyro-core/src/proxy/context.rs

@@ -14,6 +14,8 @@
 //! - **Protocol / routing fields** – filled in progressively as the request
 //!   moves through `intake → security → planner → dispatcher`.
 
+use std::any::{Any, TypeId};
+use std::collections::HashMap;
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex, OnceLock};
 use std::time::{Duration, Instant};
@@ -184,6 +186,54 @@ impl Default for TraceSink {
     }
 }
 
+// ── ContextBag ──────────────────────────────────────────────────────────────────
+
+/// Type-keyed, request-scoped scratch space shared across all phases (Nyro's
+/// equivalent of OpenResty `ngx.ctx`). Values are keyed by their concrete type,
+/// so producers and consumers agree by type rather than stringly-typed keys.
+///
+/// The bag is shared across `RequestContext` clones (like `outcome` / `trace`)
+/// so a value inserted in one phase is visible to later phases.  `get` returns a
+/// clone to avoid borrowing through the internal lock.
+#[derive(Clone, Default)]
+pub struct ContextBag(Arc<Mutex<HashMap<TypeId, Box<dyn Any + Send + Sync>>>>);
+
+impl ContextBag {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Insert (or replace) the value stored for type `T`.
+    pub fn insert<T: Any + Send + Sync>(&self, value: T) {
+        if let Ok(mut guard) = self.0.lock() {
+            guard.insert(TypeId::of::<T>(), Box::new(value));
+        }
+    }
+
+    /// Fetch a clone of the value stored for type `T`, if present.
+    pub fn get<T: Any + Send + Sync + Clone>(&self) -> Option<T> {
+        self.0
+            .lock()
+            .ok()
+            .and_then(|guard| guard.get(&TypeId::of::<T>())?.downcast_ref::<T>().cloned())
+    }
+
+    /// Returns `true` if a value of type `T` is present.
+    pub fn contains<T: Any + Send + Sync>(&self) -> bool {
+        self.0
+            .lock()
+            .map(|guard| guard.contains_key(&TypeId::of::<T>()))
+            .unwrap_or(false)
+    }
+}
+
+impl std::fmt::Debug for ContextBag {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let len = self.0.lock().map(|g| g.len()).unwrap_or(0);
+        f.debug_struct("ContextBag").field("len", &len).finish()
+    }
+}
+
 // ── RequestContext ────────────────────────────────────────────────────────────
 
 /// Unified per-request context.  Stored in `axum::Extension` and cloned into
@@ -221,6 +271,9 @@ pub struct RequestContext {
     pub outcome: Arc<OnceLock<RequestOutcome>>,
     /// Lightweight trace log.
     pub trace: TraceSink,
+    /// Type-keyed request-scoped scratch space (Nyro's `ngx.ctx`), shared
+    /// across clones and visible to every pipeline phase.
+    pub extensions: ContextBag,
 }
 
 impl RequestContext {
@@ -239,6 +292,7 @@ impl RequestContext {
             auth_subject: None,
             outcome: Arc::new(OnceLock::new()),
             trace: TraceSink::new(),
+            extensions: ContextBag::new(),
         }
     }
 

crates/nyro-core/src/proxy/dispatcher/mod.rs

@@ -71,6 +71,7 @@ pub async fn dispatch_pipeline(
     envelope: RawEnvelope,
     request: AiRequest,
     ingress: ProtocolId,
+    mut ctx: RequestContext,
 ) -> Response {
     // Derive logging strings from envelope.
     let method_owned = envelope.method.clone();
@@ -224,9 +225,11 @@ pub async fn dispatch_pipeline(
         };
 
         // Resolve egress protocol + base URL via negotiate().
+        // The request-scoped `ctx` is threaded end-to-end from the ingress
+        // middleware (no per-target throwaway context); negotiate records its
+        // trace/egress decision onto it.
         let provider_protocols = ProviderProtocols::from_provider(&provider);
-        let mut req_ctx = RequestContext::new(ingress, std::time::Duration::from_secs(30));
-        let plan = match negotiate(ingress, None, Some(&provider_protocols), &mut req_ctx) {
+        let plan = match negotiate(ingress, None, Some(&provider_protocols), &mut ctx) {
             Ok(p) => p,
             Err(e) => {
                 last_response = Some(e.render(None));
@@ -438,7 +441,7 @@ pub async fn dispatch(
     ingress: ProtocolId,
     method: &'static str,
     path: &'static str,
-    _ctx: &mut RequestContext,
+    ctx: &mut RequestContext,
 ) -> Response {
     let flat_headers: std::collections::HashMap<String, String> = headers
         .iter()
@@ -456,7 +459,7 @@ pub async fn dispatch(
         Err(e) => return log_decode_error(&gw, &envelope, ingress, e),
     };
 
-    dispatch_pipeline(gw, headers, envelope, request, ingress).await
+    dispatch_pipeline(gw, headers, envelope, request, ingress, ctx.clone()).await
 }
 
 // ── Handler context types ─────────────────────────────────────────────────────
@@ -914,6 +917,10 @@ mod tests {
             envelope,
             request,
             OPENAI_COMPATIBLE_CHAT_COMPLETIONS_V1,
+            crate::proxy::context::RequestContext::new(
+                OPENAI_COMPATIBLE_CHAT_COMPLETIONS_V1,
+                std::time::Duration::from_secs(30),
+            ),
         )
         .await;
 

crates/nyro-core/src/proxy/ingress/anthropic_messages/messages.rs

@@ -41,6 +41,7 @@ pub async fn handler(
         envelope,
         request,
         ANTHROPIC_MESSAGES_2023_06_01,
+        ctx.0,
     )
     .await
 }

crates/nyro-core/src/proxy/ingress/google_generative/generate_content.rs

@@ -57,6 +57,7 @@ pub async fn handler(
         envelope,
         request,
         GOOGLE_GEMINI_GENERATE_CONTENT_V1BETA,
+        ctx.0,
     )
     .await
 }

crates/nyro-core/src/proxy/ingress/openai_compatible/chat_completions.rs

@@ -48,6 +48,7 @@ pub async fn handler(
         envelope,
         request,
         OPENAI_COMPATIBLE_CHAT_COMPLETIONS_V1,
+        ctx.0,
     )
     .await
 }

crates/nyro-core/src/proxy/ingress/openai_compatible/embeddings.rs

@@ -41,6 +41,7 @@ pub async fn handler(
         envelope,
         request,
         OPENAI_COMPATIBLE_EMBEDDINGS_V1,
+        ctx.0,
     )
     .await
 }

crates/nyro-core/src/proxy/ingress/openai_responses/responses.rs

@@ -33,5 +33,5 @@ pub async fn handler(
         Ok(r) => r,
         Err(e) => return log_decode_error(&gw, &envelope, OPENAI_RESPONSES_V1, e),
     };
-    dispatch_pipeline(gw, headers, envelope, request, OPENAI_RESPONSES_V1).await
+    dispatch_pipeline(gw, headers, envelope, request, OPENAI_RESPONSES_V1, ctx.0).await
 }