voltaire-effect 0.2.23

package/src/services/RateLimiter/DefaultRateLimiter.ts

@@ -0,0 +1,226 @@
+/**
+ * @fileoverview Default implementation of RateLimiterService.
+ *
+ * @module DefaultRateLimiter
+ * @since 0.0.1
+ *
+ * @description
+ * Provides the default implementation layer for RateLimiterService.
+ * Uses Effect's built-in RateLimiter for token-bucket or fixed-window rate limiting.
+ *
+ * @see {@link RateLimiterService} - The service interface
+ */
+
+import * as Effect from "effect/Effect";
+import { compose } from "effect/Function";
+import * as Layer from "effect/Layer";
+import * as RateLimiter from "effect/RateLimiter";
+import {
+	RateLimitError,
+	type RateLimiterConfig,
+	RateLimiterService,
+	type RateLimiterShape,
+} from "./RateLimiterService.js";
+
+const resolveInterval = (
+	interval?: RateLimiter.RateLimiter.Options["interval"],
+	window?: RateLimiter.RateLimiter.Options["interval"],
+) => {
+	const resolved = interval ?? window;
+	if (!resolved) {
+		throw new Error("RateLimiter config requires an interval/window value");
+	}
+	return resolved;
+};
+
+/**
+ * Creates a RateLimiterShape from configuration.
+ * This is the core factory that creates the rate limiting infrastructure.
+ *
+ * @internal
+ */
+const makeRateLimiterShape = (
+	config: RateLimiterConfig,
+	globalLimiter: RateLimiter.RateLimiter | undefined,
+	methodLimiters: Map<string, RateLimiter.RateLimiter>,
+): RateLimiterShape => {
+	const behavior = config.behavior ?? config.onExceeded ?? "delay";
+
+	const getLimiter = (method: string) => methodLimiters.get(method);
+	const getGlobalLimiter = () => globalLimiter;
+
+	const consume = (method: string, cost = 1) =>
+		Effect.gen(function* () {
+			const methodLimiter = methodLimiters.get(method);
+
+			if (methodLimiter) {
+				if (behavior === "fail") {
+					const result = yield* methodLimiter(Effect.void).pipe(
+						RateLimiter.withCost(cost),
+						Effect.timeout(0),
+						Effect.option,
+					);
+					if (result._tag === "None") {
+						return yield* Effect.fail(
+							new RateLimitError({
+								method,
+								message: `Rate limit exceeded for method: ${method}`,
+							}),
+						);
+					}
+				} else {
+					yield* methodLimiter(Effect.void).pipe(RateLimiter.withCost(cost));
+				}
+			}
+
+			if (globalLimiter) {
+				if (behavior === "fail") {
+					const result = yield* globalLimiter(Effect.void).pipe(
+						RateLimiter.withCost(cost),
+						Effect.timeout(0),
+						Effect.option,
+					);
+					if (result._tag === "None") {
+						return yield* Effect.fail(
+							new RateLimitError({
+								method,
+								message: `Global rate limit exceeded for method: ${method}`,
+							}),
+						);
+					}
+				} else {
+					yield* globalLimiter(Effect.void).pipe(RateLimiter.withCost(cost));
+				}
+			}
+		});
+
+	const withRateLimit = <A, E, R>(
+		method: string,
+		effect: Effect.Effect<A, E, R>,
+	): Effect.Effect<A, E | RateLimitError, R> => {
+		const methodLimiter = methodLimiters.get(method);
+
+		if (behavior === "fail") {
+			return Effect.gen(function* () {
+				yield* consume(method);
+				return yield* effect;
+			});
+		}
+
+		let rateLimited = effect;
+		if (methodLimiter && globalLimiter) {
+			rateLimited = compose(methodLimiter, globalLimiter)(effect);
+		} else if (methodLimiter) {
+			rateLimited = methodLimiter(effect);
+		} else if (globalLimiter) {
+			rateLimited = globalLimiter(effect);
+		}
+
+		return rateLimited as Effect.Effect<A, E | RateLimitError, R>;
+	};
+
+	return {
+		withRateLimit,
+		consume,
+		getLimiter,
+		getGlobalLimiter,
+		config,
+	};
+};
+
+/**
+ * Creates a scoped effect that builds the rate limiter infrastructure.
+ *
+ * @since 0.0.1
+ */
+export const makeRateLimiter = (config: RateLimiterConfig) =>
+	Effect.gen(function* () {
+		const globalLimiter = config.global
+			? yield* RateLimiter.make({
+					limit: config.global.limit,
+					interval: resolveInterval(
+						config.global.interval,
+						config.global.window,
+					),
+					algorithm: config.global.algorithm,
+				})
+			: undefined;
+
+		const methodLimiters = new Map<string, RateLimiter.RateLimiter>();
+
+		if (config.methods) {
+			for (const [method, opts] of Object.entries(config.methods)) {
+				const limiter = yield* RateLimiter.make({
+					limit: opts.limit,
+					interval: resolveInterval(opts.interval, opts.window),
+					algorithm: opts.algorithm,
+				});
+				methodLimiters.set(method, limiter);
+			}
+		}
+
+		return makeRateLimiterShape(config, globalLimiter, methodLimiters);
+	});
+
+/**
+ * Default implementation of the rate limiter layer.
+ *
+ * @description
+ * Provides a concrete implementation of RateLimiterService that:
+ * - Supports global rate limits across all methods
+ * - Supports per-method rate limits
+ * - Configurable "delay" or "fail" behavior when limits exceeded
+ * - Uses Effect's built-in RateLimiter (token-bucket or fixed-window)
+ *
+ * @since 0.0.1
+ *
+ * @example Basic global limit
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { DefaultRateLimiter, RateLimiterService } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const rateLimiter = yield* RateLimiterService
+ *   yield* rateLimiter.consume("eth_call")
+ * }).pipe(
+ *   Effect.scoped,
+ *   Effect.provide(DefaultRateLimiter({ global: { limit: 10, interval: "1 seconds" } }))
+ * )
+ * ```
+ *
+ * @example Per-method limits with fail behavior
+ * ```typescript
+ * const RateLimited = DefaultRateLimiter({
+ *   methods: {
+ *     "eth_getLogs": { limit: 5, interval: "1 seconds" },
+ *     "eth_call": { limit: 50, interval: "1 seconds" }
+ *   },
+ *   behavior: "fail"
+ * })
+ * ```
+ *
+ * @see {@link RateLimiterService} - The service interface
+ * @see {@link RateLimitError} - Error when limit exceeded with "fail" behavior
+ */
+export const DefaultRateLimiter = (
+	config: RateLimiterConfig,
+): Layer.Layer<RateLimiterService> =>
+	Layer.scoped(RateLimiterService, makeRateLimiter(config));
+
+/**
+ * A no-op rate limiter that doesn't actually limit anything.
+ * Useful for testing or when rate limiting should be disabled.
+ *
+ * @since 0.0.1
+ */
+export const NoopRateLimiter: Layer.Layer<RateLimiterService> = Layer.succeed(
+	RateLimiterService,
+	{
+		withRateLimit: <A, E, R>(_method: string, effect: Effect.Effect<A, E, R>) =>
+			effect as Effect.Effect<A, E | RateLimitError, R>,
+		consume: () => Effect.void,
+		getLimiter: () => undefined,
+		getGlobalLimiter: () => undefined,
+		config: {},
+	},
+);

