didbot_serve/

wire.rs

//! The JSON shapes the XRPC routes read and write.
//!
//! These types exist separately from the engine's types on purpose. The engine
//! speaks `OffsetDateTime` and `Vec<u8>`; the wire speaks RFC 3339 and hex.
//! Keeping the conversion in one place means a field can be renamed in the
//! engine without silently renaming it for every client.

use std::collections::BTreeMap;

use didbot_claim_check::Credential;
use didbot_identity::OidcIdentity;
use didbot_pds::{
    AccountKind, AccountState, Cid, Holds, HostedAccount, LifecycleSnapshot, ListParams, Lock,
    Locks, Party, Precondition, RegistryStats, Tag, Written, DEFAULT_LIST_LIMIT,
};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use time::format_description::well_known::Rfc3339;

use crate::error::ApiError;

/// Body of `bot.did.createAccount`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CreateAccountRequest {
    /// The hostname of the new `did:web`: one label under a zone this
    /// server serves, taken exactly or refused. Exclusive with `pool` and
    /// `fragments`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// The pool the server makes the name in. Absent, with no `name`
    /// either, the first pool policy permits makes it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub pool: Option<String>,
    /// Text for slots of the pool's naming scheme, such as a prefix.
    /// Requires `pool`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub fragments: Vec<Fragment>,
    /// What the account is: `service`, `host`, `pipeline` or `agent`.
    pub kind: String,
    /// A multibase public key the new account holds itself, published as
    /// its `#key-1`. Exclusive with `parkedKey`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub key: Option<String>,
    /// The OpenID Connect identity the new account is, published as its
    /// `#oidc`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub oidc: Option<OidcIdentity>,
    /// The fingerprint `bot.did.parkKey` answered with, naming the parked
    /// key to publish. Exclusive with `key`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub parked_key: Option<String>,
    /// The DID of the hosted account creating this one: the account an ID
    /// token is checked against, and the account a session or a key proof
    /// must be.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub parent: Option<String>,
}

/// Text for one slot of a pool's naming scheme.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Fragment {
    /// The slot's name in the pool's scheme.
    pub slot: String,
    /// The text that fills it.
    pub value: String,
}

/// Body of `bot.did.parkKey`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ParkKeyRequest {
    /// The hostname the key waits to be admitted under.
    pub name: String,
    /// What the account will be.
    pub kind: String,
    /// The public key, multibase.
    pub key: String,
}

/// Query of `bot.did.createSession`.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct SessionQuery {
    /// The account the session is for: the account an ID token is checked
    /// against, and the `iss` a key proof must carry.
    #[serde(default)]
    pub did: Option<String>,
}

/// Query of `bot.did.describeParkedKey`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ParkedKeyQuery {
    /// The hostname a key was parked for.
    pub name: String,
    /// The fingerprint `bot.did.parkKey` answered with. Absent, the newest
    /// park under the name is described.
    #[serde(default)]
    pub fingerprint: Option<String>,
}

/// The kind a request names, or a 400 naming what it accepts.
pub fn parse_kind(kind: &str) -> Result<AccountKind, ApiError> {
    serde_json::from_value(Value::String(kind.to_owned())).map_err(|_| {
        ApiError::bad_request(format!(
            "kind: {kind:?} is not one of service, host, pipeline, agent"
        ))
    })
}

/// Body of `bot.did.approveAuthorization`.
///
/// No account field: the account is the one the presented agent token
/// authenticates as, which is what makes "the account named in the request
/// is the account approving" a check the credential enforces rather than a
/// value a caller supplies.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ApproveAuthorizationRequest {
    /// The one-time approval token from the decision record.
    pub token: String,
}

/// Body of `bot.did.declineAuthorization`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DeclineAuthorizationRequest {
    /// The one-time approval token from the decision record.
    pub token: String,
    /// Why, in the declining agent's own words. Logged, never published.
    #[serde(default)]
    pub reason: Option<String>,
}

/// Body of `bot.did.deleteAccount`, and of the freeze and deactivate routes
/// and their inverses.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DidRequest {
    /// The account to act on.
    pub did: String,
}

/// Query of `bot.did.getAccountLedger`.
///
/// A query rather than a body because it reads, and a `did` rather than a
/// handle because a handle is released when the account is: the one caller
/// this route exists for is somebody asking about an agent that is already
/// gone, and by then the name may belong to somebody else.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct LedgerQuery {
    /// The agent to read the bookkeeping of.
    pub did: String,
}

/// What this deployment is doing right now, for a reader with no
/// credential.
///
/// The same snapshot `routes::require_lifecycle` refuses from, so a page
/// saying a deployment serves reads and a `503` saying it does not cannot
/// both be answered at once. Every field is already visible to a caller who
/// tries the route and reads the refusal; this is that fact stated once,
/// where it can be read without provoking one.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct LifecycleLine {
    /// Where the deployment is; see [`didbot_pds::ServerState`].
    pub state: String,
    /// See [`didbot_pds::ServerPolicy::serves_reads`].
    pub serves_reads: bool,
    /// See [`didbot_pds::ServerPolicy::accepts_record_writes`].
    pub accepts_record_writes: bool,
    /// See [`didbot_pds::ServerPolicy::provisions_accounts`].
    pub provisions_accounts: bool,
    /// See [`didbot_pds::LifecycleSnapshot::claim_standing`].
    pub claim_standing: bool,
}

impl LifecycleLine {
    /// Reads one snapshot of the lifecycle.
    pub fn from_snapshot(snapshot: &LifecycleSnapshot) -> Self {
        Self {
            state: snapshot.state.to_string(),
            serves_reads: snapshot.policy.serves_reads,
            accepts_record_writes: snapshot.policy.accepts_record_writes,
            provisions_accounts: snapshot.policy.provisions_accounts,
            claim_standing: snapshot.claim_standing,
        }
    }
}

