arcly_http/core/

engine.rs

//! Lock-free DI engine + macro registration descriptors.
//!
//! Two-phase lifecycle:
//!
//! 1. **Boot.** `DiContainerBuilder` collects [`ProviderDescriptor`]s emitted
//!    by `#[Injectable]` / `#[Module]`. It topologically sorts them by
//!    `TypeId` dependency edges, detects cycles deterministically, then
//!    invokes each provider's `build` function in dependency order. The
//!    build function receives a `Resolver` view of already-constructed
//!    singletons.
//!
//! 2. **Run.** The container is `Box::leak`-ed to `&'static FrozenDiContainer`.
//!    Every subsequent read is a single `HashMap::get` + downcast, both
//!    inlined. Zero locks, zero allocations on the request path.

use std::any::{Any, TypeId};
use std::collections::HashMap;
use std::sync::Arc;

pub type AnyProvider = Arc<dyn Any + Send + Sync>;

/// Build-time resolver passed to each provider's `build` fn. Returns the
/// already-constructed dependency by `TypeId`. Panics if a dependency hasn't
/// been built yet — topological order guarantees this can't happen for a
/// well-formed graph.
pub struct Resolver<'a> {
    map: &'a HashMap<TypeId, AnyProvider>,
}

impl<'a> Resolver<'a> {
    /// Look up a raw provider by `TypeId`. Hidden from user-facing docs; prefer
    /// the typed `get<T>()` accessor.
    #[doc(hidden)]
    #[inline]
    pub fn get_any(&self, ty: TypeId) -> Option<&'a AnyProvider> {
        self.map.get(&ty)
    }

    /// Resolve a singleton by type, extending its lifetime to `'static`.
    ///
    /// # Safety (invariant that must hold at every call site)
    ///
    /// This method is only sound when the `FrozenDiContainer` that owns the
    /// backing `Arc<dyn Any>` allocations has been produced by `freeze()` **and
    /// then immediately `Box::leak`-ed to `&'static`**.  In that case all `Arc`
    /// allocations live for the entire process lifetime, making the lifetime
    /// extension a no-op in practice.
    ///
    /// Calling this through a `Resolver` obtained from a stack-allocated or
    /// `Arc`-wrapped `FrozenDiContainer` produces dangling `&'static T`
    /// references and is **undefined behaviour**.  The method is `#[doc(hidden)]`
    /// to prevent accidental use outside of macro-generated `__arcly_build` fns,
    /// which are the only legitimate callers.
    #[doc(hidden)]
    #[inline]
    pub fn get<T: Send + Sync + 'static>(&self) -> &'static T {
        let r: &T = self
            .map
            .get(&TypeId::of::<T>())
            .and_then(|a| a.downcast_ref::<T>())
            .expect("Arcly DI: dependency requested by a provider was not in the resolved set");
        // SAFETY: see doc comment above. Every singleton is Box::leak'd in
        // freeze() → the Arc allocation lives for the process lifetime → the
        // borrow extension cannot dangle.
        unsafe { std::mem::transmute::<&T, &'static T>(r) }
    }
}

/// One row in the dependency graph.
///
/// `deps_fn` returns the declared dependency `TypeId`s. (We use a function
/// pointer rather than a `&'static [TypeId]` because `TypeId::of` is not
/// const on stable.)
pub struct ProviderDescriptor {
    pub name: &'static str,
    pub type_id_fn: fn() -> TypeId,
    pub deps_fn: fn() -> Vec<TypeId>,
    pub build: fn(&Resolver<'_>) -> AnyProvider,
}

/// Emitted by `#[Module]`. Owns its providers, the controllers it exposes,
/// and the imports it pulls in. Used to walk the module DAG at boot.
pub struct ModuleDescriptor {
    pub name: &'static str,
    pub providers: &'static [&'static ProviderDescriptor],
    /// Names of controllers (type idents) belonging to this module. Routes
    /// emitted under these controllers are eligible to mount when this
    /// module is reachable from the root.
    pub controllers: &'static [&'static str],
    /// Submodules to walk transitively. Empty array means "leaf module".
    pub imports: &'static [fn() -> &'static ModuleDescriptor],
    /// Names of real-time gateways (type idents) belonging to this module.
    /// Gateways emitted under these names mount their WebSocket route only
    /// when the owning module is reachable from the root — same encapsulation
    /// rule as controllers.
    pub gateways: &'static [&'static str],
}

/// Implemented by every `#[Module]`-annotated struct so `App::launch::<RootMod>`
/// can find the entry point without a runtime registry lookup.
pub trait Module: 'static {
    fn descriptor() -> &'static ModuleDescriptor;
}