package/src/services/RateLimiter/RateLimiter.test.ts

@@ -0,0 +1,181 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import {
+	DefaultRateLimiter,
+	NoopRateLimiter,
+	RateLimitError,
+	RateLimiterService,
+} from "./index.js";
+
+describe("RateLimiterService", () => {
+	describe("DefaultRateLimiter", () => {
+		it.scoped("applies global rate limit with delay behavior", () =>
+			Effect.gen(function* () {
+				const rateLimiter = yield* RateLimiterService;
+
+				let callCount = 0;
+				const incrementEffect = Effect.sync(() => {
+					callCount++;
+					return callCount;
+				});
+
+				const result1 = yield* rateLimiter.withRateLimit(
+					"eth_call",
+					incrementEffect,
+				);
+				const result2 = yield* rateLimiter.withRateLimit(
+					"eth_call",
+					incrementEffect,
+				);
+
+				expect(result1).toBe(1);
+				expect(result2).toBe(2);
+				expect(callCount).toBe(2);
+			}).pipe(
+				Effect.provide(
+					DefaultRateLimiter({ global: { limit: 10, interval: "1 seconds" } }),
+				),
+			),
+		);
+
+		it.scoped("applies per-method rate limits", () =>
+			Effect.gen(function* () {
+				const rateLimiter = yield* RateLimiterService;
+
+				expect(rateLimiter.getLimiter("eth_call")).toBeDefined();
+				expect(rateLimiter.getLimiter("eth_getLogs")).toBeDefined();
+				expect(rateLimiter.getLimiter("eth_blockNumber")).toBeUndefined();
+				expect(rateLimiter.getGlobalLimiter()).toBeUndefined();
+			}).pipe(
+				Effect.provide(
+					DefaultRateLimiter({
+						methods: {
+							eth_call: { limit: 50, interval: "1 seconds" },
+							eth_getLogs: { limit: 5, interval: "1 seconds" },
+						},
+					}),
+				),
+			),
+		);
+
+		it.scoped("combines global and per-method limits", () =>
+			Effect.gen(function* () {
+				const rateLimiter = yield* RateLimiterService;
+
+				expect(rateLimiter.getGlobalLimiter()).toBeDefined();
+				expect(rateLimiter.getLimiter("eth_call")).toBeDefined();
+			}).pipe(
+				Effect.provide(
+					DefaultRateLimiter({
+						global: { limit: 100, interval: "1 seconds" },
+						methods: {
+							eth_call: { limit: 50, interval: "1 seconds" },
+						},
+					}),
+				),
+			),
+		);
+
+		it.scoped("fails immediately with fail behavior when limit exceeded", () =>
+			Effect.gen(function* () {
+				const rateLimiter = yield* RateLimiterService;
+
+				yield* rateLimiter.consume("eth_call");
+
+				const result = yield* rateLimiter.consume("eth_call").pipe(Effect.flip);
+
+				expect(result).toBeInstanceOf(RateLimitError);
+				expect(result.method).toBe("eth_call");
+			}).pipe(
+				Effect.provide(
+					DefaultRateLimiter({
+						global: { limit: 1, interval: "1 seconds" },
+						behavior: "fail",
+					}),
+				),
+			),
+		);
+
+		it.scoped("exposes config", () =>
+			Effect.gen(function* () {
+				const rateLimiter = yield* RateLimiterService;
+
+				expect(rateLimiter.config).toEqual({
+					global: { limit: 10, interval: "1 seconds" },
+					behavior: "fail",
+				});
+			}).pipe(
+				Effect.provide(
+					DefaultRateLimiter({
+						global: { limit: 10, interval: "1 seconds" },
+						behavior: "fail",
+					}),
+				),
+			),
+		);
+
+		it.scoped("consume respects cost parameter", () =>
+			Effect.gen(function* () {
+				const rateLimiter = yield* RateLimiterService;
+
+				yield* rateLimiter.consume("eth_call", 5);
+
+				const result = yield* rateLimiter
+					.consume("eth_call", 6)
+					.pipe(Effect.flip);
+
+				expect(result).toBeInstanceOf(RateLimitError);
+			}).pipe(
+				Effect.provide(
+					DefaultRateLimiter({
+						global: { limit: 10, interval: "1 seconds" },
+						behavior: "fail",
+					}),
+				),
+			),
+		);
+	});
+
+	describe("NoopRateLimiter", () => {
+		it.effect("does not limit anything", () =>
+			Effect.gen(function* () {
+				const rateLimiter = yield* RateLimiterService;
+
+				let callCount = 0;
+				for (let i = 0; i < 100; i++) {
+					yield* rateLimiter.withRateLimit(
+						"eth_call",
+						Effect.sync(() => callCount++),
+					);
+				}
+
+				expect(callCount).toBe(100);
+				expect(rateLimiter.getLimiter("eth_call")).toBeUndefined();
+				expect(rateLimiter.getGlobalLimiter()).toBeUndefined();
+			}).pipe(Effect.provide(NoopRateLimiter)),
+		);
+
+		it.effect("consume never fails", () =>
+			Effect.gen(function* () {
+				const rateLimiter = yield* RateLimiterService;
+
+				for (let i = 0; i < 100; i++) {
+					yield* rateLimiter.consume("eth_call");
+				}
+			}).pipe(Effect.provide(NoopRateLimiter)),
+		);
+	});
+
+	describe("RateLimitError", () => {
+		it("has correct tag", () => {
+			const error = new RateLimitError({
+				method: "eth_call",
+				message: "Rate limit exceeded",
+			});
+
+			expect(error._tag).toBe("RateLimitError");
+			expect(error.method).toBe("eth_call");
+			expect(error.message).toBe("Rate limit exceeded");
+		});
+	});
+});

