didbot_config/

sections.rs

//! One struct per `[section]`, read from the real flag set and from
//! `didbot-serve/src/routes.rs`'s constants — see the crate root for which
//! of these a caller actually applies today.
//!
//! Every struct here carries `#[serde(deny_unknown_fields)]` and every field
//! is optional: a section an operator has not written is a section this
//! binary decides on its own, the same as a flag nobody passed. What a
//! section may **not** hold is a scope, a permission, or an allowlist of
//! apps — see the crate root's doc for why.

use serde::{Deserialize, Serialize};

/// Where the server binds and listens.
///
/// Reload: needs a restart. A listener is bound once, at startup.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ServerSection {
    /// The address to bind, as an IP literal. No flag mirrors this, only
    /// this key.
    ///
    /// Unset binds `::`, the unspecified IPv6 address, which accepts IPv4
    /// callers too through a dual-stack socket: one listener answers both
    /// families, and `127.0.0.1` and `[::1]` both reach it. Naming an
    /// address narrows that. `127.0.0.1` reaches only callers on this host,
    /// which is what a deployment behind a reverse proxy on the same
    /// machine wants; a host's own public address pins the listener to one
    /// interface on a machine with several.
    ///
    /// An address this host does not hold refuses startup, from the bind
    /// itself, naming the address.
    pub bind: Option<String>,
    /// The port to listen on. Mirrors `--port`.
    ///
    /// **Reasonable range: 1024 to 65_535.** Below 1024 a Unix host wants
    /// privileges this process should not be started with; a deployment
    /// that answers the internet on 443 gets there through a proxy or a
    /// redirect, not by running as root. The built-in default is 3000.
    pub port: Option<u16>,
    /// How long a stop waits for requests in flight once it has stopped
    /// accepting, in seconds. No flag mirrors this, only this key.
    ///
    /// **Reasonable range: 1 to 60.** A request that outlives it is cut
    /// off. The deployment's unit allows 200 seconds from `SIGTERM` to
    /// `SIGKILL`, which this and `stop_checkpoint_secs` share. The built-in
    /// default is 10.
    pub drain_secs: Option<u64>,
    /// How long a stop waits for a checkpoint taken while the server still
    /// serves, in seconds, before it stops accepting. The next boot then
    /// replays only what was written after it. No flag mirrors this, only
    /// this key.
    ///
    /// **Reasonable range: 0 to 120.** 0 takes no checkpoint on a stop. A
    /// checkpoint still running when this runs out is abandoned, which
    /// costs nothing: the next boot replays from the one before. The
    /// built-in default is 30.
    pub stop_checkpoint_secs: Option<u64>,
}

/// The zones accounts are minted under, and who answers for them.
///
/// Reload: needs a restart. The zone is load-bearing for every DID this
/// process has already minted; changing it under a running server would
/// make existing accounts unresolvable against the new value.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ZoneSection {
    /// Mirrors `--zone`, and holds the same list. The first is the primary:
    /// the server's own hostname. Every zone mints accounts one label under
    /// it, and gets its own DNS backend and, under ACME, its own certificate
    /// pair. Unset leaves `agents.localhost`, which is what a local run
    /// wants.
    ///
    /// **Reasonable range: 1 to 20 zones.** Each one is a certificate pair
    /// renewed on its own schedule, an apex and a wildcard record, and a
    /// Route53 hosted zone id. A deployment with one zone writes a list of
    /// one.
    pub zones: Option<Vec<String>>,
    /// Mirrors `--operator`. The DID answerable for every account this run
    /// mints — never a scope or a permission, only an identifier.
    ///
    /// Outside `.localhost` the server polls this DID's repository for its
    /// `bot.did.operator` claim and its policy records, so it is the DID
    /// whose records govern this deployment as well as the one a stranger
    /// reads to find someone accountable.
    pub operator: Option<String>,
    /// The URL agents are told to use as their PDS endpoint, and the one
    /// written into every DID document this server publishes. No flag
    /// mirrors this, only this key.
    ///
    /// Unset, it is derived from the primary zone: `https://<zone>`, plus
    /// the bound port when this run did not take 443. Set it when the
    /// address agents reach is not the address this process binds — a
    /// deployment behind a proxy that terminates TLS on a different
    /// hostname, for instance.
    ///
    /// It is published, not just used: an endpoint that does not reach this
    /// server makes every account this run mints unreachable, and the DID
    /// documents already carrying it do not change when this does.
    pub pds_endpoint: Option<String>,
}

/// DNS provider selection, once [`dns-providers`](../../../plan/dns-providers.md)
/// lands a second backend.
///
/// Reload: needs a restart. A provider swap changes which credential the
/// process holds open.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DnsSection {
    /// Which `DnsProvider` to construct: `loopback`, `wildcard`, `route53`,
    /// or a name a later backend adds.
    pub provider: Option<String>,
    /// The zone id the provider writes, when the provider needs one beyond
    /// `zone.zone` itself (Route53's hosted zone id, for instance).
    pub zone_id: Option<String>,
    /// Whether this deployment may create new zones by writing `NS` records
    /// into the zone above the one it is creating.
    ///
    /// Two postures exist. *Create* needs write access above the zone it
    /// delegates, and this is what turns that on. *Use handed zones* — an
    /// operator creates the delegation out of band and hands over an
    /// already-hosted zone — needs nothing above it, and is the recommended
    /// posture; it is also what `None` (the default) means, so a deployment
    /// gets it without an operator having to opt in. Left unset, a create
    /// attempt is refused at the point of decision rather than surfacing
    /// later as an access-denied error from the DNS provider itself.
    pub may_create_zones: Option<bool>,
}

