~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
1727 lines · 65.5 KB Raw History
//! The PDS: XRPC, the firehose, and the MCP endpoint whose tools are its methods.
//!
//! This module is the router, the state every request shares, and the
//! dispatch of a call to its method. Each area's methods are in a module of
//! their own, named in `AREAS`: `server` (the server, its accounts and their
//! sessions), `sessions` (tokens, refreshing and ending sessions, and app
//! passwords), `email` (the account's email, the tokens mailed for it, and
//! the mailer), `repo` (records), `sync` (the repository whole),
//! `federation` (what a relay reads, and the crawlers the server tells),
//! `identity` (handles), `blobs` (kept in the data directory, or in a
//! bucket, `blobstore`, and moved from one to the other by `pds
//! migrate-blobs`, `migrate_blobs`), `invites`, `lifecycle` (deactivating,
//! taking down and deleting accounts, and what each state does to every
//! method), `migration` (accounts moving between servers: `importRepo`,
//! `listMissingBlobs` and the PLC operations that move a DID), `proxy`
//! (requests for other services, service tokens) with
//! `read_after_write` and `preferences`, `space_repo` (each account's space
//! repos), `space_credentials` (spaces' delegation tokens, credentials and
//! revocations), `space_authority` (the spaces each account is the
//! authority of, with who their policies authorize in `space_authz`) and
//! `space_notify` (write notifications, the writer set, syncers'
//! registrations, and the updates and notices sent them); the firehose is `events`, the MCP
//! endpoint `mcp`, the PLC directory `plc`, requests to URLs others name,
//! with SSRF protection, `outbound`, OAuth's authorization server `oauth`,
//! with the account's own routes for its OAuth sessions and devices, and
//! for its passkeys, in `oauth::account`, and passkeys, which sign it in
//! on the authorization page, in `oauth::passkeys` (they have no NSID, so
//! no area of `AREAS` answers them),
//! OAuth access tokens on every method and what their scopes allow
//! `scopes`, the single-use values OAuth spends `replay`, single-use values
//! the spaces spend `single_use`, what keeps the server up when anyone may
//! call it `limits`, what the server keeps, how it starts again from it,
//! and how it compacts it into checkpoints, `log`, `store`, `checkpoint`
//! (an account's) and `compact` (the service log's), with every account,
//! found by DID, handle, email or reset token and loaded on first use,
//! `directory`, what it holds of each account's store in memory, loaded on
//! first use and let go, `cache`, and what it tells whoever runs it, its
//! log, kept lines, health, metrics, traces and shutdown, and the admin's
//! reads of them, `ops`.

#![forbid(unsafe_code)]

mod blobs;
mod blobstore;
mod cache;
mod checkpoint;
mod compact;
mod cors;
mod directory;
mod email;
mod events;
mod federation;
mod identity;
mod invites;
mod lifecycle;
mod limits;
mod log;
mod mcp;
mod migrate_blobs;
mod migration;
mod oauth;
mod ops;
mod outbound;
mod plc;
mod preferences;
mod proxy;
mod read_after_write;
mod replay;
mod repo;
mod scopes;
mod server;
mod sessions;
mod single_use;
mod space_authority;
mod space_authz;
mod space_credentials;
mod space_notify;
mod space_repo;
mod store;
mod sync;
mod validation;

pub use blobstore::Place;

use axum::{
    Router,
    body::{Body, Bytes},
    extract::{Extension, State as AxState},
    http::{HeaderMap, Method, StatusCode, Uri, header},
    response::{IntoResponse, Response},
    routing::{any, get},
};
use oauth::account::{self, Route as Own};
use pds_lexicon::Kind;
use pds_repo::{Refused, Repo};
use pds_store::Wal;
use serde_json::{Map, Value as Json, json};
use std::path::PathBuf;
use std::pin::Pin;
use std::sync::{Arc, Mutex, OnceLock, PoisonError, RwLock, RwLockReadGuard, RwLockWriteGuard};

/// The server's configuration, from its environment (`spec/ACCOUNTS.md`,
/// `spec/FEDERATION.md`, `spec/LIMITS.md`).
pub(crate) struct Config {
    /// Its DID is `did:web:<hostname>`.
    pub hostname: String,
    /// The URL its accounts' DID documents name as their PDS.
    pub public_url: String,
    /// The domains handles may end in, each with its leading dot, in the order given.
    pub handle_domains: Vec<String>,
    pub plc_url: String,
    /// The key that signs its PLC operations.
    pub rotation_key: k256::ecdsa::SigningKey,
    /// A `did:key` listed before the server's own as a rotation key.
    pub recovery_did_key: Option<String>,
    /// The base URLs of the crawlers to tell of new events (`spec/FEDERATION.md`).
    pub crawlers: Vec<String>,
    /// `PDS_OAUTH_CLIENT_FETCH`, for development only (`spec/OAUTH-CLIENTS.md`).
    pub oauth_client_fetch: Option<oauth::ClientFetch>,
    /// `PDS_LEXICON_AUTHORITY_DID`: every NSID's authority, in place of DNS
    /// (`spec/OAUTH-PERMISSION-SETS.md`).
    pub lexicon_authority: Option<String>,
    /// The DNS server `_lexicon` records are looked up from, in place of the
    /// system's: the tests' stub; none from the environment.
    pub lexicon_dns: Option<std::net::SocketAddr>,
    /// `PDS_HANDLE_DNS_SERVER`: the DNS server handles' `_atproto` records
    /// are looked up from, in place of the system's (`spec/IDENTITY.md`).
    pub handle_dns: Option<std::net::SocketAddr>,
    /// `PDS_HANDLE_FETCH`, for development only: the base URL handles'
    /// `/.well-known/atproto-did` are fetched from instead (`spec/IDENTITY.md`).
    pub handle_fetch: Option<String>,
    /// Whether `createAccount` needs an invite code.
    pub invite_required: bool,
    /// The password of the admin's `Basic` auth; with none (unset or empty), no request is the admin.
    pub admin_password: Option<String>,
    /// The proxies whose `X-Forwarded-For` is read (`PDS_TRUSTED_PROXIES`, `spec/LIMITS.md`).
    pub trusted_proxies: limits::Trusted,
    /// Whether the rate limits apply.
    pub rate_limits: bool,
    /// The bytes of blobs an account may hold.
    pub blob_quota: u64,
    /// How long, in seconds, an upload no record references is held.
    pub blob_ttl: u64,
    /// The free space below which writes are refused.
    pub min_free: u64,
    /// The bytes of the CAR file `com.atproto.repo.importRepo` takes
    /// (`PDS_MAX_REPO_IMPORT_SIZE`, `spec/LIMITS.md`).
    pub max_import: u64,
    /// The bytes of a blob `uploadBlob` takes, and of a space repo's archive
    /// `com.atproto.space.importRepo` takes (`PDS_BLOB_UPLOAD_LIMIT`,
    /// `spec/LIMITS.md`); `describeServer` answers it.
    pub blob_upload_limit: u64,
    /// How long, in seconds, a DID document fetched from the directory is
    /// served, and a spaces token's issuer's key used with no read
    /// (`PDS_DID_CACHE_SECS`).
    pub did_cache: u64,
    /// How long, in seconds, a spaces token's issuer's key is used at all,
    /// read again in the background past `did_cache`: `did_cache` where
    /// that is more (`PDS_DID_CACHE_MAX_SECS`, `spec/SPACES-CREDENTIALS.md`,
    /// "Issuers' keys").
    pub did_cache_max: u64,
    /// How long after its input is checked `createSession` answers, at the soonest.
    pub login_floor: std::time::Duration,
    /// How long after its body is checked OAuth's sign-in answers, at the soonest.
    pub sign_in_floor: std::time::Duration,
    /// Where emails go (`spec/EMAIL.md`).
    pub mailer: email::Mailer,
    /// The default AppView and its CDN (`spec/PROXY.md`).
    pub proxy: proxy::Settings,
    /// Whether requests to URLs others name are SSRF-protected (`PDS_DISABLE_SSRF_PROTECTION`, `spec/PROXY.md`).
    pub ssrf_protection: bool,
    /// The backfill window, `PDS_REPO_BACKFILL_LIMIT_MS` (`spec/STORE.md`).
    pub backfill: std::time::Duration,
    /// The bytes a log may grow to past its checkpoint's, whatever that is (`spec/STORE.md`).
    pub log_floor: u64,
    /// The most an account's log may grow to past its table, whatever the
    /// table's size, but `log_floor` if that is more (`store::ACCOUNT_CAP`,
    /// `spec/STORE.md`, "The first request to a cold account").
    pub account_cap: u64,
    /// `PDS_CACHE_BYTES`: the most held in memory of accounts' state and data read from disk (`spec/STORE.md`).
    pub cache_bytes: u64,
    /// The accounts' logs open at once, and as many of their tables: a
    /// share of the file descriptors the process may have (`spec/LIMITS.md`,
    /// "Open files and threads").
    pub share: usize,
    /// Whether a start loads every account's state, to find every fault in
    /// the data directory before serving: the tests' way; the server's own
    /// loads each on first use.
    pub load_all: bool,
    /// The bucket blobs are kept in, if they are not kept in the data
    /// directory (`spec/BLOBS.md`).
    pub blobstore: Option<blobstore::Settings>,
    /// `PDS_SYNC`: how waiting writes are made durable (`spec/DURABILITY.md`,
    /// "Writes waiting at once").
    pub sync: Syncing,
}

