Skip to main content

hatchet_client/
rate_limits.rs

1//! Raising a tenant's rate-limit allowances.
2
3use hatchet_proto::root::{PutRateLimitRequest, RateLimitDuration as WireDuration};
4
5use crate::declare::{RateLimitDuration, saturating_i32};
6use crate::error::{Error, Result};
7use crate::{Client, retry};
8
9/// Creates and raises the tenant's rate limits.
10///
11/// Get one from [`Client::rate_limits`]. A *static*
12/// [`RateLimit`](crate::RateLimit) on a task spends an allowance that has to
13/// exist first, and this is what creates it — the official Python SDK's
14/// `rate_limits().put(..)` over the same v0 `WorkflowService/PutRateLimit`
15/// call (`sdks/python/hatchet_sdk/features/rate_limits.py:31-65`). A
16/// *dynamic* rate limit carries its own allowance in
17/// [`limit_expr`](crate::RateLimit::limit_expr) and needs nothing here.
18///
19/// **Order matters.** A task that declares a static
20/// [`RateLimit`](crate::RateLimit) whose key
21/// was never [`put`](RateLimitsClient::put) fails registration with a bare
22/// `Internal` error and no further detail — observed against both
23/// supported engine versions. Put the key before registering the worker
24/// that uses it:
25///
26/// ```no_run
27/// # async fn example(client: hatchet_client::Client) -> hatchet_client::Result<()> {
28/// use hatchet_client::{RateLimit, RateLimitDuration, TaskBuilder};
29///
30/// // 1. Create (or raise) the allowance first.
31/// client
32///     .rate_limits()
33///     .put("github-api", 5_000, RateLimitDuration::Hour)
34///     .await?;
35///
36/// // 2. Only now register a task that spends it.
37/// let call_api = TaskBuilder::<(), ()>::new("call-api")
38///     .rate_limit(RateLimit::new("github-api", 1))
39///     .handler(|_ctx, _input| async { Ok(()) });
40/// client.worker("api-worker").register(&call_api).build().await?;
41/// # Ok(())
42/// # }
43/// ```
44///
45/// Keys are **tenant-global and not namespaced**: the client's namespace
46/// configured with [`ClientBuilder::namespace`](crate::ClientBuilder::namespace)
47/// is not applied here, matching the official Python SDK. Two environments
48/// sharing a tenant share these keys.
49#[derive(Clone, Debug)]
50pub struct RateLimitsClient {
51    client: Client,
52}
53
54impl RateLimitsClient {
55    pub(crate) fn new(client: Client) -> Self {
56        Self { client }
57    }
58
59    /// Sets the allowance for `key` to `limit` per `duration`, creating it
60    /// if it is new and replacing whatever it was before.
61    ///
62    /// `key` is not namespaced; see the [`RateLimitsClient`] docs.
63    ///
64    /// # Errors
65    ///
66    /// [`Error::InvalidArgument`](crate::Error::InvalidArgument) when `key`
67    /// is empty or all whitespace — checked before any call is made, rather
68    /// than left to the engine's own `InvalidArgument`. Otherwise
69    /// [`Error::Grpc`](crate::Error::Grpc) when the call fails.
70    pub async fn put(
71        &self,
72        key: impl AsRef<str>,
73        limit: u32,
74        duration: RateLimitDuration,
75    ) -> Result<()> {
76        let key = key.as_ref();
77        if key.trim().is_empty() {
78            return Err(Error::InvalidArgument(
79                "a rate limit key must not be empty".to_string(),
80            ));
81        }
82        let request = PutRateLimitRequest {
83            key: key.to_string(),
84            limit: saturating_i32(limit),
85            duration: wire_duration(duration) as i32,
86        };
87        retry::unary(|| {
88            let mut workflows = self.client.workflows_grpc();
89            let request = retry::timed(request.clone());
90            async move { workflows.put_rate_limit(request).await }
91        })
92        .await?;
93        Ok(())
94    }
95}
96
97/// The v0 `WorkflowService` has its own `RateLimitDuration` enum, distinct
98/// from the v1 one a declaration uses, with the same values in the same
99/// order.
100fn wire_duration(duration: RateLimitDuration) -> WireDuration {
101    match duration {
102        RateLimitDuration::Second => WireDuration::Second,
103        RateLimitDuration::Minute => WireDuration::Minute,
104        RateLimitDuration::Hour => WireDuration::Hour,
105        RateLimitDuration::Day => WireDuration::Day,
106        RateLimitDuration::Week => WireDuration::Week,
107        RateLimitDuration::Month => WireDuration::Month,
108        RateLimitDuration::Year => WireDuration::Year,
109    }
110}