/// TLS certificate sourcing, mirroring `didbot-tls`'s configuration surface.
///
/// Reload: the certificate itself hot-reloads once issued (`didbot-tls`'s
/// `SwappableCert`); the ACME environment and contact address do not — they
/// govern how the *next* certificate is obtained, not the one already
/// served.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TlsSection {
    /// `staging` or `production` ACME directory. Mirrors
    /// `--acme-environment`.
    ///
    /// Staging (the default) issues untrusted certificates against generous
    /// rate limits, which is what iterating on a deployment wants.
    /// Production has hard weekly rate limits, and a run that burns them
    /// waits a week.
    pub acme_environment: Option<String>,
    /// Contact URIs (`mailto:ops@example.com`) for the ACME account.
    /// Mirrors `--acme-contact`, and holds the same list.
    pub contact: Option<Vec<String>>,
    /// Where the certificate comes from: `acme` or a path to a fixed pair,
    /// for development.
    pub cert_source: Option<String>,
    /// Which authority issues this deployment's certificate: `acme` or
    /// `local`. Mirrors `--tls`.
    ///
    /// Unset takes the one authority the primary zone may use, which is
    /// `local` for a zone under `.localhost` and `acme` for any other.
    pub mode: Option<String>,
    /// The directory holding the local certificate authority `local` signs
    /// with. Mirrors `--tls-ca`.
    ///
    /// Unset keeps it under `$XDG_STATE_HOME/didbot`, which is one
    /// authority per machine: a developer trusts it once, and every local
    /// server on that machine presents leaves it signed. Point two
    /// checkouts at one directory to share an authority, or at two to keep
    /// them apart.
    pub ca_dir: Option<String>,
    /// The `max-age` of the `Strict-Transport-Security` header, in seconds.
    /// No flag mirrors this, only this key. Unset is 63_072_000, two years,
    /// the same as did.bot's own header (`infra/site/`).
    ///
    /// Sent only by a run with `mode = "acme"` and
    /// `acme_environment = "production"`. A browser that has seen the header
    /// refuses a certificate error under the names it covers for this long,
    /// with no way to click through, and every other certificate this
    /// server can serve chains to a root browsers do not trust.
    ///
    /// **Reasonable range: 15_768_000 (six months) to 63_072_000 (two
    /// years).** Below six months, SSL Labs and the HTTP Observatory score
    /// the header as absent. `0` tells a browser to drop the header it
    /// already holds, which is how a deployment backs out of one.
    pub hsts_max_age_secs: Option<u64>,
    /// Whether the `Strict-Transport-Security` header carries
    /// `includeSubDomains`. No flag mirrors this, only this key. Unset is
    /// `false`.
    ///
    /// `true` commits every name below the one a browser reached, including
    /// names this server does not serve. That is right when this server's
    /// zone is its own domain, so every name below it is an account served
    /// under this server's wildcard certificate. It is wrong when the server
    /// sits at a domain that has other hosts.
    pub hsts_include_subdomains: Option<bool>,
}

/// What one blob, one account's blobs, and every account's blobs together
/// may come to.
///
/// Reload: needs a restart today. A running quota is enforced against the
/// value the store was built with; there is no seam to adjust it live.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct BlobsSection {
    /// Longest a single blob may be, in bytes. Mirrors `--max-blob`. The
    /// built-in default is 5 MiB (5_242_880).
    ///
    /// **Reasonable range: 1_000_000 to `account_quota_bytes`.** 1_000_000
    /// is the largest image `app.bsky`'s lexicons accept, such as an avatar,
    /// so below it an agent cannot upload one. Above the account quota, no
    /// blob that long can be stored.
    pub max_blob_bytes: Option<u64>,
    /// What one account's blobs may come to, in bytes. Mirrors
    /// `--blob-quota`. The built-in default is 64 MiB (67_108_864).
    ///
    /// **Reasonable range: `max_blob_bytes` to `total_quota_bytes`.** Below
    /// `max_blob_bytes`, an account cannot store one blob of the size it is
    /// allowed. Above the total, one account can fill what every account
    /// shares.
    pub account_quota_bytes: Option<u64>,
    /// What every account's blobs may come to together, in bytes. No flag
    /// mirrors this, only this key. An upload past it is refused with
    /// `507 StorageFull`, naming this total.
    ///
    /// **Reasonable range: `account_quota_bytes` to half the data volume.**
    /// Below one account's quota, the total refuses an account the quota it
    /// was promised. Above half, the rest of the volume may not hold what
    /// shares it: the log up to `[capacity] log_budget_bytes`, two
    /// checkpoints as large as the state while a new one is written, and the
    /// record heap, which grows with every record written. Unset, only each
    /// account's quota bounds the blobs, and that quota times the number of
    /// accounts can be more than the volume holds.
    pub total_quota_bytes: Option<u64>,
    /// How long a deleted blob is kept before collection, in seconds.
    /// Named `collection_grace` to match
    /// `didbot_pds::blobs::BlobLimits`'s field of the same name on the
    /// branch that adds it, rather than inventing a second name for the
    /// same setting.
    pub collection_grace_secs: Option<u64>,
}