package/src/services/RateLimiter/RateLimiterService.ts

@@ -0,0 +1,208 @@
+/**
+ * @fileoverview RateLimiter service definition for RPC rate limiting.
+ *
+ * @module RateLimiterService
+ * @since 0.0.1
+ *
+ * @description
+ * The RateLimiterService provides rate limiting for RPC calls to Ethereum nodes.
+ * It supports per-method and global rate limits, with configurable behavior
+ * when limits are exceeded (delay or fail).
+ *
+ * @see {@link DefaultRateLimiter} - The live implementation layer
+ */
+
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import type * as Effect from "effect/Effect";
+import type * as RateLimiter from "effect/RateLimiter";
+import type * as Scope from "effect/Scope";
+
+/**
+ * Error thrown when rate limit is exceeded and behavior is set to "fail".
+ *
+ * @since 0.0.1
+ */
+export class RateLimitError extends Data.TaggedError("RateLimitError")<{
+	readonly method: string;
+	readonly message: string;
+}> {}
+
+/**
+ * Behavior when rate limit is exceeded.
+ * - "delay": Wait until capacity is available (default)
+ * - "fail": Immediately fail with RateLimitError
+ *
+ * @since 0.0.1
+ */
+export type RateLimitBehavior = "delay" | "fail";
+
+type RateLimiterWindow = {
+	/**
+	 * Interval between allowed requests.
+	 * Alias: `window` for consistency with experimental RateLimiter APIs.
+	 */
+	readonly interval?: RateLimiter.RateLimiter.Options["interval"];
+	/**
+	 * Alias for `interval`.
+	 */
+	readonly window?: RateLimiter.RateLimiter.Options["interval"];
+};
+
+type RateLimiterRule = RateLimiterWindow & {
+	readonly limit: number;
+	readonly algorithm?: RateLimiter.RateLimiter.Options["algorithm"];
+};
+
+/**
+ * Configuration for rate limiting.
+ *
+ * @since 0.0.1
+ */
+export type RateLimiterConfig = {
+	/**
+	 * Global rate limit (requests per interval).
+	 * Applied to all methods.
+	 */
+	readonly global?: RateLimiterRule;
+
+	/**
+	 * Per-method rate limits.
+	 * Keys are RPC method names (e.g., "eth_call", "eth_getLogs").
+	 */
+	readonly methods?: Record<string, RateLimiterRule>;
+
+	/**
+	 * Behavior when rate limit is exceeded.
+	 * @default "delay"
+	 */
+	readonly behavior?: RateLimitBehavior;
+
+	/**
+	 * Alias for behavior when rate limit is exceeded.
+	 * @default "delay"
+	 */
+	readonly onExceeded?: RateLimitBehavior;
+};
+
+/**
+ * Shape of the rate limiter service.
+ *
+ * @since 0.0.1
+ */
+export type RateLimiterShape = {
+	/**
+	 * Wraps an effect with rate limiting for a specific method.
+	 *
+	 * @param method - The RPC method name
+	 * @param effect - The effect to rate limit
+	 * @returns The rate-limited effect
+	 */
+	readonly withRateLimit: <A, E, R>(
+		method: string,
+		effect: Effect.Effect<A, E, R>,
+	) => Effect.Effect<A, E | RateLimitError, R>;
+
+	/**
+	 * Consumes rate limit capacity for a method.
+	 * Use this before making an RPC call when you want explicit control.
+	 *
+	 * @param method - The RPC method name
+	 * @param cost - Optional cost (default: 1)
+	 * @returns Effect that resolves when capacity is available (or fails)
+	 */
+	readonly consume: (
+		method: string,
+		cost?: number,
+	) => Effect.Effect<void, RateLimitError>;
+
+	/**
+	 * Gets the underlying rate limiter for a method.
+	 * Returns undefined if no limiter is configured for the method.
+	 *
+	 * @param method - The RPC method name
+	 */
+	readonly getLimiter: (method: string) => RateLimiter.RateLimiter | undefined;
+
+	/**
+	 * Gets the global rate limiter.
+	 * Returns undefined if no global limiter is configured.
+	 */
+	readonly getGlobalLimiter: () => RateLimiter.RateLimiter | undefined;
+
+	/**
+	 * The current configuration.
+	 */
+	readonly config: RateLimiterConfig;
+};
+
+/**
+ * RateLimiter service for RPC rate limiting.
+ *
+ * @description
+ * Provides methods for rate limiting RPC calls to Ethereum nodes.
+ * Supports both global and per-method rate limits.
+ *
+ * @since 0.0.1
+ *
+ * @example Basic usage with withRateLimit
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { RateLimiterService, DefaultRateLimiter } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const rateLimiter = yield* RateLimiterService
+ *   const transport = yield* TransportService
+ *
+ *   // Automatically rate-limited
+ *   return yield* rateLimiter.withRateLimit(
+ *     "eth_call",
+ *     transport.request("eth_call", params)
+ *   )
+ * }).pipe(
+ *   Effect.scoped,
+ *   Effect.provide(DefaultRateLimiter({ global: { limit: 10, interval: "1 seconds" } }))
+ * )
+ * ```
+ *
+ * @example Manual consume pattern
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const rateLimiter = yield* RateLimiterService
+ *   const transport = yield* TransportService
+ *
+ *   // Manual rate limit check
+ *   yield* rateLimiter.consume("eth_call")
+ *   return yield* transport.request("eth_call", params)
+ * })
+ * ```
+ *
+ * @example Per-method limits
+ * ```typescript
+ * const RateLimited = DefaultRateLimiter({
+ *   global: { limit: 100, interval: "1 seconds" },
+ *   methods: {
+ *     "eth_getLogs": { limit: 5, interval: "1 seconds" },
+ *     "eth_call": { limit: 50, interval: "1 seconds" }
+ *   },
+ *   behavior: "fail" // Fail fast instead of waiting
+ * })
+ * ```
+ *
+ * @see {@link DefaultRateLimiter} - The live implementation layer
+ * @see {@link RateLimitError} - Error type when limit exceeded
+ */
+export class RateLimiterService extends Context.Tag("RateLimiterService")<
+	RateLimiterService,
+	RateLimiterShape
+>() {}
+
+/**
+ * Creates a scoped RateLimiter layer with the given configuration.
+ * The rate limiters are scoped and will be cleaned up when the scope closes.
+ *
+ * @since 0.0.1
+ */
+export type MakeRateLimiter = (
+	config: RateLimiterConfig,
+) => Effect.Effect<RateLimiterShape, never, Scope.Scope>;

