Skip to main content

AdminRpcServer

decdn_common::admin

Trait AdminRpcServer 

Source 
pub trait AdminRpcServer:
    Sized
    + Send
    + Sync
    + 'static {
    // Required methods
    fn health<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = RpcResult<HealthResponse>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn evict<'life0, 'async_trait>(
        &'life0 self,
        req: EvictRequest,
    ) -> Pin<Box<dyn Future<Output = RpcResult<EvictResponse>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn reload<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = RpcResult<ReloadResponse>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn drain<'life0, 'async_trait>(
        &'life0 self,
        req: DrainRequest,
    ) -> Pin<Box<dyn Future<Output = RpcResult<DrainResponse>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn status<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = RpcResult<StatusResponse>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn lanes<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = RpcResult<LanesResponse>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn slashes<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = RpcResult<SlashesResponse>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn pools<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = RpcResult<BuyerPoolsResponse>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;

    // Provided method
    fn into_rpc(self) -> RpcModule<Self> { ... }
}
Expand description

Server trait implementation for the AdminRpc RPC API.

Required Methods§

Source

fn health<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = RpcResult<HealthResponse>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Return this node’s identity and process uptime.

Source

fn evict<'life0, 'async_trait>( &'life0 self, req: EvictRequest, ) -> Pin<Box<dyn Future<Output = RpcResult<EvictResponse>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Evict a single blob from the local cache (issue #279). The eviction is logical: the iroh-blobs store still holds the bytes (Blobs::delete is pub(crate) in iroh-blobs and reserved for the GC task) until the next periodic GC sweep reclaims them (#518). The takedown itself is persisted to <cache_dir>/evicted.log so it survives a restart even when the next sweep hasn’t run yet.

When req.dry_run is true (issue #379) the cache state is not mutated: the response carries the pre-evict snapshot (size, last-access elapsed time, pin status, already-evicted flag) so operators running DMCA takedowns can confirm what the real evict will touch before committing. The same response shape is used for the real-evict path with the snapshot reflecting the pre-mutation state.

Source

fn reload<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = RpcResult<ReloadResponse>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Re-read the config file the node was started with and apply the reloadable subset (issue #373) — the same path SIGHUP triggers, exposed over the loopback admin surface for operators who want scripted control without kill -HUP. Both paths share the same RuntimeReloadState::reload, whose internal mutexes serialise concurrent reloads, so a SIGHUP racing this RPC waits behind it rather than corrupting state. Returns:

  • CONFIG_PATH_UNSET_CODE when the node was started without a config path (CLI-only flag invocation has nothing to re-read).
  • RELOAD_ERROR_CODE when the reload itself fails — previous values are retained, matching the SIGHUP behaviour.
  • On success: ReloadResponse carrying the post-reload log_level.
Source

fn drain<'life0, 'async_trait>( &'life0 self, req: DrainRequest, ) -> Pin<Box<dyn Future<Output = RpcResult<DrainResponse>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Trigger graceful shutdown via the same path SIGTERM exercises (issue #244, appendix-local-admin-http.md). Stops the iroh router’s accept loop and awaits in-flight ProtocolHandler::shutdown calls; the subsequent task drain is bounded by the runtime’s 15s SHUTDOWN_DEADLINE (the router-shutdown step itself is unbounded — a stuck handler hangs the runtime, only the post-router task join is timeout-gated).

Fire-and-forget by default: the response returns as soon as the trigger lands, not when shutdown completes. Equivalent to kill -TERM <pid> for operators who’d rather not stat the PID.

The DrainRequest parameter is required. wait_admin: false gets the SIGTERM-equivalent shutdown order. wait_admin: true (issue #604) asks the runtime to keep the admin server alive through router.shutdown so a polling client can observe admin_v1_health.in_flight_streams reach 0.

Source

fn status<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = RpcResult<StatusResponse>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Return a snapshot of this node’s DHT participation health (issue #741): routing-table bucket fill rates, the network-wide last bucket-refresh timestamp, active-staker count, provider-record store utilization, and republish-scheduler depth. Intended for decdn node status, giving operators a single human-readable (or --json) view to diagnose cold-start or routing-table degradation without scraping Prometheus. Returns DHT_UNAVAILABLE_CODE when the DHT subsystem is not wired on this node.

Source

fn lanes<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = RpcResult<LanesResponse>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Return a live snapshot of every lane this node provides against a PaymentPool (issue #749): per lane the outstanding accrued claim, time since the last voucher (in-memory, None after a restart until the next voucher), and whether the accrued claim has reached the redemption threshold. Backs decdn node lanes, giving operators a single view to spot lanes approaching settlement, stale lanes, or unusually high outstanding balances before they become a liquidity risk — without scraping metrics or logs. Returns POOL_STORE_ERROR_CODE if the pool state store cannot be read.

Source

fn slashes<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = RpcResult<SlashesResponse>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Return every slash the node’s watcher has detected against its own operator (#1032, G-NODE-05): per slash the slashId, offense type, amount, evidence digest, block, and the 30-day appeal-window close time. Consumed directly by operators/keepers (no CLI subcommand wraps it) so they notice a slash and file decdn appeal slash in time. Returns SLASH_DETECTION_UNAVAILABLE_CODE when the slash watcher is not wired on this node.

Source

fn pools<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = RpcResult<BuyerPoolsResponse>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Return the node’s buyer-side PaymentPool state: every pool its buyer leg tracks, the deposit it believes each holds, and the per-lane spend watermark it has signed against each provider.

This is the buyer-side counterpart of Self::lanes, and the only read path to buyer.redb on a running node — redb holds a process-exclusive lock on that file for the daemon’s lifetime, so a CLI pointed at the daemon’s data dir cannot open it and would otherwise report an unrelated empty store as the node’s state.

Returns BUYER_POOL_UNAVAILABLE_CODE when no buyer leg is wired, and BUYER_POOL_STORE_ERROR_CODE when the store cannot be read.

Provided Methods§

Source

fn into_rpc(self) -> RpcModule<Self>

Collects all the methods and subscriptions defined in the trait and adds them into a single RpcModule.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§