/// How many accounts this deployment may hold at once, and other bounds on
/// what this deployment keeps rather than what an agent may do.
///
/// Reload: needs a restart today. Enforced against the value `AppState` was
/// built with, the same as [`BlobsSection`]'s quotas.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CapacitySection {
    /// Mirrors `--max-accounts`. See `plan/capacity.md`.
    ///
    /// **Reasonable range: 1 to 100_000.** One account is a deployment that
    /// exists to run a single agent. The high end is where the costs this
    /// cap is holding back stop being about accounts at all: every account
    /// is a repository replayed from the log at startup, so a deployment
    /// near it should be sized against its restart time rather than against
    /// this number. The built-in default is 1000.
    pub max_accounts: Option<u64>,
    /// The most records one account's repository may hold. No flag mirrors
    /// this, only this key. A caller's write that would add records past it
    /// is refused with `403 TooManyRecords`. Updates and deletes are always
    /// accepted, and the server's own records are written past it. An
    /// account already past it keeps what it has and cannot create more.
    ///
    /// **Reasonable range: 1_000 to 100_000.** A write to a repository the
    /// server holds built costs the same at any size, about 200µs. A write
    /// that finds it not held builds it from every record: after a restart,
    /// or once more than 32 repositories have written since. That build took
    /// 10ms at a thousand records, 107ms at ten thousand, 690ms at fifty
    /// thousand and 2.6s at a hundred thousand, on a loaded 16-thread laptop.
    /// Below a thousand, an agent writing a record an hour fills it in six
    /// weeks. The built-in default is 50_000. Startup refuses a value outside
    /// the range.
    pub max_records_per_account: Option<u64>,
    /// Bytes the write-ahead log may reach before a further write is
    /// refused with `StorageFull`. Mirrors `--log-budget`. Applied by
    /// `didbot_pds::wal::Wal::set_capacity`.
    ///
    /// **Reasonable range: a tenth of the volume to most of it.** This is a
    /// budget, not a disk check: it exists so a full volume is a deployment
    /// that says `StorageFull` at a size the operator chose, rather than
    /// one that discovers the size of its disk mid-write. Set it below what
    /// the volume holds, with room for the blobs beside it, which this does
    /// not count and `[blobs] total_quota_bytes` bounds. Unset, the log grows
    /// until the filesystem stops it — an append that fails is still refused
    /// cleanly, just at a size nobody picked.
    pub log_budget_bytes: Option<u64>,
    /// Bytes the write-ahead log reaches before the running server takes a
    /// checkpoint and trims the log against it. No flag mirrors this, only
    /// this key. Applied by `didbot_pds::Durable::checkpoint_when`.
    ///
    /// **Reasonable range: 128 MiB (134_217_728) to three quarters of
    /// `log_budget_bytes`.** Each checkpoint writes the whole state, so a
    /// low watermark rewrites the state for every few segments of log it
    /// reclaims. Near the budget, the writes that land while a checkpoint
    /// runs can reach the budget first, and those are refused with
    /// `StorageFull`. Unset, it is half of `log_budget_bytes`, or 1 GiB
    /// with no budget. Startup refuses a value below 1 MiB or at or above
    /// the budget.
    pub checkpoint_log_bytes: Option<u64>,
    /// How often the running server takes a checkpoint while the log stays
    /// under `checkpoint_log_bytes`, in seconds, if anything was written
    /// since the last. No flag mirrors this, only this key.
    ///
    /// **Reasonable range: 3_600 to 604_800 (an hour to a week).** This
    /// bounds how much log a restart replays and how long churn sits in the
    /// log. An hour costs a write of the whole state every hour; a week
    /// lets a restart replay a week of writes. The built-in default is
    /// 86_400, a day. Startup refuses a value outside the range.
    pub checkpoint_interval_secs: Option<u64>,
    /// How long a sealed segment of the policy evaluation log is kept before
    /// it is trimmed, in days. No flag mirrors this yet, only this key.
    /// Applied by `didbot-serve/src/bin/didbot-pds/`'s `Enforcement::open`
    /// via `didbot_pds::evaluation_log::FileSink::set_retention`; unset
    /// leaves that sink's own `DEFAULT_RETENTION`, thirty days.
    ///
    /// This log's volume is driven by what gets refused, which an attacker
    /// controls: a single client retrying a denied write writes a row every
    /// time. A week (7) is enough to answer "why was this refused" while it
    /// is still being asked; a quarter (90) keeps a season of denials for
    /// looking at patterns, and costs disk in proportion to how noisy the
    /// deployment's callers are. One day is the shortest that survives an
    /// operator sleeping through an incident.
    pub evaluation_log_retention_days: Option<u64>,
    /// How long a sealed segment of the write log is kept before it is
    /// trimmed, in days. The same shape as
    /// [`Self::evaluation_log_retention_days`] and applied the same way,
    /// against `didbot_pds::write_log::FileWriteLog`.
    ///
    /// This log grows with real use rather than with refusals: one row per
    /// record written or deleted, naming the app that presented it. It is
    /// the only record of which app wrote what, so the window is how far
    /// back an attribution question can be answered. Thirty days (the
    /// default) covers "what did this app do last month"; a year (365) makes
    /// attribution answerable for as long as most operators keep backups,
    /// at roughly a row per write. The two logs are set separately because
    /// they fill at unrelated rates.
    pub write_log_retention_days: Option<u64>,
    /// The data volume's free space, as a percentage of its size, below
    /// which `GET /health`'s `disk.alert` reads `warning` and the journal
    /// writes a `warn` line. The built-in default is 20.
    ///
    /// **Reasonable range: 10 to 50.** The log and the blobs refuse at their
    /// own budgets, but the record heap, a checkpoint and the small files
    /// beside the log grow until the volume is full. Twenty percent of the
    /// default 20 GiB volume is 4 GiB, days of ordinary writes to act in.
    /// Above 50 the alert stays raised on a volume whose budgets are in use.
    /// Startup refuses a value outside the range.
    pub disk_warning_free_percent: Option<u8>,
    /// The same, for `critical`. The built-in default is 10.
    ///
    /// **Reasonable range: 2 to 20, and below
    /// [`Self::disk_warning_free_percent`].** A boot writes a checkpoint as
    /// large as the state, so this should leave room for one. Startup
    /// refuses a value outside the range, or at or above the warning.
    pub disk_critical_free_percent: Option<u8>,
    /// How many frames `subscribeRepos` keeps in memory for a consumer to
    /// resume from. No flag mirrors this, only this key. Default 4096,
    /// `didbot_serve::DEFAULT_REPLAY_FRAMES`.
    ///
    /// **Range: 256 to 65_536**, and startup refuses a value outside it.
    /// This is a relay's reconnect
    /// window: a cursor older than the frames kept gets `OutdatedCursor` and
    /// must read the repositories to fill the hole. Below 256 a short relay
    /// outage on a busy server is already a hole. Each frame kept also costs
    /// a few dozen bytes that [`Self::firehose_replay_bytes`] does not count,
    /// which is what this bound limits when frames are small.
    pub firehose_replay_frames: Option<usize>,
    /// How many encoded bytes those frames may come to. No flag mirrors
    /// this, only this key. Default 67_108_864 (64 MiB),
    /// `didbot_serve::DEFAULT_REPLAY_BYTES`. The oldest frames are evicted
    /// first, whichever of the two bounds is reached. Frames an open stream
    /// has not sent yet are kept past both bounds, up to twice them.
    ///
    /// **Range: 16_777_216 (16 MiB) to 1_073_741_824 (1 GiB)**, and startup
    /// refuses a value outside it. Within that, stay at or under a sixteenth
    /// of the instance's memory. A commit may carry 2,000,000 bytes, so this
    /// is the bound that holds when records are large. The firehose's memory
    /// is at most twice this, plus the one frame each open connection is
    /// writing, up to `subscribeRepos`' connection limit. Below 16 MiB a
    /// burst of large records evicts frames before a relay has read them.
    /// Above a sixteenth, twice this competes with the rest of the server
    /// for memory.
    pub firehose_replay_bytes: Option<u64>,
}

