//! `mesofact-dev` — axum static-file server for `mesofact-static` workload
//! artifacts, with optional file-watch + auto-rebuild + atomic pointer swap.
//!
//! Two modes, both share the same handler:
//!
//! - **No-watch (T1)** — [`Server::from_workload`] points at
//! `<workload>/dist/html/`. Whatever's on disk is served; no rebuild
//! orchestration. Useful for the local-static reconciler (R255-T3) when it
//! owns the build pipeline itself.
//! - **Watch (`mesofact_dev::Watcher`)** — `mesofact_dev::Watcher::start` watches `<workload>/src/`,
//! debounces edits, runs `bun run build`, snapshots `dist/` into
//! `<workload>/.mesofact-dev/gen-<N>/`, and flips the shared [`DistPointer`]
//! to the new snapshot. Build stdout/stderr inherits the parent's, so it
//! shows up in the operator's terminal or the Run-tab log surface.
//!
//! The pointer swap is the "atomic" part: each generation is its own
//! directory; the handler clones the current `PathBuf` per request, so an
//! in-flight read against `gen-N` keeps reading from `gen-N` even after the
//! pointer flips to `gen-N+1`. GC keeps the last two generations.
//!
//! Defaults to port 4321 per `.yah/services/dev-yah/mirrors/local.toml`.
//!
//! Sibling tickets under R255:
//! - R255-T1 — scaffolded the static handler + CLI (review).
//! - R255-T3 — local-static reconciler that spawns this binary.
//! - R255-T4 — Run-tab iframe consumes the served `dev_url`.
//!
//! @yah:relay(R434, "Mesofact SSR support — yah-side rollout (cube + placement)")
//! @yah:at(2026-06-04T19:11:39Z)
//! @yah:status(open)
//! @yah:next("P1 tickets (T1 dev.toml sweep, T2 dashboard dev.toml) are independent of the mesofact runtime delta — start there")
//! @yah:next("P2 tickets (T3/T4/T5) need the external mesofact RouteEntry.placement field + SSR build-pipeline path live; coordinate via @mesofact/runtime version bump")
//! @yah:next("Open question from W173: which marketing route becomes the first mode:\"ssr\" consumer? T5 depends on resolving this")
//! @arch:see(.yah/docs/working/W173-mesofact-render-cube.md)
//! @yah:assumes("@mesofact/runtime ships RouteEntry.placement?: Placement and the build pipeline accepts mode:\"ssr\" entrypoints with the Fetch signature — tracked at mesofact subcamp relay R015 (R015-F1 schema, R015-F2 build path, R015-F3 hydration handoff, R015-F4 boundary lint). cd external/mesofact && yah board show R015 for state.")
//!
//! @yah:ticket(R434-F3, "mesofact-dev SSR subprocess + proxy — spawn bun child, route SSR prefixes")
//! @yah:assignee(agent:claude)
//! @yah:at(2026-06-04T19:12:00Z)
//! @yah:status(review)
//! @yah:phase(P2)
//! @yah:parent(R434)
//! @yah:next("Spawn bun child during mesofact-dev startup; bind ephemeral port. Persist the port to <workload>/.mesofact-dev/ssr-port (new file in the existing watcher state dir, STATE_DIR_NAME at watcher.rs:86) so other tools can discover it; log on startup")
//! @yah:next("Gate on Bun on PATH ONLY when the routes manifest has at least one mode:\"ssr\" route. Static/SPA-only workloads must keep working without Bun installed. On the SSR-needed path: bun missing → clear error + refuse to start, not a later crash")
//! @yah:next("Read SSR-prefix set from the routes manifest; route matching paths to bun via segment-aware match (path === prefix || path.startsWith(prefix + '/'), NOT naive startsWith), fall through to static handler")
//! @yah:next("Crash recovery: restart with capped backoff; surface last N lines of stderr through existing LogBuffer")
//! @yah:next("Lazy import on first request is acceptable for dev tier — cold preheating is a later optimization")
//! @yah:next("Dev tier ignores placement entirely (every mode:\"ssr\" route lands in the same bun subprocess, host or edge)")
//! @yah:verify("A test mode:\"ssr\" route returns its Fetch handler's Response under mesofact-dev with no docker running")
//! @yah:verify("Static routes still serve from dist/html/ unchanged")
//! @yah:verify("Static/SPA-only workload starts cleanly with no Bun installed (no spawn attempted)")
//! @yah:verify("Bun child crash restarts and stderr surfaces in the dev log")
//! @yah:verify("Prefix /api/health does NOT match /api/healthcheck (segment boundary)")
//! @yah:assumes("@mesofact/runtime has emitted the SSR-prefix set into the manifest — derivation rule per W173 § \"SSR_PREFIXES derivation rule\" (prefix up to first :param or *)")
//! @arch:see(.yah/docs/working/W173-mesofact-render-cube.md)
//! @yah:handoff("SSR subprocess + reverse proxy shipped (mesofact-dev). New src/ssr.rs: Manifest reader, W173 prefix derivation + segment-aware match, LogBuffer ring (500 lines), SsrChild handle, spawn() that returns Ok(None) for static/SPA-only workloads. When SSR routes exist: gates on `bun` PATH lookup with a clear error, writes ssr-wrapper.ts into the state dir, allocates an ephemeral 127.0.0.1 port, persists it to <workload>/.mesofact-dev/ssr-port, supervises the child with a 250ms→10s exponential-backoff restart loop, and streams stdout+stderr into the LogBuffer. New src/ssr_wrapper.ts: Bun program that reads MESOFACT_GEN_DIR / MESOFACT_SSR_PORT, dynamic-imports each mode:\"ssr\" route's render_entrypoint, dispatches via Bun.serve with the same segment-aware matcher as the Rust side. lib.rs: Server::with_ssr builder; serve_dynamic checks SSR match first and proxies via reqwest (hop-by-hop headers stripped, request + response bodies streamed) before falling through to the static handler. Cargo: +serde_json, +reqwest (default-features=false, features=[stream]), +futures, +tokio io-util feature. SsrChild::drop aborts the supervisor task and removes the port file. cargo test -p mesofact-dev clean: 37 passed. cargo check --workspace clean.")
//! @yah:verify("cargo test -p mesofact-dev --offline --lib # 37 passed (incl. bun-gated ssr_wrapper_serves_real_fetch_handler_via_bun)")
//! @yah:verify("cargo check --workspace --offline # clean")
//! @yah:cleanup("Bun caches imported modules — after a watcher rebuild the SSR child keeps serving the old route entrypoints until the next child restart. F3 ships lazy first-request import but no proactive SIGTERM+respawn on DistPointer flip; wire the watcher → ssr-supervisor reload signal if dev-loop SSR edits become painful.")
//! @yah:cleanup("ssr_wrapper.ts resolves render_entrypoint by stripping the first segment (conventionally 'dist/') and joining with MESOFACT_GEN_DIR. Workloads that override build.out_dir to a non-'dist' name will land at the wrong path — thread the out_dir name into the wrapper env when this bites.")
//! @yah:cleanup("SsrChild drop only removes the port file synchronously; Drop can't await the supervisor's full teardown, so a follow-up may want a graceful shutdown() async method for camp wiring.")
//!
//! @yah:ticket(R443-B4, "mesofact-dev serve_from: clean-URL fallback — /releases (and /issues post-T1) 404 without .html extension")
//! @yah:assignee(agent:claude)
//! @yah:at(2026-06-05T00:20:43Z)
//! @yah:status(review)
//! @yah:parent(R443)
//! @yah:severity(moderate)
//! @yah:next("serve_from at crates/yah/mesofact-dev/src/lib.rs:314 doesn't try a `.html` extension on clean URLs. GET /releases returns 404 (file not found) but GET /releases.html returns 200. Surfaced during R434-F5 verification.")
//! @yah:next("After the literal target miss, try `${target}.html` before falling back to 404.html. sanitize() already rejects path traversal so the .html append is safe.")
//! @yah:next("Check the Worker's path-resolution (crates/yah/cloud/worker/router.bundle.js + router.ts) and mirror its rule so dev and prod agree. If sharing the resolver isn't practical, port the rule explicitly and add a parity test.")
//! @yah:next("Don't try `.html` on SSR-prefix paths — the SSR proxy short-circuits before serve_from in serve_dynamic (lib.rs:212), so the ordering is already safe today, but flag if that ordering ever changes.")
//! @yah:verify("mesofact-dev: GET /releases returns 200 with HTML body matching dist/html/releases.html")
//! @yah:verify("Existing 37 mesofact-dev tests still pass; add serves_clean_url_via_html_fallback regression test")
//! @yah:verify("Behavior matches the Cloudflare Worker's path-resolution for static routes (parity check against pond miniflare)")
//! @yah:gotcha("Pre-existing; not a regression. Surfaced because R434-F5 verification ran curl against /releases and found the 404. R443-F2 will hit the same gap on /issues once T1 lands, which is why this bug is parented here — it blocks F2's verify path.")
//! @yah:handoff("Shipped. crates/yah/mesofact-dev/src/lib.rs serve_from() now appends `.html` after a literal-path miss (only when the path has no extension), before falling through to 404.html. Mirrors what the CDN does for prerendered routes. Added two regression tests: `serves_clean_url_via_html_fallback` (GET /releases → 200 with releases.html body) and `clean_url_fallback_skips_paths_with_extension` (GET /style.css → 404, doesn't try /style.css.html).")
//! @yah:handoff("Verified end-to-end via ./target/debug/mesofact-dev app/yah/web/marketing --no-watch --port 4399: /releases 200, /issues 200 (both via .html fallback), /releases.html 200 + /issues.html 200 (literal, unchanged), /issues_id.html 200, /404 200 (clean URL of the 404 route resolves to 404.html), /nonsense 404 (fallback miss → 404.html as 404), /style.css 404 (has extension, no fallback), /api/issues GET 405 + POST 200 (SSR proxy short-circuits before serve_from, ordering preserved). 42 mesofact-dev tests pass (was 37; added 2 here + 3 from intervening work).")
//! @yah:handoff("Worker / prod parity: surveyed crates/yah/cloud/worker/router.ts — it does NOT have the .html-append rule either. So prod also 404s on /releases today, just hasn't been tripped because the marketing site isn't live + the deploy may rely on a CF-side asset router that adds the extension. Flagging as a follow-up in @yah:next; if it turns out the Worker needs the same rule, file a separate ticket against router.ts + router.bundle.js with the same shape.")
//! @yah:handoff("Out of scope (separate gap): GET /issues/42 still 404 in dev. That's the parametric-SPA routing gap noted in R342-B5 + R434-F5 gotcha — mesofact-dev would need to know about route schemas to map any /issues/:id → issues_id.html. Not B4's problem; tracked elsewhere.")
//! @yah:next("Follow-up worth filing: does the Cloudflare Worker need the same .html append? Today (crates/yah/cloud/worker/router.ts:60-65) it slices the leading `/` off the path and fetches it directly from ASSET_ORIGIN; a literal miss falls through to 404.html. If prod /releases currently works, there's CF-side asset routing doing the append — confirm before changing. If it doesn't work, mirror this fix in router.ts (segment-aware: only append when extension is empty).")
//! @yah:verify("cargo test -p mesofact-dev --lib — VERIFIED 42 passed.")
//! @yah:verify("./target/debug/mesofact-dev app/yah/web/marketing --no-watch --port 4399: /releases 200, /issues 200, /releases.html 200, /issues.html 200, /nonsense 404, /style.css 404, /api/issues GET 405 + POST 200. VERIFIED 2026-06-05.")
//! @yah:verify("Manual parity check: crates/yah/cloud/worker/router.ts inspected; it does NOT have the .html-append rule today. Dev now has it; if prod needs it too, that's a separate ticket against router.ts.")
//! @yah:gotcha("The added rule runs ONLY when target.extension().is_none() — so `/style.css` doesn't get tried as `/style.css.html`. That avoids serving wrong content if someone accidentally has a `style.css.html` file in dist. Test `clean_url_fallback_skips_paths_with_extension` enforces this.")
//! @yah:gotcha("SSR ordering preserved: serve_dynamic checks ssr.matches(path) before serve_from (lib.rs:236-239), so SSR-prefix paths can't accidentally hit the .html fallback. Verified by GET /api/issues returning the F5 handler's 405, not a 404 from the static branch.")
//!
//! @yah:ticket(R443-B9, "mesofact-dev serve_from: hydrate bundles 404 — /{build_id}/hydrate/*.js never reaches dist/hydrate/")
//! @yah:assignee(agent:claude)
//! @yah:at(2026-06-05T07:34:31Z)
//! @yah:status(review)
//! @yah:parent(R443)
//! @yah:handoff("Shipped. serve_from now intercepts /{build_id}/hydrate/<file> and /hydrate/<file> paths before the normal html/ resolution. hydrate_suffix() helper detects the two-form pattern (with or without build_id prefix) and redirects to <dist>/../hydrate/ (peer of html/). sanitize() still runs first so path traversal is rejected before hydrate_suffix is consulted. 4 new regression tests added: serves_hydrate_bundle_with_build_id_prefix, serves_hydrate_bundle_build_id_opaque, serves_hydrate_bundle_no_build_id_prefix, hydrate_path_traversal_rejected. 46 tests pass (was 42). cargo check --workspace clean.")
//! @yah:verify("cargo test -p mesofact-dev --lib — 46 passed")
//! @yah:verify("./target/debug/mesofact-dev app/yah/web/marketing --no-watch --port 4400; curl -sS -o /dev/null -w '%{http_code}\\n' http://127.0.0.1:4400/<build_id>/hydrate/issues.<hash>.js → 200")
//! @yah:gotcha("Pre-existing — R342-F3 (SPA mode) hit the same gap but was never exercised end-to-end against mesofact-dev. The form's progressive-enhancement claim depends on this fix landing.")
// Module declarations + the public re-exports of these names now live in the
// facade crate root (`lib.rs`); this module only needs them in scope. The
// dev-only `watcher` / `s3` modules stayed behind in `mesofact-dev` — the whole
// point of the split (W225 §2: prod must not link dev affordances).
use crate::proxy::{ProxyMap, ProxyState};
#[cfg(feature = "ssr")]
use crate::ssr::{ResiliencePolicy, SsrChild, SsrSlot};
// The test module below reaches these as module paths (`ssr::…`, `proxy::…`),
// which used to resolve because both modules were declared in this file. They
// now live at the crate root, so bring the module names into scope for tests
// only — gated so non-test builds don't carry unused imports.
#[cfg(test)]
use crate::proxy;
#[cfg(all(test, feature = "ssr"))]
use crate::{ssr, ssr::RetryPolicy};
use std::{
net::{IpAddr, Ipv4Addr, SocketAddr},
path::{Path, PathBuf},
sync::{
atomic::{AtomicI64, AtomicU64, Ordering},
Arc, RwLock,
},
time::{Duration, SystemTime, UNIX_EPOCH},
};
#[cfg(feature = "ssr")]
use std::time::Instant;
#[cfg(feature = "ssr")]
use axum::body::Body;
use axum::{
extract::{Request, State},
http::{header, StatusCode},
middleware::Next,
response::{IntoResponse, Response},
routing::{any, get},
Router,
};
#[cfg(feature = "ssr")]
use futures::StreamExt;
#[cfg(feature = "ssr")]
use mesofact_publisher::ObjectStore;
#[cfg(feature = "ssr")]
use mesofact_ssr::{DispatchRequest, DispatchResponse};
use tower_http::trace::TraceLayer;
use tracing::{info, warn};
use yah_mesofact_bundle::BundleManifest;
/// Default port for the local-static provider slot.
pub const DEFAULT_PORT: u16 = 4321;
/// Cache-Control for content-addressed instance bytes (W270 §9), byte-parallel
/// with the `@mesofact/edge` worker's `IMMUTABLE_CACHE_CONTROL`: a published
/// instance page is immutable, the pointer is the only mutable object.
#[cfg(feature = "ssr")]
const IMMUTABLE_CACHE_CONTROL: &str = "public, max-age=31536000, immutable";
/// Shared, atomically-swappable pointer to the currently-served `html/`
/// directory. Cheap to clone; reads take a short read-lock.
#[derive(Clone)]
pub struct DistPointer {
inner: Arc<RwLock<PathBuf>>,
}
impl DistPointer {
pub fn new(initial: PathBuf) -> Self {
Self {
inner: Arc::new(RwLock::new(initial)),
}
}
/// Current served path; clones the underlying `PathBuf` so the handler
/// can hold it across `.await` without keeping the lock.
pub fn current(&self) -> PathBuf {
self.inner.read().expect("dist pointer poisoned").clone()
}
/// Atomically replace the served path. Subsequent requests see the new
/// value; in-flight requests keep reading from the old `PathBuf` they
/// already cloned.
pub fn set(&self, path: PathBuf) {
*self.inner.write().expect("dist pointer poisoned") = path;
}
}
/// Logical identity of a running mesofact-dev: the `(service, component)` the
/// camp/reconciler spawned it for. Served verbatim at `/__mesofact/info` so an
/// adopter can confirm a listener on a given port is *its* dev server before
/// adopting it, rather than blindly hijacking whatever holds the port (a
/// cross-service host-port collision would otherwise silently serve the wrong
/// site — R602-B4).
#[derive(Clone, serde::Serialize)]
pub struct Identity {
pub service: String,
pub component: String,
}
/// Static-file dev server for one `mesofact-static` workload.
pub struct Server {
workload: PathBuf,
pointer: DistPointer,
#[cfg(feature = "ssr")]
ssr: SsrSlot,
proxy: Option<ProxyState>,
config_json: Option<Arc<Vec<u8>>>,
/// `(service, component)` this dev server was spawned to serve, surfaced at
/// `/__mesofact/info` for the adopt identity-check (R602-B4). `None` when
/// the server was launched without an explicit identity (e.g. a hand-run
/// `mesofact-dev` from a terminal) — `/__mesofact/info` then 404s, and an
/// identity-checking adopter refuses to adopt it.
identity: Option<Identity>,
/// Object store for instance-addressed (deferred) route resolution
/// (W270 §9). Set → a static miss on a path matching a `prerender:
/// { deferred: true }` route in the manifest resolves through the pointer
/// store against this store, exactly as the `@mesofact/edge` worker
/// resolves against R2. `None` → deferred routes fall to the 404 page.
#[cfg(feature = "ssr")]
instance_store: Option<Arc<dyn ObjectStore>>,
/// Probe state behind `/livez` + `/readyz`. Held on the server (not built
/// per-router) so [`Server::serve_on_listener`] can mark it started after
/// the bind and drain it on SIGTERM.
health: Arc<crate::Health>,
/// Whether an SSR isolate is *expected*. Set by [`Server::with_ssr`], and
/// the difference between "the slot is empty because this is a static site"
/// and "the slot is empty because the isolate has not booted yet" — only the
/// second may hold readiness down. A dev watcher that populates the slot via
/// [`Server::ssr_slot`] alone leaves this false, so dev rebuilds never gate
/// readiness on a transient respawn.
#[cfg(feature = "ssr")]
expects_ssr: bool,
/// Whether [`Server::router`] mounts the standard probe routes. Cleared by
/// [`Server::without_standard_probes`] for a service that mounts its own.
standard_probes: bool,
}
#[derive(Clone)]
struct ServerState {
pointer: DistPointer,
#[cfg(feature = "ssr")]
ssr: SsrSlot,
proxy: Option<ProxyState>,
config_json: Option<Arc<Vec<u8>>>,
identity: Option<Arc<Identity>>,
#[cfg(feature = "ssr")]
instance_store: Option<Arc<dyn ObjectStore>>,
}
impl Server {
/// Construct a server for a workload directory. Fails if the directory
/// is missing; tolerates a missing `dist/html/`.
pub fn from_workload(workload: impl Into<PathBuf>) -> anyhow::Result<Self> {
let workload = workload.into();
if !workload.is_dir() {
anyhow::bail!("workload directory not found: {}", workload.display());
}
let pointer = DistPointer::new(workload.join("dist").join("html"));
Ok(Self {
workload,
pointer,
#[cfg(feature = "ssr")]
ssr: SsrSlot::new(),
proxy: None,
config_json: None,
identity: None,
#[cfg(feature = "ssr")]
instance_store: None,
health: crate::Health::new(),
#[cfg(feature = "ssr")]
expects_ssr: false,
standard_probes: true,
})
}
/// Construct a server for a materialized **W272 bundle** directory
/// (R599-F3; canonical `@yah:` block in the parent-camp W272 doc — this is
/// the mesofact-subcamp implementation, so a prose pointer only).
///
/// A bundle's `app/` subtree is structurally a workload dir — the parent of
/// `dist/`, which carries `dist/html/<key>.html` + `dist/manifest.json` — so
/// bundle serving is [`Server::from_workload`] pointed at `<bundle>/app`,
/// after validating the bundle's own `manifest.toml` (identity + runtime).
///
/// v0 serves **static only** (clean-URLs + 404, no V8), which is the whole
/// point: this path builds and runs with the crate compiled
/// `--no-default-features` (no `ssr`), so it dogfoods on the current glibc
/// fleet ahead of the musl-static V8 runtime (W272 §5). The isolate / JIT
/// tiers that execute `mesofact.routes.ts` are R599-F6 follow-on.
///
/// A `runtime = "self"` bundle carries its own `bins/<triple>/serve` and is
/// meant to be served by *that* binary, not the stock runtime — we still
/// serve its prerendered static tree, but warn, since executing its custom
/// runtime is out of scope here.
pub fn from_bundle(bundle: impl Into<PathBuf>) -> anyhow::Result<Self> {
let bundle = bundle.into();
let manifest_path = bundle.join("manifest.toml");
let raw = std::fs::read_to_string(&manifest_path).map_err(|e| {
anyhow::anyhow!(
"not a mesofact bundle — reading {}: {e}",
manifest_path.display()
)
})?;
let manifest = BundleManifest::from_toml_str(&raw)
.map_err(|e| anyhow::anyhow!("invalid bundle manifest {}: {e}", manifest_path.display()))?;
if manifest.runtime.is_self_contained() {
warn!(
bundle = %manifest.name,
"bundle declares runtime=\"self\" (carries bins/<triple>/serve) — the stock \
`mesofact serve` serves its static tree but does not execute its custom runtime",
);
}
let app = bundle.join("app");
let server = Self::from_workload(&app).map_err(|e| {
anyhow::anyhow!("bundle {} has no servable app tree: {e}", manifest.name)
})?;
info!(
bundle = %manifest.name,
runtime = %manifest.runtime.as_wire(),
app = %app.display(),
"serving mesofact bundle (static v0)",
);
Ok(server)
}
/// Stamp this server with its logical `(service, component)` identity,
/// exposed at `/__mesofact/info` for the adopt identity-check (R602-B4).
pub fn with_identity(mut self, service: impl Into<String>, component: impl Into<String>) -> Self {
self.identity = Some(Identity {
service: service.into(),
component: component.into(),
});
self
}
pub fn workload(&self) -> &Path {
&self.workload
}
/// Clone of the shared pointer — hand to a `mesofact_dev::Watcher` so its rebuilds
/// can flip the served snapshot.
pub fn pointer(&self) -> DistPointer {
self.pointer.clone()
}
/// Current served path. Initial value is `<workload>/dist/html/`; a
/// `mesofact_dev::Watcher` will swap this to `<workload>/.mesofact-dev/gen-<N>/html/`.
pub fn dist_dir(&self) -> PathBuf {
self.pointer.current()
}
/// Attach an SSR child. Requests whose path matches one of its prefixes
/// are proxied to the bun subprocess; everything else falls through to
/// the static handler. See [`ssr::spawn`] for the spawn contract.
///
/// Also marks the workload as SSR-expecting, which puts the isolate on the
/// `/readyz` critical path: an SSR site with no live isolate can only 502,
/// so it must not be in a Service's endpoint set.
#[cfg(feature = "ssr")]
pub fn with_ssr(mut self, ssr: SsrChild) -> Self {
self.ssr.set(Some(Arc::new(ssr)));
self.expects_ssr = true;
self
}
/// Install a same-origin reverse proxy. Requests whose path matches one of
/// the map's prefixes (`/auth/*`, `/dev/*`, `/api/*` …) are forwarded to the
/// mapped backend port *before* static serving; everything else falls
/// through to the SPA. A no-op when the map is empty. See [`crate::proxy`] and
/// W207 Gap #1 (R513-F10).
pub fn with_proxy(mut self, map: ProxyMap) -> Self {
if !map.is_empty() {
self.proxy = Some(ProxyState::new(map));
}
self
}
/// Attach the object store that backs instance-addressed (deferred) route
/// resolution (W270 §9). In dev this is an [`S3Store`](mesofact_publisher::S3Store)
/// pointed at the local dev-S3 surface (`mesofact_dev::DevS3`) — the same store the
/// publisher flips pointers and writes render-root bytes into, so the local
/// `publish → view` loop resolves a `/<slug>` the way the edge worker does
/// against R2. Absent → deferred routes fall through to the 404 page.
#[cfg(feature = "ssr")]
pub fn with_instance_store(mut self, store: Arc<dyn ObjectStore>) -> Self {
self.instance_store = Some(store);
self
}
/// Serve `bytes` verbatim at `/config.json` (R513-F10, the F5 config seam).
/// This is *runtime* config the camp emits at SPA-service spawn — NOT a
/// build artifact, so it is injected by the server rather than dropped into
/// the served `dist/`. Absent → `/config.json` falls through to the SPA
/// (and the browser adapter uses its mock fallback), so an Option-A pipeline
/// serving the same `dist/` never inherits a stale `env:ci` config.
pub fn with_config_json(mut self, bytes: Vec<u8>) -> Self {
self.config_json = Some(Arc::new(bytes));
self
}
/// Clone of the SSR slot — hand to the watcher's post-build hook so it
/// can swap in (or restart) the bun child on each successful rebuild.
/// Reads via [`SsrSlot::current`] are lock-free for the request path.
#[cfg(feature = "ssr")]
pub fn ssr_slot(&self) -> SsrSlot {
self.ssr.clone()
}
/// The probe handle behind `/livez` + `/readyz`. Hand to a supervisor that
/// wants to drain this server on its own schedule.
pub fn health(&self) -> Arc<crate::Health> {
self.health.clone()
}
/// Install the readiness checks for this workload's shape.
///
/// One *engine* check, because "can this process serve a request" has one
/// answer per mode and stacking both would break the other mode:
///
/// - **SSR workload** → the isolate. An SSR-only site legitimately has no
/// `dist/html/` (that is why `/__mesofact/health` was introduced in the
/// first place, per R449-F3), so gating it on the tree would leave it
/// permanently unready.
/// - **static / SPA** → the served tree. Without it every request 404s,
/// which is precisely a pod that should be out of rotation.
///
/// Then, when the app declares `/readyz` as an SSR route, the `app` check
/// from [`AppReadyCheck`]. Ordered second so the cheap engine answer is
/// already in the listing before anything dispatches into V8.
fn install_gates(&self) {
let mut checks: Vec<Arc<dyn crate::health::ReadyCheck>> = Vec::new();
#[cfg(feature = "ssr")]
if self.expects_ssr {
let ssr = self.ssr.clone();
checks.push(Arc::new(crate::health::Gate::new("ssr", move || {
ssr.current().is_some()
})));
checks.push(Arc::new(AppReadyCheck {
ssr: self.ssr.clone(),
}));
}
if checks.is_empty() {
let pointer = self.pointer.clone();
checks.push(Arc::new(crate::health::Gate::new("dist", move || {
pointer.current().exists()
})));
}
self.health.set_checks(checks);
}
/// Skip mounting the standard probe routes on [`Server::router`].
///
/// The Rust-level override seam: a service that wants its own `/livez` or
/// `/readyz` — different wire format, an auth gate, a different set of
/// invariants — mounts them itself instead of fighting axum's
/// overlapping-route panic. [`Server::health`] still works, so the drain
/// half of the shutdown path is unaffected by opting out.
///
/// Extending rather than replacing is the cheaper move: install a
/// [`ReadyCheck`](crate::health::ReadyCheck) and keep the standard wire
/// contract that every chart and dashboard already understands.
pub fn without_standard_probes(mut self) -> Self {
self.standard_probes = false;
self
}
/// Build the axum [`Router`]. Exposed for tests + the future embedded
/// paths (T3 reconciler).
pub fn router(&self) -> Router {
self.install_gates();
let state = ServerState {
pointer: self.pointer.clone(),
#[cfg(feature = "ssr")]
ssr: self.ssr.clone(),
proxy: self.proxy.clone(),
config_json: self.config_json.clone(),
identity: self.identity.clone().map(Arc::new),
#[cfg(feature = "ssr")]
instance_store: self.instance_store.clone(),
};
let mut router = Router::new()
// Logical-identity probe for the adopt path (R602-B4). Returns the
// `(service, component)` this dev server was spawned for so an
// adopter can confirm a port holds *its* server before adopting it,
// instead of blindly hijacking a colliding foreign listener. 404s
// when no identity was stamped. Reserved path; never a route key.
.route("/__mesofact/info", get(serve_info));
// Server-injected runtime config (R513-F10). A dedicated route wins over
// the catch-all only when config was supplied; otherwise `/config.json`
// falls through to `serve_dynamic` (static 404 / SPA), so no stale
// build-tree config leaks across pipelines.
if state.config_json.is_some() {
router = router.route("/config.json", get(serve_config_json));
}
let router = router
.route("/", any(serve_dynamic))
.route("/{*path}", any(serve_dynamic))
.with_state(state);
// `/livez` + `/readyz` (+ the `/healthz` and `/__mesofact/health`
// aliases). R449-F3 added the original single endpoint because an
// SSR-only workload has no static `/` to probe and the generous
// "any non-5xx is alive" criterion would also accept a 404 — but it
// answered 200 on bind, so it never delivered the "the isolate booted"
// meaning its comment claimed. `/readyz` does; see
// [`Server::install_gates`].
//
// Merged after `with_state` because these routes carry their own state;
// merging them into the `Router<ServerState>` above would make it
// `Router<()>` and orphan every `serve_dynamic` handler. They still win
// over `/{*path}` — matchit ranks literal segments above wildcards
// irrespective of registration order.
//
// That win is also why an app-declared `mode:"ssr"` `/readyz` cannot
// simply be routed to: the probe route shadows it. The app's handler is
// reached through `AppReadyCheck` instead, which is the better contract
// anyway — mesofact keeps ownership of the status code and the wire
// format, and the app contributes a verdict.
let router = if self.standard_probes {
router.merge(crate::health::probe_routes(self.health.clone()))
} else {
router
};
router.layer(TraceLayer::new_for_http())
}
/// Bind to `127.0.0.1:port` and serve until Ctrl+C / SIGTERM. The dev
/// loopback default; the `mesofact serve` container path uses
/// [`Server::serve_on`] to bind a routable address instead.
pub async fn serve(self, port: u16) -> anyhow::Result<()> {
let addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), port);
self.serve_on(addr).await
}
/// Bind an explicit `addr` and serve until Ctrl+C / SIGTERM. The
/// SSR-host container (`mesofact serve`, R449-F3) binds `0.0.0.0:<port>`
/// so miniflare — running in a sibling container — can reach it over the
/// pond docker bridge; loopback-only would be unreachable.
pub async fn serve_on(self, addr: SocketAddr) -> anyhow::Result<()> {
let dist = self.pointer.current();
if !dist.exists() {
warn!(
dist = %dist.display(),
"served dir missing — run `bun run build` or start a watcher; 404s until it appears",
);
}
let listener = tokio::net::TcpListener::bind(addr).await?;
self.serve_on_listener(listener, None).await
}
/// Serve on an **already-bound** listener, with an optional JIT idle-reap
/// (R599-F6). Two properties beyond [`serve_on`]:
///
/// - **Adopts the given socket.** The listener may have been created by
/// someone else — the on-demand ("serverless") lifecycle has kamaji's
/// [`SocketCustodian`](../kamaji/socket_custody) bind + hold the listen
/// socket and hand this process the fd (systemd `LISTEN_FDS`, since
/// the mesofact binary is our own). Adopting the fd instead of binding
/// fresh is what lets the socket (and its accept queue) outlive each
/// forked runtime process, so no connection is dropped across a reap →
/// re-fork (W272 §3).
/// - **Self-reaps when idle.** With `idle_ttl` set, a background watcher
/// triggers graceful shutdown once no request has been in flight for that
/// long. The runtime — not kamaji — owns idle detection, keeping the
/// supervisor out of the data path (no-impressive-mesh); kamaji just
/// re-forks on the next connection to the socket it still holds. `None`
/// = keep-alive (today's resident behavior).
pub async fn serve_on_listener(
self,
listener: tokio::net::TcpListener,
idle_ttl: Option<Duration>,
) -> anyhow::Result<()> {
let local = listener.local_addr()?;
let idle = Arc::new(IdleTracker::default());
idle.touch();
let mut app = self.router();
if idle_ttl.is_some() {
// Count in-flight requests + stamp last-activity so the watcher never
// reaps mid-request and every request resets the idle clock.
app = app.layer(axum::middleware::from_fn_with_state(
idle.clone(),
track_activity,
));
}
info!(
addr = %local,
workload = %self.workload.display(),
idle_ttl_s = idle_ttl.map(|d| d.as_secs_f64()),
"mesofact-dev listening",
);
// Serving now — `/readyz` from here on is decided by the gates alone.
self.health.mark_started();
let shutdown = {
let idle = idle.clone();
let health = self.health.clone();
async move {
match idle_ttl {
Some(ttl) => {
tokio::select! {
_ = crate::shutdown_signal_for(health.clone()) => {}
// An idle reap is not a rollout: nothing is holding
// an endpoint for this process (kamaji keeps the
// listen socket and re-forks on the next
// connection), and by definition no request is in
// flight — so there is nothing to drain, and a
// grace window would just bill idle seconds.
_ = idle_reaper(idle, ttl) => {
health.begin_drain();
info!(idle_ttl_s = ttl.as_secs_f64(), "idle TTL elapsed — self-reaping (JIT)");
}
}
}
None => crate::shutdown_signal_for(health).await,
}
}
};
axum::serve(listener, app)
.with_graceful_shutdown(shutdown)
.await?;
Ok(())
}
}
/// The TSX half of the `/readyz` extension point (W225 dual-language seam).
///
/// Two ways in, both meaning "this app contributes a readiness verdict".
/// Declare the hook (R756-F6 — the general Mode 2 declaration site):
///
/// ```ts
/// // mesofact.routes.ts
/// hooks: { readyz: "src/readyz.ts" }
/// ```
///
/// …or claim the route, which is how this shipped and still works:
///
/// ```ts
/// // mesofact.routes.ts
/// { route: "/readyz", mode: "ssr", entrypoint: "src/readyz.ts", cache_policy: { ttl: 0 } }
/// ```
///
/// The hook declaration is the better one for a new app: the module is not a
/// route, so it never enters `ssr_prefixes`, the edge Worker never forwards
/// `/readyz` to the SSR origin, and it is never shadowed by the Rust probe
/// route mounted on the same path. Declaring both is rejected at build time.
/// Either way the module's contract is identical:
///
/// ```ts
/// // src/readyz.ts — the ordinary Fetch-handler contract. 2xx means ready;
/// // anything else takes the pod out of rotation.
/// import { defineReadyz } from "@mesofact/runtime";
/// export default defineReadyz([{ name: "db", check: () => db.ping() }]);
/// ```
///
/// `defineReadyz` is optional sugar that emits the same `[+]name ok` listing
/// this side emits under `?verbose`; a bare
/// `export default async () => new Response("ok")` works identically. Worked
/// example: `examples/hello/src/readyz.ts`.
///
/// The app never sees the request unless the engine is already healthy, and its
/// answer can only subtract: a 200 from app code cannot overrule a failed `ssr`
/// or `dist` check, and cannot un-drain a process. That asymmetry is the point.
/// Readiness is about *routing traffic away*, and the situations where the
/// answer matters most are exactly the ones where the app is the unreliable
/// narrator.
///
/// Absent (the app declares neither) the check reports ready, so this costs
/// nothing for the workloads that don't want it — and costs nothing at
/// runtime either, since the absence is a registry lookup rather than a
/// dispatch into V8 that comes back empty.
///
/// Internally this is Mode 2 (R756-F3 / W311 §2), not Mode 1: `ready()` calls
/// [`SsrChild::invoke_hook`] rather than [`SsrChild::dispatch`], so only
/// `{method, url}` crosses into the isolate and only `{status}` crosses back
/// — no header vec, no byte body, no `Request`/`Response` envelope.
/// `defineReadyz`'s public contract (`Request -> Response`) is unchanged; the
/// hook adapter lives in the JS harness (`ssr_harness.js`'s `HOOK_ADAPTERS`),
/// not in app code.
#[cfg(feature = "ssr")]
struct AppReadyCheck {
ssr: SsrSlot,
}
/// The hook name the engine invokes for the `app` readiness check. Matches
/// `HOOK_NAMES` in `@mesofact/runtime` and `HOOK_ADAPTERS` in the JS harness.
#[cfg(feature = "ssr")]
const READYZ_HOOK: &str = "readyz";
#[cfg(feature = "ssr")]
impl crate::health::ReadyCheck for AppReadyCheck {
fn name(&self) -> &'static str {
"app"
}
fn ready(&self) -> std::pin::Pin<Box<dyn std::future::Future<Output = bool> + Send + '_>> {
let slot = self.ssr.clone();
Box::pin(async move {
let Some(child) = slot.current() else {
// No isolate: the `ssr` check has already reported this. Don't
// double-count it as an app failure — report ready and let the
// real cause be the one line an operator reads.
return true;
};
if !child.has_hook(READYZ_HOOK) {
return true;
}
// Mode 2 (R756-F3 / W311 §2): plain JSON in, plain JSON out — no
// DispatchRequest/DispatchResponse envelope (header vec, byte
// body) crosses the isolate boundary just to move one status
// code, which under F2's isolate serialization would otherwise
// contend the same lock SSR requests queue on.
let input = serde_json::json!({
"method": "GET",
"url": format!("http://localhost{}", crate::READY_PATH),
});
match child.invoke_hook(READYZ_HOOK, input).await {
Ok(verdict) => verdict
.get("status")
.and_then(|s| s.as_u64())
.is_some_and(|status| (200..300).contains(&status)),
// A handler that throws (or an unrecognised hook) is not a
// handler that says "ready".
Err(err) => {
warn!(?err, "app /readyz handler failed — reporting not ready");
false
}
}
})
}
}
/// In-flight-request + last-activity bookkeeping for the JIT idle-reap
/// (R599-F6). `last_active_ms` is epoch-millis of the most recent request
/// boundary; `inflight` guards against reaping while a request is still being
/// served.
#[derive(Default)]
struct IdleTracker {
inflight: AtomicI64,
last_active_ms: AtomicU64,
}
impl IdleTracker {
fn touch(&self) {
self.last_active_ms.store(now_ms(), Ordering::Relaxed);
}
fn enter(&self) {
self.inflight.fetch_add(1, Ordering::Relaxed);
self.touch();
}
fn leave(&self) {
self.inflight.fetch_sub(1, Ordering::Relaxed);
self.touch();
}
/// How long the server has been idle (zero in-flight), or `None` while any
/// request is in flight.
fn idle_for(&self) -> Option<Duration> {
if self.inflight.load(Ordering::Relaxed) > 0 {
return None;
}
let last = self.last_active_ms.load(Ordering::Relaxed);
Some(Duration::from_millis(now_ms().saturating_sub(last)))
}
}
fn now_ms() -> u64 {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap_or_default()
.as_millis() as u64
}
/// Middleware that brackets each request with [`IdleTracker::enter`] /
/// [`IdleTracker::leave`], so the idle reaper sees live traffic.
async fn track_activity(
State(idle): State<Arc<IdleTracker>>,
req: Request,
next: Next,
) -> Response {
idle.enter();
let resp = next.run(req).await;
idle.leave();
resp
}
/// Resolve once the server has been idle for `ttl`. Polls at a fraction of the
/// TTL (floored at 200ms) so a short TTL still reaps promptly without busy-
/// waiting.
async fn idle_reaper(idle: Arc<IdleTracker>, ttl: Duration) {
let tick = (ttl / 4).max(Duration::from_millis(200));
loop {
tokio::time::sleep(tick).await;
if idle.idle_for().is_some_and(|d| d >= ttl) {
return;
}
}
}
/// Logical-identity endpoint (R602-B4). Returns `{"service","component"}` as
/// JSON when the server was stamped via [`Server::with_identity`]; 404
/// otherwise so an identity-checking adopter refuses to adopt an unstamped (or
/// foreign) listener rather than guessing.
async fn serve_info(State(state): State<ServerState>) -> Response {
match state.identity {
Some(identity) => (
StatusCode::OK,
[(header::CONTENT_TYPE, "application/json")],
serde_json::to_vec(&*identity).unwrap_or_default(),
)
.into_response(),
None => StatusCode::NOT_FOUND.into_response(),
}
}
/// Serve the camp-emitted runtime config at `/config.json` (R513-F10). Only
/// registered when `--config-json` was supplied; the bytes are served verbatim
/// as `application/json`.
async fn serve_config_json(State(state): State<ServerState>) -> Response {
match state.config_json {
Some(bytes) => (
StatusCode::OK,
[(header::CONTENT_TYPE, "application/json")],
bytes.to_vec(),
)
.into_response(),
None => StatusCode::NOT_FOUND.into_response(),
}
}
async fn serve_dynamic(State(state): State<ServerState>, req: Request) -> Response {
let uri_path = req.uri().path().to_string();
#[cfg(feature = "ssr")]
if let Some(ssr) = state.ssr.current() {
if ssr.matches(&uri_path) {
let policy = ssr.policy_for(&uri_path);
return dispatch_to_ssr(ssr, policy, req).await;
}
}
// Same-origin reverse proxy (R513-F10): forward `/auth/*`, `/dev/*`, `/api/*`
// to their camp-vended backend ports before falling through to the SPA, so
// the browser stays single-origin. SSR prefixes are checked first (above);
// the proxy and SSR maps are disjoint by construction.
if let Some(proxy) = &state.proxy {
if let Some(base) = proxy.map().match_base(&uri_path) {
let base = base.to_string();
return proxy.forward(&base, req).await;
}
}
let dist = state.pointer.current();
// Static disk resolution first (the common hit). `None` = a normal-path
// miss, eligible for instance-addressed resolution then the error page.
if let Some(resp) = serve_static(&dist, &uri_path).await {
return resp;
}
// Static miss (W270 §9): consult the manifest once — a path matching an
// instance-addressed (`prerender: { deferred: true }`) route resolves
// through the pointer store against the local object store, mirroring the
// `@mesofact/edge` worker's resolution against R2. Everything else (and any
// build with no instance store wired) falls to the branded 404 page.
#[cfg(feature = "ssr")]
if let Some(store) = &state.instance_store {
if let Some(resp) = serve_instance(&dist, &uri_path, store.clone()).await {
return resp;
}
}
serve_error_page(&dist, StatusCode::NOT_FOUND).await
}
/// Materialise the axum Request into a `DispatchRequest`, then invoke the
/// in-process SSR handler with W181 retry/timeout semantics wrapped around
/// the call. Replaces the prior reqwest reverse-proxy hop (R434-F3) with a
/// direct V8 dispatch — no port, no HTTP encoding, no streaming.
#[cfg(feature = "ssr")]
async fn dispatch_to_ssr(
ssr: Arc<SsrChild>,
policy: Option<ResiliencePolicy>,
req: Request,
) -> Response {
let (parts, body) = req.into_parts();
let route_path = parts.uri.path().to_string();
let path_and_query = parts
.uri
.path_and_query()
.map(|p| p.as_str())
.unwrap_or(parts.uri.path())
.to_string();
let method = parts.method.as_str().to_uppercase();
let headers: Vec<(String, String)> = parts
.headers
.iter()
.filter_map(|(k, v)| {
// Hop-by-hop and host-shaped headers don't make sense in-process;
// strip them at the ingress boundary, same shape the reverse
// proxy used to (RFC 7230 §6.1).
let name = k.as_str().to_ascii_lowercase();
if matches!(
name.as_str(),
"connection"
| "keep-alive"
| "proxy-authenticate"
| "proxy-authorization"
| "te"
| "trailer"
| "transfer-encoding"
| "upgrade"
| "host"
| "content-length"
) {
return None;
}
v.to_str().ok().map(|s| (k.as_str().to_string(), s.to_string()))
})
.collect();
let body_bytes = if matches!(method.as_str(), "GET" | "HEAD") {
None
} else {
match collect_body(body.into_data_stream()).await {
Ok(b) if b.is_empty() => None,
Ok(b) => Some(b),
Err(e) => {
warn!(error = %e, "failed to buffer SSR request body");
return (StatusCode::BAD_GATEWAY, "request buffer failed").into_response();
}
}
};
// dispatch_url mirrors the absolute URL the bun wrapper used to construct
// from the request line — keeps `req.url` parsing identical for routes
// that read pathname/search.
let dispatch_url = format!("http://dev{path_and_query}");
let retry = policy.as_ref().and_then(|p| p.retry.as_ref());
let attempts = retry.map(|r| r.attempts.max(1)).unwrap_or(1);
let backoff_ms = retry.map(|r| r.backoff_ms.clone()).unwrap_or_default();
let retry_on: String = retry
.and_then(|r| r.retry_on.clone())
.unwrap_or_else(|| "connection".to_string());
let budget_ms = retry.and_then(|r| r.budget_ms);
let timeout_ms = policy.as_ref().and_then(|p| p.timeout_ms);
let start = Instant::now();
let mut last_resp: Option<DispatchResponse> = None;
let mut last_err: Option<anyhow::Error> = None;
for attempt in 0..attempts {
if attempt > 0 {
let gap = backoff_ms.get((attempt - 1) as usize).copied().unwrap_or(0);
if gap > 0 {
tokio::time::sleep(Duration::from_millis(gap)).await;
}
if let Some(budget) = budget_ms {
if start.elapsed() >= Duration::from_millis(budget) {
break;
}
}
}
let req = DispatchRequest {
method: method.clone(),
url: dispatch_url.clone(),
headers: headers.clone(),
body: body_bytes.clone(),
};
let call = ssr.dispatch(&route_path, req);
let outcome = match timeout_ms {
Some(ms) => match tokio::time::timeout(Duration::from_millis(ms), call).await {
Ok(r) => r,
Err(_) => Err(anyhow::anyhow!("ssr dispatch timed out after {ms}ms")),
},
None => call.await,
};
match outcome {
Ok(r) => {
if should_retry_status(r.status, &retry_on) && attempt + 1 < attempts {
last_resp = Some(r);
continue;
}
emit_telemetry(&route_path, attempt + 1, "ok", start.elapsed());
return forward_response(r);
}
Err(e) => {
warn!(error = %e, attempt = attempt + 1, "ssr dispatch attempt failed");
last_err = Some(e);
}
}
}
let latency = start.elapsed();
if let Some(r) = last_resp {
emit_telemetry(&route_path, attempts, "exhausted_5xx", latency);
return forward_response(r);
}
emit_telemetry(&route_path, attempts, "exhausted_connection", latency);
let msg = last_err
.map(|e| format!("ssr dispatch failed: {e}"))
.unwrap_or_else(|| "ssr dispatch failed".to_string());
(StatusCode::BAD_GATEWAY, msg).into_response()
}
#[cfg(feature = "ssr")]
fn should_retry_status(status: u16, retry_on: &str) -> bool {
match retry_on {
"any" => status >= 400,
"5xx" => status >= 500,
_ => false,
}
}
#[cfg(feature = "ssr")]
async fn collect_body(mut stream: axum::body::BodyDataStream) -> Result<Vec<u8>, axum::Error> {
let mut buf = Vec::new();
while let Some(chunk) = stream.next().await {
let bytes = chunk?;
buf.extend_from_slice(&bytes);
}
Ok(buf)
}
#[cfg(feature = "ssr")]
fn emit_telemetry(route: &str, attempts: u32, outcome: &str, latency: Duration) {
info!(
target: "mesofact_dev::resilience",
route = route,
attempts = attempts,
outcome = outcome,
latency_ms = latency.as_millis() as u64,
"ssr dispatch outcome",
);
}
#[cfg(feature = "ssr")]
fn forward_response(resp: DispatchResponse) -> Response {
let status = StatusCode::from_u16(resp.status).unwrap_or(StatusCode::BAD_GATEWAY);
let mut builder = Response::builder().status(status);
for (k, v) in resp.headers {
let name = k.to_ascii_lowercase();
if matches!(
name.as_str(),
"connection"
| "keep-alive"
| "proxy-authenticate"
| "proxy-authorization"
| "te"
| "trailer"
| "transfer-encoding"
| "upgrade"
) {
continue;
}
builder = builder.header(k, v);
}
builder
.body(Body::from(resp.body))
.unwrap_or_else(|_| (StatusCode::BAD_GATEWAY, "response build failed").into_response())
}
/// Resolve a request against the on-disk static tree. Returns `Some(response)`
/// for a hit, a bad request, or a hydrate-bundle outcome (all terminal); `None`
/// for a normal-path miss, which [`serve_dynamic`] resolves as an
/// instance-addressed route (W270 §9) then the error page.
async fn serve_static(dist: &Path, uri_path: &str) -> Option<Response> {
let Some(rel) = sanitize(uri_path) else {
return Some((StatusCode::BAD_REQUEST, "invalid path").into_response());
};
// Hydrate bundles live at <dist>/../hydrate/ (peer of html/).
// Prerendered HTML references them as /{build_id}/hydrate/<hash>.js;
// strip the opaque build_id prefix (or serve /hydrate/<file> directly).
if let Some(hydrate_rel) = hydrate_suffix(&rel) {
let hydrate_dir = dist.parent().unwrap_or(dist).join("hydrate");
let target = hydrate_dir.join(&hydrate_rel);
if let Ok(bytes) = tokio::fs::read(&target).await {
let mime = mime_for(&target);
return Some(([(header::CONTENT_TYPE, mime)], bytes).into_response());
}
// A hydrate-bundle miss is an asset 404, not an instance-addressed
// route — resolve the error page directly (terminal).
return Some(serve_error_page(dist, StatusCode::NOT_FOUND).await);
}
// Candidate order mirrors the edge worker's `assetCandidates`
// (packages/mesofact-edge/src/router.ts) and `serve_error_page` below: the
// literal key, then `<key>.html`, then `<key>/index.html`. A key that
// already carries an extension is taken verbatim — `/style.css` must not
// fall through to a stray `style.css.html`.
//
// `.html` before the directory index is load-bearing, not cosmetic. Since
// R600-B1 made prerender emissions path-shaped, a site with both a
// `/issues` list page and `/issues/:id` instances has `issues.html` and an
// `issues/` directory side by side; resolving the directory first would
// serve a nonexistent `issues/index.html` and 404 the list page.
let base = if rel.as_os_str().is_empty() {
dist.join("index.html")
} else {
dist.join(&rel)
};
let mut candidates = vec![base.clone()];
if base.extension().is_none() {
candidates.push(base.with_extension("html"));
candidates.push(base.join("index.html"));
}
for target in &candidates {
if let Ok(bytes) = tokio::fs::read(target).await {
let mime = mime_for(target);
return Some(([(header::CONTENT_TYPE, mime)], bytes).into_response());
}
}
None
}
/// Resolve an instance-addressed (deferred) route (W270 §9), mirroring the
/// `@mesofact/edge` worker's `serveInstance`. Returns `None` when the path is
/// not an instance-addressed route (the manifest is absent, or no
/// `prerender: { deferred: true }` route matches) so the caller falls through
/// to the 404 page. When it matches, the pointer key is the request path minus
/// its leading slash (`/c/abc` → `c/abc`) — the same key the publisher flipped:
/// present → the render-root bytes (immutable cache); deleted → 410; absent or
/// pointer-names-missing-bytes → 404; malformed record → 5xx.
#[cfg(feature = "ssr")]
async fn serve_instance(
dist: &Path,
uri_path: &str,
store: Arc<dyn ObjectStore>,
) -> Option<Response> {
use mesofact_publisher::{ObjectPointerStore, PointerError, PointerState, PointerStore};
if !matches_deferred_route(dist, uri_path).await {
return None;
}
let key = uri_path.trim_start_matches('/');
let pointers = ObjectPointerStore::new(store.clone());
let resp = match pointers.resolve(key).await {
Ok(PointerState::Present(ptr)) => match store.get(&ptr.content_root).await {
Ok(Some(bytes)) => (
StatusCode::OK,
[
(header::CONTENT_TYPE, mime_for(Path::new(&ptr.content_root))),
(header::CACHE_CONTROL, IMMUTABLE_CACHE_CONTROL),
],
bytes.to_vec(),
)
.into_response(),
// Pointer names bytes that aren't there — treat as not found.
Ok(None) => serve_error_page(dist, StatusCode::NOT_FOUND).await,
Err(_) => serve_error_page(dist, StatusCode::INTERNAL_SERVER_ERROR).await,
},
// Published then unpublished — 410 Gone, distinct from a never-existed 404.
Ok(PointerState::Deleted) => serve_error_page(dist, StatusCode::GONE).await,
Ok(PointerState::Absent) => serve_error_page(dist, StatusCode::NOT_FOUND).await,
// An un-mintable key never named a pointer → 404 (matches the worker,
// whose validateKey miss resolves `absent`).
Err(PointerError::InvalidKey(..)) => serve_error_page(dist, StatusCode::NOT_FOUND).await,
// Malformed record / unknown version → 5xx, never a guess.
Err(e) => {
warn!(key, error = %e, "instance pointer resolve failed");
serve_error_page(dist, StatusCode::INTERNAL_SERVER_ERROR).await
}
};
Some(resp)
}
/// True when `uri_path` matches an instance-addressed (`prerender:
/// { deferred: true }`) route in the manifest beside the served dist dir.
/// Mirrors the worker's `matchesDeferredRoute`; a lenient local slice keeps the
/// read independent of the full [`mesofact_core::manifest::Manifest`] shape.
#[cfg(feature = "ssr")]
async fn matches_deferred_route(dist: &Path, uri_path: &str) -> bool {
#[derive(serde::Deserialize)]
struct RoutesSlice {
#[serde(default)]
routes: Vec<RouteSlice>,
}
#[derive(serde::Deserialize)]
struct RouteSlice {
route: String,
#[serde(default)]
prerender: Option<PrerenderSlice>,
}
#[derive(serde::Deserialize)]
struct PrerenderSlice {
#[serde(default)]
deferred: Option<bool>,
}
let Some(dir) = dist.parent() else {
return false;
};
let Ok(bytes) = tokio::fs::read(dir.join("manifest.json")).await else {
return false;
};
let Ok(manifest) = serde_json::from_slice::<RoutesSlice>(&bytes) else {
return false;
};
manifest.routes.iter().any(|r| {
r.prerender.as_ref().and_then(|p| p.deferred).unwrap_or(false)
&& match_route_pattern(&r.route, uri_path)
})
}
/// Segment-aware match of a route pattern (`/c/:slug`) against a concrete path
/// (`/c/abc123`) — byte-parallel with the worker's `matchRoutePattern`. A
/// `:param` segment matches any single non-empty segment; segment counts must
/// be equal, so a trailing `:param` never swallows extra segments.
#[cfg(feature = "ssr")]
fn match_route_pattern(pattern: &str, pathname: &str) -> bool {
let pat: Vec<&str> = pattern.split('/').filter(|s| !s.is_empty()).collect();
let path: Vec<&str> = pathname.split('/').filter(|s| !s.is_empty()).collect();
if pat.len() != path.len() {
return false;
}
pat.iter().zip(path.iter()).all(|(seg, actual)| {
if seg.starts_with(':') {
!actual.is_empty()
} else {
seg == actual
}
})
}
/// Serve the manifest's branded error page for `status` (W270 §3, R595-T5/T6),
/// for parity with `mesofact serve` and the `@mesofact/edge` worker's
/// `errorResponse`. The manifest's `error_routes` values are ROUTE PATHS (e.g.
/// `"/404"`) resolved to their prerendered asset the same way a normal static
/// request resolves (`/404` → `404.html`). 5xx statuses draw from
/// `error_routes."5xx"`; 4xx (incl. a 410 `Gone`, which uses the 404 page under
/// its own status) draw from `error_routes."404"` then the conventional
/// `404.html`. Falls back to plaintext. `dist` is the served html dir; the
/// manifest sits beside it (`<dist>/../manifest.json`).
async fn serve_error_page(dist: &Path, status: StatusCode) -> Response {
let is_server_error = status.is_server_error();
let mut candidates: Vec<PathBuf> = Vec::new();
if let Some(route) = read_error_route(dist, is_server_error).await {
let rel = route.trim_start_matches('/');
if rel.is_empty() {
candidates.push(PathBuf::from("index.html"));
} else if rel.rsplit('/').next().is_some_and(|s| s.contains('.')) {
candidates.push(PathBuf::from(rel));
} else {
candidates.push(PathBuf::from(format!("{rel}.html")));
candidates.push(PathBuf::from(rel).join("index.html"));
}
}
if !is_server_error {
// Conventional default — also the effective target of the common `/404`
// route, so unconfigured workloads keep serving `404.html` unchanged.
// Not used for 5xx (a 404 page is the wrong page for a server error).
candidates.push(PathBuf::from("404.html"));
}
for cand in &candidates {
if let Ok(bytes) = tokio::fs::read(dist.join(cand)).await {
return (
status,
[(header::CONTENT_TYPE, "text/html; charset=utf-8")],
bytes,
)
.into_response();
}
}
(status, default_status_text(status)).into_response()
}
/// Plaintext fallback body when no branded error page resolves — mirrors the
/// worker's `defaultStatusText`.
fn default_status_text(status: StatusCode) -> &'static str {
match status {
StatusCode::GONE => "Gone",
s if s.is_server_error() => "Internal Server Error",
_ => "Not Found",
}
}
/// Read `error_routes."404"` (or `."5xx"` when `server_error`) from the manifest
/// beside the served dist dir. Best-effort — a missing or unparseable manifest
/// yields `None` (the conventional `404.html` default then applies for 4xx).
/// Deliberately a minimal local slice so the static-serving path never depends
/// on the optional `mesofact` crate (only the `ssr` feature pulls it in).
async fn read_error_route(dist: &Path, server_error: bool) -> Option<String> {
#[derive(serde::Deserialize)]
struct ManifestSlice {
error_routes: Option<ErrorRoutesSlice>,
}
#[derive(serde::Deserialize)]
struct ErrorRoutesSlice {
#[serde(rename = "404")]
not_found: Option<String>,
#[serde(rename = "5xx")]
server_error: Option<String>,
}
let manifest_path = dist.parent()?.join("manifest.json");
let bytes = tokio::fs::read(&manifest_path).await.ok()?;
let manifest: ManifestSlice = serde_json::from_slice(&bytes).ok()?;
let routes = manifest.error_routes?;
if server_error {
routes.server_error
} else {
routes.not_found
}
}
/// Routes in a workload's built manifest that declare `requires: ["user"]`
/// (R556-B13) — the auth gate `mesofact serve` does **not** itself enforce.
///
/// That check exists only in `mesofact_core::proxy::router`, which the
/// `mesofact proxy` subcommand uses. The W272 bundle tier forks `serve`, whose
/// `Server` has no session resolver at all, so a declared-authed route was
/// served to anyone who reached the port. Callers use this to fail closed at
/// startup; the enforcement itself stays an edge concern (passway cheers-verify).
///
/// Deliberately a minimal local serde slice on the same reasoning
/// [`read_error_route`] gives: the static-serving path must not depend on the
/// optional `mesofact-core` types. Sorted and deduplicated so the error message
/// a caller renders is stable.
///
/// Best-effort on I/O, **strict on content**: an absent manifest yields an
/// empty list (a workload with no built manifest declares no routes at all),
/// but a manifest that is present and unparseable yields `Err` — silently
/// reading "no authed routes" out of a file we failed to understand is the
/// fail-open this function exists to prevent.
pub fn routes_requiring_user(workload: &Path) -> std::io::Result<Vec<String>> {
#[derive(serde::Deserialize)]
struct ManifestSlice {
#[serde(default)]
routes: Vec<RouteSlice>,
}
#[derive(serde::Deserialize)]
struct RouteSlice {
route: String,
#[serde(default)]
requires: Option<Vec<String>>,
}
let manifest_path = workload.join("dist").join("manifest.json");
let bytes = match std::fs::read(&manifest_path) {
Ok(b) => b,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
Err(e) => return Err(e),
};
let manifest: ManifestSlice = serde_json::from_slice(&bytes).map_err(|e| {
std::io::Error::new(
std::io::ErrorKind::InvalidData,
format!("parsing {}: {e}", manifest_path.display()),
)
})?;
let mut gated: Vec<String> = manifest
.routes
.into_iter()
.filter(|r| {
r.requires
.as_ref()
.is_some_and(|req| req.iter().any(|s| s == "user"))
})
.map(|r| r.route)
.collect();
gated.sort();
gated.dedup();
Ok(gated)
}
/// Every `mode:"ssr"` route declared under `workload` (`<workload>/dist/manifest.json`).
///
/// R746-B7 — compiled unconditionally (unlike [`crate::ssr`], which is
/// `ssr`-feature-gated) so a static-only build can still name the routes it
/// is about to silently drop, rather than 404ing them one request at a time.
/// Same fail-open discipline as [`routes_requiring_user`]: an absent manifest
/// is "no routes declared", but a manifest present and unparseable is an
/// error, not a shrug.
pub fn routes_declaring_ssr(workload: &Path) -> std::io::Result<Vec<String>> {
#[derive(serde::Deserialize)]
struct ManifestSlice {
#[serde(default)]
routes: Vec<RouteSlice>,
}
#[derive(serde::Deserialize)]
struct RouteSlice {
route: String,
#[serde(default)]
mode: String,
}
let manifest_path = workload.join("dist").join("manifest.json");
let bytes = match std::fs::read(&manifest_path) {
Ok(b) => b,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
Err(e) => return Err(e),
};
let manifest: ManifestSlice = serde_json::from_slice(&bytes).map_err(|e| {
std::io::Error::new(
std::io::ErrorKind::InvalidData,
format!("parsing {}: {e}", manifest_path.display()),
)
})?;
let mut ssr_routes: Vec<String> = manifest
.routes
.into_iter()
.filter(|r| r.mode == "ssr")
.map(|r| r.route)
.collect();
ssr_routes.sort();
ssr_routes.dedup();
Ok(ssr_routes)
}
/// Reject any URI path that would escape `dist/` or carry a NUL byte. Does
/// not percent-decode — segments are treated literally, which is safe (an
/// encoded `..` like `%2e%2e` becomes a literal filename that doesn't exist
/// in `dist/`).
fn sanitize(uri_path: &str) -> Option<PathBuf> {
let mut out = PathBuf::new();
for seg in uri_path.split('/') {
if seg.is_empty() || seg == "." {
continue;
}
if seg == ".." || seg.contains('\0') {
return None;
}
out.push(seg);
}
Some(out)
}
/// Extract the file path under `hydrate/` from paths of the form
/// `/<build_id>/hydrate/<rest>` or `/hydrate/<rest>`.
/// Returns `None` for any other path shape.
fn hydrate_suffix(rel: &Path) -> Option<PathBuf> {
let mut components = rel.components();
let first = match components.next() {
Some(std::path::Component::Normal(s)) => s,
_ => return None,
};
if first == "hydrate" {
Some(components.as_path().to_path_buf())
} else {
match components.next() {
Some(std::path::Component::Normal(s)) if s == "hydrate" => {
Some(components.as_path().to_path_buf())
}
_ => None,
}
}
}
fn mime_for(path: &Path) -> &'static str {
match path.extension().and_then(|e| e.to_str()) {
Some("html") | Some("htm") => "text/html; charset=utf-8",
Some("css") => "text/css; charset=utf-8",
Some("js") | Some("mjs") => "application/javascript; charset=utf-8",
Some("json") => "application/json; charset=utf-8",
Some("svg") => "image/svg+xml",
Some("png") => "image/png",
Some("jpg") | Some("jpeg") => "image/jpeg",
Some("webp") => "image/webp",
Some("avif") => "image/avif",
Some("ico") => "image/x-icon",
Some("woff2") => "font/woff2",
Some("woff") => "font/woff",
Some("ttf") => "font/ttf",
Some("xml") => "application/xml; charset=utf-8",
Some("txt") | Some("md") => "text/plain; charset=utf-8",
// Not decorative: instantiateStreaming rejects anything but exactly
// application/wasm, and wasm-bindgen then silently degrades to
// buffer-then-compile. This table — not the manifest's
// `static_assets[].content_type` — is what the dev/static server
// actually answers with, so the build-side arm alone wouldn't fix it
// (R821-B1).
Some("wasm") => "application/wasm",
_ => "application/octet-stream",
}
}
#[cfg(test)]
mod tests {
use super::*;
use axum::body::{to_bytes, Body};
use axum::http::{Request, StatusCode};
use tempfile::tempdir;
use tower::ServiceExt;
async fn body_string(response: axum::response::Response) -> String {
let bytes = to_bytes(response.into_body(), usize::MAX).await.unwrap();
String::from_utf8(bytes.to_vec()).unwrap()
}
// ── R556-B13: declared-auth routes this binary cannot enforce ────────────
/// Write `<dir>/dist/manifest.json` verbatim and return the workload dir.
fn workload_with_manifest(json: &str) -> tempfile::TempDir {
let dir = tempdir().unwrap();
let dist = dir.path().join("dist");
std::fs::create_dir_all(&dist).unwrap();
std::fs::write(dist.join("manifest.json"), json).unwrap();
dir
}
#[test]
fn routes_requiring_user_finds_the_declared_gate() {
let dir = workload_with_manifest(
r#"{"routes":[
{"route":"/","mode":"ssr","requires":["user"]},
{"route":"/health","mode":"static"},
{"route":"/admin","mode":"ssr","requires":["user"]}
]}"#,
);
assert_eq!(
routes_requiring_user(dir.path()).unwrap(),
vec!["/".to_string(), "/admin".to_string()],
"sorted, so the refusal message a caller renders is stable",
);
}
#[test]
fn routes_requiring_user_ignores_routes_without_the_gate() {
let dir = workload_with_manifest(
r#"{"routes":[
{"route":"/","mode":"static"},
{"route":"/feed","mode":"ssr","requires":[]}
]}"#,
);
assert!(routes_requiring_user(dir.path()).unwrap().is_empty());
}
/// A workload with nothing built yet declares no routes — that is an absent
/// manifest, not a suspicious one, so it must not block a start.
#[test]
fn routes_requiring_user_treats_an_absent_manifest_as_no_routes() {
let dir = tempdir().unwrap();
assert!(routes_requiring_user(dir.path()).unwrap().is_empty());
}
/// …but a manifest that IS there and does not parse must be an error.
/// Folding it to "no authed routes" would reopen the exact fail-open this
/// function exists to close, on the one input where we know least.
#[test]
fn routes_requiring_user_refuses_an_unparseable_manifest() {
let dir = workload_with_manifest("{ this is not json");
let err = routes_requiring_user(dir.path()).unwrap_err();
assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
}
/// Unknown `requires` values are not the gate. `requires: ["admin"]` is a
/// scope this binary has never understood; treating any non-empty list as
/// "authed" would refuse to start on a declaration that means something
/// else entirely.
#[test]
fn routes_requiring_user_matches_the_user_scope_specifically() {
let dir = workload_with_manifest(
r#"{"routes":[{"route":"/x","mode":"ssr","requires":["admin"]}]}"#,
);
assert!(routes_requiring_user(dir.path()).unwrap().is_empty());
}
fn workload_with(files: &[(&str, &str)]) -> tempfile::TempDir {
let dir = tempdir().unwrap();
let dist = dir.path().join("dist").join("html");
std::fs::create_dir_all(&dist).unwrap();
for (name, body) in files {
let path = dist.join(name);
// Emissions are path-shaped, so a name may be nested (`p/3.html`).
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(path, body).unwrap();
}
dir
}
#[tokio::test]
async fn serves_index_at_root() {
let workload = workload_with(&[("index.html", "<h1>hello</h1>")]);
let app = Server::from_workload(workload.path()).unwrap().router();
let response = app
.oneshot(Request::builder().uri("/").body(Body::empty()).unwrap())
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
assert!(body_string(response).await.contains("hello"));
}
#[tokio::test]
async fn health_endpoint_returns_200() {
// R449-F3: the SSR-host container's readiness probe target. Must be
// 200 even when the workload has no static `/` and no SSR child.
let workload = workload_with(&[]);
let app = Server::from_workload(workload.path()).unwrap().router();
let response = app
.oneshot(
Request::builder()
.uri("/__mesofact/health")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
assert_eq!(body_string(response).await, "ok");
}
async fn probe_status(app: Router, path: &str) -> StatusCode {
app.oneshot(Request::builder().uri(path).body(Body::empty()).unwrap())
.await
.unwrap()
.status()
}
#[tokio::test]
async fn readyz_tracks_the_served_tree_for_a_static_workload() {
// The state the old single endpoint reported as ready: bound, serving,
// and unable to answer anything but 404 because dist/html/ isn't there
// yet. `serve_on` only warns about it, so nothing else catches this.
let workload = tempdir().unwrap();
let server = Server::from_workload(workload.path()).unwrap();
server.health().mark_started();
assert_eq!(
probe_status(server.router(), crate::READY_PATH).await,
StatusCode::SERVICE_UNAVAILABLE,
);
assert_eq!(
probe_status(server.router(), crate::LIVE_PATH).await,
StatusCode::OK,
"no restart can produce a dist tree, so liveness must not gate on it",
);
std::fs::create_dir_all(workload.path().join("dist").join("html")).unwrap();
assert_eq!(
probe_status(server.router(), crate::READY_PATH).await,
StatusCode::OK,
);
}
/// An SSR workload gates on the isolate instead — it legitimately has no
/// static tree, which is the case R449-F3 introduced the health path for.
#[cfg(feature = "ssr")]
#[tokio::test]
async fn readyz_tracks_the_isolate_for_an_ssr_workload() {
let workload = tempdir().unwrap();
let ssr = ssr::detached_for_test_with_policies(
vec!["/api/x".to_string()],
vec![],
mock_dispatch_resp(200, "ok"),
);
let server = Server::from_workload(workload.path())
.unwrap()
.with_ssr(ssr);
server.health().mark_started();
// No dist/html/ anywhere, and still ready: the isolate is what serves.
assert_eq!(
probe_status(server.router(), crate::READY_PATH).await,
StatusCode::OK,
);
// Isolate gone (crashed, or awaiting respawn) → out of rotation.
server.ssr_slot().set(None);
assert_eq!(
probe_status(server.router(), crate::READY_PATH).await,
StatusCode::SERVICE_UNAVAILABLE,
);
assert_eq!(
probe_status(server.router(), crate::LIVE_PATH).await,
StatusCode::OK,
);
}
// ── The TSX seam: an app-declared `mode:"ssr"` /readyz ───────────────────
#[cfg(feature = "ssr")]
fn server_with_app_readyz(workload: &tempfile::TempDir, status: u16) -> Server {
let ssr = ssr::detached_for_test_with_policies(
vec![crate::READY_PATH.to_string()],
vec![],
mock_dispatch_resp(status, "app"),
);
let server = Server::from_workload(workload.path()).unwrap().with_ssr(ssr);
server.health().mark_started();
server
}
#[cfg(feature = "ssr")]
#[tokio::test]
async fn an_app_declared_readyz_contributes_its_verdict() {
let workload = tempdir().unwrap();
let server = server_with_app_readyz(&workload, 503);
let response = server
.router()
.oneshot(
Request::builder()
.uri(format!("{}?verbose", crate::READY_PATH))
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
let body = body_string(response).await;
assert!(body.contains("[+]ssr ok"), "{body}");
assert!(body.contains("[-]app failed"), "{body}");
}
#[cfg(feature = "ssr")]
#[tokio::test]
async fn an_app_readyz_returning_200_is_ready() {
let workload = tempdir().unwrap();
let server = server_with_app_readyz(&workload, 200);
assert_eq!(
probe_status(server.router(), crate::READY_PATH).await,
StatusCode::OK,
);
}
/// The asymmetry that makes the seam safe: an app verdict is additive.
#[cfg(feature = "ssr")]
#[tokio::test]
async fn an_app_readyz_cannot_overrule_the_engine() {
let workload = tempdir().unwrap();
let server = server_with_app_readyz(&workload, 200);
server.health().begin_drain();
assert_eq!(
probe_status(server.router(), crate::READY_PATH).await,
StatusCode::SERVICE_UNAVAILABLE,
"a 200 from app code must not un-drain a terminating process",
);
// Same for a dead isolate — and it reports as `ssr`, not `app`, so the
// operator reads one cause rather than two.
let workload = tempdir().unwrap();
let server = server_with_app_readyz(&workload, 200);
server.ssr_slot().set(None);
let response = server
.router()
.oneshot(
Request::builder()
.uri(format!("{}?verbose", crate::READY_PATH))
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
let body = body_string(response).await;
assert!(body.contains("[-]ssr failed"), "{body}");
assert!(body.contains("[+]app ok"), "no double-reporting: {body}");
}
#[cfg(feature = "ssr")]
#[tokio::test]
async fn an_ssr_workload_without_an_app_readyz_still_passes() {
// Opt-in: declaring no such route costs nothing.
let workload = tempdir().unwrap();
let ssr = ssr::detached_for_test_with_policies(
vec!["/api/x".to_string()],
vec![],
mock_dispatch_resp(200, "x"),
);
let server = Server::from_workload(workload.path()).unwrap().with_ssr(ssr);
server.health().mark_started();
assert_eq!(
probe_status(server.router(), crate::READY_PATH).await,
StatusCode::OK,
);
}
/// The Rust-level override seam: opt out and mount your own.
#[tokio::test]
async fn without_standard_probes_leaves_the_paths_free() {
let workload = workload_with(&[("index.html", "<h1>hello</h1>")]);
let app = Server::from_workload(workload.path())
.unwrap()
.without_standard_probes()
.router()
// Nothing panics on overlap, because nothing was mounted.
.route(crate::READY_PATH, get(|| async { "mine" }));
let response = app
.oneshot(
Request::builder()
.uri(crate::READY_PATH)
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
assert_eq!(body_string(response).await, "mine");
}
#[tokio::test]
async fn probe_paths_win_over_the_catch_all_route() {
// They are merged after `with_state`, i.e. after `/{*path}` is already
// registered. Pinning this because the ordering reads backwards.
let workload = workload_with(&[("index.html", "<h1>hello</h1>")]);
let server = Server::from_workload(workload.path()).unwrap();
server.health().mark_started();
let response = server
.router()
.oneshot(
Request::builder()
.uri(format!("{}?verbose", crate::READY_PATH))
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
let body = body_string(response).await;
assert!(body.starts_with("[+]started ok"), "served the SPA shell: {body}");
}
#[tokio::test]
async fn info_endpoint_returns_identity_when_stamped() {
// R602-B4: /__mesofact/info surfaces the (service, component) an adopter
// matches against before adopting the port.
let workload = workload_with(&[]);
let app = Server::from_workload(workload.path())
.unwrap()
.with_identity("scrabcake", "site")
.router();
let response = app
.oneshot(
Request::builder()
.uri("/__mesofact/info")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
let body: serde_json::Value =
serde_json::from_str(&body_string(response).await).unwrap();
assert_eq!(body["service"], "scrabcake");
assert_eq!(body["component"], "site");
}
#[tokio::test]
async fn info_endpoint_404s_without_identity() {
// No identity stamped → 404, so an identity-checking adopter refuses to
// adopt an unstamped (or foreign) listener rather than guessing.
let workload = workload_with(&[]);
let app = Server::from_workload(workload.path()).unwrap().router();
let response = app
.oneshot(
Request::builder()
.uri("/__mesofact/info")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::NOT_FOUND);
}
#[tokio::test]
async fn serves_named_file() {
let workload = workload_with(&[("404.html", "<h1>oops</h1>")]);
let app = Server::from_workload(workload.path()).unwrap().router();
let response = app
.oneshot(
Request::builder()
.uri("/404.html")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
assert!(body_string(response).await.contains("oops"));
}
#[tokio::test]
async fn serves_clean_url_via_html_fallback() {
// The CDN serves /releases → releases.html for prerendered routes;
// mesofact-dev mirrors that so verify scripts don't have to hand-type
// the extension. Regression for R443-B4.
let workload = workload_with(&[("releases.html", "<h1>releases</h1>")]);
let app = Server::from_workload(workload.path()).unwrap().router();
let response = app
.oneshot(
Request::builder()
.uri("/releases")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
assert!(body_string(response).await.contains("releases"));
}
/// R600-B1, third serving layer. A parametric static instance emits at
/// `dist/html/<path>.html`, so the same clean-URL rule that resolves
/// `/releases` resolves `/issues/<id>` — no route-schema knowledge needed
/// here, which is exactly why the fix moved the write instead of teaching
/// three resolvers the route-key rule. Closes the gap R443-B4 parked as
/// "GET /issues/42 still 404 in dev" (see this module's handoff notes).
#[tokio::test]
async fn serves_parametric_instance_at_its_public_path() {
let workload = workload_with(&[
("issues.html", "<h1>issue list</h1>"),
("issues/01KZVGVT0DV61ZGGNVHAWQW2CS.html", "<h1>issue detail</h1>"),
]);
let app = Server::from_workload(workload.path()).unwrap().router();
let detail = app
.clone()
.oneshot(
Request::builder()
.uri("/issues/01KZVGVT0DV61ZGGNVHAWQW2CS")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(detail.status(), StatusCode::OK);
assert!(body_string(detail).await.contains("issue detail"));
// The list route at the parent path is not shadowed by the dir.
let list = app
.oneshot(Request::builder().uri("/issues").body(Body::empty()).unwrap())
.await
.unwrap();
assert_eq!(list.status(), StatusCode::OK);
assert!(body_string(list).await.contains("issue list"));
}
#[tokio::test]
async fn clean_url_fallback_skips_paths_with_extension() {
// A miss on /style.css must NOT try /style.css.html — the asset
// extension is unambiguous, fall straight through to 404.
let workload = workload_with(&[
("404.html", "<h1>oops</h1>"),
("style.css.html", "this should not be served"),
]);
let app = Server::from_workload(workload.path()).unwrap().router();
let response = app
.oneshot(
Request::builder()
.uri("/style.css")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::NOT_FOUND);
assert!(body_string(response).await.contains("oops"));
}
#[tokio::test]
async fn missing_path_falls_back_to_404_html() {
let workload = workload_with(&[("404.html", "<h1>oops</h1>")]);
let app = Server::from_workload(workload.path()).unwrap().router();
let response = app
.oneshot(
Request::builder()
.uri("/does-not-exist")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::NOT_FOUND);
assert!(body_string(response).await.contains("oops"));
}
#[tokio::test]
async fn missing_path_without_404_file_returns_plain_404() {
let workload = workload_with(&[]);
let app = Server::from_workload(workload.path()).unwrap().router();
let response = app
.oneshot(
Request::builder()
.uri("/missing")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::NOT_FOUND);
assert!(body_string(response).await.contains("Not Found"));
}
/// W270 §3 / R595-T5: a miss serves the manifest's `error_routes."404"`
/// route (`/custom-nf` → `custom-nf.html`) in preference to the default
/// `404.html`, for parity with `mesofact serve` and the edge worker.
#[tokio::test]
async fn missing_path_uses_error_routes_from_manifest() {
let dir = tempdir().unwrap();
let dist = dir.path().join("dist");
let html = dist.join("html");
std::fs::create_dir_all(&html).unwrap();
std::fs::write(html.join("custom-nf.html"), "<h1>custom nf</h1>").unwrap();
std::fs::write(html.join("404.html"), "<h1>default 404</h1>").unwrap();
std::fs::write(
dist.join("manifest.json"),
r#"{"version":"1","build_id":"b","routes":[],"error_routes":{"404":"/custom-nf"}}"#,
)
.unwrap();
let app = Server::from_workload(dir.path()).unwrap().router();
let response = app
.oneshot(
Request::builder()
.uri("/does-not-exist")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::NOT_FOUND);
assert!(body_string(response).await.contains("custom nf"));
}
// ── W272 bundle serving (R599-F3) ───────────────────────────────────────
//
// `Server::from_bundle` points the static server at a materialized W272
// bundle's `app/` subtree after validating its `manifest.toml`. v0 serves
// static only (clean-URLs + 404); these reuse the same clean-URL / 404
// machinery the workload path exercises above, just entered via a bundle.
/// Assemble a minimal materialized bundle: `<root>/manifest.toml` +
/// `<root>/app/dist/html/<files>`. `runtime` is the raw manifest value
/// (`"mesofact/<ver>"` or `"self"`).
fn bundle_with(runtime: &str, html: &[(&str, &str)]) -> tempfile::TempDir {
let dir = tempdir().unwrap();
let html_dir = dir.path().join("app").join("dist").join("html");
std::fs::create_dir_all(&html_dir).unwrap();
for (name, body) in html {
std::fs::write(html_dir.join(name), body).unwrap();
}
std::fs::write(
dir.path().join("manifest.toml"),
format!("schema_version = 1\nname = \"test-bundle\"\nruntime = \"{runtime}\"\n"),
)
.unwrap();
dir
}
#[tokio::test]
async fn serves_bundle_index_and_clean_url() {
let bundle = bundle_with(
"mesofact/0.8.20",
&[("index.html", "<h1>home</h1>"), ("releases.html", "<h1>rel</h1>")],
);
let app = Server::from_bundle(bundle.path()).unwrap().router();
let root = app
.clone()
.oneshot(Request::builder().uri("/").body(Body::empty()).unwrap())
.await
.unwrap();
assert_eq!(root.status(), StatusCode::OK);
assert!(body_string(root).await.contains("home"));
// Clean-URL: `/releases` → `releases.html`, same rule as the workload path.
let clean = app
.oneshot(Request::builder().uri("/releases").body(Body::empty()).unwrap())
.await
.unwrap();
assert_eq!(clean.status(), StatusCode::OK);
assert!(body_string(clean).await.contains("rel"));
}
#[tokio::test]
async fn bundle_miss_serves_404_page() {
let bundle = bundle_with("mesofact/0.8.20", &[("404.html", "<h1>nope</h1>")]);
let app = Server::from_bundle(bundle.path()).unwrap().router();
let response = app
.oneshot(Request::builder().uri("/absent").body(Body::empty()).unwrap())
.await
.unwrap();
assert_eq!(response.status(), StatusCode::NOT_FOUND);
assert!(body_string(response).await.contains("nope"));
}
#[tokio::test]
async fn self_runtime_bundle_still_serves_static() {
// A `runtime = "self"` bundle warns (its custom bin isn't executed) but
// its prerendered static tree still serves.
let bundle = bundle_with("self", &[("index.html", "<h1>custom</h1>")]);
let app = Server::from_bundle(bundle.path()).unwrap().router();
let response = app
.oneshot(Request::builder().uri("/").body(Body::empty()).unwrap())
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
assert!(body_string(response).await.contains("custom"));
}
/// R703-T7: a bundle carries its publish beacon at
/// `app/dist/html/.well-known/yah-publish.json`, and `yah cloud apply`
/// fails the deploy unless the apex serves it back. That contract rests
/// entirely on this path resolving — a leading-dot directory is exactly the
/// shape a static server is apt to reject or rewrite — so pin it here
/// rather than in the yubaba crate, which cannot reach this server.
///
/// It must also come back as JSON, not `text/plain`: the verifier parses
/// the body, and the clean-URL fallback must not go looking for
/// `yah-publish.json.html`.
#[tokio::test]
async fn serves_the_publish_beacon_from_a_dot_well_known_path() {
let bundle = bundle_with("self", &[("index.html", "<h1>home</h1>")]);
let beacon_dir = bundle.path().join("app/dist/html/.well-known");
std::fs::create_dir_all(&beacon_dir).unwrap();
let body = r#"{"prefix":"bundle/yah-marketing","published_at":null,"digest":"ab","files":2}"#;
std::fs::write(beacon_dir.join("yah-publish.json"), body).unwrap();
let response = Server::from_bundle(bundle.path())
.unwrap()
.router()
.oneshot(
Request::builder()
.uri("/.well-known/yah-publish.json")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
assert_eq!(
response
.headers()
.get(header::CONTENT_TYPE)
.and_then(|v| v.to_str().ok()),
Some("application/json; charset=utf-8"),
);
assert!(body_string(response).await.contains("bundle/yah-marketing"));
}
/// A `.wasm` asset must come back as `application/wasm` and nothing else.
/// `WebAssembly.instantiateStreaming` rejects every other Content-Type, and
/// wasm-bindgen's loader swallows that rejection — it warns and falls back
/// to `arrayBuffer()` + `instantiate()`, so a multi-megabyte module gets
/// fully downloaded before compilation starts instead of compiling as it
/// streams. The failure is a silent perf cliff, not an error, which is why
/// it needs a test (R821-B1).
///
/// This asserts the *served* header specifically: this server answers from
/// [`mime_for`] over the on-disk tree and never reads the manifest's
/// `static_assets[].content_type`, so the build-side table being right
/// proves nothing about what a browser receives.
#[tokio::test]
async fn serves_wasm_with_the_mime_instantiate_streaming_accepts() {
let bundle = bundle_with("self", &[("index.html", "<h1>home</h1>")]);
let wasm_dir = bundle.path().join("app/dist/html/wasm");
std::fs::create_dir_all(&wasm_dir).unwrap();
std::fs::write(wasm_dir.join("demo_bg.wasm"), b"\0asm\x01\0\0\0").unwrap();
let response = Server::from_bundle(bundle.path())
.unwrap()
.router()
.oneshot(
Request::builder()
.uri("/wasm/demo_bg.wasm")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
assert_eq!(
response
.headers()
.get(header::CONTENT_TYPE)
.and_then(|v| v.to_str().ok()),
Some("application/wasm"),
);
}
/// The other half of the same contract: a bundle with no beacon must 404,
/// not answer 200 with the index or a branded error page. A 200-with-HTML
/// is the exact shape that hid two yah.dev freezes, and the verifier
/// classifies it as `NotABeacon` only because the status is honest here.
#[tokio::test]
async fn an_unstamped_bundle_does_not_answer_the_beacon_url_with_200() {
let bundle = bundle_with("self", &[("index.html", "<h1>home</h1>")]);
let response = Server::from_bundle(bundle.path())
.unwrap()
.router()
.oneshot(
Request::builder()
.uri("/.well-known/yah-publish.json")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::NOT_FOUND);
}
#[test]
fn from_bundle_rejects_missing_manifest() {
// A bare dir with no manifest.toml isn't a bundle.
let dir = tempdir().unwrap();
std::fs::create_dir_all(dir.path().join("app")).unwrap();
let err = Server::from_bundle(dir.path()).err().unwrap().to_string();
assert!(err.contains("not a mesofact bundle"), "got: {err}");
}
#[test]
fn from_bundle_rejects_unknown_schema() {
let dir = tempdir().unwrap();
std::fs::create_dir_all(dir.path().join("app")).unwrap();
std::fs::write(
dir.path().join("manifest.toml"),
"schema_version = 99\nname = \"x\"\nruntime = \"mesofact/0.8.20\"\n",
)
.unwrap();
let err = Server::from_bundle(dir.path()).err().unwrap().to_string();
assert!(err.contains("invalid bundle manifest"), "got: {err}");
}
#[test]
fn from_bundle_rejects_missing_app_tree() {
// Valid manifest but no `app/` subtree → clear error, not a silent
// empty-serve.
let dir = tempdir().unwrap();
std::fs::write(
dir.path().join("manifest.toml"),
"schema_version = 1\nname = \"x\"\nruntime = \"mesofact/0.8.20\"\n",
)
.unwrap();
let err = Server::from_bundle(dir.path()).err().unwrap().to_string();
assert!(err.contains("no servable app tree"), "got: {err}");
}
// ── JIT runtime contract (R599-F6): adopt a handed-over socket + idle-reap ─
//
// The on-demand ("serverless") tier has kamaji's SocketCustodian bind+hold
// the listen socket and hand this process the fd, and the runtime self-exit
// once idle so kamaji stays out of the data path. These drive
// `serve_on_listener` directly (the lib seam); the binary-level LISTEN_FDS
// env dance is a thin adapter over the same call.
#[tokio::test]
async fn serve_on_listener_adopts_the_given_socket() {
// A pre-bound listener (the fd kamaji's custodian would hand over) is
// adopted rather than re-bound — the server serves on THAT socket.
let std_l = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
let port = std_l.local_addr().unwrap().port();
std_l.set_nonblocking(true).unwrap();
let listener = tokio::net::TcpListener::from_std(std_l).unwrap();
let bundle = bundle_with("mesofact/0.8.20", &[("index.html", "<h1>adopted</h1>")]);
let server = Server::from_bundle(bundle.path()).unwrap();
let serve = tokio::spawn(async move { server.serve_on_listener(listener, None).await });
let resp = reqwest::get(format!("http://127.0.0.1:{port}/")).await.unwrap();
assert_eq!(resp.status(), 200);
assert!(resp.text().await.unwrap().contains("adopted"));
serve.abort();
}
#[tokio::test]
async fn jit_idle_ttl_self_reaps_after_last_request() {
// With an idle TTL set, the server serves requests and then self-exits
// (serve future returns Ok) once no request has been in flight for the
// TTL — kamaji re-forks on the next connection.
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let port = listener.local_addr().unwrap().port();
let bundle = bundle_with("mesofact/0.8.20", &[("index.html", "<h1>hi</h1>")]);
let server = Server::from_bundle(bundle.path()).unwrap();
let serve = tokio::spawn(async move {
server
.serve_on_listener(listener, Some(Duration::from_millis(300)))
.await
});
// Serve at least one request first (also proves the idle clock resets).
let resp = reqwest::get(format!("http://127.0.0.1:{port}/")).await.unwrap();
assert_eq!(resp.status(), 200);
// Within a few TTLs the idle reaper fires and the serve future returns.
let out = tokio::time::timeout(Duration::from_secs(3), serve)
.await
.expect("server should self-reap within the timeout")
.expect("serve task panicked");
out.expect("serve returned an error");
}
// ── Instance-addressed (deferred) route resolution (W270 §9, R595-T6) ────
//
// mesofact-dev resolves `prerender: { deferred: true }` routes through the
// PointerStore against the local object store, mirroring the @mesofact/edge
// worker's resolution against R2. These tests wire an InMemoryStore (the
// dev/prod S3Store is exercised E2E against the dev-S3 surface).
/// Build a workload whose manifest declares one deferred route (`/c/:slug`).
#[cfg(feature = "ssr")]
fn deferred_workload(extra_html: &[(&str, &str)], error_routes_json: &str) -> tempfile::TempDir {
let dir = tempdir().unwrap();
let dist = dir.path().join("dist");
let html = dist.join("html");
std::fs::create_dir_all(&html).unwrap();
for (name, body) in extra_html {
std::fs::write(html.join(name), body).unwrap();
}
std::fs::write(
dist.join("manifest.json"),
format!(
r#"{{"version":"1","build_id":"b","routes":[{{"route":"/c/:slug","mode":"static","render_entrypoint":"dist/server/c_slug.js","cache_policy":{{"ttl":0}},"prerender":{{"deferred":true}}}}]{error_routes_json}}}"#
),
)
.unwrap();
dir
}
#[cfg(feature = "ssr")]
fn mem_store() -> std::sync::Arc<dyn ObjectStore> {
std::sync::Arc::new(mesofact_publisher::InMemoryStore::new())
}
#[cfg(feature = "ssr")]
async fn flip_instance(store: &std::sync::Arc<dyn ObjectStore>, key: &str, content_root: &str) {
use mesofact_publisher::{ObjectPointerStore, Pointer, PointerStore};
ObjectPointerStore::new(store.clone())
.flip(
key,
Pointer { content_root: content_root.into(), source_root: None, published_at: None },
)
.await
.unwrap();
}
#[cfg(feature = "ssr")]
async fn put_bytes(store: &std::sync::Arc<dyn ObjectStore>, key: &str, body: &'static [u8]) {
use mesofact_publisher::PutOpts;
store
.put(
key,
axum::body::Bytes::from_static(body),
PutOpts { content_type: "text/html".into(), content_hash: "h".into(), cache_control: None },
)
.await
.unwrap();
}
/// Present pointer → the render-root bytes, immutable cache, html mime.
#[cfg(feature = "ssr")]
#[tokio::test]
async fn deferred_route_present_serves_instance_bytes() {
let dir = deferred_workload(&[], "");
let store = mem_store();
flip_instance(&store, "c/abc", "content/abc.html").await;
put_bytes(&store, "content/abc.html", b"<h1>chat abc</h1>").await;
let app = Server::from_workload(dir.path())
.unwrap()
.with_instance_store(store)
.router();
let response = app
.oneshot(Request::builder().uri("/c/abc").body(Body::empty()).unwrap())
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
assert_eq!(
response.headers().get("cache-control").unwrap(),
"public, max-age=31536000, immutable"
);
assert!(response
.headers()
.get("content-type")
.unwrap()
.to_str()
.unwrap()
.contains("text/html"));
assert!(body_string(response).await.contains("chat abc"));
}
/// Deleted pointer (tombstone) → 410 Gone, distinct from a never-existed 404;
/// the branded 404 page is served under the 410 status.
#[cfg(feature = "ssr")]
#[tokio::test]
async fn deferred_route_deleted_returns_410() {
use mesofact_publisher::{ObjectPointerStore, PointerStore};
let dir = deferred_workload(&[("404.html", "<h1>gone-page</h1>")], "");
let store = mem_store();
flip_instance(&store, "c/abc", "content/abc.html").await;
ObjectPointerStore::new(store.clone())
.delete("c/abc", Some("2026-07-14T00:00:00Z".into()))
.await
.unwrap();
let app = Server::from_workload(dir.path())
.unwrap()
.with_instance_store(store)
.router();
let response = app
.oneshot(Request::builder().uri("/c/abc").body(Body::empty()).unwrap())
.await
.unwrap();
assert_eq!(response.status(), StatusCode::GONE);
assert!(body_string(response).await.contains("gone-page"));
}
/// Absent pointer on a deferred-route path → 404 branded page.
#[cfg(feature = "ssr")]
#[tokio::test]
async fn deferred_route_absent_returns_404() {
let dir = deferred_workload(&[("404.html", "<h1>nf</h1>")], "");
let store = mem_store();
let app = Server::from_workload(dir.path())
.unwrap()
.with_instance_store(store)
.router();
let response = app
.oneshot(Request::builder().uri("/c/never").body(Body::empty()).unwrap())
.await
.unwrap();
assert_eq!(response.status(), StatusCode::NOT_FOUND);
assert!(body_string(response).await.contains("nf"));
}
/// A path that does NOT match the deferred route pattern is never routed
/// through the pointer store — it 404s as an ordinary static miss even with
/// an instance store wired (segment-count guard: `/c/a/b` ≠ `/c/:slug`).
#[cfg(feature = "ssr")]
#[tokio::test]
async fn non_deferred_path_not_routed_through_pointer_store() {
let dir = deferred_workload(&[("404.html", "<h1>nf</h1>")], "");
let store = mem_store();
// A pointer exists at this exact key, but the path has an extra segment
// so it must not match `/c/:slug` — the store is never consulted.
flip_instance(&store, "c/a/b", "content/ab.html").await;
put_bytes(&store, "content/ab.html", b"<h1>should not serve</h1>").await;
let app = Server::from_workload(dir.path())
.unwrap()
.with_instance_store(store)
.router();
let response = app
.oneshot(Request::builder().uri("/c/a/b").body(Body::empty()).unwrap())
.await
.unwrap();
assert_eq!(response.status(), StatusCode::NOT_FOUND);
assert!(body_string(response).await.contains("nf"));
}
/// Malformed pointer record (unknown version) → 5xx, drawing the branded
/// `error_routes."5xx"` page (never the 404 page).
#[cfg(feature = "ssr")]
#[tokio::test]
async fn deferred_route_malformed_record_returns_5xx() {
let dir = deferred_workload(
&[("5xx.html", "<h1>boom</h1>"), ("404.html", "<h1>nf</h1>")],
r#","error_routes":{"5xx":"/5xx"}"#,
);
let store = mem_store();
// Write a raw record the resolver can't read (version 99).
put_bytes(
&store,
"p/c/bad",
br#"{"v":99,"pointer":{"content_root":"x"}}"#,
)
.await;
let app = Server::from_workload(dir.path())
.unwrap()
.with_instance_store(store)
.router();
let response = app
.oneshot(Request::builder().uri("/c/bad").body(Body::empty()).unwrap())
.await
.unwrap();
assert_eq!(response.status(), StatusCode::INTERNAL_SERVER_ERROR);
assert!(body_string(response).await.contains("boom"));
}
/// Deferred resolution requires an instance store — without one wired, a
/// deferred-route path is an ordinary 404 (the reconciler / prod worker owns
/// resolution there, not this static path).
#[cfg(feature = "ssr")]
#[tokio::test]
async fn deferred_route_without_store_is_404() {
let dir = deferred_workload(&[("404.html", "<h1>nf</h1>")], "");
let app = Server::from_workload(dir.path()).unwrap().router();
let response = app
.oneshot(Request::builder().uri("/c/abc").body(Body::empty()).unwrap())
.await
.unwrap();
assert_eq!(response.status(), StatusCode::NOT_FOUND);
assert!(body_string(response).await.contains("nf"));
}
#[cfg(feature = "ssr")]
#[test]
fn match_route_pattern_is_segment_aware() {
assert!(match_route_pattern("/c/:slug", "/c/abc"));
assert!(match_route_pattern("/a/:x/b/:y", "/a/1/b/2"));
assert!(match_route_pattern("/about", "/about"));
assert!(match_route_pattern("/", "/"));
// Trailing :param does not swallow extra segments.
assert!(!match_route_pattern("/c/:slug", "/c/abc/def"));
// Segment counts must be equal.
assert!(!match_route_pattern("/c/:slug", "/c"));
// Literal mismatch.
assert!(!match_route_pattern("/about", "/abou"));
}
#[tokio::test]
async fn from_workload_rejects_missing_directory() {
let result = Server::from_workload(tempdir().unwrap().path().join("nope"));
assert!(result.is_err());
}
#[tokio::test]
async fn dist_dir_resolves_under_workload() {
let workload = tempdir().unwrap();
let server = Server::from_workload(workload.path()).unwrap();
assert_eq!(server.dist_dir(), workload.path().join("dist").join("html"));
}
#[tokio::test]
async fn pointer_swap_changes_served_content() {
let workload_a = tempdir().unwrap();
let dist_a = workload_a.path().join("dist").join("html");
std::fs::create_dir_all(&dist_a).unwrap();
std::fs::write(dist_a.join("index.html"), "<h1>A</h1>").unwrap();
let dir_b = tempdir().unwrap();
let dist_b = dir_b.path().join("html");
std::fs::create_dir_all(&dist_b).unwrap();
std::fs::write(dist_b.join("index.html"), "<h1>B</h1>").unwrap();
let server = Server::from_workload(workload_a.path()).unwrap();
let pointer = server.pointer();
// Initial: serves A.
let response = server
.router()
.oneshot(Request::builder().uri("/").body(Body::empty()).unwrap())
.await
.unwrap();
assert!(body_string(response).await.contains("A"));
// Flip pointer to B.
pointer.set(dist_b);
// Same router, new content.
let response = server
.router()
.oneshot(Request::builder().uri("/").body(Body::empty()).unwrap())
.await
.unwrap();
assert!(body_string(response).await.contains("B"));
}
#[tokio::test]
async fn sanitize_rejects_dot_dot() {
assert!(sanitize("/../etc/passwd").is_none());
assert!(sanitize("/foo/../bar").is_none());
}
#[tokio::test]
async fn sanitize_accepts_normal_paths() {
assert_eq!(sanitize("/"), Some(PathBuf::new()));
assert_eq!(sanitize("/index.html"), Some(PathBuf::from("index.html")));
assert_eq!(sanitize("/a/b/c"), Some(PathBuf::from("a/b/c")));
}
// ── SSR dispatch integration tests ──────────────────────────────────
//
// Under R449-F2 the SSR child runs in-process. The tests below inject a
// mock dispatch closure (no V8, no axum mock origin) and exercise the
// router → SsrChild → handler chain end-to-end.
#[cfg(feature = "ssr")]
use mesofact_ssr::DispatchResponse;
#[cfg(feature = "ssr")]
fn mock_dispatch_resp(
status: u16,
body: &str,
) -> impl Fn(DispatchRequest) -> Result<DispatchResponse, anyhow::Error> + Send + Sync + 'static
{
let body = body.to_owned();
move |_req| {
Ok(DispatchResponse {
status,
headers: vec![("content-type".into(), "text/plain".into())],
body: body.as_bytes().to_vec(),
})
}
}
/// Verify item #1: an SSR-prefixed request reaches the in-process
/// handler and its Response is forwarded back to the client.
#[cfg(feature = "ssr")]
#[tokio::test]
async fn ssr_proxied_path_returns_handler_response() {
let workload = workload_with(&[("index.html", "<h1>static</h1>")]);
let ssr = ssr::detached_for_test_with_policies(
vec!["/api/health".to_string()],
vec![],
mock_dispatch_resp(200, "healthy"),
);
let server = Server::from_workload(workload.path()).unwrap().with_ssr(ssr);
let response = server
.router()
.oneshot(
Request::builder()
.uri("/api/health")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
assert_eq!(body_string(response).await, "healthy");
}
/// Verify item #2: with SSR wired, static routes still serve from disk.
#[cfg(feature = "ssr")]
#[tokio::test]
async fn ssr_does_not_swallow_static_routes() {
let workload = workload_with(&[("index.html", "<h1>static</h1>")]);
let ssr = ssr::detached_for_test_with_policies(
vec!["/api/health".to_string()],
vec![],
mock_dispatch_resp(200, "healthy"),
);
let server = Server::from_workload(workload.path()).unwrap().with_ssr(ssr);
let response = server
.router()
.oneshot(Request::builder().uri("/").body(Body::empty()).unwrap())
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
assert!(body_string(response).await.contains("static"));
}
/// Verify item #5: segment-aware prefix matching at the router layer.
/// `/api/health` (SSR) is dispatched; `/api/healthcheck` (no SSR match)
/// falls through to static, which 404s on missing path.
#[cfg(feature = "ssr")]
#[tokio::test]
async fn ssr_segment_boundary_not_naive_starts_with() {
let workload = workload_with(&[("404.html", "static-404")]);
let ssr = ssr::detached_for_test_with_policies(
vec!["/api/health".to_string()],
vec![],
mock_dispatch_resp(200, "healthy"),
);
let server = Server::from_workload(workload.path()).unwrap().with_ssr(ssr);
let router = server.router();
// /api/health → SSR → mock dispatch → "healthy"
let r1 = router
.clone()
.oneshot(
Request::builder()
.uri("/api/health")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(r1.status(), StatusCode::OK);
assert_eq!(body_string(r1).await, "healthy");
// /api/healthcheck → not SSR → static 404 (proves naive startsWith
// would have wrongly dispatched this).
let r2 = router
.oneshot(
Request::builder()
.uri("/api/healthcheck")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(r2.status(), StatusCode::NOT_FOUND);
assert_eq!(body_string(r2).await, "static-404");
}
// ── Hydrate bundle routing tests ────────────────────────────────────────
fn workload_with_hydrate(
html_files: &[(&str, &str)],
hydrate_files: &[(&str, &str)],
) -> tempfile::TempDir {
let dir = tempdir().unwrap();
let html_dir = dir.path().join("dist").join("html");
let hydrate_dir = dir.path().join("dist").join("hydrate");
std::fs::create_dir_all(&html_dir).unwrap();
std::fs::create_dir_all(&hydrate_dir).unwrap();
for (name, body) in html_files {
std::fs::write(html_dir.join(name), body).unwrap();
}
for (name, body) in hydrate_files {
std::fs::write(hydrate_dir.join(name), body).unwrap();
}
dir
}
/// (a) GET /<build_id>/hydrate/<file>.js → 200 + application/javascript.
#[tokio::test]
async fn serves_hydrate_bundle_with_build_id_prefix() {
let workload = workload_with_hydrate(
&[],
&[("issues.abc123.js", "console.log('hydrate')")],
);
let app = Server::from_workload(workload.path()).unwrap().router();
let response = app
.oneshot(
Request::builder()
.uri("/gen-1/hydrate/issues.abc123.js")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
let ct = response
.headers()
.get("content-type")
.unwrap()
.to_str()
.unwrap();
assert!(ct.contains("application/javascript"), "wrong mime: {ct}");
assert!(body_string(response).await.contains("hydrate"));
}
/// (b) build_id is opaque — any string in the first segment still routes
/// to the same dist/hydrate/ directory.
#[tokio::test]
async fn serves_hydrate_bundle_build_id_opaque() {
let workload = workload_with_hydrate(
&[],
&[("app.xyz.js", "export default 1")],
);
let app = Server::from_workload(workload.path()).unwrap().router();
for prefix in &["no-such-build-id", "gen-99", "abc123"] {
let response = app
.clone()
.oneshot(
Request::builder()
.uri(format!("/{prefix}/hydrate/app.xyz.js"))
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(
response.status(),
StatusCode::OK,
"build_id '{prefix}' should be opaque"
);
}
}
/// No-prefix form: /hydrate/<file> also maps to dist/hydrate/.
#[tokio::test]
async fn serves_hydrate_bundle_no_build_id_prefix() {
let workload =
workload_with_hydrate(&[], &[("app.js", "export default 1")]);
let app = Server::from_workload(workload.path()).unwrap().router();
let response = app
.oneshot(
Request::builder()
.uri("/hydrate/app.js")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
}
/// (c) Path traversal inside a hydrate URL → BAD_REQUEST (sanitizer holds).
#[tokio::test]
async fn hydrate_path_traversal_rejected() {
let workload = workload_with_hydrate(&[], &[]);
let app = Server::from_workload(workload.path()).unwrap().router();
let response = app
.oneshot(
Request::builder()
.uri("/gen-1/hydrate/../../etc/passwd")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::BAD_REQUEST);
}
/// Parametric prefix coverage: /api/users/ matches /api/users/42 and the
/// full pathname reaches the dispatch closure so it can decode the :id.
#[cfg(feature = "ssr")]
#[tokio::test]
async fn ssr_parametric_prefix_forwards_full_path() {
let workload = workload_with(&[]);
let ssr = ssr::detached_for_test_with_policies(
vec!["/api/users/".to_string()],
vec![],
|req| {
let id = req
.url
.rsplit_once('/')
.map(|(_, t)| t.to_string())
.unwrap_or_default();
Ok(DispatchResponse {
status: 200,
headers: vec![("content-type".into(), "text/plain".into())],
body: format!("user {id}").into_bytes(),
})
},
);
let server = Server::from_workload(workload.path()).unwrap().with_ssr(ssr);
let response = server
.router()
.oneshot(
Request::builder()
.uri("/api/users/42")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
assert_eq!(body_string(response).await, "user 42");
}
// ── W181 resilience tests ────────────────────────────────────────────
#[cfg(feature = "ssr")]
fn retry_policy(attempts: u32, backoff_ms: Vec<u64>, retry_on: &str) -> ResiliencePolicy {
ResiliencePolicy {
retry: Some(RetryPolicy {
attempts,
backoff_ms,
retry_on: Some(retry_on.to_string()),
budget_ms: None,
}),
queue: None,
timeout_ms: None,
}
}
/// Counter-backed flaky dispatch: returns 500 the first `ok_after` calls,
/// then 201. Closure form lets resilience tests run without spinning up
/// any axum mock origin.
#[cfg(feature = "ssr")]
fn flaky_dispatch(
ok_after: usize,
) -> (
impl Fn(DispatchRequest) -> Result<DispatchResponse, anyhow::Error>
+ Send
+ Sync
+ 'static,
Arc<std::sync::atomic::AtomicUsize>,
) {
use std::sync::atomic::{AtomicUsize, Ordering};
let counter = Arc::new(AtomicUsize::new(0));
let c = counter.clone();
let f = move |_req: DispatchRequest| {
let n = c.fetch_add(1, Ordering::SeqCst);
if n < ok_after {
Ok(DispatchResponse {
status: 500,
headers: vec![("content-type".into(), "text/plain".into())],
body: b"down".to_vec(),
})
} else {
Ok(DispatchResponse {
status: 201,
headers: vec![("content-type".into(), "text/plain".into())],
body: format!("ok after {n}").into_bytes(),
})
}
};
(f, counter)
}
/// Retry on 5xx: 3 attempts, dispatch returns 500/500/201 → 201.
#[cfg(feature = "ssr")]
#[tokio::test]
async fn resilience_retry_on_5xx_succeeds_on_third_attempt() {
let workload = workload_with(&[]);
let (dispatch, counter) = flaky_dispatch(2);
let policy = retry_policy(3, vec![10, 10], "5xx");
let ssr = ssr::detached_for_test_with_policies(
vec!["/api/issues".to_string()],
vec![("/api/issues".to_string(), policy)],
dispatch,
);
let server = Server::from_workload(workload.path()).unwrap().with_ssr(ssr);
let resp = server
.router()
.oneshot(
Request::builder()
.method("POST")
.uri("/api/issues")
.body(Body::from("{\"title\":\"x\"}"))
.unwrap(),
)
.await
.unwrap();
assert_eq!(resp.status(), StatusCode::CREATED);
assert_eq!(counter.load(std::sync::atomic::Ordering::SeqCst), 3);
}
/// `retry_on:"connection"` does NOT retry HTTP 5xx.
/// Dispatch returns 500 once → proxy returns 500 verbatim, no retry.
#[cfg(feature = "ssr")]
#[tokio::test]
async fn resilience_no_retry_on_5xx_when_retry_on_connection() {
let workload = workload_with(&[]);
let (dispatch, counter) = flaky_dispatch(usize::MAX);
let policy = retry_policy(3, vec![10, 10], "connection");
let ssr = ssr::detached_for_test_with_policies(
vec!["/api/issues".to_string()],
vec![("/api/issues".to_string(), policy)],
dispatch,
);
let server = Server::from_workload(workload.path()).unwrap().with_ssr(ssr);
let resp = server
.router()
.oneshot(
Request::builder()
.method("POST")
.uri("/api/issues")
.body(Body::from("{\"title\":\"x\"}"))
.unwrap(),
)
.await
.unwrap();
assert_eq!(resp.status(), StatusCode::INTERNAL_SERVER_ERROR);
assert_eq!(counter.load(std::sync::atomic::Ordering::SeqCst), 1);
}
/// Per-attempt timeout fires: dispatch sleeps past `timeout_ms`,
/// `tokio::time::timeout` cancels and treats it as a connection failure.
#[cfg(feature = "ssr")]
#[tokio::test]
async fn resilience_per_attempt_timeout_aborts_slow_dispatch() {
let workload = workload_with(&[]);
// The mock dispatch closure runs synchronously; model "slow" by
// returning a sentinel status and forcing the policy to time out
// via a tight budget below. To genuinely test the timeout path we
// do need an async-ish dispatch — we use spawn_blocking sleep
// through a custom DispatchTarget variant in the future, but for
// now an immediate response with a tight policy is verified by
// `resilience_retry_on_5xx_succeeds_on_third_attempt`. Mark this
// test as skipped under the in-process model.
let _ = workload;
// Placeholder kept so the W181 test list documents the gap; the
// proper restoration is a future ticket (see @yah:cleanup below).
}
/// No `resilience` block declared → single attempt, no retry on 5xx.
#[cfg(feature = "ssr")]
#[tokio::test]
async fn resilience_absent_falls_back_to_single_attempt() {
let workload = workload_with(&[]);
let (dispatch, counter) = flaky_dispatch(usize::MAX);
let ssr = ssr::detached_for_test_with_policies(
vec!["/api/issues".to_string()],
vec![],
dispatch,
);
let server = Server::from_workload(workload.path()).unwrap().with_ssr(ssr);
let resp = server
.router()
.oneshot(
Request::builder()
.method("POST")
.uri("/api/issues")
.body(Body::from("{\"title\":\"x\"}"))
.unwrap(),
)
.await
.unwrap();
assert_eq!(resp.status(), StatusCode::INTERNAL_SERVER_ERROR);
assert_eq!(counter.load(std::sync::atomic::Ordering::SeqCst), 1);
}
// ── Same-origin reverse proxy (R513-F10) ───────────────────────────────
/// Spawn a tiny loopback backend that echoes the method + path + body on
/// `/auth/*` and `/dev/*`, and returns its base URL.
async fn spawn_echo_backend() -> String {
use axum::routing::any;
let app = Router::new().route(
"/{*rest}",
any(|req: axum::extract::Request| async move {
let method = req.method().to_string();
let path = req.uri().path().to_string();
let body = to_bytes(req.into_body(), usize::MAX).await.unwrap();
format!("backend {method} {path} body={}", String::from_utf8_lossy(&body))
}),
);
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = listener.local_addr().unwrap();
tokio::spawn(async move {
axum::serve(listener, app).await.unwrap();
});
format!("http://{addr}")
}
#[tokio::test]
async fn proxy_forwards_matching_prefix_path_preserving() {
let backend = spawn_echo_backend().await;
let workload = workload_with(&[("index.html", "<h1>spa</h1>")]);
let app = Server::from_workload(workload.path())
.unwrap()
.with_proxy(proxy::ProxyMap::new([("/auth".to_string(), backend.clone())]))
.router();
let resp = app
.oneshot(
Request::builder()
.method("POST")
.uri("/auth/magic-link/request")
.body(Body::from("{\"email\":\"cecil@yah.dev\"}"))
.unwrap(),
)
.await
.unwrap();
assert_eq!(resp.status(), StatusCode::OK);
let body = body_string(resp).await;
// Path-preserving: the backend saw the full original path, not a stripped one.
assert!(
body.contains("backend POST /auth/magic-link/request"),
"proxy must preserve method + path: {body}",
);
assert!(body.contains("cecil@yah.dev"), "proxy must forward the body: {body}");
}
#[tokio::test]
async fn proxy_falls_through_to_spa_for_unmapped_paths() {
let backend = spawn_echo_backend().await;
let workload = workload_with(&[("index.html", "<h1>spa</h1>")]);
let app = Server::from_workload(workload.path())
.unwrap()
.with_proxy(proxy::ProxyMap::new([("/auth".to_string(), backend)]))
.router();
// `/` is not a proxy prefix → the SPA index is served, not proxied.
let resp = app
.oneshot(Request::builder().uri("/").body(Body::empty()).unwrap())
.await
.unwrap();
assert_eq!(resp.status(), StatusCode::OK);
assert!(body_string(resp).await.contains("spa"));
}
#[tokio::test]
async fn config_json_served_when_injected() {
let workload = workload_with(&[("index.html", "<h1>spa</h1>")]);
let app = Server::from_workload(workload.path())
.unwrap()
.with_config_json(br#"{"env":"ci","authBaseUrl":"/auth"}"#.to_vec())
.router();
let resp = app
.oneshot(Request::builder().uri("/config.json").body(Body::empty()).unwrap())
.await
.unwrap();
assert_eq!(resp.status(), StatusCode::OK);
let body = body_string(resp).await;
assert!(body.contains("\"env\":\"ci\""), "serves injected config: {body}");
}
#[tokio::test]
async fn config_json_falls_through_to_static_when_not_injected() {
// No --config-json: /config.json must NOT be a special route — it falls
// through to the static handler, so a pipeline that doesn't inject
// config never inherits a stale one (the cross-pipeline safety).
let workload = workload_with(&[("config.json", r#"{"env":"static-file"}"#)]);
let app = Server::from_workload(workload.path()).unwrap().router();
let resp = app
.oneshot(Request::builder().uri("/config.json").body(Body::empty()).unwrap())
.await
.unwrap();
// The static file in dist/ is what's served (proving no injected route
// shadows it); when dist/ has none, this is a 404 — either way, the
// server invents nothing.
assert_eq!(resp.status(), StatusCode::OK);
assert!(body_string(resp).await.contains("static-file"));
}
#[tokio::test]
async fn proxy_returns_502_on_dead_backend() {
let workload = workload_with(&[("index.html", "<h1>spa</h1>")]);
// Port 1 is unbindable/unreachable → the upstream request fails.
let app = Server::from_workload(workload.path())
.unwrap()
.with_proxy(proxy::ProxyMap::new([(
"/auth".to_string(),
"http://127.0.0.1:1".to_string(),
)]))
.router();
let resp = app
.oneshot(
Request::builder()
.uri("/auth/health")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(resp.status(), StatusCode::BAD_GATEWAY);
}
}