/// How waiting writes are made durable (`PDS_SYNC`).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum Syncing {
    /// Every account's logs written to one journal too, whose sync is what
    /// a write waits for (`pds_store::journal`).
    Together,
    /// Each log synced by itself.
    Each,
}

impl Syncing {
    /// Read from `PDS_SYNC`: `together` unset or empty.
    fn from_env() -> Result<Syncing, String> {
        match std::env::var("PDS_SYNC")
            .ok()
            .filter(|v| !v.is_empty())
            .as_deref()
        {
            None | Some("together") => Ok(Syncing::Together),
            Some("each") => Ok(Syncing::Each),
            Some(v) => Err(format!("PDS_SYNC: {v:?} is neither together nor each")),
        }
    }

    /// As the `start` line says it.
    pub fn name(self) -> &'static str {
        match self {
            Syncing::Together => "together",
            Syncing::Each => "each",
        }
    }
}

impl Config {
    fn from_env() -> Result<Config, String> {
        let var = |n: &str| std::env::var(n).map_err(|_| format!("{n} is not set"));
        let key = var("PDS_PLC_ROTATION_KEY_HEX")?;
        let rotation_key = hex::decode(key.trim())
            .ok()
            .and_then(|b| k256::ecdsa::SigningKey::from_slice(&b).ok())
            .ok_or("PDS_PLC_ROTATION_KEY_HEX is not a secp256k1 key as 32 bytes of hex")?;
        Ok(Config {
            hostname: var("PDS_HOSTNAME")?,
            public_url: var("PDS_PUBLIC_URL")?,
            handle_domains: var("PDS_HANDLE_DOMAINS")?
                .split(',')
                .map(str::trim)
                .filter(|d| !d.is_empty())
                .map(str::to_lowercase)
                .collect(),
            plc_url: var("PDS_PLC_URL")?,
            rotation_key,
            recovery_did_key: std::env::var("PDS_RECOVERY_DID_KEY")
                .ok()
                .filter(|k| !k.is_empty()),
            crawlers: std::env::var("PDS_CRAWLERS")
                .unwrap_or_default()
                .split(',')
                .map(str::trim)
                .filter(|u| !u.is_empty())
                .map(str::to_string)
                .collect(),
            oauth_client_fetch: oauth::ClientFetch::from_env()?,
            lexicon_authority: match std::env::var("PDS_LEXICON_AUTHORITY_DID") {
                Ok(did) if pds_repo::data::valid_did(&did) => Some(did),
                Ok(did) => {
                    return Err(format!("PDS_LEXICON_AUTHORITY_DID is not a DID: {did:?}"));
                }
                Err(_) => None,
            },
            lexicon_dns: None,
            handle_dns: identity::resolve::dns_server_from_env()?,
            handle_fetch: identity::resolve::fetch_from_env()?,
            invite_required: limits::env_bool("PDS_INVITE_REQUIRED", false)?,
            admin_password: std::env::var("PDS_ADMIN_PASSWORD")
                .ok()
                .filter(|p| !p.is_empty()),
            trusted_proxies: limits::Trusted::from_env()?,
            rate_limits: limits::env_bool("PDS_RATE_LIMITS_ENABLED", true)?,
            blob_quota: limits::env_u64("PDS_BLOB_QUOTA_BYTES", 1 << 30)?,
            blob_ttl: limits::env_u64("PDS_BLOB_TTL_SECS", 3600)?,
            min_free: limits::env_u64("PDS_MIN_FREE_BYTES", 256 << 20)?,
            max_import: limits::env_u64("PDS_MAX_REPO_IMPORT_SIZE", 300 << 20)?,
            blob_upload_limit: limits::env_u64(
                "PDS_BLOB_UPLOAD_LIMIT",
                blobs::DEFAULT_UPLOAD_LIMIT,
            )?,
            did_cache: limits::env_u64("PDS_DID_CACHE_SECS", 3600)?,
            did_cache_max: limits::env_u64("PDS_DID_CACHE_MAX_SECS", 86_400)?,
            login_floor: std::time::Duration::from_millis(350),
            sign_in_floor: std::time::Duration::from_millis(400),
            mailer: email::Mailer::from_env()?,
            proxy: proxy::Settings::from_env()?,
            ssrf_protection: outbound::protection_from_env()?,
            backfill: std::time::Duration::from_millis(limits::env_u64(
                "PDS_REPO_BACKFILL_LIMIT_MS",
                86_400_000,
            )?),
            log_floor: store::FLOOR,
            account_cap: store::ACCOUNT_CAP,
            cache_bytes: limits::env_u64("PDS_CACHE_BYTES", 256 << 20)?,
            share: pds_store::files::share(pds_store::files::limit()),
            load_all: false,
            blobstore: blobstore::Settings::from_env()?,
            sync: Syncing::from_env()?,
        })
    }
}

/// An account, with its repository.
pub(crate) struct Account {
    pub did: String,
    /// In lower case. Changed only with the directory's lock held, as its
    /// `handles` are.
    pub handle: RwLock<String>,
    /// Its email and password, and what is known of the email
    /// (`spec/EMAIL.md`): changed only with this lock held.
    pub mail: Mutex<email::Mail>,
    /// Its KEM key (`spec/SPACES.md`); None for an account made before
    /// accounts had one.
    pub kem: Option<pds_space::KemKey>,
    /// Its DID document, as the PLC directory last served it, as JSON text
    /// (held so, a few allocations rather than one for each of its fields),
    /// and when, in seconds since the epoch: none if it may be out of date.
    pub did_doc: RwLock<(Box<str>, Option<u64>)>,
    /// Held by the one fetch of its DID document at a time.
    pub fetching: tokio::sync::Mutex<()>,
    /// Queries read it side by side; a write has it alone. Loaded from disk
    /// on first use, and let go when the cache needs the room (`cache`).
    pub store: cache::Slot,
    /// Whether it is deactivated or taken down, or deleted
    /// (`spec/LIFECYCLE.md`): changed only with `store` held for writing too.
    pub state: RwLock<lifecycle::State>,
}

impl Account {
    pub fn handle(&self) -> String {
        read(&self.handle).clone()
    }
}

/// An account's repository and the log it is kept in, apart from every other account's.
pub(crate) struct Store {
    pub repo: Repo,
    pub wal: Arc<Wal>,
    pub blobs: blobs::Blobs,
    /// Its records taken down, by path, each with its reference.
    pub takedowns: std::collections::BTreeMap<String, String>,
    /// Its space repos (`spec/SPACES-REPO.md`), kept in the same log.
    pub spaces: space_repo::Spaces,
    /// The spaces it is the authority of (`spec/SPACES-POLICIES.md`), kept in the same log.
    pub authority: space_authority::Authority,
    /// Its write notifications waiting to be sent again, and the
    /// registrations of its spaces and the notices owed them (`space_notify`).
    pub notify: space_notify::Kept,
    /// Its checkpoint's table, and where in its log what the log changed is
    /// (`checkpoint`): its tree's blocks and paths, and its events.
    pub disk: checkpoint::Disk,
    /// The greatest seq of its events, those let go too.
    pub last_seq: u64,
    /// The handle its last landed change gave it, if any did.
    pub logged_handle: Option<String>,
    /// A handle change of its recorded and not settled.
    pub pending: Option<identity::Pending>,
    /// What the accounts' stores share: the block cache, the marks of those a start loads.
    pub ctx: Arc<cache::Ctx>,
    /// The thread that loaded it.
    #[cfg(test)]
    pub thread: std::thread::ThreadId,
}