/// How fast one account may write, as two token buckets: one on write
/// operations and one on request bytes. See `didbot_serve::write_meter`.
///
/// Every account shares one write-ahead log, bounded by `[capacity]
/// log_budget_bytes` and trimmed at `[capacity] checkpoint_log_bytes`. These
/// keys bound how fast one account can take it: a rate, not a total.
///
/// A single `createRecord`, `putRecord` or `deleteRecord` costs one operation
/// and adds about 1 KiB to the log, whatever the record's size; the body goes
/// to the record heap. `applyWrites` costs one operation per write, and
/// `uploadBlob` costs one. Each request's body costs its length in bytes.
///
/// In any hour one account writes at most `ops_burst + ops_per_hour`
/// operations and `bytes_burst + bytes_per_hour` bytes. At the defaults that
/// is 4,600 operations, about 4.5 MiB of log (0.2% of the 2 GiB budget a 20
/// GiB volume gets), and 72 MiB of request bodies. One account writing flat
/// out reaches the 1 GiB watermark that budget defaults to in about nine and
/// a half days, and the server then trims it.
///
/// A write over either bucket is refused with `429 RateLimitExceeded` and a
/// `Retry-After`. The buckets are in memory and start full on every start.
///
/// Reload: needs a restart. The meter is built once, into the router.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct WritesSection {
    /// Write operations an account's bucket regains an hour.
    ///
    /// **Reasonable range: 600 to 360_000.** 600 is one write every six
    /// seconds. 360_000 is a hundred a second, about 350 MiB of log an hour
    /// from one account, which a deployment should choose only with a large
    /// budget. The built-in default is 3_600, one a second: an agent
    /// writing every five seconds uses 20% of it.
    pub ops_per_hour: Option<u32>,
    /// Write operations an account's bucket holds when full: how many it
    /// may write at once before the hourly rate applies.
    ///
    /// **Reasonable range: 200 to 100_000.** Below 200, the most writes one
    /// `applyWrites` takes, a full batch is refused however long the caller
    /// waits, so startup refuses it. The built-in default is 1_000, which
    /// refills in about 17 minutes at the default rate.
    pub ops_burst: Option<u32>,
    /// Request bytes an account's bucket regains an hour.
    ///
    /// **Reasonable range: 8 MiB to 4 GiB** (8_388_608 to 4_294_967_296).
    /// This bounds how fast one account grows the record heap, which shares
    /// the volume with the log and the blobs. The built-in default is 64 MiB
    /// (67_108_864): a 1 KiB record every five seconds uses about 1% of it,
    /// and a loop of full 2 MiB requests gets one every 112 seconds.
    pub bytes_per_hour: Option<u64>,
    /// Request bytes an account's bucket holds when full.
    ///
    /// **Reasonable range: 2 MiB to 1 GiB** (2_097_152 to 1_073_741_824).
    /// Below 2 MiB, the largest request body this server reads, a full
    /// request is refused however long the caller waits, so startup refuses
    /// it. The built-in default is 8 MiB (8_388_608), four full requests.
    pub bytes_burst: Option<u64>,
}

/// One named source of names: the zones and labels it holds, and how it
/// makes a name. See `plan/pools.md`.
///
/// A pool says how names are made, never who may take them: that is the
/// operator's `account.create` policy. With no `[[pool]]`, each zone in
/// `[zone] zones` is a pool named after itself, in zone order.
///
/// **Reasonable range: 1 to 20 pools.** Each create with no pool of its
/// own asks policy about each pool's zones in turn, so a long list is a
/// longer walk before a refusal.
///
/// Reload: needs a restart. A changed pool applies to later creates; a DID
/// already minted keeps its name.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PoolSection {
    /// What a create's `pool` and a policy's `resource.pool` call this pool.
    /// One DNS label, and no two pools share one.
    pub name: String,
    /// The zones the pool holds names under, each one of `[zone] zones`,
    /// in the order it fills them: a create lands in the first one policy
    /// permits.
    ///
    /// **Reasonable range: 1 to 20 zones**, and never more than the server
    /// serves.
    pub zones: Vec<String>,
    /// Which labels under those zones the pool holds: one `*`, with
    /// optional literal text on either side. `ci-*` holds `ci-7` and not
    /// `kestrel`, and wraps each name the pool makes: `ci-basalt-otter`.
    /// Unset is `*`, every label.
    ///
    /// **Reasonable values: `*`, or a short prefix or suffix** such as
    /// `ci-*`. Every character of literal text is one fewer for the scheme
    /// in a 63-byte label.
    pub labels: Option<String>,
    /// How the pool makes a name, in the spellings `[names] spec` takes.
    /// A braced part, such as `{repo}` in `{repo}+n`, is a slot each create
    /// fills with a fragment. Unset takes `[names] spec`, or
    /// `mineral+creature` when that is `hostname`.
    ///
    /// **Reasonable values:** a word-list spec for names people say aloud,
    /// or a spec with `n` for a pool that must never run out. `--help`
    /// says what each spelling discloses.
    pub names: Option<String>,
}

