//! `mesofact` — the Rust-native web framework facade.
//!
//! **This is the one crate consumers depend on.** Subsystems are selected by
//! feature rather than by picking crate names out of a 7-crate workspace
//! (bevy-style). Two distribution strategies, one crate:
//!
//! - **Prebuilt binary / container** — we build the `mesofact` bin with
//! the `deploy` preset, arch-native per libc, and kamaji fetches it. The
//! consumer's project compiles zero Rust, only their TypeScript — the Node.js
//! model.
//! - **Crate dependency** — the same crate from crates.io, where a consumer
//! picks features and builds a bespoke binary. What Node can't offer, because
//! it's Rust-native all the way down instead of C++ addons.
//!
//! They are the same crate at two lifecycle stages; the shared `deploy` feature
//! preset is what keeps them honest. See W225 §2a.
//!
//! # Feature tiers
//!
//! - `default` — the lean, **V8-free** Rust-handler harness: [`serve_app`] /
//! [`wrap`] + the standard stack ([`HEALTH_PATH`], `TraceLayer`, graceful
//! shutdown). For services whose handlers are Rust functions; the dogfood is
//! yah's cloud-admin dashboard. Continues the "replacing bun with Rust-native
//! SSR" arc (R448 rolldown → R449 deno_core → R450 default-flip).
//! - `ssr` — the SSR serving tier: the [`Server`] engine's V8 dispatch plus the
//! revalidate receiver. Links the *prebuilt* `librusty_v8.a` (a CDN download,
//! not a from-source compile).
//! - `build` — adds the bundler (rolldown + lightningcss), the one genuinely
//! uncached from-source compile. Its own crate so a stray feature flip can't
//! drag it into a lean consumer.
//!
//! # What lives here vs. `mesofact-dev`
//!
//! The prod serving engine ([`server`], [`proxy`], and under `ssr` the `ssr`,
//! `revalidate` and `tenants` modules) lives **here**. `mesofact-dev` holds only
//! the dev affordances — the file watcher and the local S3 surface — and depends
//! on this crate. That direction is load-bearing: it is what keeps a prod binary
//! from linking dev code (W225 §2), and it is enforced by the dependency graph
//! rather than by dead-stripping. Do not add a dev affordance to this crate, and
//! do not add a prod-serving bin to `mesofact-dev`.
//!
//! Cache / session / resilience layers live in `mesofact_core::proxy` today and are
//! bundle-shaped; lifting them here as caller-composable `tower::Layer`s is a
//! follow-up once a second Rust-handler service needs them.
//!
//! @yah:relay(R445, "mesofact-app: lean Rust-native app harness for Rust-handler services (continues R448/R449/R450 'replacing bun with rust-native SSR' arc; dogfooded by yah parent R568-T4)")
//! @yah:at(2026-06-30T07:22:46Z)
//! @yah:status(review)
//! @yah:assignee(agent:bundle-anthropic-ashguard)
//! @arch:see(.yah/docs/working/W174-mesofact-rust-native-pipeline.md)
//! @yah:next("yah parent camp R568-T4 consumes this via root [patch.crates-io] mesofact-app = { path = \"oss/mesofact/crates/mesofact-app\" } + a path-deferred version dep in crates/yah/cloud-admin.")
//! @yah:next("Once a 2nd Rust-handler mesofact service exists, lift cache/session/resilience layers from mesofact::core::proxy::* into the mesofact facade as caller-composable tower::Layers (deferred per lib doc until 2nd consumer appears).")
//! @yah:handoff("Landed mesofact-app crate (oss/mesofact/crates/mesofact-app, publish=false). Lean Rust-handler harness: pub HEALTH_PATH const + pub fn wrap(Router) -> Router (adds /__mesofact/health + tower-http TraceLayer) + pub async fn serve_app(Router, SocketAddr) -> Result<()> (binds, wraps, axum::serve with graceful Ctrl-C/SIGTERM) + pub async fn shutdown_signal. Companion to mesofact-dev: no mesofact-ssr/deno_core/V8 dep so pure-Rust services don't inherit the ~75MB V8 binary. Registered in oss/mesofact workspace members. 3 tests pass (health auto-add, serve_app round-trip, documented panic guard on duplicate health route). Continues R448/R449/R450 arc (replacing bun with Rust-native SSR) -- this is the next milestone after R449 swapped the engine, taking handlers from JS to Rust.")
//! @yah:verify("cargo test -p mesofact-app # 3 passed")
//! @yah:gotcha("Tier: Cleric -- discovery+replicate. Mirrored mesofact-dev's health/shutdown_signal shape so probes are drop-in compatible across JS-bundle and Rust-handler services.")
//! @yah:gotcha("wrap() panics if the caller already registered HEALTH_PATH (axum::Router::merge rejects overlapping method routes regardless of order). Constraint is documented + pinned by a should_panic test; richer-probe services must bypass wrap.")
//! @yah:gotcha("RESOLVED 2026-07-23 (W225 §2a) -- was: 'mesofact-dev refactor to delegate its bind/serve to mesofact-app is deferred'. The whole serving engine moved INTO this crate and mesofact-dev now depends on it, so the delegation is structural rather than deferred. Server's router now uses this crate's HEALTH_PATH + default_health + shutdown_signal instead of the byte-identical copies it carried in mesofact-dev.")
// ── Facade re-exports ────────────────────────────────────────────────────
// Subsystems are namespaced (not glob-flattened) on purpose — consumers reach
// them as `mesofact::core::…`, `mesofact::render::…`, etc. Each is gated on the
// feature that pulls the corresponding crate (see Cargo.toml `[features]`).
//
// This started as a workaround for an axum-major skew (core/dev on 0.7, facade
// on 0.8); that skew is now RESOLVED — everything is axum 0.8 — and the
// namespacing is kept deliberately, bevy-style, so each subsystem keeps its own
// namespace instead of flattening hundreds of items into the crate root.
pub use mesofact_core as core;
// NB: re-exported as `ssr_runtime`, not `ssr` — the `ssr` name at this crate
// root belongs to the SSR *dispatch* module moved in from mesofact-dev below.
// `ssr_runtime` is the raw deno_core/V8 runtime crate that dispatch drives.
#[cfg(feature = "ssr")]
pub use mesofact_ssr as ssr_runtime;
#[cfg(feature = "render")]
pub use mesofact_render as render;
#[cfg(feature = "build")]
pub use mesofact_build as build;
#[cfg(feature = "publish")]
pub use mesofact_publisher as publisher;
// ── The serving engine (moved out of mesofact-dev, W225 §2a) ─────────────
// These carry the prod serving path. They used to live in `mesofact-dev`, which
// meant the prod `mesofact-serve` binary linked the dev crate — and therefore
// the file watcher and the dev S3 surface — breaking the dev/prod crate
// boundary W225 §2 claims. `mesofact-dev` now depends on THIS crate and holds
// only `watcher` + `s3` + the dev bin, so that boundary finally holds.
pub mod cache_headers;
pub mod cli;
pub mod health;
pub mod proxy;
pub mod route_headers;
pub mod server;
#[cfg(feature = "ssr")]
pub mod revalidate;
#[cfg(feature = "ssr")]
mod sources;
#[cfg(feature = "ssr")]
pub mod ssr;
#[cfg(feature = "ssr")]
pub mod tenants;
pub use cache_headers::CachePolicyTable;
pub use health::{Health, LEGACY_HEALTH_PATH, LIVE_PATH, READY_PATH};
pub use proxy::{ProxyMap, ProxyState};
pub use route_headers::RouteHeaderTable;
pub use server::{
declared_cache_policy, read_manifest_bytes, routes_declaring_ssr, routes_requiring_user,
DistPointer, Identity, Server, DEFAULT_PORT,
};
#[cfg(feature = "ssr")]
pub use ssr::{
ResiliencePolicy, RetryPolicy, SpawnOptions as SsrSpawnOptions, SsrChild, SsrSlot,
DEFAULT_RESILIENCE_TIMEOUT_MS,
};
use std::{net::SocketAddr, sync::Arc, time::Duration};
use anyhow::{Context, Result};
use axum::Router;
use tower_http::trace::TraceLayer;
use tracing::{info, warn};
/// The historical probe path, predating the `/livez` + `/readyz` split.
///
/// Kept, and kept meaning exactly what it always meant — **liveness**, 200 as
/// soon as the process is serving — because deployed yubaba reconcilers point
/// `ready_path` here and `Dockerfile.ssr-runtime` documents it. Its doc comment
/// used to claim readiness; the check never did more than prove the socket was
/// accepting, which is why [`health`] exists. New probes should target
/// [`READY_PATH`] / [`LIVE_PATH`].
pub const HEALTH_PATH: &str = "/__mesofact/health";
/// How long `/readyz` reports failure before the listener stops accepting, on
/// SIGTERM. Covers endpoint-removal propagation (kube-proxy, ingress, sidecar
/// caches), which is concurrent with — not ordered before — the signal.
///
/// Override with `MESOFACT_DRAIN_GRACE_SECS`; `0` restores the old behavior of
/// closing the listener immediately.
pub const DEFAULT_DRAIN_GRACE: Duration = Duration::from_secs(5);
/// Wrap a caller's [`Router`] with the standard mesofact middleware stack —
/// the [`health`] probe routes, the `tower-http` trace layer, and nothing else
/// magical. The caller keeps full control of the route table.
///
/// The returned health handle is already started and carries no readiness
/// gates: a Rust-handler service is ready once its routes are mounted. Add
/// gates with [`Health::set_gates`] if it depends on something that can be
/// absent (a warmed cache, an upstream connection) — but only ever things
/// whose remedy is "route traffic elsewhere", never things a restart would fix.
///
/// **Constraint:** the caller's router must NOT already register any probe
/// path — `axum::Router::merge` panics on overlapping method routes regardless
/// of merge order.
pub fn wrap(app: Router) -> Router {
wrap_with(app, Health::ready())
}
/// [`wrap`] against a caller-owned [`Health`], for services that need to hold
/// the handle — to flip gates as subsystems come up, or to drain on their own
/// shutdown path.
pub fn wrap_with(app: Router, health: Arc<Health>) -> Router {
health::probe_routes(health)
.merge(app)
.layer(TraceLayer::new_for_http())
}
/// Bind `addr`, wrap `app` with the standard stack via [`wrap`], and serve
/// until Ctrl+C or SIGTERM — failing readiness for [`DEFAULT_DRAIN_GRACE`]
/// before the listener closes.
///
/// Errors only on bind/listener failure; per-request errors are surfaced
/// through axum's normal Response shape.
pub async fn serve_app(app: Router, addr: SocketAddr) -> Result<()> {
let health = Health::ready();
let listener = tokio::net::TcpListener::bind(addr)
.await
.with_context(|| format!("binding {addr}"))?;
let local = listener.local_addr().context("reading bound addr")?;
info!(addr = %local, "mesofact-app listening");
axum::serve(listener, wrap_with(app, health.clone()))
.with_graceful_shutdown(shutdown_signal_for(health))
.await
.context("axum::serve")
}
/// Resolve when Ctrl+C or (on unix) SIGTERM is received.
///
/// Prefer [`shutdown_signal_for`] anywhere a [`Health`] handle exists: this
/// form returns the instant the signal lands, so the listener closes while
/// load balancers still believe the pod is in rotation.
pub async fn shutdown_signal() {
let _ = wait_for_signal().await;
}
/// [`shutdown_signal`] with the readiness half of a graceful shutdown: flip
/// `/readyz` to 503, hold for the drain grace, *then* resolve so axum closes
/// the listener.
///
/// The hold applies to SIGTERM only. Ctrl+C is a human at a terminal in dev who
/// wants the port back now, and no orchestrator is watching that process's
/// probes.
pub async fn shutdown_signal_for(health: Arc<Health>) {
let signal = wait_for_signal().await;
health.begin_drain();
let grace = match signal {
Signal::Terminate => drain_grace(),
Signal::Interrupt => Duration::ZERO,
};
if grace.is_zero() {
return;
}
info!(
grace_s = grace.as_secs_f64(),
"draining — /readyz now 503, listener closes after the grace window",
);
tokio::time::sleep(grace).await;
}
/// Which signal ended the process — they warrant different drain behavior.
enum Signal {
/// SIGTERM: an orchestrator is rolling us; other components still route here.
Terminate,
/// Ctrl+C: a human in dev.
Interrupt,
}
fn drain_grace() -> Duration {
parse_grace(std::env::var("MESOFACT_DRAIN_GRACE_SECS").ok().as_deref())
}
/// Unset → the default. Set but unparseable → the default *and* a warning: a
/// typo'd grace must not silently become zero, since that is exactly the
/// connection-dropping behavior the operator was configuring away from.
fn parse_grace(raw: Option<&str>) -> Duration {
let Some(raw) = raw else {
return DEFAULT_DRAIN_GRACE;
};
match raw.trim().parse::<f64>() {
Ok(secs) if secs.is_finite() && secs >= 0.0 => Duration::from_secs_f64(secs),
_ => {
warn!(%raw, "MESOFACT_DRAIN_GRACE_SECS is not a non-negative number — using default");
DEFAULT_DRAIN_GRACE
}
}
}
async fn wait_for_signal() -> Signal {
let ctrl_c = async {
if let Err(err) = tokio::signal::ctrl_c().await {
warn!(?err, "failed to install Ctrl+C handler");
// Never resolve: a broken handler must not look like a signal and
// shut the server down on its own.
std::future::pending::<()>().await;
}
};
#[cfg(unix)]
let terminate = async {
use tokio::signal::unix::{signal, SignalKind};
match signal(SignalKind::terminate()) {
Ok(mut s) => {
s.recv().await;
}
Err(err) => {
warn!(?err, "failed to install SIGTERM handler");
std::future::pending::<()>().await;
}
}
};
#[cfg(not(unix))]
let terminate = std::future::pending::<()>();
let signal = tokio::select! {
_ = ctrl_c => Signal::Interrupt,
_ = terminate => Signal::Terminate,
};
info!("shutdown signal received");
signal
}
#[cfg(test)]
mod tests {
use super::*;
use axum::{response::Html, routing::get};
async fn home() -> Html<&'static str> {
Html("<h1>hello</h1>")
}
#[tokio::test]
async fn wrap_adds_health_to_caller_router() {
let app = wrap(Router::new().route("/", get(home)));
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = listener.local_addr().unwrap();
let handle = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
tokio::task::yield_now().await;
let base = format!("http://{addr}");
let client = reqwest::Client::new();
for path in [HEALTH_PATH, LIVE_PATH, READY_PATH, LEGACY_HEALTH_PATH] {
let probe = client.get(format!("{base}{path}")).send().await.unwrap();
assert_eq!(probe.status(), 200, "{path}");
}
let home = client.get(format!("{base}/")).send().await.unwrap();
assert_eq!(home.status(), 200);
assert!(home.text().await.unwrap().contains("hello"));
handle.abort();
}
#[test]
#[should_panic(expected = "Overlapping method route")]
fn wrap_panics_if_caller_already_registered_health_path() {
// Pin the documented constraint: callers that pre-register
// HEALTH_PATH must not pass through wrap(). Acts as a regression
// guard if axum ever changes merge semantics.
let _ = wrap(Router::new().route(HEALTH_PATH, get(|| async { "x" })));
}
#[test]
fn drain_grace_falls_back_rather_than_to_zero() {
assert_eq!(parse_grace(None), DEFAULT_DRAIN_GRACE);
assert_eq!(parse_grace(Some(" 12 ")), Duration::from_secs(12));
assert_eq!(parse_grace(Some("0")), Duration::ZERO);
assert_eq!(parse_grace(Some("0.5")), Duration::from_millis(500));
// A typo must not read as "close the listener immediately".
assert_eq!(parse_grace(Some("5s")), DEFAULT_DRAIN_GRACE);
assert_eq!(parse_grace(Some("-1")), DEFAULT_DRAIN_GRACE);
assert_eq!(parse_grace(Some("")), DEFAULT_DRAIN_GRACE);
assert_eq!(parse_grace(Some("inf")), DEFAULT_DRAIN_GRACE);
}
#[tokio::test]
async fn serve_app_binds_and_responds() {
let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
// serve_app binds and never returns until shutdown; instead, drive
// it via wrap() + a manual bind so we can poll a real request.
let listener = tokio::net::TcpListener::bind(addr).await.unwrap();
let local = listener.local_addr().unwrap();
let app = wrap(Router::new().route("/x", get(|| async { "x" })));
let handle = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
tokio::task::yield_now().await;
let body = reqwest::get(format!("http://{local}/x"))
.await
.unwrap()
.text()
.await
.unwrap();
assert_eq!(body, "x");
handle.abort();
}
}