/// The server, as every request shares it.
pub(crate) struct Service {
    config: Config,
    dir: PathBuf,
    /// The service-wide log: accounts, sessions, app passwords and invite codes.
    log: Arc<Wal>,
    /// What loading an account's state needs, and the cache it is held in.
    ctx: Arc<cache::Ctx>,
    /// Every account: those loaded, and where the rest are.
    directory: Arc<directory::Accounts>,
    /// The sessions given out, and app passwords.
    sessions: sessions::Sessions,
    /// OAuth's requests, codes, sessions and devices.
    oauth: oauth::OAuth,
    /// Single-use values, such as DPoP proofs' `jti`s.
    replay: replay::Replay,
    /// The invite codes, and their uses.
    invites: invites::Invites,
    /// The firehose: one sequence across all accounts.
    events: Arc<events::Firehose>,
    http: reqwest::Client,
    /// Each account's handle changes, one at a time, and any not yet settled.
    changes: identity::Changes,
    /// What other parts of spaces hear of each space repo commit.
    space_hooks: space_repo::Hooks,
    /// Single-use values: delegation tokens and client attestations spent.
    single_use: single_use::Spent,
    /// Spaces' credentials: revocations, and issuers' keys read.
    space_credentials: space_credentials::Credentials,
    /// What the spaces' authority shares across accounts: the managing apps
    /// asked, and the writes of published records.
    space_authority: space_authority::Host,
    /// Rate limits, the free space, the clock, and the password hashes' threads.
    limits: limits::Limits,
    /// Which account each password reset token is of.
    resets: email::Resets,
    /// Every request to another service goes out through it.
    outbound: outbound::Outbound,
    /// The DID documents of services read lately.
    did_docs: proxy::DidDocs,
    /// The resolver of handles outside the server's domains.
    handle_resolver: identity::resolve::Resolver,
    /// Each account's preferences.
    prefs: preferences::Preferences,
    /// Write notifications and notices to syncers being sent, and when next.
    space_notify: space_notify::Notify,
}

type Shared = Arc<Service>;

/// Read what a lock guards: an `RwLock`'s value, or an account's store,
/// loaded first if it is not (`cache::Slot`).
fn read<L: Locked + ?Sized>(l: &L) -> L::Read<'_> {
    l.read_lock()
}

fn write<L: Locked + ?Sized>(l: &L) -> L::Write<'_> {
    l.write_lock()
}

/// What `read` and `write` take.
trait Locked {
    type Read<'a>
    where
        Self: 'a;
    type Write<'a>
    where
        Self: 'a;
    fn read_lock(&self) -> Self::Read<'_>;
    fn write_lock(&self) -> Self::Write<'_>;
}

impl<T> Locked for RwLock<T> {
    type Read<'a>
        = RwLockReadGuard<'a, T>
    where
        T: 'a;
    type Write<'a>
        = RwLockWriteGuard<'a, T>
    where
        T: 'a;
    fn read_lock(&self) -> RwLockReadGuard<'_, T> {
        self.read().unwrap_or_else(PoisonError::into_inner)
    }
    fn write_lock(&self) -> RwLockWriteGuard<'_, T> {
        self.write().unwrap_or_else(PoisonError::into_inner)
    }
}

impl<L: Locked> Locked for Arc<L> {
    type Read<'a>
        = L::Read<'a>
    where
        L: 'a;
    type Write<'a>
        = L::Write<'a>
    where
        L: 'a;
    fn read_lock(&self) -> L::Read<'_> {
        (**self).read_lock()
    }
    fn write_lock(&self) -> L::Write<'_> {
        (**self).write_lock()
    }
}

/// Return once frame `n` of `wal` is on disk, sharing an fsync with whoever
/// else waits: an error, logged, if it cannot be made so.
async fn durable(wal: Arc<Wal>, n: u64) -> Result<(), XrpcError> {
    ops::fsync(async move {
        if wal.is_durable(n) {
            return Ok(());
        }
        match tokio::task::spawn_blocking(move || wal.wait(n)).await {
            Ok(Ok(())) => Ok(()),
            Ok(Err(e)) => {
                ops::failed("syncing a log", e);
                internal()
            }
            Err(_) => internal(),
        }
    })
    .await
}

/// Who a request's access token says it is.
enum Auth {
    None,
    /// An account's session, by its DID.
    Account(String),
    /// A token the server did not give out, or not an access token, or a
    /// header not of the `Bearer` scheme.
    Invalid,
    /// An access token past its `exp`.
    Expired,
}

impl Auth {
    /// The account's DID, or the error a method that needs one answers.
    fn did(self) -> Result<String, XrpcError> {
        match self {
            Auth::Account(did) => Ok(did),
            Auth::None => err(401, "AuthMissing", "Authentication Required"),
            Auth::Invalid => invalid_token(),
            Auth::Expired => sessions::expired(),
        }
    }
}

impl Service {
    fn auth(&self, bearer: sessions::Bearer) -> Auth {
        match sessions::access_token(self, bearer) {
            Ok(t) => Auth::Account(t.did),
            Err(e) if e.name == "AuthMissing" => Auth::None,
            Err(e) if e.name == "ExpiredToken" => Auth::Expired,
            Err(_) => Auth::Invalid,
        }
    }

    /// Read an account's repository; `missing` is the error if no account has it.
    fn with_repo<T>(
        &self,
        shown: &mut Shown,
        id: &str,
        missing: impl FnOnce() -> XrpcError,
        f: impl FnOnce(&Account, &Repo) -> Result<T, XrpcError>,
    ) -> Result<T, XrpcError> {
        self.with_store(shown, id, missing, |a, st| f(a, &st.repo))
    }

    /// Read an account's store: its repository, blobs and takedowns.
    fn with_store<T>(
        &self,
        shown: &mut Shown,
        id: &str,
        missing: impl FnOnce() -> XrpcError,
        f: impl FnOnce(&Account, &Store) -> Result<T, XrpcError>,
    ) -> Result<T, XrpcError> {
        let Some(a) = self.account(id) else {
            return Err(missing());
        };
        let st = read(&a.store);
        shown.0.push((st.wal.clone(), st.wal.written()));
        f(&a, &st)
    }
}

/// How far into each account's log an answer has read: it is sent only once
/// that much is on disk, so that nothing it shows can be lost.
#[derive(Default)]
struct Shown(Vec<(Arc<Wal>, u64)>);

impl Shown {
    /// Return once each is on disk, in order: the first error, though each
    /// after it is waited for too.
    async fn durable(self) -> Result<(), XrpcError> {
        let mut out = Ok(());
        for (wal, n) in self.0 {
            let synced = durable(wal, n).await;
            out = out.and(synced);
        }
        out
    }

    /// How far into each account's log an answer has read, after the
    /// entry in the index of the events `landing`, if any: waited for first.
    fn after(landing: Option<&events::Landing>, logs: Vec<(Arc<Wal>, u64)>) -> Shown {
        Shown(
            landing
                .and_then(|l| l.entry())
                .into_iter()
                .chain(logs)
                .collect(),
        )
    }
}

/// The media type of a STAR archive (`spec/SPACES.md`), as a space repo's
/// and a space meta archive are sent and taken.
const STAR_TYPE: &str = "application/vnd.dasl.star";