/// One entry in the `listAccounts` response.
///
/// This server's account of its own contents, which is the most a listing
/// can ever be. A reader deriving "which agents does this operator have" from
/// it gets a lower bound: a server can omit an entry, and nothing in the
/// operator's repository would contradict it, because an operator writes one
/// `bot.did.operator` record per *server* and never one per agent. What a
/// server cannot do is inflate the count — a DID it invents has no record
/// behind it in the operator's repository — so a reader that verifies each
/// entry rather than trusting the list is safe in one direction and short
/// in the other. See `docs/operator-verification.md`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct AccountSummary {
    /// The account's DID.
    pub did: String,
    /// The agent the account was minted for.
    pub account_id: String,
    /// The handle the account answers to, when it has one.
    ///
    /// The name is the interesting half of an account for anyone reading a
    /// listing: `basalt-otter.agents.example` is a thing a person can hold in
    /// their head and `a3f9c1.agents.example` is not. It is reported as the
    /// server stored it, zone and all, so that a reader can check it lands
    /// under the zone the server admits to minting rather than trusting the
    /// label alone.
    ///
    /// Absent only for an account provisioned before this deployment issued
    /// handles. An account whose handle is its own hostname reports that
    /// hostname: it is what the account actually answers to, and saying
    /// nothing would be a different claim.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub handle: Option<String>,
    /// What kind of account it is.
    #[serde(default)]
    pub kind: AccountKind,
    /// When the account was provisioned, RFC 3339.
    pub created_at: String,
    /// Whether the data exists; see [`AccountState`].
    #[serde(default)]
    pub state: AccountState,
    /// Every lock hung on the account, each with the party that hung it.
    ///
    /// The one surface that can say an account is frozen at all: `#account`
    /// cannot, because the lexicon has no wire concept of "active but not
    /// writable". See `docs/conformance.md`.
    #[serde(default, skip_serializing_if = "Locks::is_empty")]
    pub locks: Locks,
    /// Every hold set on the account.
    #[serde(default, skip_serializing_if = "Holds::is_empty")]
    pub holds: Holds,
    /// The hosted account that created this one; absent for a root, whose
    /// operator is the deployment's. See [`didbot_pds::HostedAccount::parent`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub parent: Option<String>,
    /// The human who answers for this account: the same DID its
    /// registration names, at any depth. [`Self::parent`] is the next hop
    /// of the walk in `docs/ownership.md`.
    pub operator: String,
    /// What a stranger can authenticate as this account with.
    pub proof: AccountProof,
    /// Whether the edge above this account still stands. See [`EdgeState`].
    pub edge: EdgeState,
}

/// What the account's own DID document offers a stranger as proof of being
/// it, beside the `#atproto` key this server signs its commits with.
///
/// Read off the stored account rather than the served document: the two are
/// written from the same values, and a listing that re-fetched every
/// document would make one read of a roster into one request per account.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "camelCase")]
pub enum AccountProof {
    /// A key credential: whoever signs with the private half is the
    /// account.
    Key {
        /// The public half, multibase, as the credential record holds it.
        key: String,
    },
    /// An OpenID Connect credential: an ID token from the issuer carrying
    /// every claim listed, each with the value given.
    Oidc {
        /// The issuer and the claims a token from it must carry.
        #[serde(flatten)]
        identity: OidcIdentity,
    },
    /// No credential record, so the account is reached only through a
    /// session this server issued.
    Session,
}

impl AccountProof {
    /// The first of `credentials`, a key before an identity, or `Session`
    /// when there are none.
    pub fn of(credentials: &[Credential]) -> Self {
        if let Some(key) = credentials
            .iter()
            .find_map(Credential::public_key_multibase)
        {
            return Self::Key {
                key: key.to_owned(),
            };
        }
        if let Some(identity) = credentials.iter().find_map(Credential::oidc_identity) {
            return Self::Oidc {
                identity: identity.clone(),
            };
        }
        Self::Session
    }
}

/// Whether the edge from an account to its operator still stands.
///
/// Derived from the hasp rather than stored beside it, so it cannot
/// disagree with [`AccountSummary::locks`]: `Quarantined` hung by
/// `Party::Parent` is what the confinement poll writes when a vouch above
/// an account is gone, and that tag is the one fact about the *edge*. Every
/// other lock is about the account.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum EdgeState {
    /// Nothing is hung: the walk in `docs/ownership.md` runs from here.
    Verified,
    /// A vouch above this account is gone and the grace window has passed,
    /// so the walk stops short of the operator.
    Paused,
    /// A lock an operator, a policy or the account itself hung. The edge is
    /// intact; the account is not serving normally.
    Locked,
}

impl EdgeState {
    /// What `account`'s hasp says about the edge above it.
    pub fn of(account: &HostedAccount) -> Self {
        if account
            .locks
            .holds(Tag::new(Lock::Quarantined, Party::Parent))
        {
            Self::Paused
        } else if account.locks.is_empty() {
            Self::Verified
        } else {
            Self::Locked
        }
    }

    /// The kebab-case name the page and the wire use.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Verified => "verified",
            Self::Paused => "paused",
            Self::Locked => "locked",
        }
    }
}

impl AccountSummary {
    /// Summarizes a stored account, with `operator` as the DID this
    /// deployment's operator holds.
    ///
    /// A timestamp that will not format is reported as an empty string rather
    /// than failing the whole listing. `Rfc3339` only rejects years outside
    /// 0000..=9999, which no clock this reads will produce.
    pub fn from_account(
        account: &HostedAccount,
        operator: &str,
        credentials: &[Credential],
    ) -> Self {
        Self {
            did: account.did.as_str().to_owned(),
            account_id: account.account_id.clone(),
            handle: account.handle.clone(),
            kind: account.kind,
            created_at: account.created_at.format(&Rfc3339).unwrap_or_default(),
            state: account.state,
            locks: account.locks.clone(),
            holds: account.holds.clone(),
            parent: account
                .parent
                .as_ref()
                .map(|parent| parent.as_str().to_owned()),
            operator: operator.to_owned(),
            proof: AccountProof::of(credentials),
            edge: EdgeState::of(account),
        }
    }
}

