Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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.
Expand Down
51 changes: 50 additions & 1 deletion crates/arda-server/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,12 +24,13 @@ docker run --rm -p 8787:8787 -v /abs/world:/worlds/world:ro arda:local
| `--world <dir>` | 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 <dir>` | `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 <file>` | 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 |

Expand Down Expand Up @@ -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 <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:
Expand Down
46 changes: 37 additions & 9 deletions crates/arda-server/src/admission.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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.
Expand Down Expand Up @@ -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}");
Expand Down
187 changes: 187 additions & 0 deletions crates/arda-server/src/ceiling/mod.rs
Original file line number Diff line number Diff line change
@@ -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<ServerConfig> {
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;
Loading
Loading