enum Resp {
    Json(Json),
    Car(Vec<u8>),
    /// A repository's CAR file, read as it is sent (`sync::CarStream`).
    CarStream(sync::CarStream),
    /// No answer, as a method with no output gives: `200` with an empty body.
    Nothing,
    Blob(blobs::Served),
    /// A service's answer, as the server answers it (`spec/PROXY.md`).
    Upstream(proxy::Upstream),
    /// A JSON answer with headers of its own.
    Headed(Json, Vec<(&'static str, String)>),
    /// A STAR archive, as a space meta archive (`STAR_TYPE`).
    Star(Vec<u8>),
    /// A space repo's archive, read as it is sent (`space_repo::Archive`),
    /// with headers of its own, as its commit's MAC.
    Archive(space_repo::Archive, Vec<(&'static str, String)>),
}

/// An error as XRPC answers it: an HTTP status, a name and a message.
struct XrpcError {
    status: u16,
    name: &'static str,
    message: String,
}

fn err<T>(status: u16, name: &'static str, message: impl Into<String>) -> Result<T, XrpcError> {
    Err(XrpcError {
        status,
        name,
        message: message.into(),
    })
}

fn invalid<T>(message: impl Into<String>) -> Result<T, XrpcError> {
    err(400, "InvalidRequest", message)
}

fn internal<T>() -> Result<T, XrpcError> {
    err(500, "InternalServerError", "Internal Server Error")
}

fn invalid_token<T>() -> Result<T, XrpcError> {
    err(400, "InvalidToken", "Invalid token")
}

/// A refusal of the repository's, as the reference answers it.
impl From<Refused> for XrpcError {
    fn from(r: Refused) -> XrpcError {
        let (status, name, message) = match r {
            Refused::StaleCommit => (400, "InvalidSwap", "Commit was at a different CID"),
            Refused::Exists(_) | Refused::Missing(_) => {
                (500, "InternalServerError", "Internal Server Error")
            }
            Refused::TooBig => (400, "InvalidRequest", "Commit is too large"),
        };
        XrpcError {
            status,
            name,
            message: message.into(),
        }
    }
}

/// One call of a method, over XRPC or as an MCP tool.
struct Call<'a> {
    nsid: &'a str,
    method: &'a Method,
    params: &'a [(String, String)],
    body: &'a [u8],
    /// What the `Authorization` header holds.
    bearer: sessions::Bearer<'a>,
    /// The request's headers; none for a call not made over HTTP.
    headers: &'a HeaderMap,
    /// The client it is from, as the rate limits key on it.
    client: String,
    /// What it cost of the rate limits, for its answer's headers.
    charged: OnceLock<limits::Charged>,
    /// The HTTP request, for a call made over XRPC.
    http: Option<&'a Http>,
}

/// What a call made over XRPC was sent with, beyond its method, arguments and headers.
struct Http {
    uri: Uri,
    /// The body, which `Call::body` is too, for a forwarded request to keep.
    body: Bytes,
}

/// A query's answer, given the call and its parameters; it notes in `Shown`
/// the repositories it read.
type QueryFn = fn(&Service, &Call, &mut Shown, &Map<String, Json>) -> Result<Resp, XrpcError>;

/// A repository write, once its input is checked, to apply to the repository its `repo` names.
type Apply = Box<dyn FnOnce(&mut Store) -> Result<Resp, XrpcError> + Send>;

/// A repository write: its input checked, the write to apply.
type WriteFn = fn(&Map<String, Json>) -> Result<Apply, XrpcError>;

type Answer = Pin<Box<dyn Future<Output = Result<Resp, XrpcError>> + Send>>;

/// Any other procedure, given its input. It runs to its end even if its caller goes away.
type ProcedureFn = fn(Shared, Map<String, Json>) -> Answer;

/// The token a procedure takes, checked: the session it is of, or the error to answer.
type CheckFn = fn(&Service, sessions::Bearer) -> Result<sessions::Token, XrpcError>;

/// A procedure that takes a token, given the token checked and its input.
type AuthedFn = fn(Shared, sessions::Token, Map<String, Json>) -> Answer;

/// A query that asks outside the server, given its parameters.
type LookupFn = fn(Shared, Map<String, Json>) -> Answer;

/// A method that forwards its request to another service, given the
/// request and, for a query, its parameters checked.
type ProxyFn = fn(Shared, proxy::Request, Map<String, Json>) -> Answer;

/// A method that takes its call as it came, and checks it in its own order.
type CallFn = for<'a> fn(
    &'a Shared,
    &'a Call<'a>,
    &'static pds_lexicon::Method,
) -> Pin<Box<dyn Future<Output = Result<Resp, XrpcError>> + Send + 'a>>;

/// What answers a method.
enum Handler {
    /// A query, which reads and changes nothing.
    Query(QueryFn),
    /// A query that waits on something outside the server, such as the PLC directory.
    Lookup(LookupFn),
    /// A write to the repository its `repo` names: only that account may make
    /// it, and its token is checked before its input, its `repo` after.
    Write(WriteFn),
    Procedure(ProcedureFn),
    /// A procedure that takes a token, checked before its input; or a query,
    /// its token checked before its parameters.
    Authed(CheckFn, AuthedFn),
    /// A method that may forward its request (`spec/PROXY.md`); a query's
    /// parameters are checked first.
    Proxy(ProxyFn),
    /// A method that takes its call as it came, and checks it in its own order.
    Call(CallFn),
}

/// Each area's methods: what answers a method, by its NSID, if the area has it.
const AREAS: &[fn(&str) -> Option<Handler>] = &[
    server::handler,
    sessions::handler,
    email::handler,
    repo::handler,
    sync::handler,
    federation::handler,
    identity::handler,
    blobs::handler,
    invites::handler,
    lifecycle::handler,
    migration::handler,
    proxy::handler,
    preferences::handler,
    space_repo::handler,
    space_credentials::handler,
    space_authority::handler,
    space_notify::handler,
];

fn handler(nsid: &str) -> Option<Handler> {
    AREAS.iter().find_map(|area| area(nsid))
}

/// What `pds serve` is given by its environment, as `spec/PDS.md` says.
struct Environment {
    port: u16,
    dir: PathBuf,
    address: std::net::IpAddr,
    config: Config,
    ops: ops::Settings,
}

impl Environment {
    /// Read from the environment: why not, if a variable is missing or
    /// does not parse.
    fn read() -> Result<Environment, String> {
        let var = |n: &str| std::env::var(n).map_err(|_| format!("{n} is not set"));
        let port = var("PDS_PORT")?
            .parse::<u16>()
            .map_err(|_| "PDS_PORT is not a port".to_string())?;
        let dir = PathBuf::from(var("PDS_DATA_DIR")?);
        let address = match std::env::var("PDS_BIND_ADDRESS")
            .ok()
            .filter(|a| !a.is_empty())
        {
            None => std::net::IpAddr::from([127, 0, 0, 1]),
            Some(a) => a
                .parse()
                .map_err(|_| format!("PDS_BIND_ADDRESS is {a:?}, not an IPv4 or IPv6 address"))?,
        };
        let config = Config::from_env()?;
        let ops = ops::Settings::from_env(port)?;
        Ok(Environment {
            port,
            dir,
            address,
            config,
            ops,
        })
    }
}

/// Say why the process cannot go on, on standard error, and exit 1.
fn fail(why: String) -> ! {
    eprintln!("pds: {why}");
    std::process::exit(1);
}

/// Run the server, configured by the environment as `spec/PDS.md` says,
/// until a SIGTERM or SIGINT shuts it down (`spec/OPERATIONS.md`).
pub fn run() {
    // The file descriptors it may have, before the share of them the
    // configuration takes is read, and before anything is opened: left as
    // they are where they cannot be raised.
    pds_store::files::raise();
    let Environment {
        port,
        dir,
        address,
        config,
        ops: settings,
    } = Environment::read().unwrap_or_else(|e| fail(e));
    // The data directory is this process's alone while it runs, before
    // anything is written (`spec/COMMANDS.md`).
    let _held = store::hold(&dir).unwrap_or_else(|e| fail(e));
    // Where the data directory keeps its blobs, before anything is written.
    blobstore::check_dir(&dir, config.blobstore.is_some()).unwrap_or_else(|e| fail(e));
    ops::start(settings, port, config.sync);
    let unclean = ops::unclean(&dir);
    let svc = Arc::new(
        Service::open(&dir, config)
            .unwrap_or_else(|e| fail(format!("cannot recover {}: {e}", dir.display()))),
    );
    ops::recovered(&svc, unclean).unwrap_or_else(|e| fail(e));
    let app = router(svc.clone());
    tokio::runtime::Runtime::new().unwrap().block_on(async {
        let stop = ops::signals();
        ops::serve_beside(&svc).await.unwrap_or_else(|e| fail(e));
        federation::tell_crawlers(&svc);
        let listener = tokio::net::TcpListener::bind((address, port))
            .await
            .unwrap_or_else(|e| fail(format!("listening on {address} port {port}: {e}")));
        // Handle changes in flight when the server stopped are settled while it serves.
        identity::settle_unfinished(&svc);
        // Directories of no account go while it serves.
        directory::sweep_once(&svc);
        // The firehose's index is read while it serves.
        events::find_soon(&svc);
        // What a start after a kill found is made durable while it serves,
        // the logs of accounts nothing asks for too.
        ops::sync_found_soon(&svc);
        blobs::sweep_every(&svc);
        blobstore::delete_every(&svc);
        cache::sweep_every(&svc);
        // Notifications kept when the server stopped are sent again when due.
        space_notify::start(&svc);
        // Issuers' keys the last run kept are read back while it serves.
        space_credentials::issuers::start(&svc);
        let signal = limits::serve(listener, app, stop).await;
        ops::shutdown(&svc, signal).await
    })
}

/// `pds migrate-blobs --to <to>`: move the data directory's blobs into the
/// bucket or out of it, given the environment `pds serve` is, as
/// `spec/BLOBS.md`'s "Moving them" says (`migrate_blobs`); print what it
/// moved and exit 0, or say why not and exit 1.
pub fn migrate_blobs(to: Place) -> ! {
    let env = Environment::read().unwrap_or_else(|e| fail(e));
    if env.config.blobstore.is_none() {
        fail("PDS_BLOBSTORE_S3_BUCKET is not set: it names the bucket the blobs are moved into, or out of".into());
    }
    let _held = store::hold(&env.dir).unwrap_or_else(|e| fail(e));
    let moved = tokio::runtime::Runtime::new()
        .unwrap()
        .block_on(migrate_blobs::run(&env.dir, env.config, to))
        .unwrap_or_else(|e| fail(e));
    use std::io::Write;
    let mut out = std::io::stdout();
    let _ = writeln!(
        out,
        "{{\"moved\":{},\"bytes\":{}}}",
        moved.blobs, moved.bytes
    )
    .and_then(|()| out.flush());
    std::process::exit(0);
}

/// The server's routes. Every path under `/xrpc/` is a method, served or
/// forwarded. Each answers browsers as `cors` says.
fn router(svc: Shared) -> Router {
    Router::new()
        .route(
            "/xrpc/com.atproto.sync.subscribeRepos",
            get(events::subscribe),
        )
        .route("/", any(ops::root))
        .route("/xrpc/_health", any(ops::health))
        .route("/xrpc/_logs", any(ops::logs))
        .route("/xrpc/_stats", any(ops::stats))
        .route(
            "/xrpc/_oauthSessions",
            any(|s, m, h, p, b| account::xrpc(s, m, h, p, b, Own::Sessions)),
        )
        .route(
            "/xrpc/_oauthRevokeSession",
            any(|s, m, h, p, b| account::xrpc(s, m, h, p, b, Own::RevokeSession)),
        )
        .route(
            "/xrpc/_oauthDevices",
            any(|s, m, h, p, b| account::xrpc(s, m, h, p, b, Own::Devices)),
        )
        .route(
            "/xrpc/_oauthRevokeDevice",
            any(|s, m, h, p, b| account::xrpc(s, m, h, p, b, Own::RevokeDevice)),
        )
        .route(
            "/xrpc/_passkeyList",
            any(|s, m, h, p, b| account::xrpc(s, m, h, p, b, Own::PasskeyList)),
        )
        .route(
            "/xrpc/_passkeyAdd",
            any(|s, m, h, p, b| account::xrpc(s, m, h, p, b, Own::PasskeyAdd)),
        )
        .route(
            "/xrpc/_passkeyRemove",
            any(|s, m, h, p, b| account::xrpc(s, m, h, p, b, Own::PasskeyRemove)),
        )
        .route("/xrpc/com.atproto.repo.uploadBlob", any(blobs::upload))
        .route("/xrpc/{*method}", any(handle))
        .route("/mcp", any(mcp::endpoint))
        .route("/.well-known/atproto-did", get(identity::well_known))
        .merge(oauth::routes())
        .with_state(svc)
        .layer(axum::middleware::from_fn(cors::layer))
}

/// A request's `Authorization` header, as text; one that is not is empty, which no scheme is.
fn authorization(headers: &HeaderMap) -> Option<String> {
    headers
        .get(header::AUTHORIZATION)
        .map(|v| v.to_str().unwrap_or_default().to_string())
}

/// A call over XRPC: the method is what follows `/xrpc/` in the path, as sent.
async fn handle(
    AxState(st): AxState<Shared>,
    method: Method,
    uri: Uri,
    headers: HeaderMap,
    peer: Option<Extension<limits::Peer>>,
    body: Body,
) -> Response {
    let nsid = uri
        .path()
        .strip_prefix("/xrpc/")
        .unwrap_or_default()
        .to_string();
    let params: Vec<(String, String)> = uri
        .query()
        .map(|q| {
            url::form_urlencoded::parse(q.as_bytes())
                .into_owned()
                .collect()
        })
        .unwrap_or_default();
    // Read only so far past the method's limit: `input`, and `proxy::forward`
    // for a request it forwards, refuse a body longer than it.
    let Some(body) = limits::read_body(body, limits::read_limit(&st, &nsid)).await else {
        return respond(invalid("The body could not be read"), None);
    };
    let authorization = authorization(&headers);
    let bearer = sessions::Bearer::of(authorization.as_deref());
    let client = limits::client(
        &st.config.trusted_proxies,
        &headers,
        peer.map(|Extension(p)| p.0),
    );
    let http = Http { uri, body };
    let mut call = Call {
        nsid: &nsid,
        method: &method,
        params: &params,
        body: &http.body,
        bearer,
        headers: &headers,
        client,
        charged: OnceLock::new(),
        http: Some(&http),
    };
    let grant = match scopes::look(&st, &call, &headers).await {
        Ok(g) => g,
        Err(r) => return *r,
    };
    if let Some(g) = &grant {
        call.bearer = sessions::Bearer::OAuth(g);
    }
    let answer = answer(&st, &call).await;
    scopes::answered(&st, grant.as_ref(), respond(answer, call.charged.get()))
}

/// An answer as XRPC sends it, with what it cost of the rate limits.
fn respond(answer: Result<Resp, XrpcError>, charged: Option<&limits::Charged>) -> Response {
    let mut res = match answer {
        Ok(Resp::Json(j)) => (
            StatusCode::OK,
            [(header::CONTENT_TYPE, "application/json")],
            j.to_string(),
        )
            .into_response(),
        Ok(Resp::Car(b)) => (
            StatusCode::OK,
            [(header::CONTENT_TYPE, "application/vnd.ipld.car")],
            b,
        )
            .into_response(),
        Ok(Resp::CarStream(c)) => c.response(),
        Ok(Resp::Nothing) => StatusCode::OK.into_response(),
        Ok(Resp::Blob(b)) => blobs::response(b),
        Ok(Resp::Upstream(u)) => {
            let mut r = Response::new(Body::from(u.body));
            *r.status_mut() = StatusCode::from_u16(u.status).unwrap_or(StatusCode::BAD_GATEWAY);
            for (n, v) in u.headers {
                r.headers_mut().append(n, v);
            }
            r
        }
        Ok(Resp::Headed(j, headers)) => with_headers(
            (
                StatusCode::OK,
                [(header::CONTENT_TYPE, "application/json")],
                j.to_string(),
            )
                .into_response(),
            headers,
        ),
        Ok(Resp::Star(b)) => {
            (StatusCode::OK, [(header::CONTENT_TYPE, STAR_TYPE)], b).into_response()
        }
        Ok(Resp::Archive(a, headers)) => with_headers(a.response(), headers),
        Err(e) => (
            StatusCode::from_u16(e.status).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR),
            [(header::CONTENT_TYPE, "application/json")],
            json!({ "error": e.name, "message": e.message }).to_string(),
        )
            .into_response(),
    };
    if let Some(c) = charged {
        c.apply(res.headers_mut());
    }
    res
}

/// An answer with headers of its own added.
fn with_headers(mut r: Response, headers: Vec<(&'static str, String)>) -> Response {
    for (name, value) in headers {
        if let Ok(v) = header::HeaderValue::from_str(&value) {
            r.headers_mut()
                .append(header::HeaderName::from_static(name), v);
        }
    }
    r
}

/// Whether an error is a token's, which costs a call nothing of the rate limits.
fn token_error(e: &XrpcError) -> bool {
    matches!(e.name, "AuthMissing" | "InvalidToken" | "ExpiredToken")
}

/// Answer a call. A query reads the repositories it needs side by side with
/// other calls; a write has its account's repository alone, only to apply
/// it and hand its log frame to the operating system. Either is answered
/// only once what it read or wrote is on disk, waited for with no lock held,
/// so that calls meanwhile share the fsync. Each pays the rate limits once
/// its parameters, token and input are checked (`limits::guard`). Once they
/// are, the state of the account the call is of may refuse it
/// (`lifecycle::gate`).
async fn answer(svc: &Shared, call: &Call<'_>) -> Result<Resp, XrpcError> {
    // A method the server does not serve, in any case, is forwarded, and
    // costs its point first, unless it paid already as it arrived
    // (`scopes::look`).
    let nsid = match proxy::served(svc, call.nsid) {
        Ok(Some(nsid)) => nsid,
        served => {
            if call.charged.get().is_none() {
                limits::charge(svc, call, None, None)?;
            }
            served?;
            return proxy::forward(svc, call).await;
        }
    };
    if nsid == call.nsid {
        return serve(svc, call).await;
    }
    // Named in another case: answered as the lexicon names it, its rate
    // limits' headers kept for the call's answer.
    let named = Call {
        nsid,
        method: call.method,
        params: call.params,
        body: call.body,
        bearer: call.bearer,
        headers: call.headers,
        client: call.client.clone(),
        charged: OnceLock::new(),
        http: call.http,
    };
    let out = serve(svc, &named).await;
    if let Some(c) = named.charged.into_inner() {
        let _ = call.charged.set(c);
    }
    out
}

/// Answer a call of a method the server serves, as its lexicon names it.
async fn serve(svc: &Shared, call: &Call<'_>) -> Result<Resp, XrpcError> {
    let h = handler(call.nsid).expect("a method served has a handler");
    let m = method_of(call)?;
    match h {
        Handler::Query(f) => {
            let p = params(call, m)?;
            scopes::admit(call)?;
            let mut shown = Shown::default();
            // A query changes nothing, so it may pay once it has run: its
            // token, checked within it, costs nothing if it is refused, nor
            // a scope checked with it (`getServiceAuth`'s `rpc`), nor its
            // account's state checked with it (`lifecycle::with_token`).
            let out =
                lifecycle::gate_query(svc, call, &p).and_then(|()| f(svc, call, &mut shown, &p));
            if !out.as_ref().is_err_and(|e| {
                token_error(e)
                    || e.name == "ScopeMissingError"
                    || lifecycle::refused_with_token(call.nsid, e)
            }) {
                limits::charge(svc, call, None, None)?;
            }
            shown.durable().await?;
            blobs::read_object(svc, out).await
        }
        Handler::Lookup(f) => {
            let p = params(call, m)?;
            scopes::admit(call)?;
            limits::guard(svc, call, None, None)?;
            lifecycle::gate_query(svc, call, &p)?;
            ops::spawn(f(svc.clone(), p))
                .await
                .unwrap_or_else(|_| internal())
        }
        Handler::Write(f) => write_repo(svc, call, m, f).await,
        Handler::Procedure(f) => {
            scopes::admit(call)?;
            let b = input(call, m)?;
            limits::guard(svc, call, None, Some(&b))?;
            ops::spawn(f(svc.clone(), b))
                .await
                .unwrap_or_else(|_| internal())
        }
        // An OAuth token was checked as the call arrived: what its scope
        // needs is before the token the method checks.
        Handler::Authed(check, f) => {
            scopes::admit(call)?;
            let token = check(svc, call.bearer)?;
            let early = lifecycle::with_token(call.nsid);
            if early {
                lifecycle::gate(svc, call.nsid, &token.did)?;
            }
            // A query that takes a token takes its parameters as a procedure its input.
            let b = if m.kind == Kind::Query {
                params(call, m)?
            } else {
                input(call, m)?
            };
            limits::guard(svc, call, Some(&token.did), Some(&b))?;
            scopes::of_input(call.bearer, call.nsid, &b)?;
            if !early {
                lifecycle::gate(svc, call.nsid, &token.did)?;
            }
            ops::spawn(f(svc.clone(), token, b))
                .await
                .unwrap_or_else(|_| internal())
        }
        Handler::Proxy(f) => {
            let p = match m.kind {
                Kind::Query => m
                    .parse_params(call.params.iter().map(|(k, v)| (k.as_str(), v.as_str())))
                    .or_else(|e| invalid(e.0))?,
                _ => Map::new(),
            };
            // It pays once its token, what its scope needs of the service it
            // goes to, its account's state if it is checked with the token,
            // and its input are checked, as any other call does, before it
            // goes anywhere.
            let did = match proxy::needs_token(call.nsid) {
                true => Some(preferences::token(svc, call.nsid, call.bearer)?.did),
                false => None,
            };
            proxy::scope(svc, call)?;
            if let Some(did) = did.as_deref().filter(|_| lifecycle::with_token(call.nsid)) {
                lifecycle::gate(svc, call.nsid, did)?;
            }
            let p = match m.kind {
                Kind::Procedure => filled_input(call, m)?,
                _ => p,
            };
            limits::guard(svc, call, did.as_deref(), Some(&p))?;
            ops::spawn(f(svc.clone(), proxy::Request::of(call), p))
                .await
                .unwrap_or_else(|_| internal())
        }
        // A method that checks its call in its own order pays the limits itself (`limits::guard`).
        Handler::Call(f) => blobs::read_object(svc, f(svc, call, m).await).await,
    }
}

/// A query's parameters, checked against its lexicon.
fn params(call: &Call, m: &pds_lexicon::Method) -> Result<Map<String, Json>, XrpcError> {
    m.parse_params(call.params.iter().map(|(k, v)| (k.as_str(), v.as_str())))
        .or_else(|e| invalid(e.0))
}

/// A write checks, in this order, its token, its input, its `repo`, the
/// number of its writes, what it needs of an OAuth scope, then its records'
/// `$type`.
async fn write_repo(
    svc: &Shared,
    call: &Call<'_>,
    m: &pds_lexicon::Method,
    f: WriteFn,
) -> Result<Resp, XrpcError> {
    let did = svc.auth(call.bearer).did()?;
    let b = input(call, m)?;
    let apply = f(&b)?;
    limits::guard(svc, call, Some(&did), Some(&b))?;
    let Some(account) = svc.account(required(&b, "repo")?) else {
        return err(403, "AccountNotFound", "Could not find account");
    };
    // The repository's account's state decides first, whoever's token it is.
    lifecycle::gate(svc, call.nsid, &account.did)?;
    if account.did != did {
        return err(401, "AuthenticationRequired", "Bad token scope");
    }
    if b.get("writes")
        .and_then(Json::as_array)
        .is_some_and(|w| w.len() > limits::MAX_WRITES)
    {
        return invalid(format!("Too many writes. Max: {}", limits::MAX_WRITES));
    }
    scopes::records(call.bearer, call.nsid, &b)?;
    let (out, shown, landing, doomed) = {
        let mut st = write(&account.store);
        let st = &mut *st;
        // Deleted while it waited for the lock.
        lifecycle::not_deleted(&account)?;
        st.repo.change = None;
        st.blobs.time(svc.limits.clock.now(), svc.config.blob_ttl);
        let mut out = apply(st);
        let landing = match (&out, st.repo.change.take()) {
            (Ok(_), Some(mut c)) => match log::log_commit(&svc.events, &account.did, st, &c) {
                Ok(l) => {
                    // A record deleted is no longer taken down.
                    for path in &c.dels {
                        st.takedowns.remove(path);
                    }
                    Some(l)
                }
                Err(e) => {
                    // Nothing of it reached the log: nothing of it stays.
                    ops::error(
                        "a write failed",
                        &[("did", json!(account.did)), ("error", json!(e.to_string()))],
                    );
                    if let Some(u) = c.undo.take() {
                        st.repo.undo(u);
                    }
                    st.blobs.undo();
                    out = internal();
                    None
                }
            },
            _ => None,
        };
        let shown = Shown::after(landing.as_ref(), vec![(st.wal.clone(), st.wal.written())]);
        (out, shown, landing, st.blobs.take_doomed())
    };
    // The write is in the log: the rest must happen even if the caller goes away,
    // or its event would never reach the firehose.
    let svc = svc.clone();
    let finish = ops::spawn(async move {
        let synced = shown.durable().await;
        if let Some(l) = landing {
            svc.events.land(l);
        }
        blobs::forget(&svc, &account, doomed);
        synced
    });
    finish.await.unwrap_or_else(|_| internal())?;
    out
}

/// The method a call names, called with the right HTTP method: a query by
/// `POST` or a procedure by `GET` is refused before anything else is looked at.
fn method_of(call: &Call) -> Result<&'static pds_lexicon::Method, XrpcError> {
    method_named(call.nsid, call.method)
}

/// The method `nsid` names, if it may be called with the HTTP method `method`.
fn method_named(nsid: &str, method: &Method) -> Result<&'static pds_lexicon::Method, XrpcError> {
    let not_here = || err(501, "MethodNotImplemented", "Method not implemented");
    let Some(m) = pds_lexicon::method(nsid) else {
        return not_here();
    };
    let want = match m.kind {
        Kind::Query => Method::GET,
        Kind::Procedure => Method::POST,
        Kind::Subscription => return not_here(),
    };
    if *method != want && !(want == Method::GET && *method == Method::HEAD) {
        return invalid(format!("Incorrect HTTP method ({method}) expected {want}"));
    }
    Ok(m)
}

