Skip to main content

Crate ff_sdk

Crate ff_sdk 

Source
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::types::LaneId;

#[tokio::main]
async fn main() -> Result<(), ff_sdk::SdkError> {
    let config = WorkerConfig::new(
        "localhost",
        6379,
        "my-worker",
        "my-worker-instance-1",
        "default",
        "main",
    );

    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:

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

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::AppendFrameOutcome;
pub use task::ClaimedTask;
pub use task::ConditionMatcher;
pub use task::Signal;
pub use task::SignalOutcome;
pub use task::SuspendOutcome;
pub use task::TimeoutBehavior;
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§

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.

Enums§

BugKind
FF-internal invariant-violation sub-kinds. Should not be reachable in a correctly-behaving deployment.
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.
EngineError
Typed engine-error surface. See module docs.
FailOutcome
Outcome of a fail() call.
SdkError
SDK error type.
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.
ValidationKind
Validation sub-kinds. 1:1 with the Lua validation codes.

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.