Skip to main content

hatchet_client/declare/
options.rs

1//! Options that refine how Hatchet schedules a task.
2
3use std::time::Duration;
4
5use hatchet_proto::root::WorkerLabels;
6use hatchet_proto::v1;
7
8/// What happens to runs beyond a concurrency limit.
9#[derive(Clone, Copy, Debug, PartialEq, Eq)]
10pub enum ConcurrencyLimitStrategy {
11    /// Cancel the oldest running run to make room (the engine default).
12    CancelInProgress,
13    /// Queue runs and take them round-robin across groups.
14    GroupRoundRobin,
15    /// Cancel the newly arriving run.
16    CancelNewest,
17}
18
19/// How a workflow's runs are pinned to the worker that started them.
20///
21/// Set it with [`Workflow::sticky`](crate::Workflow::sticky), or with
22/// [`TaskBuilder::sticky`](crate::TaskBuilder::sticky) for a standalone
23/// task. It is also what makes a child run's own sticky pinning
24/// meaningful: the engine's own comment on `desired_worker_id` says it
25/// "requires the workflow definition to have a sticky strategy".
26///
27/// ```
28/// use hatchet_client::{StickyStrategy, Workflow, TaskBuilder};
29///
30/// let load = TaskBuilder::<(), ()>::new("load").handler(|_ctx, _input| async { Ok(()) });
31/// let index = TaskBuilder::<(), ()>::new("index").handler(|_ctx, _input| async { Ok(()) });
32/// // Both tasks want the same machine's warm cache.
33/// let build = Workflow::new("build-index")
34///     .sticky(StickyStrategy::Soft)
35///     .task(&load)
36///     .task(&index);
37/// # let _ = build;
38/// ```
39#[derive(Clone, Copy, Debug, PartialEq, Eq)]
40pub enum StickyStrategy {
41    /// Prefer the worker that ran the first task of the run, and fall back
42    /// to another when it cannot be used. Observed against `hatchet-lite`
43    /// (both supported versions): a run's tasks landed on the same worker
44    /// 4/4 times, against 2/4 (v0.107.0) and 0/4 (v0.80.0) for a run with no
45    /// sticky strategy.
46    Soft,
47    /// Only that worker may run the rest of the run. Observed against
48    /// `hatchet-lite` (both supported versions): a run's tasks landed on the
49    /// same worker 4/4 times, **and when that worker was gone (a graceful
50    /// shutdown), the run's remaining tasks never ran** — not even when
51    /// another worker was registered and serving the same action. A `HARD`
52    /// run whose worker disappears is stranded, not rescheduled.
53    Hard,
54}
55
56impl StickyStrategy {
57    pub(crate) fn to_proto(self) -> i32 {
58        let proto = match self {
59            Self::Soft => v1::StickyStrategy::Soft,
60            Self::Hard => v1::StickyStrategy::Hard,
61        };
62        proto as i32
63    }
64}
65
66/// A concurrency limit keyed by a CEL expression over the run's input.
67///
68/// Set a [`strategy`](Concurrency::strategy) if runs beyond the limit should
69/// *wait*: without one the engine applies its own default, and that default
70/// does not queue. Observed against `hatchet-lite`, on both supported engine
71/// versions: with [`max_runs(1)`](Concurrency::max_runs), no strategy and two
72/// runs sharing a key, the run **already under way** was cancelled and the
73/// newcomer went through — the cancelled one ending as
74/// [`Error::RunCancelled`](crate::Error::RunCancelled) for its waiter, and
75/// its handler seeing [`Context::cancelled`](crate::Context::cancelled). With
76/// [`ConcurrencyLimitStrategy::GroupRoundRobin`] the second run waits for the
77/// first and then runs.
78///
79/// ```
80/// use hatchet_client::{Concurrency, ConcurrencyLimitStrategy, TaskBuilder};
81///
82/// let sync = TaskBuilder::<(), ()>::new("sync")
83///     .workflow_concurrency(
84///         Concurrency::expr("input.account_id")
85///             .max_runs(1)
86///             .strategy(ConcurrencyLimitStrategy::GroupRoundRobin),
87///     )
88///     .handler(|_ctx, _input| async { Ok(()) });
89/// # let _ = sync;
90/// ```
91#[derive(Clone, Debug, PartialEq, Eq)]
92pub struct Concurrency {
93    expression: String,
94    max_runs: Option<u32>,
95    strategy: Option<ConcurrencyLimitStrategy>,
96    name: Option<String>,
97    is_tenant_scoped: bool,
98    max_runs_expression: Option<String>,
99}
100
101impl Concurrency {
102    /// Groups runs by the value of a CEL expression such as `input.device_id`.
103    pub fn expr(expression: impl Into<String>) -> Self {
104        Self {
105            expression: expression.into(),
106            max_runs: None,
107            strategy: None,
108            name: None,
109            is_tenant_scoped: false,
110            max_runs_expression: None,
111        }
112    }
113
114    /// How many runs of one group may execute at once (engine default: 1).
115    pub fn max_runs(mut self, max_runs: u32) -> Self {
116        self.max_runs = Some(max_runs);
117        self
118    }
119
120    /// What to do with runs beyond the limit.
121    ///
122    /// Leaving this unset leaves the choice to the engine, which cancels
123    /// rather than queues: observed against `hatchet-lite`, the run that lost
124    /// was the one already under way, and it ended as
125    /// [`Error::RunCancelled`](crate::Error::RunCancelled) for its waiter.
126    /// [`ConcurrencyLimitStrategy::GroupRoundRobin`] is the strategy that
127    /// makes a run wait its turn.
128    pub fn strategy(mut self, strategy: ConcurrencyLimitStrategy) -> Self {
129        self.strategy = Some(strategy);
130        self
131    }
132
133    /// Names this entry. Required for a tenant-scoped strategy, where the
134    /// name is what makes two workflows share one limit. What the engine does
135    /// with the name of an entry that is not tenant-scoped was not verified.
136    pub fn name(mut self, name: impl Into<String>) -> Self {
137        self.name = Some(name.into());
138        self
139    }
140
141    /// Shares this limit with every other workflow declaring a tenant-scoped
142    /// entry of the same [`name`](Concurrency::name), rather than keeping it
143    /// to this workflow.
144    ///
145    /// A tenant-scoped entry without a name is an
146    /// [`Error::InvalidDeclaration`](crate::Error::InvalidDeclaration) at
147    /// registration.
148    pub fn tenant_scoped(mut self) -> Self {
149        self.is_tenant_scoped = true;
150        self
151    }
152
153    /// Takes the limit from a CEL expression over the run's input instead of
154    /// a fixed number, evaluated per group; the group's effective limit is
155    /// the value from its most recently created task. Overrides
156    /// [`max_runs`](Concurrency::max_runs) for the groups it applies to; both
157    /// may be set, and `max_runs` then stays the static default.
158    pub fn max_runs_expression(mut self, expression: impl Into<String>) -> Self {
159        self.max_runs_expression = Some(expression.into());
160        self
161    }
162
163    /// Checks that this concurrency limit can be sent to the engine.
164    pub(crate) fn validate(&self) -> Result<(), String> {
165        if self.max_runs == Some(0) {
166            return Err("concurrency max_runs must be at least 1".to_string());
167        }
168        if self.is_tenant_scoped && self.name.is_none() {
169            return Err(
170                "a tenant-scoped concurrency entry needs a name; it is what makes two \
171                 workflows share one limit"
172                    .to_string(),
173            );
174        }
175        Ok(())
176    }
177
178    pub(crate) fn to_proto(&self) -> v1::Concurrency {
179        v1::Concurrency {
180            expression: self.expression.clone(),
181            max_runs: self.max_runs.map(saturating_i32),
182            limit_strategy: self.strategy.map(|strategy| {
183                let proto = match strategy {
184                    ConcurrencyLimitStrategy::CancelInProgress => {
185                        v1::ConcurrencyLimitStrategy::CancelInProgress
186                    }
187                    ConcurrencyLimitStrategy::GroupRoundRobin => {
188                        v1::ConcurrencyLimitStrategy::GroupRoundRobin
189                    }
190                    ConcurrencyLimitStrategy::CancelNewest => {
191                        v1::ConcurrencyLimitStrategy::CancelNewest
192                    }
193                };
194                proto as i32
195            }),
196            name: self.name.clone(),
197            is_tenant_scoped: self.is_tenant_scoped.then_some(true),
198            max_runs_expression: self.max_runs_expression.clone(),
199        }
200    }
201}
202
203/// The window a rate limit's allowance refills over.
204///
205/// The engine's own default when nothing is sent was not measured; the
206/// official Go SDK leaves it unset too, and the official Python SDK always
207/// sends `MINUTE`.
208#[derive(Clone, Copy, Debug, PartialEq, Eq)]
209pub enum RateLimitDuration {
210    /// Per second.
211    Second,
212    /// Per minute.
213    Minute,
214    /// Per hour.
215    Hour,
216    /// Per day.
217    Day,
218    /// Per week.
219    Week,
220    /// Per month.
221    Month,
222    /// Per year.
223    Year,
224}
225
226impl RateLimitDuration {
227    pub(crate) fn to_proto(self) -> i32 {
228        let proto = match self {
229            Self::Second => v1::RateLimitDuration::Second,
230            Self::Minute => v1::RateLimitDuration::Minute,
231            Self::Hour => v1::RateLimitDuration::Hour,
232            Self::Day => v1::RateLimitDuration::Day,
233            Self::Week => v1::RateLimitDuration::Week,
234            Self::Month => v1::RateLimitDuration::Month,
235            Self::Year => v1::RateLimitDuration::Year,
236        };
237        proto as i32
238    }
239}
240
241/// How much of a rate limit one run of a task consumes.
242///
243/// Two kinds, and a task may carry several of either:
244///
245/// * [`new`](RateLimit::new) names a **static** limit — one the tenant
246///   already has, which
247///   [`RateLimitsClient::put`](crate::RateLimitsClient::put) creates or
248///   raises. Without that upsert, registering a task that uses this key
249///   fails with a bare `Internal` error from the engine (observed against
250///   both supported engine versions); the SDK cannot detect this ahead of
251///   time, so create the key first.
252/// * [`dynamic`](RateLimit::dynamic) computes the key from the run's input
253///   with CEL, which is how one limit per tenant or per user is expressed.
254///   A dynamic limit must also say what the allowance *is*, with
255///   [`limit_expr`](RateLimit::limit_expr) — there is no stored limit to
256///   look up for a key nobody registered. A dynamic limit without one is an
257///   [`Error::InvalidDeclaration`](crate::Error::InvalidDeclaration) at
258///   registration, which is the rule the official Python SDK enforces too
259///   (`sdks/python/hatchet_sdk/types/rate_limit.py`, `validate_rate_limit`);
260///   the official Go SDK does not check it at all. It must also say how many
261///   units a run consumes, with [`units_expr`](RateLimit::units_expr):
262///   without one, `hatchet-lite` v0.107.0 registered the task and then
263///   failed *every* run of it with a CEL syntax error on the empty
264///   expression, so a dynamic limit without `units_expr` is rejected here
265///   too (an SDK rule; neither official SDK checks it).
266///
267/// The dynamic wire shape here follows the official Python SDK: the key
268/// expression is sent as both `key` and `key_expr`. The official Go SDK
269/// instead leaves `key` empty for a dynamic limit, but both supported
270/// engine versions reject that with `InvalidArgument` (`Key: required`) —
271/// observed against `hatchet-lite` v0.107.0 and v0.80.0.
272///
273/// ```
274/// use hatchet_client::{RateLimit, RateLimitDuration, TaskBuilder};
275///
276/// let call_api = TaskBuilder::<(), ()>::new("call-api")
277///     // Five calls per customer per minute, whoever the customer is.
278///     .rate_limit(
279///         RateLimit::dynamic("input.customer_id")
280///             .units_expr("1")
281///             .limit_expr("5")
282///             .duration(RateLimitDuration::Minute),
283///     )
284///     .handler(|_ctx, _input| async { Ok(()) });
285/// # let _ = call_api;
286/// ```
287#[derive(Clone, Debug, PartialEq, Eq)]
288pub struct RateLimit {
289    key: String,
290    key_expr: Option<String>,
291    units: Option<u32>,
292    units_expr: Option<String>,
293    limit_expr: Option<String>,
294    duration: Option<RateLimitDuration>,
295}
296
297impl RateLimit {
298    /// Each run consumes `units` of the rate limit named `key`, which must
299    /// already exist on the tenant (see
300    /// [`RateLimitsClient::put`](crate::RateLimitsClient::put)).
301    pub fn new(key: impl Into<String>, units: u32) -> Self {
302        Self {
303            key: key.into(),
304            key_expr: None,
305            units: Some(units),
306            units_expr: None,
307            limit_expr: None,
308            duration: None,
309        }
310    }
311
312    /// Takes the limit's key from a CEL expression over the run's input,
313    /// such as `"input.customer_id"`. Needs
314    /// [`limit_expr`](RateLimit::limit_expr).
315    pub fn dynamic(key_expr: impl Into<String>) -> Self {
316        let key_expr = key_expr.into();
317        Self {
318            key: key_expr.clone(),
319            key_expr: Some(key_expr),
320            units: None,
321            units_expr: None,
322            limit_expr: None,
323            duration: None,
324        }
325    }
326
327    /// Takes the units consumed from a CEL expression instead of a fixed
328    /// number. Works on both a static and a dynamic rate limit.
329    pub fn units_expr(mut self, expression: impl Into<String>) -> Self {
330        self.units_expr = Some(expression.into());
331        self
332    }
333
334    /// The allowance itself, as a CEL expression — the engine's
335    /// `limit_values_expr`. A constant is written as one: `"5"`. Required on
336    /// a [`dynamic`](RateLimit::dynamic) limit; optional on a static one.
337    pub fn limit_expr(mut self, expression: impl Into<String>) -> Self {
338        self.limit_expr = Some(expression.into());
339        self
340    }
341
342    /// The window the allowance refills over. Works on both a static and a
343    /// dynamic rate limit.
344    pub fn duration(mut self, duration: RateLimitDuration) -> Self {
345        self.duration = Some(duration);
346        self
347    }
348
349    /// Checks that this rate limit can be sent to the engine.
350    pub(crate) fn validate(&self) -> Result<(), String> {
351        match &self.key_expr {
352            Some(expr) if expr.trim().is_empty() => {
353                Err("a dynamic rate limit key expression must not be empty".to_string())
354            }
355            Some(_) if self.limit_expr.is_none() => Err(
356                "a dynamic rate limit needs its allowance too; add `limit_expr(..)`, since \
357                 there is no stored limit for a key that is computed per run"
358                    .to_string(),
359            ),
360            Some(_) if self.units_expr.is_none() => Err(
361                "a dynamic rate limit needs `units_expr(..)`, the units one run consumes; \
362                 without it the engine registers the task and then fails every run of it \
363                 with a CEL syntax error"
364                    .to_string(),
365            ),
366            None if self.key.trim().is_empty() => {
367                Err("a rate limit key must not be empty".to_string())
368            }
369            _ => Ok(()),
370        }
371    }
372
373    pub(crate) fn to_proto(&self) -> v1::CreateTaskRateLimit {
374        v1::CreateTaskRateLimit {
375            key: self.key.clone(),
376            units: self.units.map(saturating_i32),
377            key_expr: self.key_expr.clone(),
378            units_expr: self.units_expr.clone(),
379            limit_values_expr: self.limit_expr.clone(),
380            duration: self.duration.map(RateLimitDuration::to_proto),
381        }
382    }
383}
384
385/// A worker label value: a string or an integer.
386#[derive(Clone, Debug, PartialEq, Eq)]
387pub enum LabelValue {
388    /// A string label such as `"macos"`.
389    Str(String),
390    /// An integer label such as `16`.
391    Int(i32),
392}
393
394impl From<&str> for LabelValue {
395    fn from(value: &str) -> Self {
396        Self::Str(value.to_string())
397    }
398}
399
400impl From<String> for LabelValue {
401    fn from(value: String) -> Self {
402        Self::Str(value)
403    }
404}
405
406impl From<i32> for LabelValue {
407    fn from(value: i32) -> Self {
408        Self::Int(value)
409    }
410}
411
412impl LabelValue {
413    /// The label as the engine takes it, whether it is being registered with
414    /// a worker or upserted from a running task.
415    pub(crate) fn to_proto(&self) -> WorkerLabels {
416        match self {
417            Self::Str(value) => WorkerLabels {
418                str_value: Some(value.clone()),
419                int_value: None,
420            },
421            Self::Int(value) => WorkerLabels {
422                str_value: None,
423                int_value: Some(*value),
424            },
425        }
426    }
427}
428
429/// A label a task wants its worker to have.
430#[derive(Clone, Debug, PartialEq, Eq)]
431pub struct DesiredLabel {
432    value: LabelValue,
433    comparator: v1::WorkerLabelComparator,
434    required: bool,
435    weight: Option<i32>,
436}
437
438impl DesiredLabel {
439    fn new(value: impl Into<LabelValue>, comparator: v1::WorkerLabelComparator) -> Self {
440        Self {
441            value: value.into(),
442            comparator,
443            required: false,
444            weight: None,
445        }
446    }
447
448    /// The worker's label equals `value`.
449    #[allow(clippy::should_implement_trait)]
450    pub fn eq(value: impl Into<LabelValue>) -> Self {
451        Self::new(value, v1::WorkerLabelComparator::Equal)
452    }
453
454    /// The worker's label differs from `value`.
455    #[allow(clippy::should_implement_trait)]
456    pub fn ne(value: impl Into<LabelValue>) -> Self {
457        Self::new(value, v1::WorkerLabelComparator::NotEqual)
458    }
459
460    /// The worker's label is greater than `value`.
461    pub fn gt(value: impl Into<LabelValue>) -> Self {
462        Self::new(value, v1::WorkerLabelComparator::GreaterThan)
463    }
464
465    /// The worker's label is at least `value`.
466    pub fn gte(value: impl Into<LabelValue>) -> Self {
467        Self::new(value, v1::WorkerLabelComparator::GreaterThanOrEqual)
468    }
469
470    /// The worker's label is less than `value`.
471    pub fn lt(value: impl Into<LabelValue>) -> Self {
472        Self::new(value, v1::WorkerLabelComparator::LessThan)
473    }
474
475    /// The worker's label is at most `value`.
476    pub fn lte(value: impl Into<LabelValue>) -> Self {
477        Self::new(value, v1::WorkerLabelComparator::LessThanOrEqual)
478    }
479
480    /// Only workers satisfying this label may take the task.
481    pub fn required(mut self) -> Self {
482        self.required = true;
483        self
484    }
485
486    /// How strongly to prefer workers satisfying this label.
487    pub fn weight(mut self, weight: i32) -> Self {
488        self.weight = Some(weight);
489        self
490    }
491
492    pub(crate) fn to_proto(&self) -> v1::DesiredWorkerLabels {
493        let (str_value, int_value) = match &self.value {
494            LabelValue::Str(value) => (Some(value.clone()), None),
495            LabelValue::Int(value) => (None, Some(*value)),
496        };
497        v1::DesiredWorkerLabels {
498            str_value,
499            int_value,
500            required: Some(self.required),
501            comparator: Some(self.comparator as i32),
502            weight: self.weight,
503        }
504    }
505}
506
507/// Run priority; higher runs are scheduled first.
508#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
509pub enum Priority {
510    /// Priority 1.
511    Low,
512    /// Priority 2.
513    Medium,
514    /// Priority 3.
515    High,
516}
517
518impl Priority {
519    pub(crate) fn to_proto(self) -> i32 {
520        match self {
521            Self::Low => 1,
522            Self::Medium => 2,
523            Self::High => 3,
524        }
525    }
526}
527
528/// How the engine buffers concurrent runs of one task into a batch.
529///
530/// The runs of a batch task are **held by the engine** until the batch fills up
531/// ([`max_size`](Self::max_size)) or its interval runs out
532/// ([`max_interval`](Self::max_interval)), and the whole group is then given to
533/// one worker as a single action. The handler is called once and answers with
534/// one output per buffered run.
535///
536/// **A batch is flushed on time as well as on size, always.** Measured against
537/// real engines, a batch with no `max_interval` set was still handed over about
538/// a second after the first run arrived — there is a default interval, so a
539/// half-full batch never waits indefinitely for the rest.
540///
541/// Needs an engine of at least
542/// [`BATCH_MIN_ENGINE_VERSION`](crate::BATCH_MIN_ENGINE_VERSION); a worker
543/// registering a batch task on an older one is refused by
544/// [`WorkerBuilder::build`](crate::WorkerBuilder::build).
545///
546/// ```
547/// use std::time::Duration;
548///
549/// use hatchet_client::{BatchConfig, TaskBuilder};
550///
551/// let embed = TaskBuilder::<String, usize>::new("embed").batch_handler(
552///     BatchConfig::max_size(32)
553///         .max_interval(Duration::from_millis(200))
554///         .group_key("input.tenant"),
555///     |_ctx, batch| async move {
556///         Ok(batch.iter().map(|(id, text)| (id.clone(), text.len())).collect())
557///     },
558/// );
559/// # let _ = embed;
560/// ```
561#[derive(Clone, Debug, PartialEq, Eq)]
562#[must_use = "a batch config configures nothing until a task is declared with it"]
563pub struct BatchConfig {
564    max_size: u32,
565    max_interval: Option<Duration>,
566    group_key: Option<String>,
567    group_max_runs: Option<u32>,
568}
569
570impl BatchConfig {
571    /// Buffer at most `max_size` runs before handing the batch to a worker.
572    /// Required, and at least 1.
573    pub fn max_size(max_size: u32) -> Self {
574        Self {
575            max_size,
576            max_interval: None,
577            group_key: None,
578            group_max_runs: None,
579        }
580    }
581
582    /// Hand a partly filled batch over after this long rather than waiting for
583    /// [`max_size`](Self::max_size) runs to arrive.
584    ///
585    /// The engine takes whole milliseconds, so anything that rounds down to
586    /// zero is an
587    /// [`Error::InvalidDeclaration`](crate::Error::InvalidDeclaration) rather
588    /// than a silent zero, which the engine reads as "no interval given".
589    pub fn max_interval(mut self, interval: Duration) -> Self {
590        self.max_interval = Some(interval);
591        self
592    }
593
594    /// Split the buffered runs into independent batches by the value of a CEL
595    /// expression over each run's input, such as `"input.tenant"`, so one
596    /// tenant's runs are never mixed into another's
597    /// (`pkg/client/types/batch.go:18-20`).
598    ///
599    /// Measured: four runs of two tenants under `"input.tenant"` arrived as two
600    /// batches, each holding only its own tenant's inputs, and each batch's
601    /// [`BatchInput::batch_key`](crate::BatchInput::batch_key) held the
602    /// **evaluated value** (`"acme"`, `"globex"`) rather than the expression.
603    /// Without a group key every run goes into one partition, which engines
604    /// name `"default"`.
605    pub fn group_key(mut self, expression: impl Into<String>) -> Self {
606        self.group_key = Some(expression.into());
607        self
608    }
609
610    /// How many batches of one group may run at once.
611    pub fn group_max_runs(mut self, max_runs: u32) -> Self {
612        self.group_max_runs = Some(max_runs);
613        self
614    }
615
616    /// Why this configuration cannot be registered, if it cannot.
617    pub(crate) fn invalid_reason(&self) -> Option<String> {
618        if self.max_size == 0 {
619            return Some(
620                "a batch config needs a max size of at least 1; a size of zero buffers nothing"
621                    .to_string(),
622            );
623        }
624        if let Some(interval) = self.max_interval {
625            if interval.is_zero() {
626                return Some(
627                    "a batch max interval of zero is not an interval; leave it unset to let the \
628                     engine use its own default"
629                        .to_string(),
630                );
631            }
632            if interval.as_millis() == 0 {
633                return Some(format!(
634                    "a batch max interval of {interval:?} rounds down to zero milliseconds, which \
635                     the engine reads as no interval at all; use at least 1ms"
636                ));
637            }
638            if i32::try_from(interval.as_millis()).is_err() {
639                return Some(format!(
640                    "a batch max interval of {interval:?} is longer than the engine's limit of \
641                     about 24 days"
642                ));
643            }
644        }
645        if self.group_max_runs == Some(0) {
646            return Some(
647                "a batch group max runs of zero would let no batch of a group run at all"
648                    .to_string(),
649            );
650        }
651        if self
652            .group_key
653            .as_ref()
654            .is_some_and(|key| key.trim().is_empty())
655        {
656            return Some("a batch group key is a CEL expression and cannot be blank".to_string());
657        }
658        None
659    }
660
661    /// The registration field. `broadcast_output` comes from the handler that
662    /// was attached, never from the caller: the flag and the handler's return
663    /// type are one decision.
664    pub(crate) fn to_proto(&self, broadcast_output: bool) -> v1::TaskBatchConfig {
665        v1::TaskBatchConfig {
666            batch_max_size: saturating_i32(self.max_size),
667            batch_max_interval_ms: self
668                .max_interval
669                .map(|interval| i32::try_from(interval.as_millis()).unwrap_or(i32::MAX)),
670            batch_group_key: self.group_key.clone(),
671            batch_group_max_runs: self.group_max_runs.map(saturating_i32),
672            broadcast_output: Some(broadcast_output),
673        }
674    }
675}
676
677pub(crate) fn saturating_i32(value: u32) -> i32 {
678    i32::try_from(value).unwrap_or(i32::MAX)
679}
680
681#[cfg(test)]
682mod tests {
683    use super::*;
684    use hatchet_proto::v1;
685
686    #[test]
687    fn a_batch_config_maps_to_the_registration_field() {
688        let proto = BatchConfig::max_size(10)
689            .max_interval(Duration::from_secs(2))
690            .group_key("input.tenant")
691            .group_max_runs(3)
692            .to_proto(false);
693        assert_eq!(
694            proto,
695            v1::TaskBatchConfig {
696                batch_max_size: 10,
697                batch_max_interval_ms: Some(2_000),
698                batch_group_key: Some("input.tenant".to_string()),
699                batch_group_max_runs: Some(3),
700                broadcast_output: Some(false),
701            }
702        );
703    }
704
705    #[test]
706    fn a_batch_config_sends_only_what_it_was_given() {
707        let proto = BatchConfig::max_size(4).to_proto(true);
708        assert_eq!(proto.batch_max_size, 4);
709        assert_eq!(proto.batch_max_interval_ms, None);
710        assert_eq!(proto.batch_group_key, None);
711        assert_eq!(proto.batch_group_max_runs, None);
712        // Explicitly true rather than absent: the handler that was attached
713        // decides it, so the wire says which decision was made.
714        assert_eq!(proto.broadcast_output, Some(true));
715    }
716
717    #[test]
718    fn a_batch_config_rejects_what_the_engine_would_read_as_nothing() {
719        for config in [
720            BatchConfig::max_size(0),
721            BatchConfig::max_size(1).max_interval(Duration::ZERO),
722            BatchConfig::max_size(1).max_interval(Duration::from_micros(999)),
723            BatchConfig::max_size(1).max_interval(Duration::from_secs(60 * 60 * 24 * 25)),
724            BatchConfig::max_size(1).group_max_runs(0),
725            BatchConfig::max_size(1).group_key(" "),
726        ] {
727            assert!(config.invalid_reason().is_some(), "{config:?}");
728        }
729        assert!(
730            BatchConfig::max_size(1)
731                .max_interval(Duration::from_millis(1))
732                .group_key("input.tenant")
733                .group_max_runs(1)
734                .invalid_reason()
735                .is_none()
736        );
737    }
738
739    #[test]
740    fn a_batch_config_saturates_rather_than_wrapping() {
741        let proto = BatchConfig::max_size(u32::MAX)
742            .group_max_runs(u32::MAX)
743            .to_proto(false);
744        assert_eq!(proto.batch_max_size, i32::MAX);
745        assert_eq!(proto.batch_group_max_runs, Some(i32::MAX));
746    }
747
748    #[test]
749    fn concurrency_maps_expression_max_runs_and_strategy() {
750        let concurrency = Concurrency::expr("input.device_id")
751            .max_runs(1)
752            .strategy(ConcurrencyLimitStrategy::GroupRoundRobin);
753        assert_eq!(
754            concurrency.to_proto(),
755            v1::Concurrency {
756                expression: "input.device_id".to_string(),
757                max_runs: Some(1),
758                limit_strategy: Some(v1::ConcurrencyLimitStrategy::GroupRoundRobin as i32),
759                ..Default::default()
760            }
761        );
762    }
763
764    #[test]
765    fn concurrency_max_runs_zero_is_invalid() {
766        let err = Concurrency::expr("input.user")
767            .max_runs(0)
768            .validate()
769            .unwrap_err();
770        assert!(err.contains("max_runs"), "{err}");
771    }
772
773    #[test]
774    fn concurrency_without_max_runs_or_with_a_positive_one_is_valid() {
775        assert!(Concurrency::expr("input.user").validate().is_ok());
776        assert!(
777            Concurrency::expr("input.user")
778                .max_runs(1)
779                .validate()
780                .is_ok()
781        );
782    }
783
784    #[test]
785    fn concurrency_leaves_unset_fields_to_the_engine_defaults() {
786        assert_eq!(
787            Concurrency::expr("input.user").to_proto(),
788            v1::Concurrency {
789                expression: "input.user".to_string(),
790                ..Default::default()
791            }
792        );
793    }
794
795    #[test]
796    fn every_strategy_maps_to_its_proto_value() {
797        use ConcurrencyLimitStrategy::*;
798        for (ours, theirs) in [
799            (
800                CancelInProgress,
801                v1::ConcurrencyLimitStrategy::CancelInProgress,
802            ),
803            (
804                GroupRoundRobin,
805                v1::ConcurrencyLimitStrategy::GroupRoundRobin,
806            ),
807            (CancelNewest, v1::ConcurrencyLimitStrategy::CancelNewest),
808        ] {
809            let proto = Concurrency::expr("x").strategy(ours).to_proto();
810            assert_eq!(proto.limit_strategy, Some(theirs as i32));
811        }
812    }
813
814    #[test]
815    fn concurrency_maps_the_name_tenant_scope_and_max_runs_expression() {
816        let concurrency = Concurrency::expr("input.tenant")
817            .name("per-tenant")
818            .tenant_scoped()
819            .max_runs_expression("input.limit");
820        assert_eq!(
821            concurrency.to_proto(),
822            v1::Concurrency {
823                expression: "input.tenant".to_string(),
824                name: Some("per-tenant".to_string()),
825                is_tenant_scoped: Some(true),
826                max_runs_expression: Some("input.limit".to_string()),
827                ..Default::default()
828            }
829        );
830    }
831
832    #[test]
833    fn a_workflow_scoped_entry_sends_neither_the_tenant_flag_nor_a_name() {
834        // The Go SDK sets `Name` only when it is non-empty and
835        // `IsTenantScoped` only when true (declaration.go:763-791); an
836        // unset optional is how the engine hears "default".
837        let proto = Concurrency::expr("input.user").max_runs(2).to_proto();
838        assert_eq!(proto.name, None);
839        assert_eq!(proto.is_tenant_scoped, None);
840        assert_eq!(proto.max_runs_expression, None);
841    }
842
843    #[test]
844    fn a_tenant_scoped_entry_without_a_name_is_invalid() {
845        let err = Concurrency::expr("input.tenant")
846            .tenant_scoped()
847            .validate()
848            .unwrap_err();
849        assert!(err.contains("name"), "{err}");
850    }
851
852    #[test]
853    fn static_rate_limit_maps_key_and_units() {
854        assert_eq!(
855            RateLimit::new("github-api", 2).to_proto(),
856            v1::CreateTaskRateLimit {
857                key: "github-api".to_string(),
858                units: Some(2),
859                ..Default::default()
860            }
861        );
862    }
863
864    #[test]
865    fn a_dynamic_rate_limit_maps_every_expression_and_the_window() {
866        // The wire shape follows the official Python SDK: `key` carries the
867        // key expression too, since both supported engine versions reject
868        // the Go SDK's empty `key` with `InvalidArgument` (observed against
869        // hatchet-lite v0.107.0 and v0.80.0).
870        let limit = RateLimit::dynamic("input.tenant")
871            .units_expr("input.cost")
872            .limit_expr("5")
873            .duration(RateLimitDuration::Minute);
874        assert_eq!(
875            limit.to_proto(),
876            v1::CreateTaskRateLimit {
877                key: "input.tenant".to_string(),
878                units: None,
879                key_expr: Some("input.tenant".to_string()),
880                units_expr: Some("input.cost".to_string()),
881                limit_values_expr: Some("5".to_string()),
882                duration: Some(v1::RateLimitDuration::Minute as i32),
883            }
884        );
885    }
886
887    #[test]
888    fn a_static_rate_limit_may_also_take_a_units_expression_and_a_window() {
889        let limit = RateLimit::new("github-api", 2)
890            .units_expr("input.cost")
891            .duration(RateLimitDuration::Hour);
892        let proto = limit.to_proto();
893        assert_eq!(proto.key, "github-api");
894        assert_eq!(proto.units, Some(2));
895        assert_eq!(proto.units_expr, Some("input.cost".to_string()));
896        assert_eq!(proto.duration, Some(v1::RateLimitDuration::Hour as i32));
897        assert_eq!(proto.key_expr, None);
898    }
899
900    #[test]
901    fn every_rate_limit_duration_maps_to_its_proto_value() {
902        use RateLimitDuration::*;
903        for (ours, theirs) in [
904            (Second, v1::RateLimitDuration::Second),
905            (Minute, v1::RateLimitDuration::Minute),
906            (Hour, v1::RateLimitDuration::Hour),
907            (Day, v1::RateLimitDuration::Day),
908            (Week, v1::RateLimitDuration::Week),
909            (Month, v1::RateLimitDuration::Month),
910            (Year, v1::RateLimitDuration::Year),
911        ] {
912            assert_eq!(ours.to_proto(), theirs as i32);
913        }
914    }
915
916    #[test]
917    fn a_dynamic_rate_limit_without_a_units_expression_is_invalid() {
918        let reason = RateLimit::dynamic("input.tenant")
919            .limit_expr("5")
920            .validate()
921            .unwrap_err();
922        assert!(reason.contains("units_expr"), "{reason}");
923    }
924
925    #[test]
926    fn a_dynamic_rate_limit_without_a_limit_expression_is_invalid() {
927        let reason = RateLimit::dynamic("input.tenant").validate().unwrap_err();
928        assert!(reason.contains("limit_expr"), "{reason}");
929    }
930
931    #[test]
932    fn a_static_rate_limit_needs_no_limit_expression() {
933        assert!(RateLimit::new("github-api", 1).validate().is_ok());
934    }
935
936    #[test]
937    fn an_empty_static_key_is_invalid() {
938        let reason = RateLimit::new("  ", 1).validate().unwrap_err();
939        assert!(reason.contains("key"), "{reason}");
940    }
941
942    #[test]
943    fn an_empty_dynamic_key_expression_is_invalid() {
944        let reason = RateLimit::dynamic("  ")
945            .limit_expr("5")
946            .units_expr("1")
947            .validate()
948            .unwrap_err();
949        assert!(reason.contains("key"), "{reason}");
950    }
951
952    #[test]
953    fn required_string_label() {
954        assert_eq!(
955            DesiredLabel::eq("macos").required().to_proto(),
956            v1::DesiredWorkerLabels {
957                str_value: Some("macos".to_string()),
958                int_value: None,
959                required: Some(true),
960                comparator: Some(v1::WorkerLabelComparator::Equal as i32),
961                weight: None,
962            }
963        );
964    }
965
966    #[test]
967    fn weighted_integer_label() {
968        assert_eq!(
969            DesiredLabel::gte(8).weight(50).to_proto(),
970            v1::DesiredWorkerLabels {
971                str_value: None,
972                int_value: Some(8),
973                required: Some(false),
974                comparator: Some(v1::WorkerLabelComparator::GreaterThanOrEqual as i32),
975                weight: Some(50),
976            }
977        );
978    }
979
980    #[test]
981    fn every_comparator_maps_to_its_proto_value() {
982        use v1::WorkerLabelComparator as C;
983        for (label, comparator) in [
984            (DesiredLabel::eq(1), C::Equal),
985            (DesiredLabel::ne(1), C::NotEqual),
986            (DesiredLabel::gt(1), C::GreaterThan),
987            (DesiredLabel::gte(1), C::GreaterThanOrEqual),
988            (DesiredLabel::lt(1), C::LessThan),
989            (DesiredLabel::lte(1), C::LessThanOrEqual),
990        ] {
991            assert_eq!(label.to_proto().comparator, Some(comparator as i32));
992        }
993    }
994
995    #[test]
996    fn priorities_are_one_to_three() {
997        assert_eq!(Priority::Low.to_proto(), 1);
998        assert_eq!(Priority::Medium.to_proto(), 2);
999        assert_eq!(Priority::High.to_proto(), 3);
1000    }
1001
1002    #[test]
1003    fn every_sticky_strategy_maps_to_its_proto_value() {
1004        assert_eq!(
1005            StickyStrategy::Soft.to_proto(),
1006            v1::StickyStrategy::Soft as i32
1007        );
1008        assert_eq!(
1009            StickyStrategy::Hard.to_proto(),
1010            v1::StickyStrategy::Hard as i32
1011        );
1012    }
1013}