From e0a83aeabf2f49841e85e8617e4c131b66c461fb Mon Sep 17 00:00:00 2001 From: Gent Bajko Date: Sun, 15 Nov 2026 00:13:51 +0100 Subject: [PATCH 1/2] feat(server): --memory-mib caps a process and derives its budgets --- crates/arda-server/API.md | 51 ++++- crates/arda-server/src/admission.rs | 46 ++++- crates/arda-server/src/ceiling/mod.rs | 187 ++++++++++++++++++ crates/arda-server/src/ceiling/tests.rs | 147 ++++++++++++++ crates/arda-server/src/lib.rs | 103 ++++++++-- crates/arda-server/src/main.rs | 79 ++++++-- crates/arda-server/src/query.rs | 8 + crates/arda-server/src/tactical/mod.rs | 16 +- .../arda-server/src/tactical/refine_blocks.rs | 27 ++- .../arda-server/tests/world_api/admission.rs | 6 +- crates/arda-server/tests/world_api/ceiling.rs | 74 +++++++ crates/arda-server/tests/world_api/main.rs | 1 + tools/docker-entrypoint.sh | 3 +- 13 files changed, 688 insertions(+), 60 deletions(-) create mode 100644 crates/arda-server/src/ceiling/mod.rs create mode 100644 crates/arda-server/src/ceiling/tests.rs create mode 100644 crates/arda-server/tests/world_api/ceiling.rs diff --git a/crates/arda-server/API.md b/crates/arda-server/API.md index b82c9a5f..9b0cfce9 100644 --- a/crates/arda-server/API.md +++ b/crates/arda-server/API.md @@ -24,12 +24,13 @@ docker run --rm -p 8787:8787 -v /abs/world:/worlds/world:ro arda:local | `--world ` | required | World directory (holds `world.json`) | | `--port` | `8787` | TCP port | | `--host` | `127.0.0.1` | Bind address | +| `--memory-mib` | none | Per-process memory ceiling, MiB; also `ARDA_MEMORY_MIB` (the flag wins). The worst case the server admits stays under it and every budget not set by a flag derives from it; see [Memory ceiling](#memory-ceiling). Without it the ceiling is 16,384 MiB and every budget keeps its default | | `--area-cache-mib` | `256` | Decoded-area cache budget (1024 before the serving-concurrency fix, review 3.6-8; 384 before the server-startup fix) | | `--fine-cache-mib` | `128` | Fine-terrain window cache budget (512 before review 3.6-8; 256 before the server-startup fix) | | `--max-overview-px` | `8192` | Largest `overview.png` long edge clients may request | | `--tile-base-px` | `4096` | Tile-pyramid base edge; `256 · 2^max_zoom`, at least 512 | | `--library ` | `assets/tactical/placeholder` | Tactical asset library (holds `catalog.json`), relative to the working directory. It is loaded once and validated with the arda-tactical loader; any validation issue stops startup | -| `--prefetch-workers` | `2` | Background threads warming prefetched tactical cells (at most 8; `0` disables prefetch). Each worker is admitted against the 16 GiB ceiling as one more transient render | +| `--prefetch-workers` | `2` | Background threads warming prefetched tactical cells (at most 8; `0` disables prefetch). Each worker lane is admitted against the ceiling (16 GiB, or `--memory-mib`) as one more transient render | | `--probe` | off | Health probe for container healthchecks: `GET /v1/health` on loopback at `--port`; exit 0 on `200`, 1 otherwise. Serves nothing and needs no `--world` | | `--sheet-mapping ` | none | Sheet mapping that reshapes every served NPC into a game's schema (see [Sheet mapping](#sheet-mapping)). Checked at startup; a bad file stops the server | @@ -114,6 +115,54 @@ docker run --rm -p 8787:8787 -v /abs/world:/worlds/world:ro arda:local PNG, tile and body caches (160 MiB each) and `--max-connections` (32) were trimmed to make room. +### Memory ceiling + +`--memory-mib ` (or `ARDA_MEMORY_MIB`, which the image's default entry reads too) caps +one process: admission holds the worst case (every budget above, plus what the world and +library hold) under it instead of under 16,384 MiB, and the budgets derive from it (logic/16 +§api-memory). + +- **What derives.** Each of these sits at a floor plus one shared fraction of the way to its + default, the largest fraction that fits: the area, derived-layer and fine-window caches, + the overview and relief tile caches, the tactical render, pyramid and encoded caches, the + largest render (`max_render_px`), `--max-connections`, concurrent area builds, concurrent + compositions, the composed- and refined-block caches, the town-plan budget and, with baking + on, `--bake-result-mib`. A flag given on the command line (`--area-cache-mib`, + `--fine-cache-mib`, `--max-connections`, `--bake-result-mib`) keeps its value. The floors: + areas 64 MiB, derived layers and fine windows 32 MiB each, overview and relief tiles 32 MiB + each, renders 96 MiB (one 64-px cell), pyramids 128 MiB (its pyramid), encoded caches 32 MiB + each, renders up to one cell with its apron at 64 px per square (23.7 Mpx), 8 connections, + 1 area build, 2 compositions, composed blocks 32 MiB, 64 refined blocks, town plans 128 MiB; + baking, one worst-case cell set. +- **Fixed.** The pyramid base (`--tile-base-px`), the relief working set (768 MiB), the + refine source's decoded areas (312 MiB), one area build (512 MiB), 48 MiB a connection and + the transient render and encode of each lane at the fitted render size do not shrink further; + nor do the world's and library's residents. +- **Too small.** Below the least ceiling the server refuses to start: + `--memory-mib 4608 is below the 5507 MiB this world, library and these flags need at + least (library 89 MiB, society 773 MiB, shore 85 MiB, largest town plan 462 MiB, …)`. +- **What a small ceiling costs.** A render larger than the fitted `max_render_px` is refused + with `413 payload_too_large` (at the floor, a 96 or 128 px cell, or a window wider than one + cell at 64 px); smaller caches evict sooner; prefetch renders fewer neighbour images ahead + (it renders only what fits the render and pyramid caches beside the open cell), so view + tiles of a neighbour are drawn on demand. +- **Least ceilings, DiceMaster's profile** (prefetch on, baking off, placeholder library): + the 500 × 1,000 km seed-42 world `out/site-renders/full42` needs **5,507 MiB**; the MICRO + seed-42 society world (the contract kit's) **4,282 MiB**. With baking on, add the bake lane + (one transient render and one worst-case cell set, about 750 MiB at the floor). +- **Measured** (Ryzen 9 9950X3D, release build, 150-cell walk at 64 px per square: open a + cell, read 12 view tiles, prefetch its ring, step to a neighbour; then the same walk again): + + | World, ceiling | Open | Idle RSS | Peak RSS | Prefetched cell JSON p50 / p95 | View tiles p95 | Re-walk: cell bodies missed | + |---|---|---|---|---|---|---| + | full42, none (13,839 MiB admitted) | 16.5 s | 2,586 MiB | 6,764 MiB | 2.6 / 224 ms | 1,325 ms | not measured | + | full42, 5,507 MiB | 14.4 s | 2,360 MiB | 2,723 MiB | 1.1 / 42 ms (re-walk 65 ms) | 86 ms | 11 of 118 | + | MICRO, none (12,614 MiB admitted) | 2.3 s | 883 MiB | 5,346 MiB | 3.5 / 334 ms (re-walk 7.5 ms) | 1,321 ms | 0 of 150 | + | MICRO, 4,608 MiB | 2.9 s | 700 MiB | 1,609 MiB | 1.2 / 276 ms (re-walk 332 ms) | 3.2 ms | 33 of 150 | + + The default's slow view tiles come from prefetch: with the default caches it renders up to + ten neighbour images per step, competing with the request for cores. + ## Errors Every error is JSON with the right HTTP status: diff --git a/crates/arda-server/src/admission.rs b/crates/arda-server/src/admission.rs index 5ff19a23..c87b1a32 100644 --- a/crates/arda-server/src/admission.rs +++ b/crates/arda-server/src/admission.rs @@ -14,7 +14,8 @@ use crate::refine_source; use crate::tactical::refine_blocks::{ - COMPOSE_SLOTS, COMPOSE_TRANSIENT_BYTES, REFINED_BLOCKS, REFINED_BLOCK_BYTES, + COMPOSED_CACHE_BYTES, COMPOSE_SLOTS, COMPOSE_TRANSIENT_BYTES, REFINED_BLOCKS, + REFINED_BLOCK_BYTES, }; use crate::tactical::world_routes::WINDOW_PPSQ; use crate::tactical::PPSQ_OPTIONS; @@ -36,15 +37,42 @@ pub const NOTABLES_INDEX_FACTOR: u64 = 3; /// and the relief world's. pub const SHORE_COPIES: u64 = 2; -/// The tactical pipeline's fixed bounds: [`COMPOSE_SLOTS`] transient -/// compositions, the refined-block cache, the refine source's decoded -/// areas and the town-plan cache's byte budget. +/// Budgets of the tactical pipeline. The defaults are the bounds the +/// server has always kept; a memory ceiling ([`crate::ceiling`]) lowers +/// them. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct PipelineLimits { + /// Compositions running at once ([`COMPOSE_SLOTS`]). + pub compose_slots: usize, + /// Bytes of composed blocks kept ([`COMPOSED_CACHE_BYTES`]). + pub composed_cache_bytes: usize, + /// Refined blocks kept ([`REFINED_BLOCKS`]). + pub refined_blocks: usize, + /// Bytes of town plans kept ([`PLAN_CACHE_BYTES`]). + pub plan_cache_bytes: u64, +} + +impl Default for PipelineLimits { + fn default() -> Self { + Self { + compose_slots: COMPOSE_SLOTS, + composed_cache_bytes: COMPOSED_CACHE_BYTES, + refined_blocks: REFINED_BLOCKS, + plan_cache_bytes: PLAN_CACHE_BYTES, + } + } +} + +/// The tactical pipeline's bounds under `limits`: that many transient +/// compositions, the composed- and refined-block caches, the refine +/// source's decoded areas and the town-plan cache's byte budget. #[must_use] -pub const fn pipeline_bytes() -> u64 { - COMPOSE_SLOTS as u64 * COMPOSE_TRANSIENT_BYTES - + REFINED_BLOCKS as u64 * REFINED_BLOCK_BYTES +pub const fn pipeline_bytes(limits: &PipelineLimits) -> u64 { + limits.compose_slots as u64 * COMPOSE_TRANSIENT_BYTES + + limits.composed_cache_bytes as u64 + + limits.refined_blocks as u64 * REFINED_BLOCK_BYTES + refine_source::admitted_bytes() - + PLAN_CACHE_BYTES + + limits.plan_cache_bytes } /// What the opened world and library hold, measured at startup. @@ -164,7 +192,7 @@ mod tests { #[test] fn the_pipeline_bound_counts_every_holder() { - let p = pipeline_bytes(); + let p = pipeline_bytes(&PipelineLimits::default()); assert!(p >= COMPOSE_SLOTS as u64 * COMPOSE_TRANSIENT_BYTES); assert!(p >= refine_source::admitted_bytes() + PLAN_CACHE_BYTES); assert!(p < 2 << 30, "{p}"); diff --git a/crates/arda-server/src/ceiling/mod.rs b/crates/arda-server/src/ceiling/mod.rs new file mode 100644 index 00000000..36077ddf --- /dev/null +++ b/crates/arda-server/src/ceiling/mod.rs @@ -0,0 +1,187 @@ +//! The per-process memory ceiling (`--memory-mib`, `ARDA_MEMORY_MIB`; +//! logic/16 §api-memory). +//! +//! Without a ceiling the server admits its configured budgets against +//! [`crate::MEMORY_CEILING_BYTES`] and nothing changes. With one, every +//! budget the operator did not pin with a flag derives from it: each sits +//! at a floor (the least that still serves a cell at 64 px per square) +//! plus one shared fraction `s` of the way to its default, and `s` is the +//! largest that keeps [`ServerConfig::admitted_bytes`] plus what the world +//! and library hold ([`Resident`]) under the ceiling. Admission then +//! checks the same sum, so the worst case the server admits is the +//! ceiling's by construction. + +use crate::admission::{PipelineLimits, Resident}; +use crate::error::{ServerError, ServerResult}; +use crate::tactical::cells::APRON; +use crate::ServerConfig; + +/// Output pixels of one cell and its apron at 64 px per square: the +/// largest render a fitted server always admits (DiceMaster's cells). +pub const ONE_CELL_64_PX: u64 = { + let side = (64 + 2 * APRON as u64) * 64; + side * side +}; + +/// Budgets the operator set with a flag, which a ceiling leaves alone. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] +pub struct Pinned { + /// `--area-cache-mib`. + pub area_cache: bool, + /// `--fine-cache-mib`. + pub fine_cache: bool, + /// `--max-connections`. + pub max_connections: bool, + /// `--bake-result-mib`. + pub bake_result: bool, +} + +const MIB: u64 = 1 << 20; + +/// Floors of the derived budgets. Each still serves its route: an area +/// cache of five decoded areas, a render cache of one 64-px cell render, +/// a pyramid cache of its pyramid, eight connections, two compositions. +mod floor { + pub const AREA: usize = 64 << 20; + pub const DERIVED: usize = 32 << 20; + pub const FINE: usize = 32 << 20; + pub const OVERVIEW: usize = 32 << 20; + pub const RELIEF: usize = 32 << 20; + pub const RENDER: usize = 96 << 20; + pub const PYRAMID: usize = 128 << 20; + pub const ENCODED: usize = 32 << 20; + pub const CONNECTIONS: usize = 8; + pub const AREA_BUILDS: usize = 1; + // Two, as by default: with one, a request for a cell whose prefetch + // has not finished waits behind the prefetch workers' compositions + // (measured: p95 680 ms on the MICRO kit world at 4,608 MiB). + pub const COMPOSE_SLOTS: usize = 2; + pub const COMPOSED: usize = 32 << 20; + pub const REFINED_BLOCKS: usize = 64; + pub const PLANS: u64 = 128 << 20; +} + +/// `lo + s × (hi − lo)`, rounded down; `hi` when `lo ≥ hi`. +fn lerp(lo: u64, hi: u64, s: f64) -> u64 { + if lo >= hi { + return hi; + } + #[allow( + clippy::cast_possible_truncation, + clippy::cast_sign_loss, + clippy::cast_precision_loss + )] + let step = ((hi - lo) as f64 * s.clamp(0.0, 1.0)).floor() as u64; + lo + step +} + +/// `lerp` on byte budgets, rounded down to whole MiB. +fn lerp_mib(lo: usize, hi: usize, s: f64) -> usize { + let b = lerp(lo as u64, hi as u64, s) / MIB * MIB; + usize::try_from(b.max(lo as u64)).unwrap_or(lo) +} + +fn lerp_count(lo: usize, hi: usize, s: f64) -> usize { + usize::try_from(lerp(lo as u64, hi as u64, s)).unwrap_or(lo) +} + +/// `config` with every unpinned budget at fraction `s` of the way from its +/// floor to its default. +fn at(config: &ServerConfig, s: f64) -> ServerConfig { + let d = ServerConfig::new(config.world.clone()); + let mut c = config.clone(); + if !c.pinned.area_cache { + c.query.area_bytes = lerp_mib(floor::AREA, d.query.area_bytes, s); + } + if !c.pinned.fine_cache { + c.query.fine_bytes = lerp_mib(floor::FINE, d.query.fine_bytes, s); + } + c.query.derived_bytes = lerp_mib(floor::DERIVED, d.query.derived_bytes, s); + c.overview.cache_bytes = lerp_mib(floor::OVERVIEW, d.overview.cache_bytes, s); + c.relief.cache_bytes = lerp_mib(floor::RELIEF, d.relief.cache_bytes, s); + let t = &mut c.tactical; + t.render_cache_bytes = lerp_mib(floor::RENDER, d.tactical.render_cache_bytes, s); + t.pyramid_cache_bytes = lerp_mib(floor::PYRAMID, d.tactical.pyramid_cache_bytes, s); + t.encoded_cache_bytes = lerp_mib(floor::ENCODED, d.tactical.encoded_cache_bytes, s); + t.max_render_px = lerp(ONE_CELL_64_PX, d.tactical.max_render_px, s); + if !c.pinned.max_connections { + c.serve.max_connections = lerp_count(floor::CONNECTIONS, d.serve.max_connections, s); + } + c.area_builds = lerp_count(floor::AREA_BUILDS, d.area_builds, s); + let (p, dp) = (&mut c.pipeline, PipelineLimits::default()); + p.compose_slots = lerp_count(floor::COMPOSE_SLOTS, dp.compose_slots, s); + p.composed_cache_bytes = lerp_mib(floor::COMPOSED, dp.composed_cache_bytes, s); + p.refined_blocks = lerp_count(floor::REFINED_BLOCKS, dp.refined_blocks, s); + p.plan_cache_bytes = lerp(floor::PLANS, dp.plan_cache_bytes, s) / MIB * MIB; + if c.bake_workers > 0 && !c.pinned.bake_result { + let one = crate::tactical::bake::worst_set_bytes().div_ceil(MIB); + let lo = usize::try_from(one).unwrap_or(d.bake_result_mib); + c.bake_result_mib = lerp_count(lo, d.bake_result_mib, s); + } + c +} + +fn need(c: &ServerConfig, resident: &Resident) -> u64 { + c.admitted_bytes().saturating_add(resident.total()) +} + +/// The least ceiling `config`'s flags admit with `resident`: every derived +/// budget at its floor. +#[must_use] +pub fn smallest(config: &ServerConfig, resident: &Resident) -> u64 { + need(&at(config, 0.0), resident) +} + +/// Fits `config` to its ceiling, if it has one (module docs); without one +/// it is returned unchanged. +/// +/// # Errors +/// [`ServerError::ResourceLimit`] when the ceiling is below +/// [`smallest`], naming it in MiB. +pub fn fit(config: &ServerConfig, resident: &Resident) -> ServerResult { + let Some(ceiling) = config.memory_ceiling else { + return Ok(config.clone()); + }; + let least = smallest(config, resident); + if least > ceiling { + return Err(ServerError::ResourceLimit(format!( + "--memory-mib {} is below the {} MiB this world, library and these flags need \ + at least (library {} MiB, society {} MiB, shore {} MiB, largest town plan {} MiB, \ + every derived budget at its floor)", + ceiling / MIB, + least.div_ceil(MIB), + resident.library / MIB, + resident.society / MIB, + resident.shore / MIB, + resident.plans / MIB, + ))); + } + let full = at(config, 1.0); + let top = need(&full, resident); + if top <= ceiling { + return Ok(full); + } + // The admitted sum is affine in `s` up to rounding, so start at the + // interpolated fraction and step down until it fits; `s = 0` fits. + #[allow(clippy::cast_precision_loss)] + let mut s = (ceiling - least) as f64 / (top - least) as f64; + loop { + let c = at(config, s); + if need(&c, resident) <= ceiling || s <= 0.0 { + return Ok(c); + } + s = (s - 1.0 / 1024.0).max(0.0); + } +} + +/// The plan budget the town warm-up runs under, before it has measured +/// the largest plan: `config`'s fitted one without that plan, or the floor +/// when even that does not fit (the fit after the warm-up then refuses +/// with the full measurement). +#[must_use] +pub fn warm_plan_budget(config: &ServerConfig, before: &Resident) -> u64 { + fit(config, before).map_or(floor::PLANS, |c| c.pipeline.plan_cache_bytes) +} + +#[cfg(test)] +mod tests; diff --git a/crates/arda-server/src/ceiling/tests.rs b/crates/arda-server/src/ceiling/tests.rs new file mode 100644 index 00000000..b2bc87dd --- /dev/null +++ b/crates/arda-server/src/ceiling/tests.rs @@ -0,0 +1,147 @@ +//! The ceiling holds (logic/16 §api-memory): every fitted configuration's +//! admitted worst case, with what the world and library hold, stays under +//! the ceiling; a ceiling below the floors is refused, naming the least. + +use super::*; +use crate::admission::Resident; +use crate::ServerConfig; + +const MIB: u64 = 1 << 20; + +/// The MICRO-42 kit world with the placeholder library. +const MICRO: Resident = Resident { + library: 89 * MIB, + society: 20 * MIB, + shore: 4 * MIB, + plans: 73 * MIB, +}; +/// `out/site-renders/full42` (500 × 1,000 km) with the placeholder library. +const FULL: Resident = Resident { + library: 89 * MIB, + society: 773 * MIB, + shore: 85 * MIB, + plans: 462 * MIB, +}; + +fn config(ceiling: Option) -> ServerConfig { + let mut c = ServerConfig::new("world".into()); + c.memory_ceiling = ceiling; + c +} + +/// DiceMaster's profile: prefetch on, baking off. +fn dicemaster(ceiling: Option) -> ServerConfig { + let mut c = config(ceiling); + c.bake_workers = 0; + c +} + +fn profiles(ceiling: u64) -> Vec { + let mut out = vec![config(Some(ceiling)), dicemaster(Some(ceiling))]; + let mut quiet = dicemaster(Some(ceiling)); + quiet.prefetch_workers = 0; + out.push(quiet); + let mut pinned = config(Some(ceiling)); + pinned.serve.max_connections = 8; + pinned.query.area_bytes = 200 << 20; + pinned.pinned = Pinned { + area_cache: true, + max_connections: true, + ..Pinned::default() + }; + out.push(pinned); + out +} + +#[test] +fn without_a_ceiling_nothing_changes() { + let c = config(None); + assert_eq!(format!("{:?}", fit(&c, &FULL).unwrap()), format!("{c:?}")); + assert_eq!(c.ceiling(), crate::MEMORY_CEILING_BYTES); + assert_eq!(c.admitted_bytes() >> 20, 14_422); +} + +#[test] +fn every_fitted_worst_case_stays_under_its_ceiling() { + for resident in [MICRO, FULL] { + for probe in profiles(16 << 30) { + let least = smallest(&probe, &resident); + let mut ceiling = least; + while ceiling <= 16 << 30 { + let mut c = probe.clone(); + c.memory_ceiling = Some(ceiling); + let f = fit(&c, &resident).unwrap_or_else(|e| panic!("{ceiling}: {e}")); + let need = f.admitted_bytes() + resident.total(); + assert!(need <= ceiling, "{need} > {ceiling}"); + f.admit().unwrap(); + f.admit_resident(&resident).unwrap(); + assert!(f.tactical.max_render_px >= ONE_CELL_64_PX); + ceiling += 97 << 20; + } + } + } +} + +#[test] +fn a_ceiling_below_the_floors_is_refused_naming_the_least() { + let c = dicemaster(Some(1 << 30)); + let least = smallest(&c, &FULL); + let err = fit(&c, &FULL).unwrap_err().to_string(); + assert!( + err.contains(&format!("{} MiB", least.div_ceil(MIB))), + "{err}" + ); + let mut at = c.clone(); + at.memory_ceiling = Some(least); + assert!(fit(&at, &FULL).is_ok()); + at.memory_ceiling = Some(least - MIB); + assert!(fit(&at, &FULL).is_err()); +} + +#[test] +fn budgets_grow_with_the_ceiling_up_to_the_defaults() { + let mut last = fit( + &dicemaster(Some(smallest(&dicemaster(None), &MICRO))), + &MICRO, + ) + .unwrap(); + for gib in 5..=16 { + let f = fit(&dicemaster(Some(gib << 30)), &MICRO).unwrap(); + assert!(f.query.area_bytes >= last.query.area_bytes); + assert!(f.tactical.render_cache_bytes >= last.tactical.render_cache_bytes); + assert!(f.tactical.max_render_px >= last.tactical.max_render_px); + assert!(f.pipeline.plan_cache_bytes >= last.pipeline.plan_cache_bytes); + last = f; + } + let roomy = fit(&dicemaster(Some(64 << 30)), &MICRO).unwrap(); + let mut defaults = dicemaster(Some(64 << 30)); + defaults.memory_ceiling = roomy.memory_ceiling; + assert_eq!( + format!("{roomy:?}"), + format!("{defaults:?}"), + "a roomy ceiling keeps every default" + ); +} + +#[test] +fn pinned_flags_keep_their_values() { + let mut c = dicemaster(Some(8 << 30)); + c.query.fine_bytes = 300 << 20; + c.serve.max_connections = 12; + c.pinned = Pinned { + fine_cache: true, + max_connections: true, + ..Pinned::default() + }; + let f = fit(&c, &FULL).unwrap(); + assert_eq!(f.query.fine_bytes, 300 << 20); + assert_eq!(f.serve.max_connections, 12); +} + +/// The figures `crates/arda-server/API.md` § Memory ceiling quotes. +#[test] +fn the_documented_least_ceilings_hold() { + let mib = |c: &ServerConfig, r: &Resident| smallest(c, r).div_ceil(MIB); + assert_eq!(mib(&dicemaster(None), &FULL), 5_505); + assert_eq!(mib(&dicemaster(None), &MICRO), 4_282); +} diff --git a/crates/arda-server/src/lib.rs b/crates/arda-server/src/lib.rs index 4b3dd576..b4e24d62 100644 --- a/crates/arda-server/src/lib.rs +++ b/crates/arda-server/src/lib.rs @@ -12,6 +12,7 @@ pub mod admission; pub mod bindings; pub mod cache; +pub mod ceiling; pub mod columnar; pub mod contract; pub mod derived; @@ -52,7 +53,8 @@ pub use tactical::{Tactical, TacticalLimits}; use std::path::PathBuf; -/// The goal-prompt §8 memory ceiling; configured budgets must fit inside it. +/// The goal-prompt §8 memory ceiling; configured budgets must fit inside +/// it unless `--memory-mib` sets another ([`ServerConfig::memory_ceiling`]). pub const MEMORY_CEILING_BYTES: u64 = 16 << 30; /// Everything needed to serve one world. @@ -84,6 +86,16 @@ pub struct ServerConfig { /// Sheet mapping file (`--sheet-mapping`, goal 69): reshapes every NPC /// the server sends; `None` serves Arda's own shape. pub sheet_mapping: Option, + /// The tactical pipeline's budgets (compositions, composed and refined + /// blocks, town plans). + pub pipeline: admission::PipelineLimits, + /// Per-process memory ceiling, bytes (`--memory-mib`, + /// `ARDA_MEMORY_MIB`): admission holds the worst case under it and every + /// unpinned budget derives from it ([`ceiling::fit`]). `None` admits + /// against [`MEMORY_CEILING_BYTES`] and keeps every budget as set. + pub memory_ceiling: Option, + /// Budgets set by a flag, which a ceiling leaves alone. + pub pinned: ceiling::Pinned, } /// Worst-case transient bytes of one `/area/.../cells` build: 262,144 @@ -111,9 +123,18 @@ impl ServerConfig { bake_workers: tactical::bake::DEFAULT_WORKERS, bake_result_mib: tactical::bake::DEFAULT_RESULT_MIB, sheet_mapping: None, + pipeline: admission::PipelineLimits::default(), + memory_ceiling: None, + pinned: ceiling::Pinned::default(), } } + /// The ceiling admission holds the worst case under. + #[must_use] + pub fn ceiling(&self) -> u64 { + self.memory_ceiling.unwrap_or(MEMORY_CEILING_BYTES) + } + /// Worst-case resident bytes: every cache full, the decoded pyramid base, /// `area_builds` transient area builds (samples, columns, encoding, and /// the 3 × 3 neighbourhood load for coast derivation), one buffered @@ -143,7 +164,7 @@ impl ServerConfig { self.bake_workers, self.bake_result_bytes(), )) - .saturating_add(admission::pipeline_bytes()) + .saturating_add(admission::pipeline_bytes(&self.pipeline)) } /// The finished bake tile sets' budget, bytes. @@ -152,7 +173,7 @@ impl ServerConfig { (self.bake_result_mib as u64).saturating_mul(1 << 20) } - /// Refuses configurations whose worst case exceeds [`MEMORY_CEILING_BYTES`], + /// Refuses configurations whose worst case exceeds [`Self::ceiling`], /// and a bake result budget too small for one worst-case cell set. /// /// # Errors @@ -165,10 +186,10 @@ impl ServerConfig { self.bake_result_mib ))); } - let need = self.admitted_bytes(); - if need > MEMORY_CEILING_BYTES { + let (need, ceiling) = (self.admitted_bytes(), self.ceiling()); + if need > ceiling { return Err(ServerError::ResourceLimit(format!( - "configured budgets need {need} bytes, above the {MEMORY_CEILING_BYTES}-byte ceiling" + "configured budgets need {need} bytes, above the {ceiling}-byte ceiling" ))); } Ok(()) @@ -180,12 +201,16 @@ impl ServerConfig { /// # Errors /// [`ServerError::ResourceLimit`] naming each resident term. pub fn admit_resident(&self, resident: &admission::Resident) -> ServerResult<()> { - let need = self.admitted_bytes().saturating_add(resident.total()); - if need > MEMORY_CEILING_BYTES { + let (need, ceiling) = ( + self.admitted_bytes().saturating_add(resident.total()), + self.ceiling(), + ); + if need > ceiling { return Err(ServerError::ResourceLimit(format!( "configured budgets ({} bytes) plus this world and library ({} bytes: library {}, \ society {}, shore {}, plans {}) need {need} bytes, above the \ - {MEMORY_CEILING_BYTES}-byte ceiling; lower --area-cache-mib or --fine-cache-mib", + {ceiling}-byte ceiling; lower --area-cache-mib or --fine-cache-mib, or set \ + --memory-mib", self.admitted_bytes(), resident.total(), resident.library, @@ -243,6 +268,14 @@ pub struct AppState { /// What the opened world and library hold beyond the configured /// budgets, admitted at startup ([`admission::Resident`]). pub resident: admission::Resident, + /// The admitted worst case of the budgets in force (fitted to the + /// ceiling when there is one), bytes, without [`Self::resident`]. + pub admitted: u64, + /// The ceiling it was admitted against, bytes. + pub ceiling: u64, + /// The connection limits in force (`--max-connections`, or the + /// ceiling's). + pub serve_limits: serve::ServeLimits, /// The world's dungeon and cave sites, placed at open. pub sites: sites::Sites, } @@ -254,14 +287,19 @@ impl AppState { /// # Errors /// Admission, library validation, world loading or limit failures. pub fn open(config: &ServerConfig) -> ServerResult { - config.admit()?; + // Without a ceiling the configured budgets are admitted up front; + // with one they are fitted once the world and library are measured + // (`ceiling`), before anything fills a cache. + if config.memory_ceiling.is_none() { + config.admit()?; + } // Goal 69: a bad mapping refuses startup before the world loads. let sheet_mapping = config .sheet_mapping .as_deref() .map(sheet_map::SheetMapping::load) .transpose()?; - let query = WorldQuery::open(&config.world, config.query)?; + let mut query = WorldQuery::open(&config.world, config.query)?; let mut tactical = Tactical::open(&config.library, query.world().seed(), config.tactical)?; // Request-keyed ETags (review 3.6-11). tactical.set_etags(etag::Etags::new( @@ -288,12 +326,44 @@ impl AppState { None }; if let Some(w) = &people { + // A ceiling sizes the plan cache before the warm-up fills it: + // fitted first without the largest plan, which the warm-up + // draws, then again below with it. + let budget = if config.memory_ceiling.is_some() { + let before = admission::Resident::measure( + tactical.library(), + &config.world, + query.cells(), + None, + ); + ceiling::warm_plan_budget(config, &before) + } else { + config.pipeline.plan_cache_bytes + }; + w.set_plan_budget(budget); // Towns and cities have the costliest plans: draw them now, so // their first tactical block is quick (goal 50): only plans // that read WARM_AREAS areas between them at once, so the areas // in flight fit the refine source (`refine_source` docs). w.warm_towns(refine_source::WARM_AREAS); } + let resident = admission::Resident::measure( + tactical.library(), + &config.world, + query.cells(), + people.as_deref().and_then(largest_plan_bytes), + ); + let fitted = ceiling::fit(config, &resident)?; + let config = &fitted; + config.admit()?; + config.admit_resident(&resident)?; + if config.memory_ceiling.is_some() { + query.set_limits(config.query); + tactical.set_limits(config.tactical); + if let Some(w) = &people { + w.set_plan_budget(config.pipeline.plan_cache_bytes); + } + } // logic/18 §site-place: placed here, before the listener binds, so // `/v1/health` never answers ahead of the site set. let sites = sites::Sites::place( @@ -336,6 +406,7 @@ impl AppState { Some(std::sync::Arc::new(arda_blocks::sites::SiteOverlays::new( society, entrances, ))), + &config.pipeline, ), )); let overview = overview::Overview::new(&query, config.overview)?; @@ -355,14 +426,10 @@ impl AppState { overview.set_labels(labels); } } - let resident = admission::Resident::measure( - tactical.library(), - &config.world, - query.cells(), - people.as_deref().and_then(largest_plan_bytes), - ); - config.admit_resident(&resident)?; Ok(Self { + admitted: config.admitted_bytes(), + ceiling: config.ceiling(), + serve_limits: config.serve, resident, sites, query, diff --git a/crates/arda-server/src/main.rs b/crates/arda-server/src/main.rs index 2ce01c44..4ca3a00d 100644 --- a/crates/arda-server/src/main.rs +++ b/crates/arda-server/src/main.rs @@ -1,6 +1,7 @@ //! `arda-server --world --port 8787 [--library ]`: serves one //! stored world and a tactical asset library under `/v1`. +use arda_server::ceiling::Pinned; use arda_server::serve::{serve, ServeLimits}; use arda_server::{router, AppState, ServerConfig}; use clap::Parser; @@ -27,12 +28,19 @@ struct Args { /// Bind address; loopback by default. #[arg(long, default_value = "127.0.0.1")] host: std::net::IpAddr, - /// Decoded-area cache budget, MiB. - #[arg(long, default_value_t = arda_server::QueryLimits::default().area_bytes >> 20)] - area_cache_mib: usize, - /// Fine-terrain window cache budget, MiB. - #[arg(long, default_value_t = arda_server::QueryLimits::default().fine_bytes >> 20)] - fine_cache_mib: usize, + /// Per-process memory ceiling, MiB (also `ARDA_MEMORY_MIB`): the worst + /// case the server admits stays under it, and every budget not set by + /// a flag below derives from it. Without it the ceiling is 16384 MiB + /// and the budgets are their defaults. + #[arg(long)] + memory_mib: Option, + /// Decoded-area cache budget, MiB [default: 256, or from --memory-mib]. + #[arg(long)] + area_cache_mib: Option, + /// Fine-terrain window cache budget, MiB [default: 128, or from + /// --memory-mib]. + #[arg(long)] + fine_cache_mib: Option, /// Largest `/overview.png` long edge clients may request, pixels. #[arg(long, default_value_t = 8192)] max_overview_px: u32, @@ -46,9 +54,10 @@ struct Args { /// Seconds a client may take to send a complete request head. #[arg(long, default_value_t = 10)] header_timeout_s: u64, - /// Most connections served at once; further clients wait. - #[arg(long, default_value_t = arda_server::serve::ServeLimits::default().max_connections)] - max_connections: usize, + /// Most connections served at once; further clients wait [default: 32, + /// or from --memory-mib]. + #[arg(long)] + max_connections: Option, /// Background threads warming prefetched tactical cells (0 disables). #[arg(long, default_value_t = arda_server::tactical::prefetch::DEFAULT_WORKERS)] prefetch_workers: usize, @@ -57,9 +66,10 @@ struct Args { #[arg(long, default_value_t = arda_server::tactical::bake::DEFAULT_WORKERS)] bake_workers: usize, /// Budget for finished bake tile sets awaiting download, MiB; the - /// oldest finished set is evicted when a new one does not fit. - #[arg(long, default_value_t = arda_server::tactical::bake::DEFAULT_RESULT_MIB)] - bake_result_mib: usize, + /// oldest finished set is evicted when a new one does not fit + /// [default: 384, or from --memory-mib]. + #[arg(long)] + bake_result_mib: Option, /// Sheet mapping file reshaping every served NPC into the game's schema /// (goal 69); checked at startup, a bad file refuses to start. #[arg(long)] @@ -69,21 +79,36 @@ struct Args { async fn run(args: Args) -> Result<(), String> { let world = args.world.ok_or("--world is required")?; let mut config = ServerConfig::new(world); - config.query.area_bytes = args.area_cache_mib << 20; - config.query.fine_bytes = args.fine_cache_mib << 20; + let memory_mib = match args.memory_mib { + Some(m) => Some(m), + None => memory_mib_env()?, + }; + config.memory_ceiling = memory_mib.map(|m| m.saturating_mul(1 << 20)); + config.pinned = Pinned { + area_cache: args.area_cache_mib.is_some(), + fine_cache: args.fine_cache_mib.is_some(), + max_connections: args.max_connections.is_some(), + bake_result: args.bake_result_mib.is_some(), + }; + if let Some(mib) = args.area_cache_mib { + config.query.area_bytes = mib << 20; + } + if let Some(mib) = args.fine_cache_mib { + config.query.fine_bytes = mib << 20; + } config.overview.max_quality_px = args.max_overview_px; config.overview.tile_base_px = args.tile_base_px; config.library = args.library; config.serve = ServeLimits { header_read_timeout: Duration::from_secs(args.header_timeout_s), - max_connections: args.max_connections, + max_connections: args.max_connections.unwrap_or(config.serve.max_connections), }; config.prefetch_workers = args.prefetch_workers; config.bake_workers = args.bake_workers; - config.bake_result_mib = args.bake_result_mib; + if let Some(mib) = args.bake_result_mib { + config.bake_result_mib = mib; + } config.sheet_mapping = args.sheet_mapping; - let limits = config.serve; - let admitted = config.admitted_bytes(); let state = tokio::task::spawn_blocking(move || AppState::open(&config)) .await .map_err(|e| e.to_string())? @@ -99,14 +124,28 @@ async fn run(args: Args) -> Result<(), String> { state.query.world().seed(), state.tactical.library_version(), state.sheet_mapping.as_ref().map_or("none", |m| m.name()), - (admitted + state.resident.total()) >> 20, - arda_server::MEMORY_CEILING_BYTES >> 20 + (state.admitted + state.resident.total()) >> 20, + state.ceiling >> 20 ); + let limits = state.serve_limits; serve(listener, router(Arc::new(state)), limits, shutdown_signal()) .await .map_err(|e| e.to_string()) } +/// `ARDA_MEMORY_MIB`, when set: the ceiling for an image started without +/// arguments. +fn memory_mib_env() -> Result, String> { + match std::env::var("ARDA_MEMORY_MIB") { + Ok(v) if !v.trim().is_empty() => v + .trim() + .parse() + .map(Some) + .map_err(|_| format!("ARDA_MEMORY_MIB {v:?} is not a whole number of MiB")), + _ => Ok(None), + } +} + /// Resolves on Ctrl-C (SIGINT) or, on Unix, SIGTERM, which is what /// `docker stop` sends to PID 1. async fn shutdown_signal() { diff --git a/crates/arda-server/src/query.rs b/crates/arda-server/src/query.rs index 5a136c33..5a8d3759 100644 --- a/crates/arda-server/src/query.rs +++ b/crates/arda-server/src/query.rs @@ -111,6 +111,14 @@ impl WorldQuery { }) } + /// Replaces the cache budgets, emptying the caches: a memory ceiling + /// fits them once the world is open ([`crate::ceiling`]). + pub fn set_limits(&mut self, limits: QueryLimits) { + self.areas = Mutex::new(ByteLru::new(limits.area_bytes)); + self.derived = Mutex::new(ByteLru::new(limits.derived_bytes)); + self.windows = Mutex::new(ByteLru::new(limits.fine_bytes)); + } + /// The stored world. #[must_use] pub fn world(&self) -> &World { diff --git a/crates/arda-server/src/tactical/mod.rs b/crates/arda-server/src/tactical/mod.rs index 07d49160..f63c4d98 100644 --- a/crates/arda-server/src/tactical/mod.rs +++ b/crates/arda-server/src/tactical/mod.rs @@ -102,8 +102,9 @@ impl TacticalLimits { #[must_use] pub fn admitted_bytes(&self) -> u64 { let caches = self.render_cache_bytes + self.pyramid_cache_bytes; - // PNGs, tiles and JSON bodies, plus the composed-block cache. - let encoded = 3 * self.encoded_cache_bytes + refine_blocks::COMPOSED_CACHE_BYTES; + // PNGs, tiles and JSON bodies; the composed-block cache is the + // pipeline's (`admission::pipeline_bytes`). + let encoded = 3 * self.encoded_cache_bytes; (caches + encoded) as u64 + self.transient_render_bytes() + self.transient_encode_bytes() @@ -234,6 +235,17 @@ impl Tactical { }) } + /// Replaces the limits and cache budgets, emptying the caches: a memory + /// ceiling fits them once the library is open ([`crate::ceiling`]). + pub fn set_limits(&mut self, limits: TacticalLimits) { + self.limits = limits; + self.renders = Mutex::new(ByteLru::new(limits.render_cache_bytes)); + self.pyramids = Mutex::new(ByteLru::new(limits.pyramid_cache_bytes)); + self.pngs = Mutex::new(ByteLru::new(limits.encoded_cache_bytes)); + self.tiles = Mutex::new(ByteLru::new(limits.encoded_cache_bytes)); + self.bodies = Mutex::new(ByteLru::new(limits.encoded_cache_bytes)); + } + /// Sets the `ETag`s every response is tagged with. pub fn set_etags(&mut self, etags: crate::etag::Etags) { self.etags = etags; diff --git a/crates/arda-server/src/tactical/refine_blocks.rs b/crates/arda-server/src/tactical/refine_blocks.rs index ef7bae59..040ee06b 100644 --- a/crates/arda-server/src/tactical/refine_blocks.rs +++ b/crates/arda-server/src/tactical/refine_blocks.rs @@ -46,7 +46,8 @@ const DEMO_ANCHORS: usize = 16; pub struct RefineBlocks { pipeline: Pipeline, composed: Mutex>, - /// At most [`COMPOSE_SLOTS`] compositions at a time. + /// At most [`COMPOSE_SLOTS`] compositions at a time, or the ceiling's + /// count. slots: Gate, demos: Mutex>>, society: Option>, @@ -88,12 +89,26 @@ impl RefineBlocks { } /// Blocks over an opened world, with its overlays (the society's and - /// the sites' entrances) when given. + /// the sites' entrances) when given, under the pipeline budgets + /// `limits` (a memory ceiling lowers them, [`crate::ceiling`]). #[must_use] - pub fn with_society(src: SharedSource, society: Option>) -> Self { - let mut b = Self::new(pipeline(Box::new(src))); - b.society = society; - b + pub fn with_society( + src: SharedSource, + society: Option>, + limits: &crate::admission::PipelineLimits, + ) -> Self { + let seed = super::key::render_seed( + arda_refine::Source::seed(&src), + &super::Anchor::Origin(0, 0), + ); + let pipeline = Pipeline::new(Box::new(src), limits.refined_blocks).with_art_seed(seed); + Self { + pipeline, + composed: Mutex::new(ByteLru::new(limits.composed_cache_bytes)), + slots: Gate::new(limits.compose_slots.max(1)), + demos: Mutex::new(BTreeMap::new()), + society, + } } fn demo(&self, at: [i64; 2]) -> Result, BlockError> { diff --git a/crates/arda-server/tests/world_api/admission.rs b/crates/arda-server/tests/world_api/admission.rs index fce8549b..56f3522b 100644 --- a/crates/arda-server/tests/world_api/admission.rs +++ b/crates/arda-server/tests/world_api/admission.rs @@ -5,7 +5,7 @@ use crate::support::{config, society_dir, society_state}; use arda_refine::{CellKey, Source, WorldSource}; -use arda_server::admission::{pipeline_bytes, Resident}; +use arda_server::admission::{pipeline_bytes, PipelineLimits, Resident}; use arda_server::refine_source::{BoundedSource, REFINE_AREAS}; use arda_server::tactical::block::BlockRequest; use arda_server::tactical::cells::APRON; @@ -116,7 +116,7 @@ fn the_default_config_is_admitted_with_the_measured_world() { eprintln!( "admitted {} MiB (pipeline {} MiB) + resident {:?} = {} MiB of {} MiB", c.admitted_bytes() >> 20, - pipeline_bytes() >> 20, + pipeline_bytes(&PipelineLimits::default()) >> 20, s.resident, need >> 20, MEMORY_CEILING_BYTES >> 20 @@ -231,7 +231,7 @@ fn the_plan_cache_is_bounded_in_bytes_and_admits_its_largest_plan() { bytes >= 2 * json + plan.grid.kind.len() as u64, "{bytes} vs {json}" ); - assert!(pipeline_bytes() >= arda_people::people::PLAN_CACHE_BYTES); + assert!(pipeline_bytes(&PipelineLimits::default()) >= arda_people::people::PLAN_CACHE_BYTES); } #[test] diff --git a/crates/arda-server/tests/world_api/ceiling.rs b/crates/arda-server/tests/world_api/ceiling.rs new file mode 100644 index 00000000..8dc0c85e --- /dev/null +++ b/crates/arda-server/tests/world_api/ceiling.rs @@ -0,0 +1,74 @@ +//! `--memory-mib` (logic/16 §api-memory) on the MICRO seed-42 society +//! world: the server opens under a 4.5 GiB ceiling with every derived +//! budget fitted, admits a worst case under it, serves a cell at 64 px per +//! square and refuses a ceiling below its floors, naming the least. + +use crate::support::{config, get_with, society_dir}; +use arda_server::ceiling::{self, ONE_CELL_64_PX}; +use arda_server::{AppState, ServerConfig, ServerError}; +use axum::http::StatusCode; +use std::sync::Arc; + +const MIB: u64 = 1 << 20; + +/// DiceMaster's profile: prefetch on, baking off, under `mib`. +fn dicemaster(mib: u64) -> ServerConfig { + let mut c = config(); + c.world = society_dir().to_path_buf(); + c.bake_workers = 0; + c.memory_ceiling = Some(mib * MIB); + c +} + +#[tokio::test] +async fn a_ceiling_admits_its_worst_case_and_serves_a_64_px_cell() { + let state = AppState::open(&dicemaster(4_608)).unwrap(); + let need = state.admitted + state.resident.total(); + eprintln!( + "admitted {} MiB + resident {} MiB = {} MiB of {} MiB", + state.admitted / MIB, + state.resident.total() / MIB, + need / MIB, + state.ceiling / MIB + ); + assert_eq!(state.ceiling, 4_608 * MIB); + assert!(need <= state.ceiling, "{need} > {}", state.ceiling); + assert!(state.tactical.limits().max_render_px >= ONE_CELL_64_PX); + assert!(state.serve_limits.max_connections >= 8); + let state = Arc::new(state); + let cell = get_with( + Arc::clone(&state), + "/v1/tactical/cell/479/1245?ppsq=64", + None, + ) + .await; + assert_eq!(cell.status, StatusCode::OK); + let png = get_with(state, "/v1/tactical/cell/479/1245.png?ppsq=128", None).await; + assert_eq!( + png.status, + StatusCode::PAYLOAD_TOO_LARGE, + "a 128-px cell needs more than the fitted render size" + ); +} + +#[test] +fn a_ceiling_below_the_floors_refuses_to_start_naming_the_least() { + let err = AppState::open(&dicemaster(2_048)).unwrap_err(); + let ServerError::ResourceLimit(text) = &err else { + panic!("{err}"); + }; + assert!(text.contains("--memory-mib 2048 is below the"), "{text}"); + let least: u64 = text + .split("below the ") + .nth(1) + .and_then(|t| t.split(' ').next()) + .and_then(|n| n.parse().ok()) + .unwrap(); + assert!(AppState::open(&dicemaster(least)).is_ok(), "{least} MiB"); + let probe = dicemaster(least); + let state = AppState::open(&probe).unwrap(); + assert_eq!( + ceiling::smallest(&probe, &state.resident).div_ceil(MIB), + least + ); +} diff --git a/crates/arda-server/tests/world_api/main.rs b/crates/arda-server/tests/world_api/main.rs index 230d163f..ed8c70b6 100644 --- a/crates/arda-server/tests/world_api/main.rs +++ b/crates/arda-server/tests/world_api/main.rs @@ -4,6 +4,7 @@ mod admission; mod bake; +mod ceiling; mod cells; mod contract; mod dungeon; diff --git a/tools/docker-entrypoint.sh b/tools/docker-entrypoint.sh index 4fb5977c..38e3d881 100755 --- a/tools/docker-entrypoint.sh +++ b/tools/docker-entrypoint.sh @@ -3,7 +3,8 @@ # mounted at /worlds/world on 0.0.0.0:8787 with the best library the image # holds (the AI library stacked over the placeholder when present, else the # placeholder alone). ARDA_LIBRARY overrides the library, ARDA_WORLD the -# world path. With arguments, they go to arda-server verbatim. +# world path. ARDA_MEMORY_MIB, read by arda-server itself, caps the +# process (--memory-mib). With arguments, they go to arda-server verbatim. set -eu if [ "$#" -gt 0 ]; then From a599ea2b5df510e69760f8a61cdebb2be1c2eb6d Mon Sep 17 00:00:00 2001 From: Gent Bajko Date: Sun, 15 Nov 2026 00:13:51 +0100 Subject: [PATCH 2/2] docs: the memory ceiling in the API reference, logic/16, operations and the ledger --- CHANGELOG.md | 7 +++++++ docs/capstone/07-operations.md | 1 + docs/capstone/changelog.md | 13 +++++++++++++ docs/capstone/logic/16-service-api.md | 10 +++++++++- docs/capstone/open-items.md | 9 +++++++++ 5 files changed, 39 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0db8ce3d..35fb56ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,13 @@ Release notes for Arda. The design ledger (decisions, stage records and per-change detail) lives in `docs/capstone/changelog.md` and `docs/capstone/changelog.d/`. +## Unreleased + +**Server** + +- `--memory-mib ` (or `ARDA_MEMORY_MIB`) caps one `arda-server` process: startup admits the worst case (every cache and transient, plus what the world and library hold) under it instead of under 16 GiB, and every budget not set by a flag derives from it: the query, overview, relief and tactical caches, the largest render, connections, area builds, compositions, the composed- and refined-block caches, the town-plan budget and, with baking on, the bake results. A ceiling below what the world needs refuses to start and names the least ceiling. Least ceilings for prefetch on and baking off: 5,507 MiB for the 500 × 1,000 km seed-42 world, 4,282 MiB for the MICRO kit world. At its least the full-size world peaks at 2.7 GiB over a 150-cell walk at 64 px per square, and a prefetched cell's JSON is served in 42 ms at p95. Without the flag nothing changes. +- With a ceiling, a render larger than the fitted size is refused with `413 payload_too_large`; at the least ceiling only 64 px per square cells render. + ## 1.1.1 — 2026-11-14 Dependency security updates. No API, format or content change from 1.1.0, which was tagged but not published; 1.1.1 is the first published release with the dungeon and cave sites described under 1.1.0. diff --git a/docs/capstone/07-operations.md b/docs/capstone/07-operations.md index bcd450bc..6c2571ae 100644 --- a/docs/capstone/07-operations.md +++ b/docs/capstone/07-operations.md @@ -99,6 +99,7 @@ Defined in `crates/arda-server/src/main.rs:16`; routes are nested under `/v1` (` | `--world` | required unless `--probe` | `crates/arda-server/src/main.rs:19` | | `--port` | 8787 | `crates/arda-server/src/main.rs:26` | | `--host` | `127.0.0.1` | `crates/arda-server/src/main.rs:29` | +| `--memory-mib` | none (16,384 MiB ceiling, every budget its default); also `ARDA_MEMORY_MIB`. With a value, admission holds the worst case under it and every unpinned budget derives from it (`crates/arda-server/src/ceiling/mod.rs`; API.md § Memory ceiling) | `crates/arda-server/src/main.rs` | | `--area-cache-mib` | 256 (`crates/arda-server/src/query.rs:42`; 1024 before review 3.6-8, 384 before the server-startup fix) | `crates/arda-server/src/main.rs:32` | | `--fine-cache-mib` | 128 (`crates/arda-server/src/query.rs:44`; 512 before review 3.6-8, 256 before the server-startup fix) | `crates/arda-server/src/main.rs:35` | | `--max-overview-px` | 8192 | `crates/arda-server/src/main.rs:38` | diff --git a/docs/capstone/changelog.md b/docs/capstone/changelog.md index ddd7f44c..69a4daee 100644 --- a/docs/capstone/changelog.md +++ b/docs/capstone/changelog.md @@ -2,6 +2,19 @@ generated_date: 2026-08-24 --- +## 2026-11-14 - implement: 2026-11-14-memory-ceiling +key: implement/2026-11-14-memory-ceiling@Q4 + +- What: `--memory-mib` / `ARDA_MEMORY_MIB`, one setting that caps an `arda-server` process, for DiceMaster's three worlds on one 16 GB box. +- Approach: `ceiling::fit` puts every unpinned budget at `floor + s × (default − floor)` with one shared `s`, the largest whose admitted worst case plus the measured residents fits; admission checks the same sum against the ceiling. `AppState::open` measures the residents before filling caches (the town warm-up runs under the plan budget fitted without the largest plan), then resizes the query, tactical and plan caches. The pipeline's constants (compositions, composed and refined blocks, plan budget) became `PipelineLimits`. +- Rejected: a fixed 4.5 GiB profile (the brief: a setting, not a number); per-budget flags for the unflagged caches (the ask was one setting); scaling the fixed estimates (relief working set, area build, connection body) without measuring them. +- Divergence: the brief's target, about 4.5 GiB for a full-size world, is not reachable: the least ceiling is 5,507 MiB (residents 1,409 MiB: library 89, society 773, shore 85, largest town plan 462). Recorded as OI-65; several worlds in one process as OI-66. +- Found while measuring: one composition slot at the floor made a request wait behind the prefetch workers (MICRO at 4,608 MiB: prefetched cell p95 680 ms); the floor is two, as by default (276 ms). +- Measured (Ryzen 9 9950X3D, release, 150-cell walk at 64 px per square with 12 view tiles and a ring prefetch per step): full42 at 5,507 MiB opens in 14.4 s, idles at 2,360 MiB, peaks at 2,723 MiB; prefetched cell JSON p50 1.1 ms, p95 42 ms; view tiles p95 86 ms; re-walk 11 of 118 cell bodies missed. Default config on the same walk: peak 6,764 MiB, prefetched p95 224 ms, view tiles p95 1,325 ms (prefetch renders up to ten neighbour images per step). MICRO at 4,608 MiB: peak 1,609 MiB, prefetched p95 276 ms, re-walk 332 ms, 33 of 150 bodies missed. +- Tests: `ceiling::tests` (no ceiling changes nothing; every fitted worst case at every ceiling from the least to 16 GiB, four flag profiles, MICRO and full residents, stays under it; below the least refuses naming it; budgets grow with the ceiling to the defaults; pinned flags kept; documented least ceilings); `world_api/ceiling.rs` (MICRO opens at 4,608 MiB, admits 4,575 MiB, serves a 64 px cell, refuses a 128 px PNG with 413; 2,048 MiB refuses naming the least, which opens). +- Process: the user was away; spec and plan written from the DiceMaster session's brief without the approval gates; the pull request is the gate. +- `API.md` § Memory ceiling and the flag row; `logic/16` §api-memory; `07-operations.md` flag row; `open-items.md` OI-65, OI-66; `tools/docker-entrypoint.sh` comment. + ## 2026-11-14 - implement: 2026-11-14-dungeon-sites key: implement/2026-11-14-dungeon-sites@Q12 diff --git a/docs/capstone/logic/16-service-api.md b/docs/capstone/logic/16-service-api.md index 7f6236e7..0f4816d9 100644 --- a/docs/capstone/logic/16-service-api.md +++ b/docs/capstone/logic/16-service-api.md @@ -14,7 +14,7 @@ Code cites rules as `// logic/16 §`. ## Trigger & preconditions - Trigger: `arda-server --world [--library ] [--port 8787] [--host 127.0.0.1]` and HTTP requests. -- Preconditions at start: the world loads (`World::load`); the tactical library validates (11 §validator); `society/` is optional (routes that need it answer `404 not_found` naming the missing file); cache budgets pass admission against the 16 GiB ceiling (§api-cache). Any failure refuses to start with the reason on stderr. Before serving, the most populous towns and cities have their plans drawn (goal 50): most populous first, in batches whose plans read at most 8 areas between them (`refine_source::WARM_AREAS`, the refine source's area bound) and whose plan estimates fit the plan budget beside the cache, until the cache holds half its count or bytes. Before this, 32 plans across the world thrashed the refine source, which reopened and re-verified the whole world every few reads, and startup never finished at default size. +- Preconditions at start: the world loads (`World::load`); the tactical library validates (11 §validator); `society/` is optional (routes that need it answer `404 not_found` naming the missing file); cache budgets pass admission against the 16 GiB ceiling, or the `--memory-mib` one (§api-cache, §api-memory). Any failure refuses to start with the reason on stderr. Before serving, the most populous towns and cities have their plans drawn (goal 50): most populous first, in batches whose plans read at most 8 areas between them (`refine_source::WARM_AREAS`, the refine source's area bound) and whose plan estimates fit the plan budget beside the cache, until the cache holds half its count or bytes. Before this, 32 plans across the world thrashed the refine source, which reopened and re-verified the whole world every few reads, and startup never finished at default size. ## Rules @@ -132,6 +132,14 @@ The political map is the default look of `arda-settle render` and the `political - Every tactical build is single-flight per key (`crates/arda-server/src/flight.rs`): a full-resolution render, pyramid, PNG, tile, JSON body or block composition runs once per key at a time and concurrent requests for the same key wait for it (review 3.6-1). Requests are cancellable: a request whose client disconnects leaves the request lane, the encode slot or another build's queue and starts no further stage; a stage already running finishes and caches its result, so bytes stay deterministic (review 3.6-2). A tile pyramid shares its render as its deepest level and the render cache then lets the render go, so a render is held once; a PNG of the same key reads it from the pyramid (review 3.6-5). Compositions refine their cells and run their three overlay layers on the shared, bounded rayon pool, never a thread per request (review 3.6-12). - Bakes bypass every shared cache: `POST /v1/tactical/bake` reads and writes no render, pyramid, PNG or tile entry, and keeps only the encoded tiles of finished jobs, in memory, within `--bake-result-mib` (default 384 MiB, oldest finished set evicted first, no time-to-live) until `DELETE`. Admission adds, when baking is on, one transient render with its pyramid, the parsed bodies of the queued jobs and the result budget (about 1.9 GiB with defaults, 15.9 GiB in all), and refuses a result budget below one worst-case 128-ppsq set (341 tiles, about 362 MiB). +### §api-memory + +- `--memory-mib` (or `ARDA_MEMORY_MIB`) sets the ceiling admission holds the worst case under, in place of 16 GiB (§api-cache). Without it nothing changes. +- With it, every budget not pinned by a flag is `floor + s × (default − floor)` with one shared `s ∈ [0, 1]`, the largest for which the configured worst case plus the measured residents (library, `society/`, shore, largest town plan) fit the ceiling (`ceiling::fit`). The floors serve a cell at 64 px per square: renders of one cell with its apron (23.7 Mpx), a render cache of one such render, a pyramid cache of its pyramid, two concurrent compositions (with one, a request whose prefetch has not finished waits behind the prefetch workers), 8 connections, one area build. +- The residents are measured before any cache is filled: the town warm-up runs under the plan budget fitted without the largest plan, then the configuration is fitted with it and the query, tactical and plan caches are resized before sites are placed. +- A ceiling below the floors refuses to start, naming the least ceiling in MiB and each resident term. +- A fitted server refuses a render above its `max_render_px` with 413, as any server does above its limit. + ### §api-prefetch `POST /v1/tactical/prefetch` enqueues a cell's 8 neighbours at low priority (`radius` 1, or 2 for the 24 cells of two rings), nearest ring first and cardinal neighbours before diagonals, which also take the image slots first. The queue is bounded (64 cells) and deduplicated; when full, its oldest waiting cells give way to the fresh ones (review 3.6-5). Prefetching never changes any response's bytes. Prefetch stops at sea cells and the world edge (goal 67). A prefetch or bake job that panics is caught: prefetch drops it, bake marks it `failed` with `internal`, and the worker carries on (review 3.6-7). diff --git a/docs/capstone/open-items.md b/docs/capstone/open-items.md index 2b15dd6b..9634ed73 100644 --- a/docs/capstone/open-items.md +++ b/docs/capstone/open-items.md @@ -331,6 +331,15 @@ Left open by the dungeon and cave sites feature (logic/18 §site-place to §site | OI-63 | Site placement cost on a default-size world | Placement runs in `AppState::open` as one sequential pass over every area and holds one `CellFacts` per cell until the sites are chosen (`crates/arda-server/src/sites/mod.rs:111`); on the MICRO fixture a release server reaches `/v1/health` in 2.3 s, placement included. | A measurement on a 500 × 1000 km world (none exists on the development machine): start time with about 200 areas read, and the transient of about 200 MB, which admission does not count. If it is slow, place per area in parallel. | | OI-64 | AI-library art for the site props (closed 2026-11-14) | Placeholder `prop.site_entrance`, `prop.cave_mouth`, `prop.stairs_sealed` and their `tools/art-gen` prompt families (`tools/art-gen/expansion.mjs`). Generated art for all three is in the maintainer's AI library (`out/art-gen/lib/props/`, 1,462 assets), imported with the openings painted black and checked in context on a dungeon entrance cell, a cave cell and a sealed deepest level. | `.alt1` variants of the three props. The AI library is not published (D1), so the released image draws the placeholder art. | +## Open items recorded on `feat/memory-ceiling` (2026-11-14) + +Left open by the per-process memory ceiling (`--memory-mib`, logic/16 §api-memory), asked for by DiceMaster's plan of three worlds on one 16 GB box. + +| ID | Item | Exists | Does not exist | +|---|---|---|---| +| OI-65 | A full-size world under about 4.5 GiB | `--memory-mib` fits every derived budget to the ceiling; the least ceiling for DiceMaster's profile on the 500 × 1,000 km seed-42 world is 5,507 MiB (MICRO: 4,282 MiB), so three such processes admit 16.1 GiB, above the 14.5 GiB DiceMaster leaves them. Measured use is far below the admitted worst case (peak RSS 2.7 GiB at 5,507 MiB over a 150-cell walk). | Lower fixed terms. The largest are estimates, not measurements: the relief working set (768 MiB, `relief::RELIEF_WORKING_BYTES`), one area build (512 MiB, `AREA_BUILD_BYTES`), 48 MiB a connection (`MAX_BODY_BYTES`), the parsed `society/` files at twice their size (773 MiB on the full world) and the largest town plan (462 MiB). Measuring and tightening them, or one process serving several worlds under one ceiling (see the next row), is the maintainer's call. | +| OI-66 | Several worlds in one process | One process serves one world. | One process serving three worlds would admit the per-process fixed terms once: one area build, the connections' bodies, each lane's transient render and encode and the two compositions, about 2.2 GiB at the floors, so three full-size worlds would admit about 12.1 GiB instead of 16.1 GiB. It needs a world segment in every route (`/v1/{world}/…` or a header), a shared cache budget across worlds and per-world ETags; a larger change than the ceiling, not started. | + ## Scope boundaries and conditional extensions These are explicit future choices, not hidden blockers for the map pipeline.