/// A procedure's input, checked against its lexicon, once its length is: a
/// body longer than its method takes is `413 PayloadTooLargeError`. A
/// procedure that takes none takes no body either.
fn input(call: &Call, m: &pds_lexicon::Method) -> Result<Map<String, Json>, XrpcError> {
    if m.input.is_none() {
        return if call.body.is_empty() {
            Ok(Map::new())
        } else {
            invalid("Request body is not allowed")
        };
    }
    if call.body.len() > limits::body_limit(call.nsid) {
        return limits::too_large();
    }
    let Ok(input) = serde_json::from_slice::<Json>(call.body) else {
        return invalid("Invalid request body");
    };
    m.check_input(&input).or_else(|e| invalid(e.0))?;
    let Json::Object(b) = input else {
        return invalid("Invalid request body");
    };
    Ok(b)
}

/// A procedure's input, as `input` reads it, with the defaults its lexicon
/// gives filled in before it is checked.
fn filled_input(call: &Call, m: &pds_lexicon::Method) -> Result<Map<String, Json>, XrpcError> {
    if call.body.len() > limits::body_limit(call.nsid) {
        return limits::too_large();
    }
    let Ok(mut input) = serde_json::from_slice::<Json>(call.body) else {
        return invalid("Invalid request body");
    };
    m.fill_input_defaults(&mut input);
    m.check_input(&input).or_else(|e| invalid(e.0))?;
    let Json::Object(b) = input else {
        return invalid("Invalid request body");
    };
    Ok(b)
}