/// How agents are named.
///
/// Reload: needs a restart. The namer is built once and handed to the
/// provisioner.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct NamesSection {
    /// A `--names`-shaped spec: `hostname`, a `+`-joined word-list spec,
    /// `toml:<path>`, `cmd:<program args...>`, or one of the generated
    /// forms. Mirrors `--names`, and takes exactly the same spellings —
    /// `--help` lists them and says what each one discloses.
    pub spec: Option<String>,
    /// A second naming to fall back on, same shapes as `spec`. Mirrors
    /// `--names-if-down`.
    pub fallback: Option<String>,
    /// How a number is written into a label: the `n` and `t` slots, and
    /// the `counter` and `timestamp` namings. Mirrors
    /// `--number-encoding`. One key rather than one per number, because
    /// a label carrying a count and a time should read in one number
    /// system rather than two.
    ///
    /// **Reasonable values: `decimal` or `base32`.** `decimal` (the
    /// default) writes the count as anyone would write it, up to twenty
    /// characters. `base32` is lowercase Crockford, which drops the four
    /// symbols a person misreads and fits the same range in thirteen
    /// characters; a deployment past a million accounts, or one whose
    /// template already spends most of a DNS label on words, gets shorter
    /// names from it. Both are legal in a label at every count, so the
    /// choice is about length and readability rather than validity.
    pub number_encoding: Option<String>,
    /// Days a released name stays held before it can be taken again.
    /// Mirrors `--name-hold`.
    ///
    /// **Reasonable range: 1 to 365.** The hold is what keeps a name from
    /// being handed to a second agent while callers still have the first
    /// one cached, so the low end is however long anything caches a name —
    /// a day covers a DNS TTL and a restart. The high end holds a name for
    /// a year, which suits a deployment where a name is a published
    /// identity somebody wrote down. The cost of a long hold is names: a
    /// word-list naming with a small pool runs out of unheld names sooner.
    /// The built-in default is 30 days.
    pub hold_days: Option<i64>,
}

/// The operator: how long their sign-in lasts, and how long their claim
/// outlives a poll that cannot see it.
///
/// Reload: needs a restart. The TTL is read once when the sign-in is built,
/// and a session already issued keeps the lifetime it was issued with; the
/// grace window is handed to the operator poll when it is spawned.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct OperatorSection {
    /// How long a signed-in operator stays signed in, in seconds. Mirrors
    /// `--operator-session-ttl`.
    ///
    /// **Reasonable range: 300 to 86_400** — five minutes to a day.
    ///
    /// Below five minutes an operator is signing in again mid-incident,
    /// which is the one time the round trip to their own server is least
    /// welcome. Above a day the window in which a borrowed browser stays
    /// the operator outlives any sitting a person actually had. The
    /// built-in default is twelve hours: one working day, so a sign-in in
    /// the morning does not expire before the evening.
    ///
    /// Nothing enforces the range — it is documented for whoever sets this,
    /// not checked — but a value outside it is worth a second thought.
    pub session_ttl_secs: Option<u64>,
    /// Hours an unreachable operator keeps this deployment writing, counted
    /// from the moment their `bot.did.operator` claim stops standing. No
    /// flag mirrors this, only this key. Applied to
    /// `didbot_serve::operator_poll::configure`.
    ///
    /// Only a running server counts it. One restarted while the operator's
    /// PDS is down boots unclaimed, and refuses writes and creates until that
    /// PDS answers, however long this is.
    ///
    /// **Reasonable range: 1 to 168** — an hour to a week.
    ///
    /// This is a trade between two ways of being wrong. Short, and an
    /// operator whose own PDS is down for an afternoon takes this
    /// deployment's accounts down with it, because the poll cannot see a
    /// claim that is still there. Long, and an operator who has genuinely
    /// stood down leaves accounts writing under a vouch nobody is behind.
    /// An hour is about as short as the poll's own interval makes
    /// meaningful; a week outlasts most outages and most holidays. The
    /// built-in default is six hours: long enough to sleep through, short
    /// enough that a stood-down operator is not a month of writes.
    pub grace_window_hours: Option<i64>,
    /// The shortest `idleFor` a `neverWrote` account delete takes, in
    /// seconds. A shorter one is refused. No flag mirrors this, only this
    /// key.
    ///
    /// **Reasonable range: 3600 to 604_800** — an hour to a week.
    ///
    /// An agent's account is created before its session makes its first
    /// write. Below an hour, a delete can take an account that is about to
    /// write. The built-in default is an hour. Nothing enforces the range,
    /// but zero is read as one second, since a delete always names a span.
    pub never_wrote_min_idle_secs: Option<u64>,
    /// The DNS-over-HTTPS resolver the operator's handle is checked
    /// through: it is asked for the `_atproto` TXT record under the handle
    /// the operator's DID document claims, before the homepage names them
    /// by it. Default `https://cloudflare-dns.com/dns-query`.
    ///
    /// **Reasonable range: an `https://` DNS-over-HTTPS (RFC 8484) endpoint
    /// that also answers the JSON form**, `?name=&type=TXT` answered as
    /// `application/dns-json`: Cloudflare's, Google's at
    /// `https://dns.google/resolve`, or one on this deployment's own network.
    /// Anything else refuses startup. Whoever runs the resolver sees the
    /// operator's handle once per operator poll.
    pub dns_resolver: Option<String>,
}

/// Which `bot.did.*` routes this deployment has closed to a public,
/// unauthenticated caller.
///
/// Every field defaults to open (`None`, meaning "leave it public") and only
/// `Some(false)` ever narrows — mirrors `auth::Disclosure` and
/// `--close-disclosure`. There is no spelling that widens past public,
/// because there is nothing wider than public to widen into.
///
/// Reload: hot. Nothing here is built into another structure at startup; a
/// caller may re-read this section and assign it directly onto a live
/// `auth::Disclosure` at any point.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DisclosureSection {
    /// `bot.did.listAccounts`.
    pub list_accounts: Option<bool>,
    /// `bot.did.listAccountLedgers`.
    pub list_account_ledgers: Option<bool>,
    /// `bot.did.getAccountLedger`.
    pub get_account_ledger: Option<bool>,
    /// `bot.did.stats`.
    pub stats: Option<bool>,
}