/// Mutable builder used only during boot.
#[derive(Default)]
pub struct DiContainerBuilder {
    providers: Vec<&'static ProviderDescriptor>,
    /// Direct-registered singletons (legacy / hand-wired). Always treated as
    /// dep-less and appended at the front of the build order.
    direct: HashMap<TypeId, AnyProvider>,
}

impl DiContainerBuilder {
    pub fn new() -> Self {
        Self::default()
    }

    /// Register a fully-constructed singleton. Useful for primitives and
    /// configuration values that aren't `#[Injectable]`.
    #[inline]
    pub fn register<T: Send + Sync + 'static>(&mut self, v: T) -> &mut Self {
        self.direct.insert(TypeId::of::<T>(), Arc::new(v));
        self
    }

    /// Register a provider descriptor (emitted by `#[Injectable]`).
    #[inline]
    pub fn add_provider(&mut self, d: &'static ProviderDescriptor) -> &mut Self {
        self.providers.push(d);
        self
    }

    /// Run topological sort, detect cycles, build providers in dependency
    /// order, then leak as `&'static`.
    pub fn freeze(self) -> &'static FrozenDiContainer {
        let order = Self::topo_sort(&self.providers, &self.direct);

        let mut map: HashMap<TypeId, AnyProvider> = self.direct;
        for d in order {
            let resolver = Resolver { map: &map };
            let instance = (d.build)(&resolver);
            map.insert((d.type_id_fn)(), instance);
        }

        Box::leak(Box::new(FrozenDiContainer { map }))
    }

    /// Kahn's algorithm with deterministic ordering for stable build traces.
    fn topo_sort(
        providers: &[&'static ProviderDescriptor],
        direct: &HashMap<TypeId, AnyProvider>,
    ) -> Vec<&'static ProviderDescriptor> {
        use std::collections::VecDeque;

        // Index providers by their produced TypeId.
        let mut by_ty: HashMap<TypeId, &'static ProviderDescriptor> = HashMap::new();
        for p in providers {
            let prev = by_ty.insert((p.type_id_fn)(), *p);
            if prev.is_some() {
                panic!("Arcly DI: provider for `{}` registered twice", p.name);
            }
        }

        // Compute in-degree: number of deps that are themselves providers.
        // Deps satisfied by direct-registered singletons are free.
        let mut indeg: HashMap<TypeId, usize> = HashMap::new();
        let mut adj: HashMap<TypeId, Vec<TypeId>> = HashMap::new();
        for p in providers {
            let ty = (p.type_id_fn)();
            let mut d = 0usize;
            for dep in (p.deps_fn)() {
                if by_ty.contains_key(&dep) {
                    d += 1;
                    adj.entry(dep).or_default().push(ty);
                } else if direct.contains_key(&dep) {
                    // satisfied by direct singleton — no edge
                } else {
                    panic!(
                        "Arcly DI: provider `{}` depends on type `{:?}` which has no registered provider",
                        p.name, dep
                    );
                }
            }
            indeg.insert(ty, d);
        }

        let mut q: VecDeque<TypeId> = indeg
            .iter()
            .filter_map(|(k, &v)| (v == 0).then_some(*k))
            .collect();
        let mut order: Vec<&'static ProviderDescriptor> = Vec::with_capacity(providers.len());

        while let Some(ty) = q.pop_front() {
            order.push(by_ty[&ty]);
            if let Some(children) = adj.get(&ty) {
                for c in children {
                    let e = indeg.get_mut(c).unwrap();
                    *e -= 1;
                    if *e == 0 {
                        q.push_back(*c);
                    }
                }
            }
        }

        if order.len() != providers.len() {
            let unresolved: Vec<&'static str> = providers
                .iter()
                .filter(|p| !order.iter().any(|q| (q.type_id_fn)() == (p.type_id_fn)()))
                .map(|p| p.name)
                .collect();
            panic!("Arcly DI: dependency cycle detected. Unresolved providers: {unresolved:?}");
        }
        order
    }
}

/// Immutable, lock-free DI container. Reads are O(1) and inlined.
pub struct FrozenDiContainer {
    map: HashMap<TypeId, AnyProvider>,
}