/// A string argument, which the lexicon checked is there.
fn required<'a>(args: &'a Map<String, Json>, name: &str) -> Result<&'a str, XrpcError> {
    args.get(name)
        .and_then(Json::as_str)
        .map_or_else(|| invalid(format!("{name} must be a string")), Ok)
}

fn opt<'a>(args: &'a Map<String, Json>, name: &str) -> Option<&'a str> {
    args.get(name).and_then(Json::as_str)
}

/// The latest commit, as a write and `getLatestCommit` answer it.
fn commit_meta(r: &Repo) -> Json {
    json!({ "cid": r.head_string(), "rev": r.rev })
}

/// What the area modules' tests share: a PLC directory, a server on a
/// scratch directory, and calls to it as a request would make them.
#[cfg(test)]
mod testing {
    use super::*;
    use axum::body::Bytes;
    use std::collections::HashMap;
    use std::path::Path as FsPath;

    /// A PLC directory, at the URL answered, which takes a genesis operation
    /// only if its signature and DID are as `atproto/did-plc.md` says, and
    /// refuses any for a handle starting `refused`. It serves each DID's
    /// document at `/<did>`, and its current data at `/<did>/data`; a `PUT`
    /// there, which no real directory takes, names another PDS in it, as an
    /// operation moving the DID would.
    pub async fn plc() -> String {
        use axum::extract::{Path, State};
        type Ops = Arc<std::sync::Mutex<HashMap<String, Json>>>;
        async fn post(State(ops): State<Ops>, Path(did): Path<String>, body: Bytes) -> StatusCode {
            let Ok(op) = serde_json::from_slice::<Json>(&body) else {
                return StatusCode::BAD_REQUEST;
            };
            if op["alsoKnownAs"][0]
                .as_str()
                .is_some_and(|h| h.starts_with("at://refused"))
                || crate::plc::verify(&did, &op).is_err()
            {
                return StatusCode::BAD_REQUEST;
            }
            ops.lock().unwrap().insert(did, op);
            StatusCode::OK
        }
        async fn get_doc(State(ops): State<Ops>, Path(did): Path<String>) -> Response {
            let Some(op) = ops.lock().unwrap().get(&did).cloned() else {
                return StatusCode::NOT_FOUND.into_response();
            };
            (
                [(header::CONTENT_TYPE, "application/json")],
                did_document(&did, &op).to_string(),
            )
                .into_response()
        }
        async fn get_data(State(ops): State<Ops>, Path(did): Path<String>) -> Response {
            let Some(op) = ops.lock().unwrap().get(&did).cloned() else {
                return StatusCode::NOT_FOUND.into_response();
            };
            let data = json!({
                "did": did, "verificationMethods": op["verificationMethods"], "rotationKeys": op["rotationKeys"],
                "alsoKnownAs": op["alsoKnownAs"], "services": op["services"],
            });
            (
                [(header::CONTENT_TYPE, "application/json")],
                data.to_string(),
            )
                .into_response()
        }
        async fn move_pds(
            State(ops): State<Ops>,
            Path(did): Path<String>,
            body: Bytes,
        ) -> StatusCode {
            let mut ops = ops.lock().unwrap();
            let Some(op) = ops.get_mut(&did) else {
                return StatusCode::NOT_FOUND;
            };
            op["services"]["atproto_pds"]["endpoint"] = json!(String::from_utf8_lossy(&body));
            StatusCode::OK
        }
        let app = Router::new()
            .route("/{did}", get(get_doc).post(post))
            .route("/{did}/data", get(get_data).put(move_pds))
            .with_state(Ops::default());
        let listener = tokio::net::TcpListener::bind(("127.0.0.1", 0))
            .await
            .unwrap();
        let url = format!("http://{}", listener.local_addr().unwrap());
        tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
        url
    }