/// Which relays `didbot announce` and the dashboard's
/// `POST /dashboard/api/relay/announce` announce this server to, over
/// `com.atproto.sync.requestCrawl` and `notifyOfUpdate`. Every relay named
/// by either key is asked, `hostname` first, and a relay named twice is
/// asked once.
///
/// `None` — no `[relay]` table at all — means there is no relay to reach,
/// the same as never passing `--relay-hostname`; there is no default relay
/// address, because this project vendors nobody's as one. A `*.localhost`
/// zone is left unwired regardless of what this section holds, since no
/// relay can reach a loopback address; see `didbot_serve::relay`'s own doc.
///
/// Reload: needs a restart. This is read once at startup and it does not
/// itself trigger anything, so there is nothing to re-read on a running
/// process.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RelaySection {
    /// One relay's hostname, e.g. `bsky.network`. Reached over `https://`
    /// unconditionally — a relay worth announcing to is on the public
    /// internet.
    pub hostname: Option<String>,
    /// Relay hostnames, in the form `hostname` takes. Mirrors
    /// `--relay-hostname`, given once per relay. Zero to a few: each is
    /// asked at once on every announce, with its own ten-second limit.
    pub hostnames: Option<Vec<String>>,
}

/// The authorization server's own bounds: the scope ceiling every grant is
/// narrowed to, how many decisions may sit undecided at once, and the
/// resolver it finds a permission set's authority through.
///
/// `scope_ceiling` is the one place this file names scopes, and it may only
/// **narrow**. Whatever it holds is intersected with the compiled-in ceiling
/// (`didbot_serve::oauth::authorize::GrantAnyScope`) before it is applied, so
/// a configured value can shrink what an agent may hold and can never reach
/// past what the binary already allows — the hard-blocked capabilities stay
/// outside it whatever this section says. See the crate root's doc for why
/// that direction is the only one permitted.
///
/// Reload: needs a restart. The ceiling is built once and handed to the
/// router's `OAuthState`.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct OAuthSection {
    /// The most any agent may be granted, as an enumeration of scope atoms
    /// — `plan/scope-policy.md`'s "a ceiling is an enumeration, not a
    /// pattern". Absent leaves the compiled-in ceiling in place.
    ///
    /// A **seam**, and the first half of that plan's "from server
    /// configuration first, from the operator's records second": a ceiling read
    /// from policy records in the operator's repository replaces this one at
    /// the same `ScopePolicy` interface, without either side changing. It is
    /// here so the boundary is testable before that source exists, not
    /// because a ceiling belongs in a configuration file.
    pub scope_ceiling: Option<Vec<String>>,
    /// How many decisions one account may have awaiting an answer before a
    /// further pushed authorization request is refused. Mirrors
    /// `didbot_serve::oauth::decision::DEFAULT_PENDING_PER_ACCOUNT`, 8.
    ///
    /// **Reasonable range: 1 to 64.** At 1, a second sign-in started before
    /// the first is answered displaces it. Above 64, one account can hold
    /// many sign-ins nobody will answer, and a caller with no credential
    /// can push them.
    pub pending_per_account: Option<usize>,
    /// How many decisions this server may hold in total, counting an
    /// answered one until its pushed request expires.
    ///
    /// Left unset, the default is derived rather than fixed: `didbot-pds`
    /// computes `[capacity] max_accounts * pending_per_account`, floored at
    /// `didbot_serve::oauth::decision::DEFAULT_PENDING_TOTAL`, so a deployment
    /// sized above 64 accounts is not left with a total bound tighter than
    /// `pending_per_account` gives each one; with no `max_accounts` configured
    /// either, that same fixed default applies outright. A value written here
    /// is never adjusted against `max_accounts` -- only checked, with a
    /// startup warning if it comes up short.
    ///
    /// **Reasonable range: `max_accounts * pending_per_account` to twice
    /// that.** Below it, a full deployment refuses a push before every
    /// account has used its own bound. An answered decision is held until
    /// its pushed request expires, so some room above it keeps a busy
    /// deployment from refusing. Each one held is memory that `POST
    /// /oauth/par`, which needs no credential, can fill.
    pub pending_total: Option<usize>,
    /// The DNS-over-HTTPS resolver an `include:` scope's permission set is
    /// found through: it is asked for the `_lexicon` TXT record under the
    /// set's authority. `com.atproto.identity.resolveHandle` asks it for the
    /// `_atproto` TXT record of a handle no account here holds. Default
    /// `https://cloudflare-dns.com/dns-query`.
    ///
    /// **Reasonable range: an `https://` DNS-over-HTTPS (RFC 8484) endpoint
    /// that also answers the JSON form**, `?name=&type=TXT` answered as
    /// `application/dns-json`: Cloudflare's, Google's at
    /// `https://dns.google/resolve`, or one on this deployment's own network.
    /// Anything else refuses startup. The default is Cloudflare's because it
    /// answers that form and is the resolver the operator's own onboarding
    /// checks ask. Whoever runs the resolver sees which permission sets
    /// sign-ins here name, and which handles callers ask this server to
    /// resolve.
    pub dns_resolver: Option<String>,
    /// How long a browser stays signed in as an account, in seconds, counted
    /// from the sign-in. Use does not extend it. Default 43_200, twelve
    /// hours, as an operator's session.
    ///
    /// **Reasonable range: 300 to 86_400** — five minutes to a day. Below
    /// five minutes an agent signs its browser in again for most web
    /// sign-ins. Above a day a copied cookie outlives any session an agent
    /// has. Nothing enforces the range.
    pub browser_session_ttl_secs: Option<u64>,
}