package/src/services/RateLimiter/index.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview RateLimiter module exports for RPC rate limiting.
+ *
+ * @module RateLimiter
+ * @since 0.0.1
+ *
+ * @description
+ * This module provides the rate limiter service for controlling RPC call rates
+ * to Ethereum nodes. It includes the service definition, layer implementation,
+ * and all related types.
+ *
+ * Main exports:
+ * - {@link RateLimiterService} - The service tag/interface
+ * - {@link DefaultRateLimiter} - The live implementation layer factory
+ * - {@link NoopRateLimiter} - A no-op layer for testing
+ * - {@link RateLimitError} - Error type when limit exceeded
+ *
+ * @example Typical usage
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import {
+ *   RateLimiterService,
+ *   DefaultRateLimiter,
+ *   TransportService
+ * } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const rateLimiter = yield* RateLimiterService
+ *   const transport = yield* TransportService
+ *
+ *   return yield* rateLimiter.withRateLimit(
+ *     "eth_call",
+ *     transport.request("eth_call", params)
+ *   )
+ * }).pipe(
+ *   Effect.scoped,
+ *   Effect.provide(DefaultRateLimiter({ global: { limit: 10, interval: "1 seconds" } })),
+ *   Effect.provide(HttpTransport('https://...'))
+ * )
+ * ```
+ */
+
+export {
+	DefaultRateLimiter,
+	makeRateLimiter,
+	NoopRateLimiter,
+} from "./DefaultRateLimiter.js";
+export {
+	type RateLimitBehavior,
+	RateLimitError,
+	type RateLimiterConfig,
+	RateLimiterService,
+	type RateLimiterShape,
+} from "./RateLimiterService.js";