impl FrozenDiContainer {
    #[inline(always)]
    pub fn get<T: Send + Sync + 'static>(&self) -> &T {
        self.map
            .get(&TypeId::of::<T>())
            .and_then(|a| a.downcast_ref::<T>())
            .expect("Arcly DI: missing provider")
    }

    /// Non-panicking variant. Returns `None` when the type has not been provided.
    /// Used in `boundary.rs` to skip JWT decoding when no `JwtService` is registered.
    #[inline]
    pub fn try_get<T: Send + Sync + 'static>(&self) -> Option<&T> {
        self.map
            .get(&TypeId::of::<T>())
            .and_then(|a| a.downcast_ref::<T>())
    }

    /// Produce a borrowing [`Resolver`] view over the frozen singleton set.
    ///
    /// # Safety (invariant)
    ///
    /// `Resolver::get<T>` extends borrows to `'static` under the assumption that
    /// `self` has been `Box::leak`-ed (i.e. produced by `freeze()` and never
    /// dropped).  Only macro-generated `__arcly_build` functions call this; it
    /// is `#[doc(hidden)]` to prevent accidental use from application code.
    #[doc(hidden)]
    #[inline]
    pub fn resolver(&self) -> Resolver<'_> {
        Resolver { map: &self.map }
    }
}

// ─── HTTP method + route descriptors (unchanged shape) ───────────────────

#[derive(Clone, Copy, Debug)]
pub enum HttpMethod {
    GET,
    POST,
    PUT,
    DELETE,
    PATCH,
}

impl From<HttpMethod> for axum::http::Method {
    #[inline]
    fn from(m: HttpMethod) -> Self {
        match m {
            HttpMethod::GET => axum::http::Method::GET,
            HttpMethod::POST => axum::http::Method::POST,
            HttpMethod::PUT => axum::http::Method::PUT,
            HttpMethod::DELETE => axum::http::Method::DELETE,
            HttpMethod::PATCH => axum::http::Method::PATCH,
        }
    }
}

#[derive(Clone, Copy, Debug)]
pub enum ParamLoc {
    Path,
    Query,
    Header,
}

pub struct ParamSpec {
    pub name: &'static str,
    pub loc: ParamLoc,
    pub required: bool,
    pub schema: fn() -> serde_json::Value,
}

pub struct RouteSpec {
    pub summary: &'static str,
    pub description: &'static str,
    pub operation_id: &'static str,
    pub tags: &'static [&'static str],
    pub security: &'static [&'static str],
    pub status_code: Option<u16>,
    pub deprecated: bool,
    pub params: &'static [ParamSpec],
    pub has_body: bool,
    pub body_schema: Option<fn() -> serde_json::Value>,
    pub query_schema: Option<fn() -> serde_json::Value>,
    pub response_schema: Option<fn() -> serde_json::Value>,
    /// `#[CacheTTL(N)]` — seconds. 0/None disables the cache interceptor for
    /// this route regardless of `#[UseInterceptors(CacheInterceptor)]`.
    pub cache_ttl_secs: u64,
    /// `#[CacheKey("template")]` — empty string falls back to
    /// `method + ' ' + path + '?' + query`.
    pub cache_key: &'static str,
    /// `#[Version("v1")]` on the controller — empty string = unversioned.
    /// The version is also baked into the mounted path (`/v1/...`).
    pub api_version: &'static str,
    /// `#[Deprecated(sunset = "YYYY-MM-DD")]` — when non-empty the boundary
    /// adds RFC 8594 `Deprecation`/`Sunset` response headers.
    pub sunset: &'static str,
    /// `#[Idempotent(ttl = "…")]` — TTL seconds; 0 = not idempotent.
    /// Surfaces the `Idempotency-Key` header + 409 + replay header in OpenAPI.
    pub idempotent_ttl_secs: u64,
    /// `#[RequirePolicies("…")]` — ABAC actions gating this route.
    pub policies: &'static [&'static str],
    /// `#[AuditLog(action, resource)]` — empty action = no audit.
    pub audit_action: &'static str,
    pub audit_resource: &'static str,
    /// `#[Timeout("…")]` — milliseconds; 0 = no route deadline.
    pub timeout_ms: u64,
    /// `#[Transactional]` present on the handler.
    pub transactional: bool,
    /// `#[MaskFields("…")]` — route-local PII rules (surfaced in OpenAPI).
    pub mask_fields: &'static [&'static str],
}

pub struct RouteDescriptor {
    pub method: HttpMethod,
    pub path: &'static str,
    pub handler: fn(
        crate::web::context::RequestContext,
    ) -> futures::future::BoxFuture<'static, axum::response::Response>,
    pub spec: &'static RouteSpec,
    /// Owning controller's type name. Empty string for free-fn routes (those
    /// always mount). Routes whose controller is not in the reachable module
    /// DAG are skipped at launch — enforcing NestJS-style encapsulation.
    pub controller: &'static str,
}

inventory::collect!(&'static ModuleDescriptor);
inventory::collect!(&'static RouteDescriptor);