Module admin 

Wire types for the loopback admin JSON-RPC surface (appendix-local-admin-http.md).

Shared between the daemon (which implements AdminRpcServer over a local cache + peer table) and the user CLI (which speaks AdminRpcClient from decdn node …). jsonrpsee’s #[rpc(server, client)] macro consumes the source AdminRpc trait and emits separate AdminRpcServer / AdminRpcClient traits in its place; the original AdminRpc name is not a linkable rustdoc item, hence the bare backticks.

DTO fields are deliberately wire-only: no engine handles, no peer-table types, no daemon runtime types. They use simple owned values (String, u64, primitive arrays). Pulling decdn-common into the CLI does not pull the daemon runtime.

The helper parse_hash_arg returns Hash from the decdn-config-types leaf crate (the same leaf the typed config fields DecompressMode, RetryPolicy, OriginUrl, PinnedHashes come from). That keeps decdn-cache/iroh-blobs out of the publisher CLI’s dependency tree (#578); the daemon’s evict handler converts the leaf hash to the blob-store hash at its boundary via decdn_cache::to_store_hash. The parser is used only by that handler today.

Structs

BucketStat

Per-bucket fill stat for admin_v1_status (issue #741). One entry per non-empty Kademlia k-bucket — empty buckets (the vast majority of the 256-bucket keyspace on a small network) are omitted so the snapshot stays compact. The bucket capacity is the same Kademlia K for every bucket and so lives once on RoutingHealth::bucket_capacity rather than being repeated here.

BuyerLaneSnapshot

One lane the node pays on, as the buyer’s own store records it (admin_v1_pools). The buyer-side mirror of LaneSnapshot: where that reports what a lane has accrued against this node, this reports what this node has already promised to pay a provider.

BuyerPoolSnapshot

One PaymentPool deposit the node’s buyer leg tracks (admin_v1_pools).

BuyerPoolsResponse

Snapshot of the node’s buyer-side PaymentPool state (admin_v1_pools).

DrainRequest

Request body for admin_v1_drain (issue #244). Required, as is its one field: a caller states which shutdown ordering it wants.

DrainResponse

Response body for admin_v1_drain (issue #244). initiated: true reports that the trigger fired; wait_admin_honored reports whether the server actually plans to keep admin alive through router.shutdown (issue #604). The trigger is first-writer-wins, so a wait_admin: true request that loses the race to an earlier drain without it gets false here. The decdn node drain --wait client then refuses to enter the polling loop instead of treating the imminent ECONNREFUSED as drain completion. A true ack covers admin-RPC races only: a SIGINT/SIGTERM that wins the runtime’s shutdown select still closes admin early.

EvictPreview

Pre-evict snapshot returned inside EvictResponse::preview. Mirrors the cache engine’s EvictionPreview minus the engine-internal served field (folded into EvictResponse::was_present).

EvictRequest

Request body for admin_v1_evict (issue #279).

EvictResponse

Response body for admin_v1_evict.

HealthResponse

Response body for admin_v1_health. Shared between the server (serializes) and decdn node health (deserializes via the generated client). Intentionally minimal: this method exists so an operator script can answer “is this admin port the node I think it is, and has it been up since I started watching?” with one RPC call.

LaneSnapshot

JSON view of one lane this node provides against a PaymentPool, emitted by admin_v1_lanes (issue #749). A lane is keyed by (pool_id, signer, provider) — decdn_incentive::LaneKey. Defined separately from decdn-incentive’s internal LaneState so the replay-critical last_* accessors, the U256 money types, and any future internal fields can’t leak into the wire format: every field here is a plain owned wire value. Shared between the server (serializes) and decdn node lanes (deserializes via the generated client).

LanesResponse

Response body for admin_v1_lanes (issue #749). Shared between the server (serializes), decdn node lanes (deserializes via the generated client), and the integration tests.

RecordStoreHealth

DHT provider-record store utilization for admin_v1_status (issue #741).

ReloadResponse

Response body for admin_v1_reload (issue #373). Reports the post-reload values the SIGHUP arm logs to stdout, so operators using the RPC path get the same after-state confirmation without scraping tracing output. Only the reloadable fields appear here: changes to non-reloadable sections are logged by the reload path itself (one info! per changed-but-ignored field) and aren’t echoed in the RPC response.

RepublishHealth

Republish-scheduler health for admin_v1_status (issue #741).

RoutingHealth

Routing-table health section of admin_v1_status (issue #741).

SlashRecordDto

One slash detected against this node’s operator (SlashJudge.Slashed, #1032, G-NODE-05). Surfaced so an operator (or a keeper script) can notice a slash and file decdn appeal slash within the 30-day window without watching the chain directly.

SlashesResponse

Snapshot of every slash the watcher has detected against this node’s operator (#1032). Empty list when none — a clean operator.

StatusResponse

Response body for admin_v1_status (issue #741): a single-shot snapshot of this node’s DHT participation health, so an operator can diagnose cold-start / routing-table degradation without scraping Prometheus or reading logs.

Enums

BindingStatus

Whether the node’s local iroh key is the one bound to its operator address on-chain (#1034).

Constants

BUYER_POOL_STORE_ERROR_CODE

JSON-RPC error code: admin_v1_pools could not read the buyer pool store. Distinct from POOL_STORE_ERROR_CODE, which covers the seller-side lane store: the two are different files, and a fault in one says nothing about the other.

BUYER_POOL_UNAVAILABLE_CODE

JSON-RPC error code: admin_v1_pools was called on an admin surface with no buyer pool store attached, so it can say nothing about what this node tracks.

CACHE_ERROR_CODE

JSON-RPC error code: the cache layer reported an error during evict (e.g. the underlying iroh-blobs store I/O failed when persisting the evicted-hash log).

CONFIG_PATH_UNSET_CODE

JSON-RPC error code: the node was started without a config file path, so admin_v1_reload has nothing to re-read. Distinct from RELOAD_ERROR_CODE so an operator script can tell “this node can’t reload, ever, until it’s restarted with --config <path>” from “this node tried and failed”.

DHT_POISONED_CODE

JSON-RPC error code: admin_v1_status found a DHT subsystem mutex (routing table or record store) poisoned — i.e. a thread panicked while holding it, so the DHT’s in-memory state may be inconsistent. This is a severe in-process fault, kept distinct from the benign DHT_UNAVAILABLE_CODE (“no DHT wired”) so an operator script can tell “this node never had a DHT” from “this node’s DHT just broke”. The server also logs the poisoning at error level.

DHT_UNAVAILABLE_CODE

JSON-RPC error code: admin_v1_status was called on a node whose DHT subsystem is not wired (e.g. a future CLI-only or test invocation that brings up the admin surface without the DHT handler). A benign, expected configuration state — distinct from a generic failure so an operator gets “this node has no DHT to report on” rather than a confusing transport error, and distinct from DHT_POISONED_CODE so it isn’t confused with an in-process fault.

INVALID_PARAMS_CODE

JSON-RPC error code: the request shape was wrong (bad hex, etc.). Matches the standard JSON-RPC 2.0 Invalid params code.

POOL_STORE_ERROR_CODE

JSON-RPC error code: admin_v1_lanes could not read the pool state store (issue #749) — e.g. the redb load failed or a poisoned in-memory mutex. A read-side fault distinct from the cache/DHT codes so an operator script can tell “lane snapshot is unavailable right now” from a generic transport failure. The server also logs the underlying store error.

RELOAD_ERROR_CODE

JSON-RPC error code: RuntimeReloadState::reload returned an error (file unreadable, malformed TOML, rejected resolution, mutex poison, log-level setter failed). Mirrors the SIGHUP arm’s “previous values retained” guarantee — by the time this surfaces, the running config is unchanged.

SLASH_DETECTION_UNAVAILABLE_CODE

JSON-RPC error code: admin_v1_slashes was called on a node whose slash watcher is not wired (e.g. no slash_judge_address, or a test/CLI-only invocation). Benign config state, distinct from a generic failure so an operator gets “no slash detection on this node” rather than an opaque error.

Traits

AdminRpcClient

Client implementation for the AdminRpc RPC API.

AdminRpcServer

Server trait implementation for the AdminRpc RPC API.

Functions

parse_hash_arg

Decode a 64-character hex BLAKE3 hash into a Hash.