1use std::time::Duration;
4
5use hatchet_proto::root::WorkerLabels;
6use hatchet_proto::v1;
7
8#[derive(Clone, Copy, Debug, PartialEq, Eq)]
10pub enum ConcurrencyLimitStrategy {
11 CancelInProgress,
13 GroupRoundRobin,
15 CancelNewest,
17}
18
19#[derive(Clone, Copy, Debug, PartialEq, Eq)]
40pub enum StickyStrategy {
41 Soft,
47 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#[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 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 pub fn max_runs(mut self, max_runs: u32) -> Self {
116 self.max_runs = Some(max_runs);
117 self
118 }
119
120 pub fn strategy(mut self, strategy: ConcurrencyLimitStrategy) -> Self {
129 self.strategy = Some(strategy);
130 self
131 }
132
133 pub fn name(mut self, name: impl Into<String>) -> Self {
137 self.name = Some(name.into());
138 self
139 }
140
141 pub fn tenant_scoped(mut self) -> Self {
149 self.is_tenant_scoped = true;
150 self
151 }
152
153 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 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#[derive(Clone, Copy, Debug, PartialEq, Eq)]
209pub enum RateLimitDuration {
210 Second,
212 Minute,
214 Hour,
216 Day,
218 Week,
220 Month,
222 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#[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 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 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 pub fn units_expr(mut self, expression: impl Into<String>) -> Self {
330 self.units_expr = Some(expression.into());
331 self
332 }
333
334 pub fn limit_expr(mut self, expression: impl Into<String>) -> Self {
338 self.limit_expr = Some(expression.into());
339 self
340 }
341
342 pub fn duration(mut self, duration: RateLimitDuration) -> Self {
345 self.duration = Some(duration);
346 self
347 }
348
349 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#[derive(Clone, Debug, PartialEq, Eq)]
387pub enum LabelValue {
388 Str(String),
390 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 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#[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 #[allow(clippy::should_implement_trait)]
450 pub fn eq(value: impl Into<LabelValue>) -> Self {
451 Self::new(value, v1::WorkerLabelComparator::Equal)
452 }
453
454 #[allow(clippy::should_implement_trait)]
456 pub fn ne(value: impl Into<LabelValue>) -> Self {
457 Self::new(value, v1::WorkerLabelComparator::NotEqual)
458 }
459
460 pub fn gt(value: impl Into<LabelValue>) -> Self {
462 Self::new(value, v1::WorkerLabelComparator::GreaterThan)
463 }
464
465 pub fn gte(value: impl Into<LabelValue>) -> Self {
467 Self::new(value, v1::WorkerLabelComparator::GreaterThanOrEqual)
468 }
469
470 pub fn lt(value: impl Into<LabelValue>) -> Self {
472 Self::new(value, v1::WorkerLabelComparator::LessThan)
473 }
474
475 pub fn lte(value: impl Into<LabelValue>) -> Self {
477 Self::new(value, v1::WorkerLabelComparator::LessThanOrEqual)
478 }
479
480 pub fn required(mut self) -> Self {
482 self.required = true;
483 self
484 }
485
486 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#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
509pub enum Priority {
510 Low,
512 Medium,
514 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#[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 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 pub fn max_interval(mut self, interval: Duration) -> Self {
590 self.max_interval = Some(interval);
591 self
592 }
593
594 pub fn group_key(mut self, expression: impl Into<String>) -> Self {
606 self.group_key = Some(expression.into());
607 self
608 }
609
610 pub fn group_max_runs(mut self, max_runs: u32) -> Self {
612 self.group_max_runs = Some(max_runs);
613 self
614 }
615
616 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 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 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 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 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}