    /// The DID document a directory renders from a DID's last operation:
    /// the signing key as a `Multikey`, and a KEM key in the legacy form
    /// `spec/SPACES.md` says the harness's directory renders it in.
    pub fn did_document(did: &str, op: &Json) -> Json {
        let key = op["verificationMethods"]["atproto"]
            .as_str()
            .unwrap()
            .trim_start_matches("did:key:")
            .to_string();
        let mut context = vec![json!("https://www.w3.org/ns/did/v1")];
        let mut methods = vec![
            json!({ "id": format!("{did}#atproto"), "type": "Multikey", "controller": did, "publicKeyMultibase": key }),
        ];
        if let Some(kem) = op["verificationMethods"]["atproto_kem"].as_str() {
            let point = pds_space::PublicKey::from_did_key(kem)
                .unwrap()
                .uncompressed();
            context.push(json!("https://w3id.org/security/suites/ecdsa-2019/v1"));
            methods.push(json!({
                "id": "#atproto_kem", "type": "EcdsaSecp256r1VerificationKey2019", "controller": did,
                "publicKeyMultibase": format!("z{}", bs58::encode(point).into_string()),
            }));
        }
        json!({
            "@context": context,
            "id": did, "alsoKnownAs": op["alsoKnownAs"],
            "verificationMethod": methods,
            "service": [{ "id": "#atproto_pds", "type": "AtprotoPersonalDataServer", "serviceEndpoint": op["services"]["atproto_pds"]["endpoint"] }],
        })
    }

    std::thread_local! {
        /// How the servers a test's thread opens sync (`syncing`).
        static SYNC: std::cell::Cell<Syncing> = const { std::cell::Cell::new(Syncing::Together) };
    }

    /// Both ways a server syncs, for a test of what a power cut leaves to
    /// run in each.
    pub const SYNCS: [Syncing; 2] = [Syncing::Together, Syncing::Each];

    /// Have the servers this thread opens from now on sync so: `together`
    /// until it is said.
    pub fn syncing(sync: Syncing) {
        SYNC.with(|s| s.set(sync));
    }