/// Reads a field that may be present and `null`.
///
/// `Option<Option<T>>` with this on it distinguishes an absent key from one
/// written as `null`, which `Option<T>` alone cannot. `putRecord` declares
/// `swapRecord` nullable and an explicit `null` there means "assert this
/// record does not exist yet" -- a different request from not asking at all,
/// and one this server has to be able to see in order to refuse it.
fn present<'de, D, T>(de: D) -> Result<Option<T>, D::Error>
where
    D: serde::Deserializer<'de>,
    T: Deserialize<'de>,
{
    T::deserialize(de).map(Some)
}

/// The compare-and-swap fields, as they arrive on the wire.
///
/// Both are CIDs naming a version to swap against, and both are now
/// evaluated. [`Swap::resolve`] turns them into the preconditions the store
/// and the registry check; a CID that does not decode is refused there,
/// before anything is read, because it is a statement about the request
/// rather than about the repository.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Swap {
    /// Swap against the previous version of this record.
    ///
    /// Nullable in the lexicon, so it is read as a double option: `null`
    /// asserts the record does not exist, and absent asserts nothing.
    #[serde(
        default,
        deserialize_with = "present",
        skip_serializing_if = "Option::is_none"
    )]
    pub swap_record: Option<Option<String>>,
    /// Swap against the repository's current commit.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub swap_commit: Option<String>,
}

impl Swap {
    /// The preconditions these fields ask for.
    ///
    /// `swapRecord: null` is [`Precondition::Absent`] -- the lexicon marks
    /// the field nullable and `null` asserts the record does not exist yet --
    /// and a CID is [`Precondition::Version`]. An absent field asserts
    /// nothing, which is what leaving it out means.
    pub fn resolve(&self) -> Result<didbot_pds::Swap, ApiError> {
        Ok(didbot_pds::Swap {
            record: match self.swap_record.as_ref() {
                None => Precondition::Unconditional,
                Some(None) => Precondition::Absent,
                Some(Some(cid)) => Precondition::Version(parse_swap_cid("swapRecord", cid)?),
            },
            commit: self
                .swap_commit
                .as_deref()
                .map(|cid| parse_swap_cid("swapCommit", cid))
                .transpose()?,
        })
    }

    /// The same, for a route whose lexicon declares only `swapCommit`.
    ///
    /// `createRecord` and `applyWrites` have no `swapRecord` field. A body
    /// carrying one is refused rather than ignored: a client that sent it
    /// believes its write is conditional, and neither route has one key to
    /// make it conditional on -- `applyWrites` writes many records, and
    /// `createRecord` is already conditional on the key being free.
    pub fn resolve_commit_only(&self, route: &str) -> Result<didbot_pds::Swap, ApiError> {
        if self.swap_record.is_some() {
            return Err(ApiError::bad_request(format!(
                "`{route}` declares no `swapRecord`; swap against one record with `putRecord` \
                 or `deleteRecord`"
            )));
        }
        self.resolve()
    }
}

/// Decodes a swap field, or refuses the request.
///
/// A 400 rather than an `InvalidSwap`: `InvalidSwap` means the swap did not
/// hold, and tells a client to re-read the record and retry. A CID that does
/// not decode will not decode on the retry either.
fn parse_swap_cid(field: &str, cid: &str) -> Result<Cid, ApiError> {
    Cid::parse(cid).map_err(|err| {
        ApiError::bad_request(format!("`{field}` is not a usable cid: {cid:?}: {err}"))
    })
}

/// The `validate` flag, which is atproto's own name for the three stances.
///
/// The Lexicon specification names three: *explicit*, where every record must
/// resolve to a known schema and satisfy it; *optimistic*, where a record is
/// checked when a schema is at hand and stored faithfully when it is not; and
/// *skip*. The parameter is a tri-state and each state is one of them.
///
/// Unset is optimistic, and it is the stance this server takes.
/// `true` is explicit and is honoured for the one request: a record in a
/// collection this server holds no lexicon for is refused rather than stored.
///
/// `false` skips the schema check, and this server honours it for a
/// collection it holds no lexicon for: there is no check to skip, and the
/// record is stored and reported `unknown` just as it is when the flag is
/// unset. A collection whose lexicon it holds is read by an index, a
/// clusterer and a canvas that rely on its shape, and a record stored past
/// its own schema is one no reader downstream can rely on. So `false` naming
/// one of those `collections` is refused rather than ignored, for the same
/// reason a swap field is: a request whose precondition this server will
/// not meet should say so.
pub fn refuse_skipped_validation<'a>(
    validate: Option<bool>,
    collections: impl IntoIterator<Item = &'a str>,
) -> Option<ApiError> {
    if validate != Some(false) {
        return None;
    }
    let held = collections
        .into_iter()
        .find(|collection| didbot_pds::schema_is_held(collection))?;
    Some(ApiError::bad_request(format!(
        "`validate: false` is not supported for `{held}`: this server holds its lexicon and \
         checks every record written to it"
    )))
}

/// The pre-check `validate: true` asks for, which is the explicit stance for
/// one request.
///
/// Runs before anything is stored. The optimistic check the store performs is
/// a subset of this one, so a record that passes here passes there.
pub fn require_known_lexicon(
    collection: &str,
    record: &Value,
    validate: Option<bool>,
) -> Option<ApiError> {
    if validate != Some(true) {
        return None;
    }
    didbot_pds::validate_with(collection, record, didbot_pds::Stance::Explicit)
        .err()
        .map(|err| crate::error::repo_surface(&didbot_pds::ProvisionError::Record(err)))
}

/// Body of `com.atproto.repo.createRecord`.
///
/// `record` is an opaque [`Value`], checked against the collection's lexicon
/// on write.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CreateRecordRequest {
    /// The repository to write into, as a DID or a handle.
    pub repo: String,
    /// The collection NSID the record belongs to.
    pub collection: String,
    /// The record key to write under, if the caller has one in mind.
    ///
    /// Optional, and a request rather than an instruction. The collection's
    /// lexicon declares how its keys are chosen and that is what decides: a
    /// `literal:self` collection lands at `self` whether this is given or not,
    /// and a key the strategy will not admit is a 400 rather than something
    /// quietly written elsewhere.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub rkey: Option<String>,
    /// The record itself.
    pub record: Value,
    /// Whether to check the record against its lexicon; see
    /// [`refuse_skipped_validation`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub validate: Option<bool>,
    /// The compare-and-swap field this route declares. Refused; see [`Swap`].
    #[serde(flatten)]
    pub swap: Swap,
}

