Crate ff_sdk

Expand description

FlowFabric Worker SDK — public API for worker authors.

This crate depends on ff-script for the Lua-function types, Lua error kinds (ScriptError), and retry helpers (is_retryable_kind, kind_to_stable_str). Consumers using ff-sdk do not need to import ff-script directly for normal worker operations, but can if they need the ScriptError or retry types.

§Quick start

The production claim path is FlowFabricWorker::claim_from_grant: obtain a ClaimGrant from ff_scheduler::Scheduler::claim_for_worker (the scheduler enforces budget, quota, and capability checks), then hand it to the SDK. claim_next is gated behind the default-off direct-valkey-claim feature and bypasses admission control — fine for benchmarks, not production.

use ff_sdk::{FlowFabricWorker, WorkerConfig};
use ff_core::backend::BackendConfig;
use ff_core::types::{LaneId, Namespace, WorkerId, WorkerInstanceId};

#[tokio::main]
async fn main() -> Result<(), ff_sdk::SdkError> {
    let config = WorkerConfig {
        backend: BackendConfig::valkey("localhost", 6379),
        worker_id: WorkerId::new("my-worker"),
        worker_instance_id: WorkerInstanceId::new("my-worker-instance-1"),
        namespace: Namespace::new("default"),
        lanes: vec![LaneId::new("main")],
        capabilities: Vec::new(),
        lease_ttl_ms: 30_000,
        claim_poll_interval_ms: 1_000,
        max_concurrent_tasks: 1,
    };

    let worker = FlowFabricWorker::connect(config).await?;
    let lane = LaneId::new("main");

    // In a real deployment `grant` is obtained from the
    // scheduler's `claim_for_worker` RPC/helper; it carries the
    // execution id, capability match, and admission result.
    let task = worker.claim_from_grant(lane, grant).await?;
    println!("claimed: {}", task.execution_id());
    // Process task...
    task.complete(Some(b"done".to_vec())).await?;
    Ok(())
}

§Migration: `direct-valkey-claim` → scheduler-issued grants

The direct-valkey-claim cargo feature — which gates [FlowFabricWorker::claim_next] — is deprecated in favour of the pair of scheduler-issued grant entry points:

FlowFabricWorker::claim_from_grant — fresh claims. Use ff_scheduler::Scheduler::claim_for_worker to obtain the ClaimGrant, then hand it to the SDK.
FlowFabricWorker::claim_from_reclaim_grant — resumed claims for an attempt_interrupted execution. Wraps a ReclaimGrant.

claim_next bypasses budget and quota admission control; the grant-based path does not. See each method’s rustdoc for the exact migration recipe.

