Effect API Rate Limit, Cache Control & Remove Experimental (#809)

* Update cusror rules

* Add rate limit support

* Per call effect cache config via context.cache

* Remove experimental for createEffect

Author: DZakh

.cursor/worktrees.json

@@ -1,3 +1,8 @@
 {
-  "setup-worktree": ["cd scenarios/test_codegen && pnpm install"]
+  "setup-worktree": [
+    "cd scenarios/test_codegen && pnpm install",
+    "pnpm codegen",
+    "pnpm rescript",
+    "pnpm ts:build"
+  ]
 }

codegenerator/cli/npm/envio/index.d.ts

@@ -4,6 +4,8 @@ export type {
   effectContext as EffectContext,
   effectArgs as EffectArgs,
   effectOptions as EffectOptions,
+  rateLimitDuration as RateLimitDuration,
+  rateLimit as RateLimit,
   blockEvent as BlockEvent,
   onBlockArgs as OnBlockArgs,
   onBlockOptions as OnBlockOptions,
@@ -13,6 +15,7 @@ export type { EffectCaller } from "./src/Types.ts";
 import type {
   effect as Effect,
   effectArgs as EffectArgs,
+  rateLimit as RateLimit,
 } from "./src/Envio.gen.ts";
 
 import { schema as bigDecimalSchema } from "./src/bindings/BigDecimal.gen.ts";
@@ -73,6 +76,33 @@ type Flatten<T> = T extends object
 // })
 // The behaviour is inspired by Sury code:
 // https://github.com/DZakh/sury/blob/551f8ee32c1af95320936d00c086e5fb337f59fa/packages/sury/src/S.d.ts#L344C1-L355C50
+export function createEffect<
+  IS,
+  OS,
+  I = UnknownToOutput<IS>,
+  O = UnknownToOutput<OS>,
+  // A hack to enforce that the inferred return type
+  // matches the output schema type
+  R extends O = O
+>(
+  options: {
+    /** The name of the effect. Used for logging and debugging. */
+    readonly name: string;
+    /** The input schema of the effect. */
+    readonly input: IS;
+    /** The output schema of the effect. */
+    readonly output: OS;
+    /** Rate limit for the effect. Set to false to disable or provide {calls: number, per: "second" | "minute"} to enable. */
+    readonly rateLimit: RateLimit;
+    /** Whether the effect should be cached. */
+    readonly cache?: boolean;
+  },
+  handler: (args: EffectArgs<I>) => Promise<R>
+): Effect<I, O>;
+
+/**
+ * @deprecated Use createEffect instead. The only difference is that rateLimit option becomes required. Set it to false to keep the same behaviour.
+ */
 export function experimental_createEffect<
   IS,
   OS,
@@ -89,6 +119,8 @@ export function experimental_createEffect<
     readonly input: IS;
     /** The output schema of the effect. */
     readonly output: OS;
+    /** Rate limit for the effect. Set to false to disable or provide {calls: number, per: "second" | "minute"} to enable. */
+    readonly rateLimit?: RateLimit;
     /** Whether the effect should be cached. */
     readonly cache?: boolean;
   },

codegenerator/cli/npm/envio/src/Envio.gen.ts

@@ -29,13 +29,34 @@ export type logger = $$logger;
 
 export type effect<input,output> = $$effect<input,output>;
 
+export type rateLimitDuration = "second" | "minute" | number;
+
+export type rateLimit = 
+    false
+  | { readonly calls: number; readonly per: rateLimitDuration };
+
+export type experimental_effectOptions<input,output> = {
+  /** The name of the effect. Used for logging and debugging. */
+  readonly name: string; 
+  /** The input schema of the effect. */
+  readonly input: RescriptSchema_S_t<input>; 
+  /** The output schema of the effect. */
+  readonly output: RescriptSchema_S_t<output>; 
+  /** Rate limit for the effect. Set to false to disable or provide {calls: number, per: "second" | "minute"} to enable. */
+  readonly rateLimit?: rateLimit; 
+  /** Whether the effect should be cached. */
+  readonly cache?: boolean
+};
+
 export type effectOptions<input,output> = {
   /** The name of the effect. Used for logging and debugging. */
   readonly name: string; 
   /** The input schema of the effect. */
   readonly input: RescriptSchema_S_t<input>; 
   /** The output schema of the effect. */
   readonly output: RescriptSchema_S_t<output>; 
+  /** Rate limit for the effect. Set to false to disable or provide {calls: number, per: "second" | "minute"} to enable. */
+  readonly rateLimit: rateLimit; 
   /** Whether the effect should be cached. */
   readonly cache?: boolean
 };

codegenerator/cli/npm/envio/src/Envio.res

@@ -32,6 +32,28 @@ type logger = {
 @@warning("-30") // Duplicated type names (input)
 @genType.import(("./Types.ts", "Effect"))
 type rec effect<'input, 'output>
+@genType @unboxed
+and rateLimitDuration =
+  | @as("second") Second
+  | @as("minute") Minute
+  | Milliseconds(int)
+@genType @unboxed
+and rateLimit =
+  | @as(false) Disable
+  | Enable({calls: int, per: rateLimitDuration})
+@genType
+and experimental_effectOptions<'input, 'output> = {
+  /** The name of the effect. Used for logging and debugging. */
+  name: string,
+  /** The input schema of the effect. */
+  input: S.t<'input>,
+  /** The output schema of the effect. */
+  output: S.t<'output>,
+  /** Rate limit for the effect. Set to false to disable or provide {calls: number, per: "second" | "minute"} to enable. */
+  rateLimit?: rateLimit,
+  /** Whether the effect should be cached. */
+  cache?: bool,
+}
 @genType
 and effectOptions<'input, 'output> = {
   /** The name of the effect. Used for logging and debugging. */
@@ -40,13 +62,16 @@ and effectOptions<'input, 'output> = {
   input: S.t<'input>,
   /** The output schema of the effect. */
   output: S.t<'output>,
+  /** Rate limit for the effect. Set to false to disable or provide {calls: number, per: "second" | "minute"} to enable. */
+  rateLimit: rateLimit,
   /** Whether the effect should be cached. */
   cache?: bool,
 }
 @genType.import(("./Types.ts", "EffectContext"))
 and effectContext = {
   log: logger,
   effect: 'input 'output. (effect<'input, 'output>, 'input) => promise<'output>,
+  mutable cache: bool,
 }
 @genType
 and effectArgs<'input> = {
@@ -55,12 +80,23 @@ and effectArgs<'input> = {
 }
 @@warning("+30")
 
-let experimental_createEffect = (
+let durationToMs = (duration: rateLimitDuration) =>
+  switch duration {
+  | Second => 1000
+  | Minute => 60000
+  | Milliseconds(ms) => ms
+  }
+
+let createEffect = (
   options: effectOptions<'input, 'output>,
   handler: effectArgs<'input> => promise<'output>,
 ) => {
   let outputSchema =
     S.schema(_ => options.output)->(Utils.magic: S.t<S.t<'output>> => S.t<Internal.effectOutput>)
+  let itemSchema = S.schema((s): Internal.effectCacheItem => {
+    id: s.matches(S.string),
+    output: s.matches(outputSchema),
+  })
   {
     name: options.name,
     handler: handler->(
@@ -78,20 +114,48 @@ let experimental_createEffect = (
       Utils.magic: S.t<S.t<'input>> => S.t<Internal.effectInput>
     ),
     output: outputSchema,
-    cache: switch options.cache {
-    | Some(true) =>
-      let itemSchema = S.schema((s): Internal.effectCacheItem => {
-        id: s.matches(S.string),
-        output: s.matches(outputSchema),
-      })
+    storageMeta: {
+      table: Internal.makeCacheTable(~effectName=options.name),
+      outputSchema,
+      itemSchema,
+    },
+    defaultShouldCache: switch options.cache {
+    | Some(true) => true
+    | _ => false
+    },
+    rateLimit: switch options.rateLimit {
+    | Disable => None
+    | Enable({calls, per}) =>
       Some({
-        table: Internal.makeCacheTable(~effectName=options.name),
-        outputSchema,
-        itemSchema,
+        callsPerDuration: calls,
+        durationMs: per->durationToMs,
+        availableCalls: calls,
+        windowStartTime: Js.Date.now(),
+        queueCount: 0,
+        nextWindowPromise: None,
       })
-    | None
-    | Some(false) =>
-      None
     },
   }->(Utils.magic: Internal.effect => effect<'input, 'output>)
 }
+
+@deprecated(
+  "Use createEffect instead. The only difference is that rateLimit option becomes required. Set it to false to keep the same behaviour."
+)
+let experimental_createEffect = (
+  options: experimental_effectOptions<'input, 'output>,
+  handler: effectArgs<'input> => promise<'output>,
+) => {
+  createEffect(
+    {
+      name: options.name,
+      input: options.input,
+      output: options.output,
+      rateLimit: switch options.rateLimit {
+      | Some(rateLimit) => rateLimit
+      | None => Disable
+      },
+      cache: ?options.cache,
+    },
+    handler,
+  )
+}

codegenerator/cli/npm/envio/src/Internal.res

@@ -281,27 +281,37 @@ let makeEnumConfig = (~name, ~variants) => {
 
 type effectInput
 type effectOutput
-type effectContext
+type effectContext = private {mutable cache: bool}
 type effectArgs = {
   input: effectInput,
   context: effectContext,
   cacheKey: string,
 }
 type effectCacheItem = {id: string, output: effectOutput}
-type effectCacheMeta = {
+type effectCacheStorageMeta = {
   itemSchema: S.t<effectCacheItem>,
   outputSchema: S.t<effectOutput>,
   table: Table.table,
 }
+type rateLimitState = {
+  callsPerDuration: int,
+  durationMs: int,
+  mutable availableCalls: int,
+  mutable windowStartTime: float,
+  mutable queueCount: int,
+  mutable nextWindowPromise: option<promise<unit>>,
+}
 type effect = {
   name: string,
   handler: effectArgs => promise<effectOutput>,
-  cache: option<effectCacheMeta>,
+  storageMeta: effectCacheStorageMeta,
+  defaultShouldCache: bool,
   output: S.t<effectOutput>,
   input: S.t<effectInput>,
   // The number of functions that are currently running.
   mutable activeCallsCount: int,
   mutable prevCallStartTimerRef: Hrtime.timeRef,
+  rateLimit: option<rateLimitState>,
 }
 let cacheTablePrefix = "envio_effect_"
 let cacheOutputSchema = S.json(~validate=false)->(Utils.magic: S.t<Js.Json.t> => S.t<effectOutput>)

codegenerator/cli/npm/envio/src/PgStorage.res

@@ -789,13 +789,7 @@ let make = (
     ~items: array<Internal.effectCacheItem>,
     ~initialize: bool,
   ) => {
-    let {table, itemSchema} = switch effect.cache {
-    | Some(cacheMeta) => cacheMeta
-    | None =>
-      Js.Exn.raiseError(
-        `Failed to set effect cache for "${effect.name}". Effect has no cache enabled.`,
-      )
-    }
+    let {table, itemSchema} = effect.storageMeta
 
     if initialize {
       let _ =

codegenerator/cli/npm/envio/src/Prometheus.res

@@ -646,6 +646,18 @@ module EffectCacheInvalidationsCount = {
   }
 }
 
+module EffectQueueCount = {
+  let gauge = SafeGauge.makeOrThrow(
+    ~name="envio_effect_queue_count",
+    ~help="The number of effect calls waiting in the rate limit queue.",
+    ~labelSchema=effectLabelsSchema,
+  )
+
+  let set = (~count, ~effectName) => {
+    gauge->SafeGauge.handleInt(~labels=effectName, ~value=count)
+  }
+}
+
 module StorageLoad = {
   let operationLabelsSchema = S.object(s => s.field("operation", S.string))
 

codegenerator/cli/npm/envio/src/Types.ts

@@ -44,6 +44,11 @@ export type EffectContext = {
    * Define a new Effect using createEffect outside of the handler.
    */
   readonly effect: EffectCaller;
+  /**
+   * Whether to cache the result of the effect. Defaults to the effect's cache configuration.
+   * Set to false to disable caching for this specific call.
+   */
+  cache: boolean;
 };
 
 export type GenericContractRegister<Args> = (