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] macro consumes the source AdminRpc trait and emits AdminRpcClient in its place, plus AdminRpcServer under the admin-server feature, which only the daemon enables: the client SDK and the CLI link no JSON-RPC server. 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.

Functions

parse_hash_arg

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