ClaimGrant / ReclaimGrant (and the ClaimPolicy / ReclaimToken wire types on the scheduler-owner side) are re-exported from ff-sdk (#283) so consumers do not need a direct ff-scheduler dep just to type these signatures.

Re-exports§

pub use admin::rotate_waitpoint_hmac_secret_all_partitions;
pub use admin::FlowFabricAdminClient;
pub use admin::PartitionRotationOutcome;
pub use admin::RotateWaitpointSecretRequest;
pub use admin::RotateWaitpointSecretResponse;
pub use config::WorkerConfig;
pub use task::read_stream;
pub use task::tail_stream;
pub use task::tail_stream_with_visibility;
pub use task::ClaimedTask;
pub use task::Signal;
pub use task::SignalOutcome;
pub use task::SuspendedHandle;
pub use task::TrySuspendOutcome;
pub use task::MAX_TAIL_BLOCK_MS;
pub use worker::FlowFabricWorker;

Modules§

admin: Admin REST client for operator-facing endpoints on ff-server.
config
engine_error: Compatibility shim preserving the ff_sdk::engine_error surface.
snapshot: Typed read-models that decouple consumers from FF’s storage engine.
task
worker

Structs§

AppendFrameOutcome: Outcome of append_frame().
ClaimGrant: A claim grant issued by the scheduler for a specific execution.
ClaimPolicy: Policy hints for claim. Carries the worker identity the backend needs to invoke ff_claim_execution (v0.7 Wave 2) plus the blocking-wait bound.
IdempotencyKey: Partition-scoped idempotency key for retry-safe EngineBackend::suspend.
ReclaimGrant: A reclaim grant issued for a resumed (attempt_interrupted) execution.
ReclaimToken: Opaque cookie returned by the reclaim scanner; consumed by claim_from_reclaim to mint a resumed Handle.
ResumePolicy: Resume-side policy carried alongside ResumeCondition.
ResumeSignal: Signal that satisfied a waitpoint matcher and is therefore part of the reason an execution resumed. Returned by observe_signals (RFC-012 §3.1.2) and by ClaimedTask::resume_signals in ff-sdk.
StreamFrames: Result of read_stream / tail_stream — frames plus the terminal signal so polling consumers can exit cleanly.
SummaryDocument: Materialised rolling summary document returned by a summary-read call (RFC-015 §6.3).
SuspendArgs: Trait-surface input to [EngineBackend::suspend] (RFC-013 §2.2 + RFC-014 Pattern 3 widening).
SuspendOutcomeDetails: Shared “what happened on the waitpoint” payload carried in both SuspendOutcome variants.

Enums§

BackendError: Backend-agnostic transport error carried across public ff-sdk / ff-server error surfaces (#88).
BackendErrorKind: Classified backend transport errors, kept backend-agnostic on purpose (#88). Each variant maps a family of native backend error kinds into a stable, consumer-matchable shape.
BugKind: FF-internal invariant-violation sub-kinds. Should not be reachable in a correctly-behaving deployment.
CompositeBody: RFC-013 reserves this enum slot; RFC-014 populates it with the concrete composition vocabulary (AllOf + Count). The enum is #[non_exhaustive] so RFC-016 or later RFCs may add variants (AnyOf has been explicitly rejected per RFC-014 §2.3 in favour of Count { n: 1, .. }; the guard exists for orthogonal future work).
ConflictKind: Permanent conflict sub-kinds. Caller must reconcile rather than retry.
ContentionKind: Contention sub-kinds (retryable per RFC-010 §10.7). Caller should re-dispatch or re-read and retry.
CountKind: How Count nodes distinguish satisfiers. RFC-014 §2.1 + §3.2.
EngineError: Typed engine-error surface. See module docs.
FailOutcome: Outcome of a fail() call.
PatchKind: Patch format used by StreamMode::DurableSummary to apply each frame’s payload against the server-side rolling summary document.
ResumeCondition: Declarative resume condition for SuspendArgs::resume_condition.
ResumeTarget: Where a satisfied suspension routes back to.
SdkError: SDK error type.
SignalMatcher: v1 signal-match predicate inside ResumeCondition::Single.
StateKind: Legal-but-surprising state sub-kinds. Per-variant semantics vary (some are benign no-ops, some are terminal). Consult the RFC-010 §10.7 classification table.
StreamCursor: Opaque cursor for read_stream / tail_stream — re-export of ff_core::contracts::StreamCursor. Wire tokens: "start", "end", "<ms>", "<ms>-<seq>". Bare - / + are rejected — use StreamCursor::Start / StreamCursor::End instead. Opaque cursor for attempt-stream reads/tails.
StreamMode: Per-call durability mode for [EngineBackend::append_frame].
SuspendOutcome: Trait-surface output from [EngineBackend::suspend] (RFC-013 §2.3).
SuspensionReasonCode: Reason category for a suspension (RFC-004 §Suspension Reason Categories).
SuspensionRequester: Who requested the suspension.
TailVisibility: Tail-stream visibility filter (RFC-015 §6).
TimeoutBehavior: Timeout behavior at the suspension deadline (RFC-004 §Timeout Behavior).
ValidationKind: Validation sub-kinds. 1:1 with the Lua validation codes.
WaitpointBinding: How the waitpoint resource backing a SuspendArgs is obtained.

Constants§

STREAM_READ_HARD_CAP: Maximum frames per read/tail call. Mirrors ff_core::contracts::STREAM_READ_HARD_CAP — re-exported here so SDK callers don’t need to import ff-core just to read the bound. Hard cap on the number of frames returned by a single read/tail call.
SUMMARY_NULL_SENTINEL: Byte-exact null-sentinel used by StreamMode::DurableSummary + PatchKind::JsonMergePatch to set a field to JSON null (RFC-015 §3.2).

Crate ff_sdk

Crate ff_sdk Copy item path

§Quick start

§Migration: direct-valkey-claim → scheduler-issued grants

Re-exports§

Modules§

Structs§

Enums§

Constants§

Crate ff_sdk

§Migration: `direct-valkey-claim` → scheduler-issued grants