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}