/// Body of `com.atproto.repo.putRecord`.
///
/// The same as [`CreateRecordRequest`] with a required `rkey`. The two do the
/// same thing here, and that is a divergence worth naming: atproto's
/// `createRecord` refuses a key that is already in use and `putRecord` is the
/// upsert, and telling them apart needs a compare-and-swap this server cannot
/// perform. Both overwrite.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PutRecordRequest {
    /// The repository to write into, as a DID or a handle.
    pub repo: String,
    /// The collection NSID the record belongs to.
    pub collection: String,
    /// The record key to write under. Required, unlike on `createRecord`.
    pub rkey: String,
    /// The record itself.
    pub record: Value,
    /// Whether to check the record against its lexicon.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub validate: Option<bool>,
    /// Both compare-and-swap fields. Refused; see [`Swap`].
    #[serde(flatten)]
    pub swap: Swap,
}

/// Body of `com.atproto.repo.deleteRecord`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DeleteRecordRequest {
    /// The repository to delete from, as a DID or a handle.
    pub repo: String,
    /// The collection NSID the record is in.
    pub collection: String,
    /// The record key.
    pub rkey: String,
    /// Both compare-and-swap fields. Refused; see [`Swap`].
    #[serde(flatten)]
    pub swap: Swap,
}

/// Query of `com.atproto.repo.getRecord`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GetRecordQuery {
    /// The repository to read, as a DID or a handle.
    pub repo: String,
    /// The collection NSID the record is in.
    pub collection: String,
    /// The record key.
    pub rkey: String,
    /// Which version of the record, by CID.
    ///
    /// Accepted and never satisfied. The lexicon says an absent `cid` returns
    /// the most recent version, so the ordinary request works; a request that
    /// names a version is asking for a record this server cannot say it holds,
    /// because it attaches no CID to anything. That is `RecordNotFound`, which
    /// is exactly what the reference implementation answers when a named
    /// version is not the one it has.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cid: Option<String>,
}

/// Query of `com.atproto.repo.describeRepo`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DescribeRepoQuery {
    /// The repository to describe, as a DID or a handle.
    pub repo: String,
}

/// Response of `com.atproto.repo.createRecord`.
///
/// # The `cid` names the record, and it is the one the export uses
///
/// The lexicon declares `cid` a *required* output and this server now emits
/// one: the hash of the record's canonical DAG-CBOR encoding, computed by
/// `didbot_pds::content_id`. It is the same value the Merkle search
/// tree keys the record by and the CAR export at
/// `com.atproto.sync.getRepo` files it under, which is what makes it safe for
/// a client to do the things a client does with a CID — pin it, deduplicate
/// by it, quote it from another record, or hand it back as a
/// compare-and-swap precondition.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CreateRecordResponse {
    /// The `at://` URI the record was written to.
    pub uri: String,
    /// The CID naming the record's contents.
    pub cid: String,
    /// `valid` or `unknown`, and a real report rather than a constant.
    ///
    /// The lexicon's `knownValues` are `valid` and `unknown`, and `unknown` is
    /// what a server says when it stored a record whose lexicon it could not
    /// resolve. That is exactly what the optimistic stance makes possible
    ///, so this field is how a client learns which of the two happened
    /// to the record it just wrote.
    pub validation_status: &'static str,
}

impl CreateRecordResponse {
    /// The answer for a record the store has just written.
    pub fn written(did: &str, collection: &str, written: &Written) -> Self {
        Self {
            uri: record_uri(did, collection, &written.rkey),
            cid: written.cid.to_string(),
            validation_status: didbot_pds::validation_status(
                collection,
                didbot_pds::Stance::Optimistic,
            ),
        }
    }
}

/// Response of `com.atproto.repo.getRecord`.
///
/// The `cid` is optional in the lexicon and is always present here: it is
/// derived from the record being returned rather than stored beside it, so
/// there is no state in which one is available and the other is not. See
/// [`CreateRecordResponse`].
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct GetRecordResponse {
    /// The `at://` URI of the record.
    pub uri: String,
    /// The CID naming the record's contents.
    pub cid: String,
    /// The record, byte for byte as it was written.
    pub value: Value,
}

/// Response of `com.atproto.repo.describeRepo`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DescribeRepoResponse {
    /// The handle the account answers to.
    pub handle: String,
    /// The account's DID.
    pub did: String,
    /// The account's whole DID document.
    pub did_doc: Value,
    /// Every collection the repository holds at least one record in.
    ///
    /// An open set, and a report rather than a menu; see
    /// `describe_repo`.
    pub collections: Vec<String>,
    /// Whether the handle resolves back to this DID.
    ///
    /// atproto's handle rule is bidirectional and this field is the server
    /// saying whether it holds. Here it is computed the same way a stranger
    /// would compute it -- the document claims a handle, the handle is
    /// resolved, and the two are compared -- rather than asserted, so a
    /// deployment whose naming has drifted reports `false` instead of
    /// insisting.
    pub handle_is_correct: bool,
}

/// Response of `com.atproto.server.describeServer`.
///
/// Every field this server can answer honestly. `inviteCodeRequired`,
/// `phoneVerificationRequired`, `blobUploadLimit`, `links` and `contact` are
/// all optional in the lexicon and this server states none of them today —
/// there is no invite system, no phone verification, and no configured
/// policy or contact document to point at — so they are left out rather
/// than filled with a value nobody chose. `availableUserDomains` is the one
/// field this response exists to get right; see
/// [`Registry::available_user_domains`](didbot_pds::Registry::available_user_domains).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DescribeServerResponse {
    /// This server's own service DID.
    pub did: String,
    /// Every domain suffix a handle issued by this deployment may end in.
    pub available_user_domains: Vec<String>,
}

