Crate ff_sdk 

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

use ff_sdk::{FlowFabricWorker, WorkerConfig};
use std::time::Duration;

#[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?;

    loop {
        match worker.claim_next().await? {
            Some(task) => {
                println!("claimed: {}", task.execution_id());
                // Process task...
                task.complete(Some(b"done".to_vec())).await?;
            }
            None => {
                tokio::time::sleep(Duration::from_secs(1)).await;
            }
        }
    }
}

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.

Re-exports

pub use admin::FlowFabricAdminClient;

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::FailOutcome;

pub use task::ResumeSignal;

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

task

worker

Structs

StreamFrames

Result of read_stream / tail_stream — frames plus the terminal signal so polling consumers can exit cleanly.

Enums

SdkError

SDK error type.

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.