Struct FlowFabricAdminClient 

pub struct FlowFabricAdminClient { /* private fields */ }

Client for the ff-server admin REST surface.

Construct via FlowFabricAdminClient::new (no auth) or FlowFabricAdminClient::with_token (Bearer auth). Both return a ready-to-use client backed by a single pooled reqwest::Client — reuse the instance across calls instead of building one per request.

Implementations

impl FlowFabricAdminClient

pub fn new(base_url: impl Into<String>) -> Result<Self, SdkError>

Build a client without auth. Suitable for a dev ff-server whose api_token is unconfigured. Production deployments should use with_token.

pub fn with_token( base_url: impl Into<String>, token: impl AsRef<str>, ) -> Result<Self, SdkError>

Build a client that sends Authorization: Bearer <token> on every request. The token is passed by value so the caller retains ownership policy (e.g. zeroize on drop at the caller side); the SDK only reads it.

Empty-token guard

An empty or all-whitespace token returns SdkError::Config instead of silently constructing Authorization: Bearer (which the server rejects with 401, leaving the operator chasing a “why is auth broken” ghost). Common source: FF_ADMIN_TOKEN="" in a shell where the var was meant to be set; the unset-expansion is the empty string. Prefer an obvious error at construction over a silent 401 at first request.

If the caller genuinely wants an unauthenticated client (dev ff-server without api_token configured), use FlowFabricAdminClient::new instead.

pub async fn claim_for_worker( &self, req: ClaimForWorkerRequest, ) -> Result<Option<ClaimForWorkerResponse>, SdkError>

POST /v1/workers/{worker_id}/claim — scheduler-routed claim.

Batch C item 2 PR-B. Swaps the SDK’s direct-Valkey claim for a server-side one: the request carries lane + identity + capabilities + grant TTL; the server runs budget, quota, and capability admission via ff_scheduler::Scheduler::claim_for_worker and returns a ClaimGrant on success.

Returns Ok(None) when the server responds 204 No Content (no eligible execution on the lane). Callers that want to keep polling should back off per their claim cadence.

pub async fn rotate_waitpoint_secret( &self, req: RotateWaitpointSecretRequest, ) -> Result<RotateWaitpointSecretResponse, SdkError>

Rotate the waitpoint HMAC secret on the server.

Promotes the currently-installed kid to previous_kid (accepted for the server’s configured FF_WAITPOINT_HMAC_GRACE_MS window) and installs new_secret_hex under new_kid as the new current. Fans out across every execution partition. Idempotent: re-running with the same (new_kid, new_secret_hex) converges.

The server returns 200 if at least one partition rotated OR at least one partition was already rotating under a concurrent request. See RotateWaitpointSecretResponse fields for the breakdown.

Errors

• SdkError::AdminApi — non-2xx response (400 invalid input, 401 missing/bad bearer, 429 concurrent rotate, 500 all partitions failed, 504 server-side timeout).
• SdkError::Http — transport error (connect, body decode, client-side timeout).

Retry semantics

Rotation is idempotent on the same (new_kid, new_secret_hex) so retries are SAFE even on 504s or partial failures.

pub async fn issue_reclaim_grant( &self, execution_id: &str, req: IssueReclaimGrantRequest, ) -> Result<IssueReclaimGrantResponse, SdkError>

Request a lease-reclaim grant for an execution in lease_expired_reclaimable or lease_revoked state (RFC-024 §3.5).

Routes POST /v1/executions/{execution_id}/reclaim. The ff-server handler dispatches through the EngineBackend trait to whichever backend the server was started with (Valkey / Postgres / SQLite).

worker_capabilities (RFC-024 §3.2 B-2)

The request body carries worker_capabilities. Consumers typically source these from their registered worker’s configured WorkerConfig::capabilities. Admission compares worker_capabilities against the execution’s required_capabilities (persisted on exec_core at create_execution time from ExecutionPolicy.routing_requirements.required_capabilities); any required capability missing from the worker set surfaces as IssueReclaimGrantResponse::NotReclaimable { detail: "capability_mismatch: <missing csv>" } (Lua ff_issue_reclaim_grant, crates/ff-script/src/flowfabric.lua §3969-3982; sqlite/PG backends mirror the check). The SDK does not re-read worker state automatically — admin clients are not bound to a worker — so the consumer threads the capabilities through at call-time.

capability_hash is NOT consulted for admission; it is stored verbatim on the grant hash for audit / downstream observability only.

Consumer flow (RFC-024 §4.4)

1. Consumer’s POST /v1/runs/:id/complete returns lease_expired.
2. Consumer calls this method; handles IssueReclaimGrantResponse::Granted → builds a ff_core::contracts::ReclaimGrant via IssueReclaimGrantResponse::into_grant.
3. Consumer passes the grant to crate::FlowFabricWorker::claim_from_reclaim_grant along with a fresh ff_core::contracts::ReclaimExecutionArgs; the new attempt is minted with HandleKind::Reclaimed.
4. Consumer drives terminal writes on the fresh lease.

Errors

• SdkError::AdminApi — non-2xx response. 404 when the execution does not exist; 400 on malformed execution_id or body.
• SdkError::Http — transport error (connect, body decode, client-side timeout).

Retry semantics

Idempotent on the Lua side: repeated calls against an execution already re-leased (a concurrent reclaim beat this one) surface as NotReclaimable. Safe to retry on transport faults.

Trait Implementations

impl Clone for FlowFabricAdminClient

fn clone(&self) -> FlowFabricAdminClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FlowFabricAdminClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.