/// Query of `com.atproto.repo.listRecords`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ListRecordsQuery {
    /// The repository to read, as a DID or a handle.
    pub repo: String,
    /// The collection NSID to list.
    pub collection: String,
    /// How many records to return.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub limit: Option<usize>,
    /// The record key a previous page ended on, resumed after.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cursor: Option<String>,
    /// Read oldest first rather than newest first.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reverse: Option<bool>,
}

/// The most records `listRecords` will return in one answer.
///
/// The lexicon's `maximum`. A request above it is capped rather than refused,
/// which is the same posture the query service takes: a client
/// asking for ten thousand wants as many as it can have, and an error only
/// teaches it to ask for exactly the ceiling with a round trip in front.
pub const MAX_LIST_LIMIT: usize = 100;

impl ListRecordsQuery {
    /// The limit to apply, defaulting when the caller did not choose one.
    ///
    /// A limit of zero is honoured rather than treated as unset: a caller
    /// asking for no records is asking a question about existence, and
    /// answering it with fifty records would be answering a different one.
    /// The lexicon's `minimum` is one, so a conformant client cannot ask it
    /// anyway.
    pub fn effective_limit(&self) -> usize {
        self.limit.unwrap_or(DEFAULT_LIST_LIMIT).min(MAX_LIST_LIMIT)
    }

    /// The page this query asks the store for.
    ///
    /// The cursor is passed through as the record key it is. It is not
    /// decoded, checked or signed: it names a position in public data the
    /// same request would have reached anyway, and a cursor naming a key
    /// that is not there is not an error — it is where to carry on from,
    /// which is what makes a page survive the deletion of the row it
    /// resumed after.
    pub fn page(&self) -> ListParams {
        ListParams::new(self.effective_limit())
            .maybe_after(self.cursor.clone())
            .reversed(self.reverse.unwrap_or(false))
    }
}

/// One operation in a `com.atproto.repo.applyWrites` batch.
///
/// A closed union, tagged by `$type` exactly as the lexicon spells the
/// variants. Closed means a `$type` that is none of the three is refused, and
/// serde's internally tagged enum gives that for free: an unrecognised tag is
/// a deserialization failure and becomes a 400 naming the field.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "$type")]
pub enum RepoWrite {
    /// Write a new record, minting a key when none is named.
    #[serde(rename = "com.atproto.repo.applyWrites#create")]
    Create {
        /// The collection NSID.
        collection: String,
        /// The record key, if the caller has one in mind.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        rkey: Option<String>,
        /// The record. Named `value` here, unlike `record` on the single
        /// routes; the lexicon spells it both ways and this is the one it
        /// spells here.
        value: Value,
    },
    /// Replace the record at a key.
    #[serde(rename = "com.atproto.repo.applyWrites#update")]
    Update {
        /// The collection NSID.
        collection: String,
        /// The record key.
        rkey: String,
        /// The record.
        value: Value,
    },
    /// Remove the record at a key, or make sure it is gone.
    #[serde(rename = "com.atproto.repo.applyWrites#delete")]
    Delete {
        /// The collection NSID.
        collection: String,
        /// The record key.
        rkey: String,
    },
}

/// The most writes one `com.atproto.repo.applyWrites` batch may carry.
///
/// A batch is one commit, and atproto's sync specification says "at most 200
/// record operations can be included in a commit"; a relay drops a commit
/// that carries more. The reference PDS refuses such a batch the same way.
pub const MAX_APPLY_WRITES: usize = 200;

/// Body of `com.atproto.repo.applyWrites`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ApplyWritesRequest {
    /// The repository to act on, as a DID or a handle.
    pub repo: String,
    /// The operations, applied in order: at most 200, see
    /// `MAX_APPLY_WRITES` (this module).
    pub writes: Vec<RepoWrite>,
    /// Whether to check every record against its lexicon.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub validate: Option<bool>,
    /// The compare-and-swap field this route declares. Refused; see [`Swap`].
    #[serde(flatten)]
    pub swap: Swap,
}

/// One entry in the `applyWrites` results, one per write, in order.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "$type")]
pub enum WriteResult {
    /// A record was created.
    #[serde(rename = "com.atproto.repo.applyWrites#createResult")]
    #[serde(rename_all = "camelCase")]
    Create {
        /// Where it landed.
        uri: String,
        /// `valid` or `unknown`; see [`CreateRecordResponse`].
        /// The CID naming what was written; see [`CreateRecordResponse`].
        cid: String,
        /// `valid`; see [`CreateRecordResponse`].
        validation_status: &'static str,
    },
    /// A record was replaced.
    #[serde(rename = "com.atproto.repo.applyWrites#updateResult")]
    #[serde(rename_all = "camelCase")]
    Update {
        /// Where it landed.
        uri: String,
        /// `valid` or `unknown`; see [`CreateRecordResponse`].
        /// The CID naming what was written; see [`CreateRecordResponse`].
        cid: String,
        /// `valid`; see [`CreateRecordResponse`].
        validation_status: &'static str,
    },
    /// A record was removed, or was already gone.
    ///
    /// The lexicon's `deleteResult` has no properties at all, so this carries
    /// nothing -- not even whether anything was there. A caller that needs to
    /// know asks `getRecord` first.
    #[serde(rename = "com.atproto.repo.applyWrites#deleteResult")]
    Delete {},
}

/// One entry in the `listRecords` response.
///
/// The lexicon requires a `cid` on every row; see [`CreateRecordResponse`].
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct RecordView {
    /// The `at://` URI of this record.
    pub uri: String,
    /// The CID naming this record's contents.
    pub cid: String,
    /// The stored record, byte for byte as it was written.
    pub value: Value,
}

impl RecordView {
    /// Renders one stored record for the wire, naming it by its contents.
    ///
    /// Fails only for a record the atproto data model cannot encode, which
    /// the write path refuses before storing anything; see
    /// [`didbot_pds::content_id`].
    pub fn new(
        did: &str,
        collection: &str,
        rkey: &str,
        value: Value,
    ) -> Result<Self, didbot_pds::RecordError> {
        Ok(Self {
            uri: record_uri(did, collection, rkey),
            cid: didbot_pds::content_id(&value)?.to_string(),
            value,
        })
    }
}