/// Which DID's records this server reads as policy, once
/// [`policy-store`](../../../plan/policy-store.md) exists to read anything.
///
/// This is the one field this whole file may say about policy: **which**
/// repository to read, never what that repository is allowed to grant. See
/// the crate root's doc.
///
/// Reload: hot, by design — `policy-store`'s own poll is how a revision
/// takes effect, and this section only says where the poll points.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PolicySection {
    /// The operator's DID, whose repository holds ceilings, admitted apps
    /// and collection permissions this server enforces but never stores here.
    pub operator_did: Option<String>,
}

/// How `bot.did.parkKey` holds a key and bounds who may park one.
///
/// Reload: needs a restart. The values are read once, into the router's
/// own state.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ParkSection {
    /// How long a parked key is held, in seconds. Mirrors `--park-key-ttl`.
    ///
    /// **Reasonable range: 60 to 3600.** The key waits for a person to run
    /// `didbot operate` on another machine, so it has to outlast reading a
    /// fingerprint off one screen and typing on another; past an hour a
    /// park nobody admitted is holding a name against the next machine to
    /// register it. Default 600.
    pub ttl_seconds: Option<u64>,
    /// How many parks and lookups one caller address may make per window.
    /// Mirrors `--park-key-rate-limit`.
    ///
    /// **Reasonable range: 1 to 1000.** A machine parks once; six covers
    /// one retrying through a flaky first boot. Default 6.
    pub rate_limit: Option<u32>,
    /// The window the limit is measured over, in seconds. Mirrors
    /// `--park-key-rate-window`.
    ///
    /// **Reasonable range: 1 to 86400.** Default 600, matching the default
    /// hold, so one address gets as many parks per window as could be live
    /// at once.
    pub rate_window_seconds: Option<u64>,
}

/// The shape one creator may give the ownership tree, enforced by the
/// server whatever policy says.
///
/// Reload: hot for the three bounds below. A running server re-reads this
/// file every `[intervals] tree_reload_secs` and judges every later create
/// by what it found; a create already judged keeps its answer. A re-read
/// that fails — the file gone, the TOML bad, a bound outside its range —
/// changes nothing and warns, naming the file and the key.
///
/// `reserved_labels` is read once, into the router, and needs a restart.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TreeSection {
    /// The deepest an account may sit, in edges from the operator.
    ///
    /// **Reasonable range: 1 to 64.** This bounds how long a chain a reader
    /// walks to reach the operator, and how many parties it rests on. Ten,
    /// the default, leaves room above a service, a host beneath it and an
    /// agent beneath that for agents that register agents of their own.
    pub max_depth: Option<u32>,
    /// The most accounts one creator may operate at once.
    ///
    /// **Reasonable range: 1 to 1_000_000.** This bounds how many accounts
    /// one leaked key can be holding when the operator notices. Ten
    /// thousand, the default, is above the pools this deployment expects
    /// and under what a loop reaches.
    pub max_children: Option<u32>,
    /// The most accounts one creator may create in an hour.
    ///
    /// **Reasonable range: 1 to 1_000_000.** This bounds the rate rather
    /// than the total, and is what stops a loop before `max_children` is
    /// reached. A hundred, the default, admits a pool of a hundred coming
    /// up at once.
    pub creates_per_hour: Option<u32>,
    /// Labels no account may take directly under a zone: the hostnames the
    /// deployment answers at itself, and names a browser or resolver asks
    /// for on its own. Absent, `didbot_serve::tree::RESERVED_LABELS`
    /// stands; an empty list reserves nothing.
    ///
    /// **Reasonable range: 0 to 100 labels.** Each one is a name the
    /// deployment's own `www`, `xrpc` or `dashboard` would otherwise share
    /// with an agent through the zone's wildcard.
    pub reserved_labels: Option<Vec<String>>,
}

/// Which OpenID Connect issuers this server will fetch keys from, and how
/// fresh a token has to be.
///
/// Reload: needs a restart. The values are read once, into the router.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct OidcSection {
    /// The issuers whose tokens are accepted, as their `iss` spells them.
    /// Empty admits any issuer reachable over HTTPS at a public address.
    ///
    /// **Reasonable range: 0 to 64 entries.** A deployment names the
    /// platforms it runs on; a list longer than that is an allowlist nobody
    /// reviews.
    #[serde(default)]
    pub issuers: Vec<String>,
    /// How old a token's `iat` may be, in seconds.
    ///
    /// **Reasonable range: 60 to 3600.** Five minutes, the default, is clock
    /// skew and a slow network; past an hour a token a run left in a log is
    /// still a session.
    pub freshness_secs: Option<u64>,
}

/// The sessions this server issues from a proof.
///
/// Reload: needs a restart. The values are read once, into the registry
/// and its token store.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SessionsSection {
    /// How long a session minted from a key-signed JWT or an OpenID Connect
    /// token lasts, in seconds. A session minted at creation keeps its own
    /// lifetime.
    ///
    /// **Reasonable range: 300 to 86_400.** An hour, the default: a run
    /// that holds a session longer re-proves itself for one round trip.
    pub proof_ttl_secs: Option<u64>,
    /// How many live sessions one account may hold; the one expiring
    /// soonest makes room for the next.
    ///
    /// **Reasonable range: 1 to 64.** Eight, the default, covers a
    /// pipeline whose runs overlap.
    pub live_per_account: Option<usize>,
}

/// The bearer credential provisioning mints for a freshly created account.
///
/// Reload: needs a restart. The value is read once, into the provisioner
/// that issues every later token.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CredentialSection {
    /// How long a freshly issued agent token is good for, in days. Mirrors
    /// `didbot_pds::credential::DEFAULT_AGENT_TOKEN_TTL`.
    ///
    /// **Reasonable range: 1 to 3650** — a day to ten years. There is no
    /// rotation path for this token (`didbot_pds::credential`'s own doc): an
    /// account whose token has expired is provisioned again, so the low end
    /// suits a deployment that already re-provisions often and the high end
    /// suits one that would rather live with a long-lived credential than
    /// re-provision at all. The built-in default is 365, long enough that a
    /// running deployment never meets the expiry in the ordinary course of
    /// things.
    pub agent_token_ttl_days: Option<u64>,
    /// The shortest time between two of an account's own credential
    /// replaces through `bot.did.updateCredentials`, in seconds. Mirrors
    /// `didbot_pds::DEFAULT_REPLACE_INTERVAL`.
    ///
    /// **Reasonable range: 10 to 3600** — ten lets a test replace twice in
    /// one run, and an hour is still far below any schedule a host keeps.
    /// Every replace stays in the account's ledger for good, and this bounds
    /// how fast an account grows it. The built-in default is 60.
    pub replace_interval_secs: Option<u64>,
}

