Struct CommandServer 

pub struct CommandServer { /* private fields */ }

Core command server implementation.

Uses CommandRegistry as source of truth for metadata. Uses KV for operational data (params, responses, indices, leases).

Implementations

impl CommandServer

pub fn new( kv: Arc<dyn Kv>, storage: Arc<dyn Storage>, command_dispatcher: Arc<dyn CommandDispatcher>, command_registry: Arc<dyn CommandRegistry>, base_url: String, response_signing_key: Vec<u8>, ) -> Self

Create a new command server instance

pub fn with_inline_limit( kv: Arc<dyn Kv>, storage: Arc<dyn Storage>, command_dispatcher: Arc<dyn CommandDispatcher>, command_registry: Arc<dyn CommandRegistry>, base_url: String, inline_max_bytes: usize, response_signing_key: Vec<u8>, ) -> Self

Create a new command server with custom inline size limit

pub fn verify_response_token( &self, command_id: &str, token: &str, expires: i64, ) -> bool

Verify a response token for a specific command.

Performs HMAC verification first (constant-time), then checks expiration, to avoid leaking timing information about token validity windows.

pub async fn create_command( &self, request: CreateCommandRequest, ) -> Result<CreateCommandResponse>

Create a new command.

Flow:

1. Validate request
2. Registry creates command metadata (source of truth)
3. KV stores params blob
4. KV creates pending index (for Pull) or dispatch (for Push)

pub async fn upload_complete( &self, command_id: &str, upload_request: UploadCompleteRequest, ) -> Result<UploadCompleteResponse>

Mark upload as complete and dispatch command.

pub async fn get_command_status( &self, command_id: &str, ) -> Result<CommandStatusResponse>

Get command status.

Queries registry for metadata (source of truth), KV for response blob.

pub async fn submit_command_response( &self, command_id: &str, response: CommandResponse, ) -> Result<()>

Submit response from deployment.

Stores response blob in KV, updates state in registry.

pub async fn acquire_lease( &self, deployment_id: &str, lease_request: &LeaseRequest, ) -> Result<LeaseResponse>

Acquire leases for polling deployments.

Scans KV pending index, queries registry for metadata, creates leases in KV.

pub async fn release_lease( &self, command_id: &str, lease_id: &str, ) -> Result<()>

Release a lease manually.

Increments attempt count in registry, returns command to Pending state.

pub async fn get_command_deployment_id( &self, command_id: &str, ) -> Result<Option<String>>

Get the deployment_id that owns a command.

Used by the manager’s auth layer to check whether the caller has access to a specific command without fetching the full status.

pub async fn get_command_access_context( &self, command_id: &str, ) -> Result<Option<CommandAccessContext>>

Get the command’s canonical ownership fields for route authorization.

pub async fn get_lease_owner( &self, lease_id: &str, ) -> Result<Option<(String, String)>>

Resolve a lease_id to (command_id, owner_deployment_id) via the lease:{lease_id} reverse index, re-verifying against the live lease record (the reverse entry can outlive a released lease briefly, and a command can have been re-leased under a new lease_id since).

Used by the manager’s auth layer to check that the caller may act on the deployment that holds the lease.

pub async fn release_lease_by_id(&self, lease_id: &str) -> Result<()>

Release a lease by lease_id only (for the API).

pub async fn store_params( &self, command_id: &str, params: &BodySpec, ) -> Result<()>

pub async fn get_params(&self, command_id: &str) -> Result<Option<BodySpec>>

pub async fn store_response( &self, command_id: &str, response: &CommandResponse, ) -> Result<()>

pub async fn get_response( &self, command_id: &str, ) -> Result<Option<CommandResponse>>

pub async fn reap_expired_commands(&self) -> Result<u32>

Expire every overdue non-terminal command recorded in the deadline index. Intended to run periodically from the hosting process.

Deadlines are otherwise only enforced lazily (status polls and lease scans), which never reaches a command nobody polls — most notably a PendingUpload whose params upload never completed, which has no pending-index entry and would otherwise live forever.

Uses the conditional terminal transition, so racing a concurrent submit is safe: whoever wins, the record stays consistent. Returns the number of commands expired.