/// The `at://` URI naming one record.
///
/// Assembled here rather than in a handler so that the URI a write returns and
/// the URI a listing reports cannot drift apart.
pub fn record_uri(did: &str, collection: &str, rkey: &str) -> String {
    format!("at://{did}/{collection}/{rkey}")
}

/// Response of `bot.did.stats`.
///
/// One field per subject, and a subject with more than one figure to it
/// carries them in an object of its own rather than in a row of prefixed
/// keys: `blobs` is what this deployment's blobs come to, and every question
/// about them is answered inside it.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct StatsResponse {
    /// How many accounts are provisioned.
    pub accounts: usize,
    /// How many records exist across every repository.
    pub records: usize,
    /// The stored size of those records as compact JSON.
    pub bytes: usize,
    /// How many records each collection holds.
    pub collections: BTreeMap<String, usize>,
    /// What this deployment's blobs come to, by the state each blob is in.
    ///
    /// Measured apart from `bytes` rather than folded into it: records are
    /// measured as compact JSON and blobs as themselves, and one number over
    /// two units would be a number nothing could act on. An operator
    /// watching a run wants to know which of the two is growing.
    pub blobs: BlobsView,
    /// How many live accounts hold a reference on a parent, by the child's
    /// kind: what a principal cannot be deactivated or erased over. Absent
    /// while nothing hangs beneath anything.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub live_children: BTreeMap<String, usize>,
    /// What operator policy this deployment enforces.
    #[serde(default)]
    pub policy: PolicyView,
    /// The `[tree]` bounds this deployment is judging creates by right now.
    ///
    /// Read live rather than at startup, so an operator who has edited
    /// `[tree]` can see here whether the running server has picked the
    /// edit up yet.
    #[serde(default)]
    pub tree: TreeView,
}

/// The `tree` member of [`StatsResponse`]: one field per `[tree]` key,
/// spelled the way the key is.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct TreeView {
    /// `[tree] max_depth`.
    pub max_depth: u32,
    /// `[tree] max_children`.
    pub max_children: u32,
    /// `[tree] creates_per_hour`.
    pub creates_per_hour: u32,
}

impl Default for TreeView {
    fn default() -> Self {
        didbot_pds::TreeLimits::default().into()
    }
}

impl From<didbot_pds::TreeLimits> for TreeView {
    fn from(limits: didbot_pds::TreeLimits) -> Self {
        Self {
            max_depth: limits.max_depth,
            max_children: limits.max_children,
            creates_per_hour: limits.creates_per_hour,
        }
    }
}

/// The `policy` member of [`StatsResponse`].
///
/// The digest alone answers "is this server on my newest edit"; the lists
/// answer the two questions that follow, which are "which of my records is
/// it enforcing, and on whom" and "why is the one I just wrote not among
/// them". Every value here is either a record key from the operator's own
/// public repository or a DID `bot.did.listAgents` answers with, so this
/// carries the same `Credential::Disclosure` decision the rest of
/// `bot.did.stats` does.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PolicyView {
    /// The digest of the operator's policy and binding records this
    /// deployment enforces, over every record's key and body. An operator
    /// computes the same digest over their own repository and compares;
    /// absent until a revision has been read.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub enforced: Option<String>,
    /// Every `bot.did.policy` record in force, by record key.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub policies: Vec<PolicyRecordView>,
    /// Every `bot.did.policyBinding` record in force, by record key.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub bindings: Vec<PolicyBindingView>,
    /// Every record the newest build would not honour and had nothing in
    /// force at its key to keep. These enforce nothing.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub refused: Vec<PolicyRefusalView>,
    /// Every record the newest build would not honour where the record in
    /// force at its key keeps being enforced. The reason is the newer
    /// record's, and what is enforced is the older one.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub carried: Vec<PolicyRefusalView>,
}

/// One `bot.did.policy` record in force.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PolicyRecordView {
    /// The record's key.
    pub key: String,
    /// What it is asked to decide.
    pub actions: Vec<String>,
    /// The `$type` of its document, which says which engine answers it.
    pub document: String,
}

/// One `bot.did.policyBinding` record in force, and whom it reaches.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PolicyBindingView {
    /// The record's key.
    pub key: String,
    /// The keys of the policies it names.
    pub policies: Vec<String>,
    /// Every account on this server it reaches, in DID order.
    pub accounts: Vec<String>,
}

/// One record a build would not honour, and why.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PolicyRefusalView {
    /// The collection the record is in.
    pub collection: String,
    /// The record's key.
    pub key: String,
    /// Why the build refused it.
    pub reason: String,
}

impl PolicyView {
    /// The view of `set`, as the gate holds it.
    #[must_use]
    pub fn of(set: &didbot_pds::EnforcedSet) -> Self {
        let refusals = |failures: &[didbot_pds::BuildFailure]| {
            failures
                .iter()
                .map(|failure| PolicyRefusalView {
                    collection: failure.collection.to_owned(),
                    key: failure.key.clone(),
                    reason: failure.reason.clone(),
                })
                .collect()
        };
        Self {
            enforced: Some(set.digest.clone()),
            policies: set
                .policies
                .iter()
                .map(|policy| PolicyRecordView {
                    key: policy.key.clone(),
                    actions: policy.actions.clone(),
                    document: policy.document.clone(),
                })
                .collect(),
            bindings: set
                .bindings
                .iter()
                .map(|binding| PolicyBindingView {
                    key: binding.key.clone(),
                    policies: binding.policies.clone(),
                    accounts: binding.accounts.clone(),
                })
                .collect(),
            refused: refusals(&set.refused),
            carried: refusals(&set.carried),
        }
    }
}

/// How many blobs, and what they occupy.
///
/// Every member of [`BlobsView`] is one of these, so that a reader taking a
/// figure out of this response gets the same two words wherever it took it
/// from.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct TallyView {
    /// How many blobs are in this state.
    pub count: u64,
    /// What they occupy, in bytes.
    pub bytes: u64,
}

