use std::time::Duration;
use hatchet_proto::root::WorkerLabels;
use hatchet_proto::v1;
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ConcurrencyLimitStrategy {
CancelInProgress,
GroupRoundRobin,
CancelNewest,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum StickyStrategy {
Soft,
Hard,
}
impl StickyStrategy {
pub(crate) fn to_proto(self) -> i32 {
let proto = match self {
Self::Soft => v1::StickyStrategy::Soft,
Self::Hard => v1::StickyStrategy::Hard,
};
proto as i32
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Concurrency {
expression: String,
max_runs: Option<u32>,
strategy: Option<ConcurrencyLimitStrategy>,
name: Option<String>,
is_tenant_scoped: bool,
max_runs_expression: Option<String>,
}
impl Concurrency {
pub fn expr(expression: impl Into<String>) -> Self {
Self {
expression: expression.into(),
max_runs: None,
strategy: None,
name: None,
is_tenant_scoped: false,
max_runs_expression: None,
}
}
pub fn max_runs(mut self, max_runs: u32) -> Self {
self.max_runs = Some(max_runs);
self
}
pub fn strategy(mut self, strategy: ConcurrencyLimitStrategy) -> Self {
self.strategy = Some(strategy);
self
}
pub fn name(mut self, name: impl Into<String>) -> Self {
self.name = Some(name.into());
self
}
pub fn tenant_scoped(mut self) -> Self {
self.is_tenant_scoped = true;
self
}
pub fn max_runs_expression(mut self, expression: impl Into<String>) -> Self {
self.max_runs_expression = Some(expression.into());
self
}
pub(crate) fn validate(&self) -> Result<(), String> {
if self.max_runs == Some(0) {
return Err("concurrency max_runs must be at least 1".to_string());
}
if self.is_tenant_scoped && self.name.is_none() {
return Err(
"a tenant-scoped concurrency entry needs a name; it is what makes two \
workflows share one limit"
.to_string(),
);
}
Ok(())
}
pub(crate) fn to_proto(&self) -> v1::Concurrency {
v1::Concurrency {
expression: self.expression.clone(),
max_runs: self.max_runs.map(saturating_i32),
limit_strategy: self.strategy.map(|strategy| {
let proto = match strategy {
ConcurrencyLimitStrategy::CancelInProgress => {
v1::ConcurrencyLimitStrategy::CancelInProgress
}
ConcurrencyLimitStrategy::GroupRoundRobin => {
v1::ConcurrencyLimitStrategy::GroupRoundRobin
}
ConcurrencyLimitStrategy::CancelNewest => {
v1::ConcurrencyLimitStrategy::CancelNewest
}
};
proto as i32
}),
name: self.name.clone(),
is_tenant_scoped: self.is_tenant_scoped.then_some(true),
max_runs_expression: self.max_runs_expression.clone(),
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum RateLimitDuration {
Second,
Minute,
Hour,
Day,
Week,
Month,
Year,
}
impl RateLimitDuration {
pub(crate) fn to_proto(self) -> i32 {
let proto = match self {
Self::Second => v1::RateLimitDuration::Second,
Self::Minute => v1::RateLimitDuration::Minute,
Self::Hour => v1::RateLimitDuration::Hour,
Self::Day => v1::RateLimitDuration::Day,
Self::Week => v1::RateLimitDuration::Week,
Self::Month => v1::RateLimitDuration::Month,
Self::Year => v1::RateLimitDuration::Year,
};
proto as i32
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RateLimit {
key: String,
key_expr: Option<String>,
units: Option<u32>,
units_expr: Option<String>,
limit_expr: Option<String>,
duration: Option<RateLimitDuration>,
}
impl RateLimit {
pub fn new(key: impl Into<String>, units: u32) -> Self {
Self {
key: key.into(),
key_expr: None,
units: Some(units),
units_expr: None,
limit_expr: None,
duration: None,
}
}
pub fn dynamic(key_expr: impl Into<String>) -> Self {
let key_expr = key_expr.into();
Self {
key: key_expr.clone(),
key_expr: Some(key_expr),
units: None,
units_expr: None,
limit_expr: None,
duration: None,
}
}
pub fn units_expr(mut self, expression: impl Into<String>) -> Self {
self.units_expr = Some(expression.into());
self
}
pub fn limit_expr(mut self, expression: impl Into<String>) -> Self {
self.limit_expr = Some(expression.into());
self
}
pub fn duration(mut self, duration: RateLimitDuration) -> Self {
self.duration = Some(duration);
self
}
pub(crate) fn validate(&self) -> Result<(), String> {
match &self.key_expr {
Some(expr) if expr.trim().is_empty() => {
Err("a dynamic rate limit key expression must not be empty".to_string())
}
Some(_) if self.limit_expr.is_none() => Err(
"a dynamic rate limit needs its allowance too; add `limit_expr(..)`, since \
there is no stored limit for a key that is computed per run"
.to_string(),
),
Some(_) if self.units_expr.is_none() => Err(
"a dynamic rate limit needs `units_expr(..)`, the units one run consumes; \
without it the engine registers the task and then fails every run of it \
with a CEL syntax error"
.to_string(),
),
None if self.key.trim().is_empty() => {
Err("a rate limit key must not be empty".to_string())
}
_ => Ok(()),
}
}
pub(crate) fn to_proto(&self) -> v1::CreateTaskRateLimit {
v1::CreateTaskRateLimit {
key: self.key.clone(),
units: self.units.map(saturating_i32),
key_expr: self.key_expr.clone(),
units_expr: self.units_expr.clone(),
limit_values_expr: self.limit_expr.clone(),
duration: self.duration.map(RateLimitDuration::to_proto),
}
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum LabelValue {
Str(String),
Int(i32),
}
impl From<&str> for LabelValue {
fn from(value: &str) -> Self {
Self::Str(value.to_string())
}
}
impl From<String> for LabelValue {
fn from(value: String) -> Self {
Self::Str(value)
}
}
impl From<i32> for LabelValue {
fn from(value: i32) -> Self {
Self::Int(value)
}
}
impl LabelValue {
pub(crate) fn to_proto(&self) -> WorkerLabels {
match self {
Self::Str(value) => WorkerLabels {
str_value: Some(value.clone()),
int_value: None,
},
Self::Int(value) => WorkerLabels {
str_value: None,
int_value: Some(*value),
},
}
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct DesiredLabel {
value: LabelValue,
comparator: v1::WorkerLabelComparator,
required: bool,
weight: Option<i32>,
}
impl DesiredLabel {
fn new(value: impl Into<LabelValue>, comparator: v1::WorkerLabelComparator) -> Self {
Self {
value: value.into(),
comparator,
required: false,
weight: None,
}
}
#[allow(clippy::should_implement_trait)]
pub fn eq(value: impl Into<LabelValue>) -> Self {
Self::new(value, v1::WorkerLabelComparator::Equal)
}
#[allow(clippy::should_implement_trait)]
pub fn ne(value: impl Into<LabelValue>) -> Self {
Self::new(value, v1::WorkerLabelComparator::NotEqual)
}
pub fn gt(value: impl Into<LabelValue>) -> Self {
Self::new(value, v1::WorkerLabelComparator::GreaterThan)
}
pub fn gte(value: impl Into<LabelValue>) -> Self {
Self::new(value, v1::WorkerLabelComparator::GreaterThanOrEqual)
}
pub fn lt(value: impl Into<LabelValue>) -> Self {
Self::new(value, v1::WorkerLabelComparator::LessThan)
}
pub fn lte(value: impl Into<LabelValue>) -> Self {
Self::new(value, v1::WorkerLabelComparator::LessThanOrEqual)
}
pub fn required(mut self) -> Self {
self.required = true;
self
}
pub fn weight(mut self, weight: i32) -> Self {
self.weight = Some(weight);
self
}
pub(crate) fn to_proto(&self) -> v1::DesiredWorkerLabels {
let (str_value, int_value) = match &self.value {
LabelValue::Str(value) => (Some(value.clone()), None),
LabelValue::Int(value) => (None, Some(*value)),
};
v1::DesiredWorkerLabels {
str_value,
int_value,
required: Some(self.required),
comparator: Some(self.comparator as i32),
weight: self.weight,
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
pub enum Priority {
Low,
Medium,
High,
}
impl Priority {
pub(crate) fn to_proto(self) -> i32 {
match self {
Self::Low => 1,
Self::Medium => 2,
Self::High => 3,
}
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
#[must_use = "a batch config configures nothing until a task is declared with it"]
pub struct BatchConfig {
max_size: u32,
max_interval: Option<Duration>,
group_key: Option<String>,
group_max_runs: Option<u32>,
}
impl BatchConfig {
pub fn max_size(max_size: u32) -> Self {
Self {
max_size,
max_interval: None,
group_key: None,
group_max_runs: None,
}
}
pub fn max_interval(mut self, interval: Duration) -> Self {
self.max_interval = Some(interval);
self
}
pub fn group_key(mut self, expression: impl Into<String>) -> Self {
self.group_key = Some(expression.into());
self
}
pub fn group_max_runs(mut self, max_runs: u32) -> Self {
self.group_max_runs = Some(max_runs);
self
}
pub(crate) fn invalid_reason(&self) -> Option<String> {
if self.max_size == 0 {
return Some(
"a batch config needs a max size of at least 1; a size of zero buffers nothing"
.to_string(),
);
}
if let Some(interval) = self.max_interval {
if interval.is_zero() {
return Some(
"a batch max interval of zero is not an interval; leave it unset to let the \
engine use its own default"
.to_string(),
);
}
if interval.as_millis() == 0 {
return Some(format!(
"a batch max interval of {interval:?} rounds down to zero milliseconds, which \
the engine reads as no interval at all; use at least 1ms"
));
}
if i32::try_from(interval.as_millis()).is_err() {
return Some(format!(
"a batch max interval of {interval:?} is longer than the engine's limit of \
about 24 days"
));
}
}
if self.group_max_runs == Some(0) {
return Some(
"a batch group max runs of zero would let no batch of a group run at all"
.to_string(),
);
}
if self
.group_key
.as_ref()
.is_some_and(|key| key.trim().is_empty())
{
return Some("a batch group key is a CEL expression and cannot be blank".to_string());
}
None
}
pub(crate) fn to_proto(&self, broadcast_output: bool) -> v1::TaskBatchConfig {
v1::TaskBatchConfig {
batch_max_size: saturating_i32(self.max_size),
batch_max_interval_ms: self
.max_interval
.map(|interval| i32::try_from(interval.as_millis()).unwrap_or(i32::MAX)),
batch_group_key: self.group_key.clone(),
batch_group_max_runs: self.group_max_runs.map(saturating_i32),
broadcast_output: Some(broadcast_output),
}
}
}
pub(crate) fn saturating_i32(value: u32) -> i32 {
i32::try_from(value).unwrap_or(i32::MAX)
}
#[cfg(test)]
mod tests {
use super::*;
use hatchet_proto::v1;
#[test]
fn a_batch_config_maps_to_the_registration_field() {
let proto = BatchConfig::max_size(10)
.max_interval(Duration::from_secs(2))
.group_key("input.tenant")
.group_max_runs(3)
.to_proto(false);
assert_eq!(
proto,
v1::TaskBatchConfig {
batch_max_size: 10,
batch_max_interval_ms: Some(2_000),
batch_group_key: Some("input.tenant".to_string()),
batch_group_max_runs: Some(3),
broadcast_output: Some(false),
}
);
}
#[test]
fn a_batch_config_sends_only_what_it_was_given() {
let proto = BatchConfig::max_size(4).to_proto(true);
assert_eq!(proto.batch_max_size, 4);
assert_eq!(proto.batch_max_interval_ms, None);
assert_eq!(proto.batch_group_key, None);
assert_eq!(proto.batch_group_max_runs, None);
assert_eq!(proto.broadcast_output, Some(true));
}
#[test]
fn a_batch_config_rejects_what_the_engine_would_read_as_nothing() {
for config in [
BatchConfig::max_size(0),
BatchConfig::max_size(1).max_interval(Duration::ZERO),
BatchConfig::max_size(1).max_interval(Duration::from_micros(999)),
BatchConfig::max_size(1).max_interval(Duration::from_secs(60 * 60 * 24 * 25)),
BatchConfig::max_size(1).group_max_runs(0),
BatchConfig::max_size(1).group_key(" "),
] {
assert!(config.invalid_reason().is_some(), "{config:?}");
}
assert!(
BatchConfig::max_size(1)
.max_interval(Duration::from_millis(1))
.group_key("input.tenant")
.group_max_runs(1)
.invalid_reason()
.is_none()
);
}
#[test]
fn a_batch_config_saturates_rather_than_wrapping() {
let proto = BatchConfig::max_size(u32::MAX)
.group_max_runs(u32::MAX)
.to_proto(false);
assert_eq!(proto.batch_max_size, i32::MAX);
assert_eq!(proto.batch_group_max_runs, Some(i32::MAX));
}
#[test]
fn concurrency_maps_expression_max_runs_and_strategy() {
let concurrency = Concurrency::expr("input.device_id")
.max_runs(1)
.strategy(ConcurrencyLimitStrategy::GroupRoundRobin);
assert_eq!(
concurrency.to_proto(),
v1::Concurrency {
expression: "input.device_id".to_string(),
max_runs: Some(1),
limit_strategy: Some(v1::ConcurrencyLimitStrategy::GroupRoundRobin as i32),
..Default::default()
}
);
}
#[test]
fn concurrency_max_runs_zero_is_invalid() {
let err = Concurrency::expr("input.user")
.max_runs(0)
.validate()
.unwrap_err();
assert!(err.contains("max_runs"), "{err}");
}
#[test]
fn concurrency_without_max_runs_or_with_a_positive_one_is_valid() {
assert!(Concurrency::expr("input.user").validate().is_ok());
assert!(
Concurrency::expr("input.user")
.max_runs(1)
.validate()
.is_ok()
);
}
#[test]
fn concurrency_leaves_unset_fields_to_the_engine_defaults() {
assert_eq!(
Concurrency::expr("input.user").to_proto(),
v1::Concurrency {
expression: "input.user".to_string(),
..Default::default()
}
);
}
#[test]
fn every_strategy_maps_to_its_proto_value() {
use ConcurrencyLimitStrategy::*;
for (ours, theirs) in [
(
CancelInProgress,
v1::ConcurrencyLimitStrategy::CancelInProgress,
),
(
GroupRoundRobin,
v1::ConcurrencyLimitStrategy::GroupRoundRobin,
),
(CancelNewest, v1::ConcurrencyLimitStrategy::CancelNewest),
] {
let proto = Concurrency::expr("x").strategy(ours).to_proto();
assert_eq!(proto.limit_strategy, Some(theirs as i32));
}
}
#[test]
fn concurrency_maps_the_name_tenant_scope_and_max_runs_expression() {
let concurrency = Concurrency::expr("input.tenant")
.name("per-tenant")
.tenant_scoped()
.max_runs_expression("input.limit");
assert_eq!(
concurrency.to_proto(),
v1::Concurrency {
expression: "input.tenant".to_string(),
name: Some("per-tenant".to_string()),
is_tenant_scoped: Some(true),
max_runs_expression: Some("input.limit".to_string()),
..Default::default()
}
);
}
#[test]
fn a_workflow_scoped_entry_sends_neither_the_tenant_flag_nor_a_name() {
let proto = Concurrency::expr("input.user").max_runs(2).to_proto();
assert_eq!(proto.name, None);
assert_eq!(proto.is_tenant_scoped, None);
assert_eq!(proto.max_runs_expression, None);
}
#[test]
fn a_tenant_scoped_entry_without_a_name_is_invalid() {
let err = Concurrency::expr("input.tenant")
.tenant_scoped()
.validate()
.unwrap_err();
assert!(err.contains("name"), "{err}");
}
#[test]
fn static_rate_limit_maps_key_and_units() {
assert_eq!(
RateLimit::new("github-api", 2).to_proto(),
v1::CreateTaskRateLimit {
key: "github-api".to_string(),
units: Some(2),
..Default::default()
}
);
}
#[test]
fn a_dynamic_rate_limit_maps_every_expression_and_the_window() {
let limit = RateLimit::dynamic("input.tenant")
.units_expr("input.cost")
.limit_expr("5")
.duration(RateLimitDuration::Minute);
assert_eq!(
limit.to_proto(),
v1::CreateTaskRateLimit {
key: "input.tenant".to_string(),
units: None,
key_expr: Some("input.tenant".to_string()),
units_expr: Some("input.cost".to_string()),
limit_values_expr: Some("5".to_string()),
duration: Some(v1::RateLimitDuration::Minute as i32),
}
);
}
#[test]
fn a_static_rate_limit_may_also_take_a_units_expression_and_a_window() {
let limit = RateLimit::new("github-api", 2)
.units_expr("input.cost")
.duration(RateLimitDuration::Hour);
let proto = limit.to_proto();
assert_eq!(proto.key, "github-api");
assert_eq!(proto.units, Some(2));
assert_eq!(proto.units_expr, Some("input.cost".to_string()));
assert_eq!(proto.duration, Some(v1::RateLimitDuration::Hour as i32));
assert_eq!(proto.key_expr, None);
}
#[test]
fn every_rate_limit_duration_maps_to_its_proto_value() {
use RateLimitDuration::*;
for (ours, theirs) in [
(Second, v1::RateLimitDuration::Second),
(Minute, v1::RateLimitDuration::Minute),
(Hour, v1::RateLimitDuration::Hour),
(Day, v1::RateLimitDuration::Day),
(Week, v1::RateLimitDuration::Week),
(Month, v1::RateLimitDuration::Month),
(Year, v1::RateLimitDuration::Year),
] {
assert_eq!(ours.to_proto(), theirs as i32);
}
}
#[test]
fn a_dynamic_rate_limit_without_a_units_expression_is_invalid() {
let reason = RateLimit::dynamic("input.tenant")
.limit_expr("5")
.validate()
.unwrap_err();
assert!(reason.contains("units_expr"), "{reason}");
}
#[test]
fn a_dynamic_rate_limit_without_a_limit_expression_is_invalid() {
let reason = RateLimit::dynamic("input.tenant").validate().unwrap_err();
assert!(reason.contains("limit_expr"), "{reason}");
}
#[test]
fn a_static_rate_limit_needs_no_limit_expression() {
assert!(RateLimit::new("github-api", 1).validate().is_ok());
}
#[test]
fn an_empty_static_key_is_invalid() {
let reason = RateLimit::new(" ", 1).validate().unwrap_err();
assert!(reason.contains("key"), "{reason}");
}
#[test]
fn an_empty_dynamic_key_expression_is_invalid() {
let reason = RateLimit::dynamic(" ")
.limit_expr("5")
.units_expr("1")
.validate()
.unwrap_err();
assert!(reason.contains("key"), "{reason}");
}
#[test]
fn required_string_label() {
assert_eq!(
DesiredLabel::eq("macos").required().to_proto(),
v1::DesiredWorkerLabels {
str_value: Some("macos".to_string()),
int_value: None,
required: Some(true),
comparator: Some(v1::WorkerLabelComparator::Equal as i32),
weight: None,
}
);
}
#[test]
fn weighted_integer_label() {
assert_eq!(
DesiredLabel::gte(8).weight(50).to_proto(),
v1::DesiredWorkerLabels {
str_value: None,
int_value: Some(8),
required: Some(false),
comparator: Some(v1::WorkerLabelComparator::GreaterThanOrEqual as i32),
weight: Some(50),
}
);
}
#[test]
fn every_comparator_maps_to_its_proto_value() {
use v1::WorkerLabelComparator as C;
for (label, comparator) in [
(DesiredLabel::eq(1), C::Equal),
(DesiredLabel::ne(1), C::NotEqual),
(DesiredLabel::gt(1), C::GreaterThan),
(DesiredLabel::gte(1), C::GreaterThanOrEqual),
(DesiredLabel::lt(1), C::LessThan),
(DesiredLabel::lte(1), C::LessThanOrEqual),
] {
assert_eq!(label.to_proto().comparator, Some(comparator as i32));
}
}
#[test]
fn priorities_are_one_to_three() {
assert_eq!(Priority::Low.to_proto(), 1);
assert_eq!(Priority::Medium.to_proto(), 2);
assert_eq!(Priority::High.to_proto(), 3);
}
#[test]
fn every_sticky_strategy_maps_to_its_proto_value() {
assert_eq!(
StickyStrategy::Soft.to_proto(),
v1::StickyStrategy::Soft as i32
);
assert_eq!(
StickyStrategy::Hard.to_proto(),
v1::StickyStrategy::Hard as i32
);
}
}