    /// The configuration the tests run with: no rate limits, no floor of
    /// free space or of `createSession`'s time, and every DID document
    /// fetched again, so that each test sees what it changes at once.
    pub fn config(plc_url: &str) -> Config {
        Config {
            hostname: "localhost".into(),
            public_url: "http://127.0.0.1:2583".into(),
            handle_domains: vec![".test".into(), ".example".into()],
            plc_url: plc_url.into(),
            rotation_key: k256::ecdsa::SigningKey::from_slice(&[9u8; 32]).unwrap(),
            recovery_did_key: Some(
                "did:key:zQ3shokFTS3brHcDQrn82RUDfCZESWL1ZdCEJwekUDPQiYBme".into(),
            ),
            crawlers: vec![],
            oauth_client_fetch: None,
            // A DID the directory does not have: no set resolves, and nothing asks DNS.
            lexicon_authority: Some("did:plc:aaaaaaaaaaaaaaaaaaaaaaaa".into()),
            lexicon_dns: None,
            // The tests' own DNS server and web: a handle resolves only as a test serves it.
            handle_dns: Some(identity::resolve::stub::addrs().0),
            handle_fetch: Some(identity::resolve::stub::addrs().1),
            invite_required: false,
            admin_password: Some(ADMIN_PASSWORD.into()),
            trusted_proxies: Default::default(),
            rate_limits: false,
            blob_quota: 1 << 30,
            blob_ttl: 3600,
            min_free: 0,
            max_import: 5 << 20,
            blob_upload_limit: crate::blobs::DEFAULT_UPLOAD_LIMIT,
            did_cache: 0,
            did_cache_max: 86_400,
            login_floor: std::time::Duration::ZERO,
            sign_in_floor: std::time::Duration::ZERO,
            mailer: Default::default(),
            proxy: proxy::Settings::default(),
            ssrf_protection: false,
            backfill: std::time::Duration::from_millis(86_400_000),
            log_floor: crate::store::FLOOR,
            account_cap: crate::store::ACCOUNT_CAP,
            cache_bytes: 256 << 20,
            share: 64,
            load_all: true,
            blobstore: None,
            sync: SYNC.with(std::cell::Cell::get),
        }
    }

    /// The admin's password in `config`.
    pub const ADMIN_PASSWORD: &str = "admin-pw";

    /// The server on `dir`, registering DIDs at `plc_url`.
    pub fn open(dir: &FsPath, plc_url: &str) -> Shared {
        Arc::new(try_open(dir, plc_url).unwrap())
    }

    pub fn try_open(dir: &FsPath, plc_url: &str) -> Result<Service, String> {
        Service::open(dir, config(plc_url))
    }

    /// The server on `dir`, configured as `config` and then `change` says.
    pub fn open_with(dir: &FsPath, plc_url: &str, change: impl FnOnce(&mut Config)) -> Shared {
        let mut c = config(plc_url);
        change(&mut c);
        Arc::new(Service::open(dir, c).unwrap())
    }

    /// A call with a bearer token; a `null` body is none.
    pub async fn call_with(
        s: &Shared,
        nsid: &str,
        token: Option<&str>,
        params: &[(String, String)],
        body: Json,
    ) -> Result<Json, String> {
        let bearer = token.map_or(sessions::Bearer::None, sessions::Bearer::Token);
        call_raw(
            s,
            nsid,
            bearer,
            params,
            &if body.is_null() {
                String::new()
            } else {
                body.to_string()
            },
        )
        .await
    }

    /// A call as sent: its `Authorization` header and body. A method's empty answer is `null`.
    pub async fn call_raw(
        s: &Shared,
        nsid: &str,
        bearer: sessions::Bearer<'_>,
        params: &[(String, String)],
        body: &str,
    ) -> Result<Json, String> {
        let method = if pds_lexicon::method(nsid).is_some_and(|m| m.kind == Kind::Query) {
            Method::GET
        } else {
            Method::POST
        };
        let headers = HeaderMap::new();
        let call = Call {
            nsid,
            method: &method,
            params,
            body: body.as_bytes(),
            bearer,
            headers: &headers,
            client: "127.0.0.1".into(),
            charged: OnceLock::new(),
            http: None,
        };
        match answer(s, &call).await {
            Ok(Resp::Json(j) | Resp::Headed(j, _)) => Ok(j),
            Ok(Resp::Car(_) | Resp::CarStream(_)) => Err("a CAR file".into()),
            Ok(Resp::Star(_) | Resp::Archive(..)) => Err("bytes".into()),
            Ok(Resp::Nothing) => Ok(Json::Null),
            Ok(Resp::Blob(_)) => Err("a blob".into()),
            // A service's answer: its JSON, or for an error, its name.
            Ok(Resp::Upstream(u)) if u.status < 400 => {
                Ok(serde_json::from_slice(&u.body).unwrap_or(Json::Null))
            }
            Ok(Resp::Upstream(u)) => Err(serde_json::from_slice::<Json>(&u.body)
                .ok()
                .and_then(|j| j["error"].as_str().map(str::to_string))
                .unwrap_or_else(|| u.status.to_string())),
            Err(e) => Err(e.name.to_string()),
        }
    }

    pub async fn call(
        s: &Shared,
        nsid: &str,
        token: Option<&str>,
        body: Json,
    ) -> Result<Json, String> {
        call_with(s, nsid, token, &[], body).await
    }

    pub fn scratch(name: &str) -> std::path::PathBuf {
        let d = std::env::temp_dir().join(format!("pds-test-{}-{name}", std::process::id()));
        let _ = std::fs::remove_dir_all(&d);
        d
    }

    /// How many syncs to the disk this thread has made (`pds_store::on_sync`)
    /// since this was first asked, on any thread: a test counts those of
    /// what it does on its own thread, as loading a store, whatever the
    /// tests beside it sync.
    pub fn syncs() -> u64 {
        use std::cell::Cell;
        thread_local!(static MADE: Cell<u64> = const { Cell::new(0) });
        pds_store::on_sync(|_| MADE.with(|n| n.set(n.get() + 1)));
        MADE.with(Cell::get)
    }

    /// Shut the server down in order, as a SIGTERM does, but for exiting:
    /// its mark is left, with its word if the run may leave it.
    pub fn shut_down(s: Shared) {
        s.events.close();
        ops::settle(&s).unwrap();
        ops::mark(&s).unwrap();
    }

    /// What the journal of the data directory `dir` holds put back where it
    /// is kept, and its segments let go, as a start does before anything
    /// else: the logs then hold every frame the server wrote, and a test
    /// changes or cuts them as a kill leaves them, a write a kill cut short
    /// in its log never having reached the journal.
    pub fn redone(dir: &FsPath) {
        pds_store::journal::redo(dir, pds_store::journal::Redo::Eager).unwrap();
    }

    /// Create an account `<name>.test`, with password `<name>-pw`; answers its DID and access token.
    pub async fn create(s: &Shared, name: &str) -> (String, String) {
        let body = json!({ "handle": format!("{name}.test"), "email": format!("{name}@mail.com"), "password": format!("{name}-pw") });
        let got = call(s, "com.atproto.server.createAccount", None, body)
            .await
            .unwrap();
        (
            got["did"].as_str().unwrap().to_string(),
            got["accessJwt"].as_str().unwrap().to_string(),
        )
    }

    /// A new session of `<name>.test`'s.
    pub async fn session(s: &Shared, name: &str) -> String {
        let body =
            json!({ "identifier": format!("{name}.test"), "password": format!("{name}-pw") });
        let sess = call(s, "com.atproto.server.createSession", None, body)
            .await
            .unwrap();
        sess["accessJwt"].as_str().unwrap().to_string()
    }

    /// The repository of the account `did`.
    pub fn repo_of<T>(s: &Service, did: &str, f: impl FnOnce(&Repo) -> T) -> T {
        store_of(s, did, |st| f(&st.repo))
    }

    /// The store of the account `did`.
    pub fn store_of<T>(s: &Service, did: &str, f: impl FnOnce(&Store) -> T) -> T {
        let a = s.account(did).unwrap();
        let st = read(&a.store);
        f(&st)
    }

    /// Every record of the account `did`, in order of path.
    pub fn records_of(s: &Service, did: &str) -> Vec<(String, pds_repo::Record)> {
        store_of(s, did, |st| {
            let mut paths = Vec::new();
            st.each_path(|p, _, _| paths.push(p.to_string()));
            paths
                .into_iter()
                .map(|p| (p.clone(), st.record(&p).unwrap()))
                .collect()
        })
    }

    /// A record as the tests write them.
    pub fn record(n: i64) -> Json {
        json!({ "$type": "a.b.c", "n": n, "b": { "$bytes": "AQID" } })
    }
}