impl From<didbot_pds::BlobTally> for TallyView {
    fn from(tally: didbot_pds::BlobTally) -> Self {
        Self {
            count: tally.count,
            bytes: tally.bytes,
        }
    }
}

/// The `blobs` member of [`StatsResponse`]: this deployment's blobs, by the
/// state each one is in.
///
/// Aggregates over every repository and nothing narrower. `bot.did.stats` is
/// open by default — `auth::Disclosure` — so a figure that said which
/// account held what would publish one account's content to anyone who
/// asked; a total cannot. The names of the blobs an incomplete restore lost
/// are in the startup log, where the operator is, and `didbot_pds::Reconciled`
/// keeps a sample of them for that line.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct BlobsView {
    /// Every blob the log names, whatever state it is in.
    ///
    /// `held.count` and `held.bytes` are this deployment's blob inventory
    /// and its blob footprint. The three states below partition this one and
    /// sum back to it.
    pub held: TallyView,
    /// Blobs at least one live record points at.
    pub referenced: TallyView,
    /// Blobs no live record points at, still inside the collection grace
    /// window.
    ///
    /// The ordinary state of every upload between `uploadBlob` and the
    /// `createRecord` that names it, so a nonzero reading is a working
    /// server rather than a problem.
    pub unreferenced: TallyView,
    /// Blobs no live record points at whose grace window has run out: what
    /// the next collection pass will take, and the quota it will give back.
    ///
    /// A figure that climbs and does not fall is the one an operator acts
    /// on — it says collection is not getting through.
    pub collectable: TallyView,
    /// Blobs the log named whose bytes the disk did not have when this
    /// server last started.
    ///
    /// Named for when it was read, because that is the only way to read it:
    /// it is what the startup reconcile counted, held for the life of the
    /// process. Nonzero means this deployment came back from an incomplete
    /// copy and will answer `404` for that many blobs until they are put
    /// back, and `bytes` is how much a restore would have to bring. Zero
    /// means the disk agreed with the log *at that start*, not that it
    /// agrees now: nothing recounts while the server runs, and a restart is
    /// what takes the reading again.
    ///
    /// These blobs are in `held` as well. The log names them, so `listBlobs`
    /// still does.
    pub missing_at_boot: TallyView,
    /// Bytes the disk held that the log named none of, deleted during that
    /// same startup.
    ///
    /// An upload interrupted before it was named, a blob whose bytes landed
    /// and whose log entry did not, or an account directory the log no
    /// longer mentions. Nonzero after a restore says the copy carried blob
    /// bytes the log could not account for. Nothing counted here is in
    /// `held`.
    pub discarded_at_boot: TallyView,
}

impl StatsResponse {
    /// Renders a registry snapshot for the wire.
    pub fn from_stats(stats: &RegistryStats) -> Self {
        Self {
            accounts: stats.accounts,
            records: stats.records.records,
            bytes: stats.records.bytes,
            collections: stats.records.collections.clone(),
            blobs: BlobsView {
                held: stats.blobs.held.into(),
                referenced: stats.blobs.referenced.into(),
                unreferenced: stats.blobs.unreferenced.into(),
                collectable: stats.blobs.collectable.into(),
                missing_at_boot: stats.blobs.missing_at_boot.into(),
                discarded_at_boot: stats.blobs.discarded_at_boot.into(),
            },
            live_children: stats.live_children.clone(),
            policy: PolicyView {
                enforced: stats.policy_revision.clone(),
                ..PolicyView::default()
            },
            tree: stats.tree.into(),
        }
    }

    /// Replaces [`StatsResponse::policy`] with the whole set `enforced`
    /// describes, rather than its digest alone.
    ///
    /// Separate from [`Self::from_stats`] because the digest comes off a
    /// counted snapshot and the records come off the gate; a caller that
    /// has both hands in both.
    #[must_use]
    pub fn with_policy(mut self, enforced: Option<&didbot_pds::EnforcedSet>) -> Self {
        if let Some(enforced) = enforced {
            self.policy = PolicyView::of(enforced);
        }
        self
    }
}

/// Query of `com.atproto.sync.getRepo`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GetRepoQuery {
    /// The repository to export, as a DID.
    pub did: String,
    /// The revision the caller last synced at, if it has one.
    ///
    /// A revision this deployment can place turns the answer into the blocks
    /// created after it; one it cannot is answered in full. See the route.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub since: Option<String>,
}

/// Query of `com.atproto.sync.getRecord`.
///
/// Named for its namespace: `com.atproto.repo.getRecord` has a query of its
/// own with the same shape and a different meaning — that one answers with the
/// record, this one with the proof that it is in the tree.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SyncGetRecordQuery {
    /// The repository to read, as a DID.
    pub did: String,
    /// The collection NSID.
    pub collection: String,
    /// The record key.
    pub rkey: String,
}

/// Query of `com.atproto.sync.listRepos`.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct ListReposQuery {
    /// How many repositories to return.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub limit: Option<usize>,
    /// The DID the previous page ended at.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cursor: Option<String>,
}

/// The default page size `com.atproto.sync.listRepos` declares.
pub const DEFAULT_REPO_LIMIT: usize = 500;

/// The largest page `com.atproto.sync.listRepos` declares.
pub const MAX_REPO_LIMIT: usize = 1000;

impl ListReposQuery {
    /// The page size to apply, defaulted and capped.
    ///
    /// A limit above the ceiling is capped rather than refused, which is the
    /// position the query service takes and holds for the same reason:
    /// a client asking for ten thousand wants as many as it can have, and an
    /// error teaches it to ask for exactly the ceiling instead.
    pub fn effective_limit(&self) -> usize {
        self.limit.unwrap_or(DEFAULT_REPO_LIMIT).min(MAX_REPO_LIMIT)
    }
}

/// Query of `com.atproto.sync.getBlob`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GetBlobQuery {
    /// The account holding the blob, as a DID.
    pub did: String,
    /// The blob's content identifier.
    pub cid: String,
}

