docs: add documentation for rate limiting

Add a new guide for rate limiting tasks and update the introduction, task overview, and sidebar to include the new functionality. This allows users to control run execution frequency using static or dynamic keys.

Author: aquiveal

docs/docs.json

@@ -82,6 +82,7 @@
                 ]
               },
               "queue-concurrency",
+              "rate-limiting",
               "versioning",
               "machines",
               "idempotency",

docs/introduction.mdx

@@ -74,6 +74,9 @@ We provide everything you need to build and manage background tasks: a CLI and S
   <Card title="Concurrency & Queues" icon="line-height" href="/queue-concurrency" color="#D946EF">
     Configure what you want to happen when there is more than one run at a time.
   </Card>
+  <Card title="Rate Limiting" icon="gauge-high" href="/rate-limiting" color="#F59E0B">
+    Control how many runs can execute within a specific time window.
+  </Card>
   <Card
     title="Wait for token (human-in-the-loop)"
     icon="hand"

docs/tasks/overview.mdx

@@ -100,7 +100,7 @@ It's also worth mentioning that you can [retry a block of code](/errors-retrying
 
 ### `queue` options
 
-Queues allow you to control the concurrency of your tasks. This allows you to have one-at-a-time execution and parallel executions. There are also more advanced techniques like having different concurrencies for different sets of your users. For more information read [the concurrency & queues guide](/queue-concurrency).
+Queues allow you to control the concurrency of your tasks. This allows you to have one-at-a-time execution and parallel executions. There are also more advanced techniques like having different concurrencies for different sets of your users. For more information read [the concurrency, queues & rate limiting guide](/queue-concurrency).
 
 ```ts /trigger/one-at-a-time.ts
 export const oneAtATime = task({
@@ -114,6 +114,31 @@ export const oneAtATime = task({
 });
 ```
 
+### `rateLimits` options
+
+Rate limits allow you to control how many runs can execute within a specific time window. You can define both static and dynamic rate limits. For more information read [the rate limiting guide](/rate-limiting).
+
+```ts /trigger/rate-limited.ts
+export const rateLimitedTask = task({
+  id: "rate-limited-task",
+  rateLimits: [
+    {
+      staticKey: "my-api",
+      limit: 100,
+      window: 60, // 100 runs per 60 seconds
+    },
+    {
+      dynamicKey: "payload.userId",
+      limit: 10,
+      window: 60, // 10 runs per 60 seconds per user
+    }
+  ],
+  run: async (payload: any, { ctx }) => {
+    //...
+  },
+});
+```
+
 ### `machine` options
 
 Some tasks require more vCPUs or GBs of RAM. You can specify these requirements in the `machine` field. For more information read [the machines guide](/machines).

docs/writing-tasks-introduction.mdx

@@ -16,6 +16,7 @@ Before digging deeper into the details of writing tasks, you should read the [fu
 | [Errors & retrying](/errors-retrying)        | How to deal with errors and write reliable tasks.                                                   |
 | [Wait](/wait)                                | Wait for periods of time or for external events to occur before continuing.                         |
 | [Concurrency & Queues](/queue-concurrency)   | Configure what you want to happen when there is more than one run at a time.                        |
+| [Rate Limiting](/rate-limiting)              | Control how many runs can execute within a specific time window.                                    |
 | [Realtime notifications](/realtime/overview) | Send realtime notifications from your task that you can subscribe to from your backend or frontend. |
 | [Versioning](/versioning)                    | How versioning works.                                                                               |
 | [Machines](/machines)                        | Configure the CPU and RAM of the machine your task runs on                                          |