ff_sdk/
config.rs

1use ff_core::backend::BackendConfig;
2use ff_core::partition::PartitionConfig;
3use ff_core::types::{LaneId, Namespace, WorkerId, WorkerInstanceId};
4
5/// Configuration for a FlowFabric worker.
6///
7/// **RFC-012 Stage 1c tranche 1.** Valkey-specific connection
8/// parameters (`host`, `port`, `tls`, `cluster`) moved to the nested
9/// [`BackendConfig`] field, which also carries
10/// [`BackendTimeouts`](ff_core::backend::BackendTimeouts) and
11/// [`BackendRetry`](ff_core::backend::BackendRetry) policy. Build one
12/// with [`BackendConfig::valkey`] for the common standalone case; for
13/// TLS / cluster / tuned retry, construct the
14/// [`ValkeyConnection`](ff_core::backend::ValkeyConnection) and
15/// [`BackendConfig`] fields directly.
16///
17/// Worker-policy fields (`lease_ttl_ms`, `claim_poll_interval_ms`,
18/// capability set, lane list, identity) stay on `WorkerConfig` —
19/// those are orthogonal to the storage backend choice.
20///
21/// `WorkerConfig::new` was removed in this stage (pre-1.0 clean
22/// break); construct via struct literal.
23pub struct WorkerConfig {
24    /// Backend connection + shared timeouts / retry policy.
25    ///
26    /// **v0.13 ergonomics fix (cairn, feedback_sdk_reclaim_ergonomics
27    /// Finding 2):** this field is only consumed by
28    /// [`FlowFabricWorker::connect`] (the URL-based Valkey-native
29    /// entry point that dials a fresh `ferriskey::Client`).
30    /// [`FlowFabricWorker::connect_with`] — the backend-agnostic
31    /// entry point that takes a pre-built `Arc<dyn EngineBackend>` —
32    /// ignores it entirely. Pre-v0.13 this field was required and
33    /// `connect_with` callers had to supply a placeholder
34    /// `BackendConfig::valkey(...)` just to satisfy the struct
35    /// literal; the SC-10 `incident-remediation` example surfaced
36    /// this as a rough edge.
37    ///
38    /// * `Some(cfg)` + [`FlowFabricWorker::connect`]: dial using
39    ///   `cfg` (unchanged behaviour).
40    /// * `None` + [`FlowFabricWorker::connect`]: rejected with
41    ///   [`SdkError::Config`]. The URL-based path needs a
42    ///   `BackendConfig` to dial.
43    /// * `None` + [`FlowFabricWorker::connect_with`]: clean —
44    ///   the injected backend is authoritative.
45    /// * `Some(cfg)` + [`FlowFabricWorker::connect_with`]:
46    ///   accepted but logs a WARN (`cfg` is ignored — the
47    ///   injected backend is authoritative).
48    ///
49    /// [`FlowFabricWorker::connect`]: crate::FlowFabricWorker::connect
50    /// [`FlowFabricWorker::connect_with`]: crate::FlowFabricWorker::connect_with
51    /// [`SdkError::Config`]: crate::SdkError::Config
52    pub backend: Option<BackendConfig>,
53    /// Logical worker identity (e.g., "gpu-worker-pool-1").
54    pub worker_id: WorkerId,
55    /// Concrete worker process/runtime instance identity (e.g., container ID).
56    pub worker_instance_id: WorkerInstanceId,
57    /// Namespace this worker operates in.
58    pub namespace: Namespace,
59    /// Lanes this worker claims work from.
60    pub lanes: Vec<LaneId>,
61    /// Capabilities this worker advertises for routing.
62    pub capabilities: Vec<String>,
63    /// Lease TTL in milliseconds. Default: 30,000 (30s).
64    pub lease_ttl_ms: u64,
65    /// Interval between claim attempts when idle, in milliseconds. Default: 1,000 (1s).
66    pub claim_poll_interval_ms: u64,
67    /// Maximum concurrent tasks. Default: 1.
68    pub max_concurrent_tasks: usize,
69    /// Override for the server-published partition config.
70    ///
71    /// v0.12 PR-6: closes the follow-up flagged in
72    /// [`FlowFabricWorker::connect_with`]'s pre-PR-6 rustdoc
73    /// ("callers needing a non-default `PartitionConfig` under
74    /// non-Valkey backends use `connect` (Valkey) or override
75    /// post-construction through a future `WorkerConfig` field").
76    ///
77    /// * `None` (default) — `connect_with` uses
78    ///   [`PartitionConfig::default()`] (256 / 32 / 32);
79    ///   `connect` ignores this field and reads
80    ///   `ff:config:partitions` from Valkey as before.
81    /// * `Some(cfg)` — `connect_with` binds the worker to `cfg`
82    ///   directly; `connect` still prefers Valkey's published
83    ///   hash (this override is a `connect_with`-only knob, since
84    ///   Valkey's `ff:config:partitions` is authoritative when
85    ///   present).
86    ///
87    /// Consumers using a PG / SQLite backend whose deployment
88    /// uses a non-default `num_flow_partitions` (e.g. 512) must
89    /// set this — otherwise `describe_execution` + partition-
90    /// keyed claim paths compute the wrong partition index and
91    /// silently miss data.
92    ///
93    /// [`FlowFabricWorker::connect_with`]: crate::FlowFabricWorker::connect_with
94    pub partition_config: Option<PartitionConfig>,
95}
96
97impl WorkerConfig {
98    /// Lease renewal interval: TTL / 3 (renew at 1/3 of TTL, leaving 2/3 margin).
99    pub fn renewal_interval_ms(&self) -> u64 {
100        self.lease_ttl_ms / 3
101    }
102}
ff_sdk/config.rs

ff_sdk/
config.rs