/// Query of `com.atproto.sync.listBlobs`.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct ListBlobsQuery {
    /// The repository to list, as a DID.
    pub did: String,
    /// The revision to list from. Refused by name; see the handler.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub since: Option<String>,
    /// How many CIDs to return.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub limit: Option<usize>,
    /// The CID the previous page ended at.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cursor: Option<String>,
}

impl ListBlobsQuery {
    /// The page size to apply, defaulted and capped.
    ///
    /// Capped rather than refused, for the reason
    /// [`ListReposQuery::effective_limit`] gives.
    pub fn effective_limit(&self) -> usize {
        self.limit
            .unwrap_or(didbot_pds::blobs::DEFAULT_LIST_LIMIT)
            .min(didbot_pds::blobs::MAX_LIST_LIMIT)
    }
}

/// Every value given for `key` in a raw query string, in the order they appear.
///
/// `com.atproto.sync.getBlocks` takes an array parameter, and an array in an
/// XRPC query is a repeated key — `?cids=a&cids=b`. `serde_urlencoded`, which
/// is what `axum::extract::Query` is built on, cannot deserialize a sequence
/// from one, so the raw string is read here instead of growing a dependency
/// for one parameter.
#[must_use]
pub fn repeated(query: &str, key: &str) -> Vec<String> {
    query
        .split('&')
        .filter_map(|pair| pair.split_once('='))
        .filter(|(name, _)| percent_decode(name) == key)
        .map(|(_, value)| percent_decode(value))
        .collect()
}

/// Percent-decoding, with `+` as a space, as a query string is written.
///
/// A `%` that is not followed by two hex digits is left alone rather than
/// refused: this decodes a parameter that is about to be looked up as a CID
/// and fail on its own if it is nonsense, and there is nothing a decoding
/// error could say that the lookup will not say better.
///
/// The escape is read as two *bytes* and never as a `&str` slice. A query
/// string is only guaranteed to be UTF-8, not ASCII — `http`'s URI parser
/// admits any byte above `0x7F` as long as the path and query decode as
/// UTF-8 — so a `%` followed by one ASCII byte and then a multi-byte
/// character puts the end of a `[index + 1..index + 3]` slice inside that
/// character, and slicing a `str` there panics. Nothing authenticates
/// `com.atproto.sync.getBlocks`, which is what reads its parameters out of
/// the raw query, so that panic was reachable by anyone who could reach the
/// port.
fn percent_decode(value: &str) -> String {
    /// One hexadecimal digit, as a nibble.
    fn nibble(byte: u8) -> Option<u8> {
        match byte {
            b'0'..=b'9' => Some(byte - b'0'),
            b'a'..=b'f' => Some(byte - b'a' + 10),
            b'A'..=b'F' => Some(byte - b'A' + 10),
            _ => None,
        }
    }

    let bytes = value.as_bytes();
    let mut out = Vec::with_capacity(bytes.len());
    let mut index = 0;
    while index < bytes.len() {
        match bytes[index] {
            b'+' => {
                out.push(b' ');
                index += 1;
            }
            b'%' if index + 2 < bytes.len() => {
                match (nibble(bytes[index + 1]), nibble(bytes[index + 2])) {
                    (Some(high), Some(low)) => {
                        out.push((high << 4) | low);
                        index += 3;
                    }
                    _ => {
                        out.push(b'%');
                        index += 1;
                    }
                }
            }
            byte => {
                out.push(byte);
                index += 1;
            }
        }
    }
    String::from_utf8_lossy(&out).into_owned()
}

#[cfg(test)]
mod tests {
    use super::*;

    /// An array parameter is a repeated key, and the order it was sent in is
    /// the order it is read in — a caller asking for three blocks gets them
    /// back keyed by CID, but the request itself is a list.
    #[test]
    fn a_repeated_parameter_reads_as_a_list() {
        assert_eq!(
            repeated("did=did:web:a&cids=one&cids=two", "cids"),
            vec!["one".to_owned(), "two".to_owned()]
        );
        assert_eq!(repeated("did=did:web:a", "cids"), Vec::<String>::new());
    }

    /// A DID with a port in it arrives percent-encoded, which is the case
    /// this whole helper exists for: every account in a development zone has
    /// one.
    #[test]
    fn a_percent_encoded_value_comes_back_whole() {
        assert_eq!(
            repeated("did=did%3Aweb%3Aa.agents.localhost%253A3000", "did"),
            vec!["did:web:a.agents.localhost%3A3000".to_owned()]
        );
    }

    /// A `%` escape whose second digit is the first byte of a multi-byte
    /// character. The two bytes after the `%` are read as bytes, so the
    /// character is left alone rather than sliced through the middle; reading
    /// them as a `&str` slice panics instead, which is what this asserts is
    /// gone. `com.atproto.sync.getBlocks` reads its parameters through here
    /// with no credential in front of it.
    #[test]
    fn a_percent_escape_running_into_a_multi_byte_character_does_not_panic() {
        assert_eq!(
            repeated("cids=%a\u{e9}", "cids"),
            vec!["%a\u{e9}".to_owned()]
        );
        // The same shape in the key rather than the value, and in the one
        // parameter `getBlocks` reads before it reads `cids` at all.
        assert_eq!(repeated("%a\u{e9}=1&did=x", "did"), vec!["x".to_owned()]);
    }

    /// An escape at the very end of a value still decodes: the bound that
    /// keeps the two digits in range must not be one short.
    #[test]
    fn a_trailing_escape_is_still_decoded() {
        assert_eq!(repeated("cids=a%41", "cids"), vec!["aA".to_owned()]);
        assert_eq!(repeated("cids=%4", "cids"), vec!["%4".to_owned()]);
    }

    #[test]
    fn a_page_size_is_defaulted_and_capped() {
        assert_eq!(
            ListReposQuery::default().effective_limit(),
            DEFAULT_REPO_LIMIT
        );
        assert_eq!(
            ListReposQuery {
                limit: Some(99_999),
                cursor: None
            }
            .effective_limit(),
            MAX_REPO_LIMIT
        );
    }
}