/// How often each background loop runs.
///
/// Every one of these trades freshness against load, and they are set apart
/// because they load different things: one talks to a DNS provider with its
/// own rate limits, one walks this server's own disk, and one only reads
/// state already in memory.
///
/// Reload: needs a restart. Each loop is handed its period when it is
/// spawned.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct IntervalsSection {
    /// Seconds between passes of the blob collector, which reclaims upload
    /// bytes nothing references once their grace window has passed.
    ///
    /// **Reasonable range: 300 to 86_400** — five minutes to a day.
    ///
    /// This is how promptly deleted bytes come back, and each pass walks
    /// every account's blobs. Five minutes suits a deployment near its
    /// quota, where the disk is the scarce thing. A day suits one with room
    /// to spare, where the walk is the more expensive half. Nothing is lost
    /// by a long period: a blob past its grace window stays collectable
    /// until a pass reaches it. The built-in default is an hour.
    pub blob_collect_secs: Option<u64>,
    /// Seconds between passes of the confinement poll, which notices an
    /// account whose hostname no longer resolves the way this server
    /// published it.
    ///
    /// **Reasonable range: 60 to 3600** — a minute to an hour.
    ///
    /// Each pass reads records back from the DNS provider, so this is the
    /// knob that decides how much of a provider's rate limit this
    /// deployment spends on noticing drift. A minute catches a hijacked or
    /// clobbered record fast and costs the most requests; an hour is
    /// cheaper and leaves a wrong record standing longer. The built-in
    /// default is five minutes.
    pub confinement_poll_secs: Option<u64>,
    /// Seconds between health ticks, which refresh what `bot.did.stats` and
    /// the dashboard report about this server's own state.
    ///
    /// **Reasonable range: 5 to 300** — five seconds to five minutes.
    ///
    /// This one costs nothing outside the process: it reads state already
    /// in memory, so the period is how stale a readout may be rather than a
    /// load question. Match it to whatever scrapes the dashboard. The
    /// built-in default is ten seconds.
    pub health_secs: Option<u64>,
    /// Seconds between re-reads of this configuration file for `[tree]`'s
    /// three bounds, which take effect without a restart.
    ///
    /// **Reasonable range: 5 to 3600** — five seconds to an hour.
    ///
    /// Each pass reads and parses one local file, so the period is how long
    /// an operator waits for an edit to take rather than a load question.
    /// Five seconds suits raising a cap that is refusing work right now; an
    /// hour suits a file nobody edits. The built-in default is thirty
    /// seconds.
    pub tree_reload_secs: Option<u64>,
}

/// What one account may spend of `atproto-proxy`, which forwards a call to
/// whatever service a DID document names, from this server's address.
///
/// Reload: needs a restart. The values are read once, into the router.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ProxySection {
    /// How many proxied calls one account's budget refills by each minute.
    ///
    /// **Reasonable range: 1 to 6000.** Sixty, the default, is one a second
    /// sustained: far above the few calls a minute an agent makes, and the
    /// most one account can make a third party see from this server's
    /// address. A call over it is refused `429` with `Retry-After`.
    pub calls_per_minute: Option<u32>,
    /// How many proxied calls one account may make at once from a full
    /// budget.
    ///
    /// **Reasonable range: 1 to 1000.** Sixty, the default, covers a client
    /// that opens a view by fanning out a few dozen calls.
    pub burst_calls: Option<u32>,
    /// How many of one account's proxied calls may be open at once.
    ///
    /// **Reasonable range: 1 to 64.** Eight, the default, is more than an
    /// agent opens at once, and a sixteenth of `in_flight_total`.
    pub in_flight_per_account: Option<usize>,
    /// How many proxied calls may be open at once across one account tree:
    /// an account the operator admitted, and every account created beneath
    /// it.
    ///
    /// **Reasonable range: 1 to 512.** 64, the default, is half of
    /// `in_flight_total`, so one creator's accounts leave half for every
    /// other tree. A per-tree cap at or above `in_flight_total` has no
    /// effect.
    pub in_flight_per_tree: Option<usize>,
    /// How many proxied calls may be open at once across every account.
    ///
    /// **Reasonable range: 1 to 512.** 128, the default, is a quarter of the
    /// 512 requests this server serves at once. One creator may hold
    /// thousands of accounts, and this keeps their calls to a service that
    /// never answers from holding the rest. A per-account cap above it has
    /// no effect.
    pub in_flight_total: Option<usize>,
    /// How long the endpoint a target's DID document names is kept, in
    /// seconds.
    ///
    /// **Reasonable range: 10 to 3600.** Five minutes, the default, fetches
    /// a document once for every few hundred calls to it, and reaches a
    /// service that moved within five minutes. Every call still checks the
    /// addresses the endpoint resolves to.
    pub target_cache_secs: Option<u64>,
    /// How many targets' endpoints are kept, the least recently used
    /// dropped first.
    ///
    /// **Reasonable range: 16 to 100_000.** An entry is a few kilobytes at
    /// most. 1024, the default, holds the services a deployment's agents
    /// call in a few megabytes.
    pub target_cache_entries: Option<usize>,
    /// Where an `app.bsky.*` call with no `atproto-proxy` header goes, as
    /// that header names a service: `did#service`, such as
    /// `did:web:api.bsky.app#bsky_appview`. The call is authorized and
    /// signed as a proxied call to that service is.
    ///
    /// Unset, the default, sends such a call nowhere: it is
    /// `MethodNotImplemented`.
    pub app_view: Option<String>,
}