Files
horizon-airdef/crates/horizon-server/src/reference.rs
T
Ludovic Marie f80d00802e Server reference generated from horizon-server's source
docs/api/server-reference.md lists horizon-server's commands (its help
text), every server.toml key (config::TEMPLATE: default, the
server.properties key it writes, what it does) and the control API's
endpoints. Tests fail when the page is out of date (HORIZON_WRITE_DOCS=1
rewrites it), when the template and Config disagree on the keys, when a key
has no comment, or when api::ROUTES and the endpoints route() answers
differ.

api::ROUTES replaces the endpoint list in api.rs's module comment and the
hand-kept path list of the 405 arm. The template's uncommented keys get a
comment (what init writes for new servers; no setting changes).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-24 20:42:51 +02:00

191 lines
6.8 KiB
Rust

//! docs/api/server-reference.md: `horizon-server`'s commands, every `server.toml` key and the control API's
//! endpoints, generated from the source, and the tests that fail when it is out of date. Update it with:
//! `HORIZON_WRITE_DOCS=1 cargo test -p horizon-server reference`.
use crate::{api::ROUTES, config};
use std::fmt::Write;
const DOC: &str = "docs/api/server-reference.md";
/// One `key = value # what it means` line of the template, under its `[section]`.
struct Key {
section: String,
name: String,
default: String,
what: String,
}
/// The template's sections, each with the comment lines above it, and its keys, in order.
fn template() -> (Vec<(String, String)>, Vec<Key>) {
let (mut sections, mut keys, mut notes) = (Vec::new(), Vec::new(), Vec::<&str>::new());
for line in config::TEMPLATE.lines().map(str::trim) {
if let Some(note) = line.strip_prefix('#') {
notes.push(note.trim());
} else if let Some(section) = line.strip_prefix('[').and_then(|l| l.strip_suffix(']')) {
sections.push((section.to_owned(), notes.join(" ")));
notes.clear();
} else if let Some((name, rest)) = line.split_once(" = ") {
let (default, what) = rest.split_once(" # ").unwrap_or((rest, ""));
keys.push(Key {
section: sections.last().map(|(s, _)| s.clone()).unwrap_or_default(),
name: name.trim().to_owned(),
default: default.trim().to_owned(),
what: what.trim().to_owned(),
});
}
}
(sections, keys)
}
pub fn markdown() -> String {
let mut out = String::new();
let w = &mut out;
let _ = writeln!(
w,
"<!-- Generated from crates/horizon-server/src (the help text, config::TEMPLATE, api::ROUTES) by reference.rs; a test fails when this file is out of date. Update it with: HORIZON_WRITE_DOCS=1 cargo test -p horizon-server reference -->"
);
let _ = writeln!(w, "# Server reference\n");
let _ = writeln!(
w,
"Everything `horizon-server` offers a host or a tool: its commands, every `server.toml` key and the \
control API. How to host: [hosting.md](../hosting.md); the design: [server.md](../server.md); \
stability and versions: [stability.md](stability.md).\n"
);
let _ = writeln!(w, "## Commands\n\n`horizon-server help` prints:\n");
let _ = writeln!(w, "```text\n{}```\n", crate::HELP);
let _ = writeln!(w, "## `server.toml`\n");
let (sections, keys) = template();
let _ = writeln!(
w,
"{} Unknown keys are refused. `horizon-server init` writes this file with these defaults; \
`horizon-server config set SECTION.KEY=VALUE` changes it.\n",
sections[0].1
);
for (i, (section, note)) in sections.iter().enumerate() {
let _ = writeln!(w, "### `[{section}]`\n");
if i > 0 && !note.is_empty() {
let _ = writeln!(w, "{note}\n");
}
let rows: Vec<&Key> = keys.iter().filter(|k| &k.section == section).collect();
if rows.is_empty() {
continue;
}
let _ = writeln!(
w,
"| Key | Default | In `server.properties` | What it does |\n| --- | --- | --- | --- |"
);
for k in rows {
let vanilla = config::TYPED
.iter()
.find(|(s, n, _)| s == section && *n == k.name)
.map_or(String::new(), |(_, _, v)| format!("`{v}`"));
let _ = writeln!(
w,
"| `{}` | `{}` | {vanilla} | {} |",
k.name, k.default, k.what
);
}
let _ = writeln!(w);
}
let _ = writeln!(w, "## Control API (`/api/v1`)\n");
let _ = writeln!(
w,
"HTTP and JSON on 127.0.0.1. A running server writes its address and a random token to \
`.horizon/api.json`, readable only by its own user; every request sends \
`Authorization: Bearer <token>` and a `Host` that is that address. Errors answer \
`{{\"error\": \"...\"}}` with 400, 401, 403, 404, 405 or 409. The web panel uses the same \
routes with its session.\n"
);
let _ = writeln!(
w,
"| Method | Path | Takes | Answers | What it does |\n| --- | --- | --- | --- | --- |"
);
for r in &ROUTES {
let takes = if r.takes.is_empty() {
"nothing"
} else {
r.takes
};
let _ = writeln!(
w,
"| `{}` | `{}` | {takes} | {} | {} |",
r.method, r.path, r.answers, r.what
);
}
out
}
#[test]
fn the_server_reference_is_up_to_date() {
let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../..")
.join(DOC);
let want = markdown();
if std::env::var_os("HORIZON_WRITE_DOCS").is_some() {
std::fs::write(&path, &want).unwrap();
}
let have = std::fs::read_to_string(&path)
.unwrap_or_default()
.replace("\r\n", "\n");
assert!(
have == want,
"{DOC} is out of date: HORIZON_WRITE_DOCS=1 cargo test -p horizon-server reference"
);
}
/// The template, which the reference lists, holds every key `Config` reads and no other.
#[test]
fn the_reference_lists_every_setting() {
let config = toml::Value::try_from(config::Config::default()).unwrap();
let mut listed: Vec<String> = template()
.1
.iter()
.map(|k| format!("{}.{}", k.section, k.name))
.collect();
let mut read: Vec<String> = config
.as_table()
.unwrap()
.iter()
.filter_map(|(section, keys)| Some((section, keys.as_table()?)))
.flat_map(|(section, keys)| keys.keys().map(move |k| format!("{section}.{k}")))
.collect();
listed.sort();
read.sort();
assert_eq!(listed, read);
for key in template().1 {
assert!(
!key.what.is_empty(),
"{}.{} needs a `# what it does` comment in config::TEMPLATE",
key.section,
key.name
);
}
}
/// `ROUTES` holds exactly the endpoints the API's code answers.
#[test]
fn the_routes_table_matches_the_code() {
let source = include_str!("api.rs");
let mut answered: Vec<(String, String)> = Vec::new();
for method in ["GET", "POST"] {
let open = format!("(\"{method}\", \"/api/v1/");
for (at, _) in source.match_indices(&open) {
let rest = &source[at + open.len()..];
let path = &rest[..rest.find('"').unwrap()];
if rest[path.len()..].starts_with("\")") {
answered.push((method.into(), format!("/api/v1/{path}")));
}
}
}
let mut listed: Vec<(String, String)> = ROUTES
.iter()
.map(|r| (r.method.into(), r.path.into()))
.collect();
answered.sort();
listed.sort();
assert_eq!(answered, listed);
}