Struct FlowFabricAdminClient 

pub struct FlowFabricAdminClient { /* private fields */ }

Client for FlowFabric admin primitives — backend-agnostic facade (v0.13 SC-10 ergonomics).

Two construction shapes:

• FlowFabricAdminClient::new / FlowFabricAdminClient::with_token — HTTP transport targeting a running ff-server.
• FlowFabricAdminClient::connect_with — embedded transport that dispatches directly through an Arc<dyn EngineBackend>. No ff-server required; works under FF_DEV_MODE=1 + SQLite and in any in-process deployment.

The public method surface is identical across both transports; consumers choose at construction time. Admin methods that have no backend-trait equivalent return SdkError::AdminApi with status 503 on the embedded path — today every method on this client maps cleanly, so this fallback is only reached if a future admin primitive lands HTTP-first.

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 connect_with(backend: Arc<dyn EngineBackend>) -> Self

Build a client that dispatches admin primitives directly through an Arc<dyn EngineBackend>, bypassing HTTP entirely.

When to use

• FF_DEV_MODE=1 SQLite scenarios where no ff-server is running.
• In-process / embedded deployments that hold a backend handle already (e.g. tests, examples, scheduler-hosting binaries).

Semantic parity

Each method on FlowFabricAdminClient dispatches to the equivalent EngineBackend trait method (see the RFC-024 / RFC-017 admin surfaces). Validation rules + request-body translation mirror the server-side handler in ff-server so callers get the same accept / reject behaviour across transports. Note: the exact SdkError variant differs — embedded-path validation rejects surface as SdkError::Config (no HTTP round-trip) while HTTP returns SdkError::AdminApi with status 400. Callers that need to distinguish a 4xx from a transport fault should use SdkError::is_retryable or match on Config + AdminApi together rather than relying on a single variant.

EngineError::Unavailable from the backend — emitted by backends that have not implemented a given method — is mapped to SdkError::AdminApi with status = 503 and kind = Some("unavailable") so callers see a uniform admin-error surface across transports.

Divergence from the HTTP transport

• rotate_waitpoint_secret forwards EMBEDDED_WAITPOINT_HMAC_GRACE_MS (24 h, matching ff-server’s default FF_WAITPOINT_HMAC_GRACE_MS) as the per-partition grace window. The HTTP transport reads the server’s env-configured value; the embedded client has no config surface so it pins the documented default.
• No single-writer admin semaphore, no audit-log emission. These are ff-server responsibilities; embedded consumers wanting them bring their own gate.

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 read_waitpoint_token( &self, execution_id: &ExecutionId, waitpoint_id: &WaitpointId, ) -> Result<Option<String>, SdkError>

Read the raw HMAC waitpoint_token for a specific (execution_id, waitpoint_id) pair.

Operator-only

The sibling list_pending_waitpoints API intentionally sanitises this field (RFC-017 Stage E4 / v0.8.0 §8) — consumers correlate via (token_kid, token_fingerprint) and normally obtain the raw token from their own worker’s SuspendOutcome at suspend time. This admin method re-exposes the token behind the server’s bearer-auth layer so operator tooling (approval CLIs, external-callback bridges) can fetch a delivery credential programmatically instead of copy-pasting from worker logs.

Deployments MUST run ff-server with api_token configured when exposing this endpoint to untrusted networks. The embedded transport has no auth boundary — access is gated by whoever holds the Arc<dyn EngineBackend>.

Returns

• Ok(Some(token)) — HMAC token string suitable for DeliverSignalArgs::waitpoint_token / /signal request body.
• Ok(None) — waitpoint is unknown, consumed, expired, or the stored token column is empty.
• Err(SdkError::AdminApi { status: 503, kind: Some("unavailable") }) — the backend (e.g. an out-of-tree implementation) has not overridden EngineBackend::read_waitpoint_token.

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.