add configurable rate limit

Author: sethconve

README.md

@@ -163,6 +163,15 @@ Check out the [docstrings](./src/client/index.ts), but notable options include:
   develop your project, `testMode` is default **true**. You need to explicitly
   set this to `false` for the component to allow you to enqueue emails to
   artibrary addresses.
+- `rateLimitPerSecond`: The rate limit in requests per second for the Resend
+  API. Defaults to 2 requests per second, which is the default Resend rate
+  limit. If your Resend account has a higher rate limit (e.g., 100 requests per
+  second), set this value accordingly. For example:
+  ```ts
+  export const resend: Resend = new Resend(components.resend, {
+    rateLimitPerSecond: 100,
+  });
+  ```
 - `onEmailEvent`: Your email event callback, as outlined above! Check out the
   [docstrings](./src/client/index.ts) for details on the events that are
   emitted.

src/client/index.ts

@@ -46,6 +46,7 @@ function getDefaultConfig(): Config {
     initialBackoffMs: 30000,
     retryAttempts: 5,
     testMode: true,
+    rateLimitPerSecond: 2,
   };
 }
 
@@ -94,6 +95,14 @@ export type ResendOptions = {
       event: EmailEvent;
     }
   > | null;
+
+  /**
+   * The rate limit in requests per second for the Resend API.
+   * Defaults to 2 requests per second, which is the default Resend rate limit.
+   * If your Resend account has a higher rate limit (e.g., 100 requests per second),
+   * set this value accordingly.
+   */
+  rateLimitPerSecond?: number;
 };
 
 async function configToRuntimeConfig(
@@ -112,6 +121,7 @@ async function configToRuntimeConfig(
     initialBackoffMs: config.initialBackoffMs,
     retryAttempts: config.retryAttempts,
     testMode: config.testMode,
+    rateLimitPerSecond: config.rateLimitPerSecond,
     onEmailEvent: onEmailEvent
       ? { fnHandle: await createFunctionHandle(onEmailEvent) }
       : undefined,
@@ -225,6 +235,8 @@ export class Resend {
         options?.initialBackoffMs ?? defaultConfig.initialBackoffMs,
       retryAttempts: options?.retryAttempts ?? defaultConfig.retryAttempts,
       testMode: options?.testMode ?? defaultConfig.testMode,
+      rateLimitPerSecond:
+        options?.rateLimitPerSecond ?? defaultConfig.rateLimitPerSecond,
     };
     if (options?.onEmailEvent) {
       this.onEmailEvent = options.onEmailEvent;

src/component/lib.ts

@@ -34,10 +34,10 @@ const BASE_BATCH_DELAY = 1000;
 const BATCH_SIZE = 100;
 const EMAIL_POOL_SIZE = 4;
 const CALLBACK_POOL_SIZE = 4;
-const RESEND_ONE_CALL_EVERY_MS = 600; // Half the stated limit, but it keeps us sane.
 const FINALIZED_EMAIL_RETENTION_MS = 1000 * 60 * 60 * 24 * 7; // 7 days
 const FINALIZED_EPOCH = Number.MAX_SAFE_INTEGER;
 const ABANDONED_EMAIL_RETENTION_MS = 1000 * 60 * 60 * 24 * 30; // 30 days
+const DEFAULT_RATE_LIMIT_PER_SECOND = 2;
 
 const RESEND_TEST_EMAILS = ["delivered", "bounced", "complained"];
 
@@ -70,7 +70,7 @@ function getSegment(now: number) {
   return Math.floor(now / SEGMENT_MS);
 }
 
-// Four threads is more than enough, especially given the low rate limiting.
+// Four threads is more than enough for the email sending workpool.
 const emailPool = new Workpool(components.emailWorkpool, {
   maxParallelism: EMAIL_POOL_SIZE,
 });
@@ -81,14 +81,7 @@ const callbackPool = new Workpool(components.callbackWorkpool, {
 });
 
 // We rate limit our calls to the Resend API.
-// FUTURE -- make this rate configurable if an account ups its sending rate with Resend.
-const resendApiRateLimiter = new RateLimiter(components.rateLimiter, {
-  resendApi: {
-    kind: "fixed window",
-    period: RESEND_ONE_CALL_EVERY_MS,
-    rate: 1,
-  },
-});
+const resendApiRateLimiter = new RateLimiter(components.rateLimiter);
 
 // Periodic background job to clean up old emails that have already
 // been delivered, bounced, what have you.
@@ -443,7 +436,12 @@ export const makeBatch = internalMutation({
     }
 
     // Okay, let's calculate rate limiting as best we can globally in this distributed system.
-    const delay = await getDelay(ctx);
+    // Handle backward compatibility: old database records may not have rateLimitPerSecond.
+    // Use fallback to default (2 req/s) for migration safety.
+    const delay = await getDelay(
+      ctx,
+      options.rateLimitPerSecond ?? DEFAULT_RATE_LIMIT_PER_SECOND,
+    );
 
     // Give the batch to the workpool! It will call the Resend batch API
     // in a durable background action.
@@ -707,9 +705,23 @@ async function createResendBatchPayload(
 }
 
 const FIXED_WINDOW_DELAY = 100;
-async function getDelay(ctx: RunMutationCtx & RunQueryCtx): Promise<number> {
+async function getDelay(
+  ctx: RunMutationCtx & RunQueryCtx,
+  rateLimitPerSecond: number,
+): Promise<number> {
+  // Calculate the period in milliseconds based on the configured rate limit.
+  // We use a conservative approach: allow 1 request per period.
+  // For example, 100 requests/second = 10ms period, 2 requests/second = 500ms period.
+  // Ensure minimum period of 1ms to allow high rate limits.
+  const periodMs = Math.max(1, Math.floor(1000 / rateLimitPerSecond));
+
   const limit = await resendApiRateLimiter.limit(ctx, "resendApi", {
     reserve: true,
+    config: {
+      kind: "fixed window",
+      period: periodMs,
+      rate: 1,
+    },
   });
   //console.log(`RL: ${limit.ok} ${limit.retryAfter}`);
   const jitter = Math.random() * FIXED_WINDOW_DELAY;

src/component/setup.test.ts

@@ -155,6 +155,7 @@ export const createTestRuntimeConfig = (): RuntimeConfig => ({
   testMode: true,
   initialBackoffMs: 1000,
   retryAttempts: 3,
+  rateLimitPerSecond: 2,
 });
 
 export const setupTestLastOptions = (

src/component/shared.ts

@@ -37,6 +37,7 @@ export const vOptions = v.object({
   retryAttempts: v.number(),
   apiKey: v.string(),
   testMode: v.boolean(),
+  rateLimitPerSecond: v.optional(v.number()),
   onEmailEvent: v.optional(onEmailEvent),
 });