voltaire-effect 0.2.23

package/src/services/Transport/WebSocketTransportConfig.test.ts

@@ -0,0 +1,185 @@
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { describe, expect, it } from "vitest";
+import { WebSocketTransportConfigSchema } from "./WebSocketTransportConfig.js";
+
+describe("WebSocketTransportConfigSchema", () => {
+	it("reads config from Map provider", async () => {
+		const configProvider = ConfigProvider.fromMap(
+			new Map([
+				["ws.url", "wss://mainnet.infura.io/ws/v3/KEY"],
+				["ws.timeout", "60 seconds"],
+				["ws.reconnectEnabled", "true"],
+				["ws.reconnect.maxAttempts", "5"],
+				["ws.reconnect.delay", "2 seconds"],
+				["ws.reconnect.maxDelay", "60 seconds"],
+				["ws.reconnect.multiplier", "1.5"],
+				["ws.keepAlive", "30 seconds"],
+			]),
+		);
+
+		const result = await Effect.runPromise(
+			WebSocketTransportConfigSchema.pipe(
+				Effect.provide(Layer.setConfigProvider(configProvider)),
+			),
+		);
+
+		expect(result.url).toBe("wss://mainnet.infura.io/ws/v3/KEY");
+		expect(Duration.toMillis(result.timeout)).toBe(60000);
+		expect(result.reconnectEnabled).toBe(true);
+		expect(Option.isSome(result.reconnect)).toBe(true);
+		if (Option.isSome(result.reconnect)) {
+			expect(result.reconnect.value.maxAttempts).toBe(5);
+			expect(Duration.toMillis(result.reconnect.value.delay)).toBe(2000);
+			expect(Duration.toMillis(result.reconnect.value.maxDelay)).toBe(60000);
+			expect(result.reconnect.value.multiplier).toBe(1.5);
+		}
+		expect(Option.isSome(result.keepAlive)).toBe(true);
+		if (Option.isSome(result.keepAlive)) {
+			expect(Duration.toMillis(result.keepAlive.value)).toBe(30000);
+		}
+	});
+
+	it("uses defaults when optional values not provided", async () => {
+		const configProvider = ConfigProvider.fromMap(
+			new Map([["ws.url", "wss://eth.llamarpc.com"]]),
+		);
+
+		const result = await Effect.runPromise(
+			WebSocketTransportConfigSchema.pipe(
+				Effect.provide(Layer.setConfigProvider(configProvider)),
+			),
+		);
+
+		expect(result.url).toBe("wss://eth.llamarpc.com");
+		expect(Duration.toMillis(result.timeout)).toBe(30000);
+		expect(result.reconnectEnabled).toBe(false);
+		expect(Option.isNone(result.protocols)).toBe(true);
+		expect(Option.isNone(result.keepAlive)).toBe(true);
+	});
+
+	it("validates URL must start with ws:// or wss://", async () => {
+		const configProvider = ConfigProvider.fromMap(
+			new Map([["ws.url", "http://invalid-url"]]),
+		);
+
+		const result = await Effect.runPromiseExit(
+			WebSocketTransportConfigSchema.pipe(
+				Effect.provide(Layer.setConfigProvider(configProvider)),
+			),
+		);
+
+		expect(result._tag).toBe("Failure");
+	});
+
+	it("accepts ws:// URLs", async () => {
+		const configProvider = ConfigProvider.fromMap(
+			new Map([["ws.url", "ws://localhost:8545"]]),
+		);
+
+		const result = await Effect.runPromise(
+			WebSocketTransportConfigSchema.pipe(
+				Effect.provide(Layer.setConfigProvider(configProvider)),
+			),
+		);
+
+		expect(result.url).toBe("ws://localhost:8545");
+	});
+
+	it("accepts wss:// URLs", async () => {
+		const configProvider = ConfigProvider.fromMap(
+			new Map([["ws.url", "wss://mainnet.infura.io/ws/v3/KEY"]]),
+		);
+
+		const result = await Effect.runPromise(
+			WebSocketTransportConfigSchema.pipe(
+				Effect.provide(Layer.setConfigProvider(configProvider)),
+			),
+		);
+
+		expect(result.url).toBe("wss://mainnet.infura.io/ws/v3/KEY");
+	});
+
+	it("fails when required url is missing", async () => {
+		const configProvider = ConfigProvider.fromMap(new Map());
+
+		const result = await Effect.runPromiseExit(
+			WebSocketTransportConfigSchema.pipe(
+				Effect.provide(Layer.setConfigProvider(configProvider)),
+			),
+		);
+
+		expect(result._tag).toBe("Failure");
+	});
+
+	it("parses duration formats correctly", async () => {
+		const configProvider = ConfigProvider.fromMap(
+			new Map([
+				["ws.url", "wss://eth.llamarpc.com"],
+				["ws.timeout", "1 minute"],
+				["ws.keepAlive", "500 millis"],
+			]),
+		);
+
+		const result = await Effect.runPromise(
+			WebSocketTransportConfigSchema.pipe(
+				Effect.provide(Layer.setConfigProvider(configProvider)),
+			),
+		);
+
+		expect(Duration.toMillis(result.timeout)).toBe(60000);
+		expect(Option.isSome(result.keepAlive)).toBe(true);
+		if (Option.isSome(result.keepAlive)) {
+			expect(Duration.toMillis(result.keepAlive.value)).toBe(500);
+		}
+	});
+
+	it("reads protocols as comma-separated string", async () => {
+		const configProvider = ConfigProvider.fromMap(
+			new Map([
+				["ws.url", "wss://eth.llamarpc.com"],
+				["ws.protocols", "protocol1, protocol2, protocol3"],
+			]),
+		);
+
+		const result = await Effect.runPromise(
+			WebSocketTransportConfigSchema.pipe(
+				Effect.provide(Layer.setConfigProvider(configProvider)),
+			),
+		);
+
+		expect(Option.isSome(result.protocols)).toBe(true);
+		if (Option.isSome(result.protocols)) {
+			expect(result.protocols.value).toBe("protocol1, protocol2, protocol3");
+		}
+	});
+
+	it("uses reconnect defaults when reconnect enabled without options", async () => {
+		const configProvider = ConfigProvider.fromMap(
+			new Map([
+				["ws.url", "wss://eth.llamarpc.com"],
+				["ws.reconnectEnabled", "true"],
+			]),
+		);
+
+		const result = await Effect.runPromise(
+			WebSocketTransportConfigSchema.pipe(
+				Effect.provide(Layer.setConfigProvider(configProvider)),
+			),
+		);
+
+		expect(result.reconnectEnabled).toBe(true);
+		// When no reconnect options are provided, the nested config returns
+		// Some with default values (maxAttempts=10, delay=1s, maxDelay=30s, multiplier=2)
+		expect(Option.isSome(result.reconnect)).toBe(true);
+		if (Option.isSome(result.reconnect)) {
+			expect(result.reconnect.value.maxAttempts).toBe(10);
+			expect(Duration.toMillis(result.reconnect.value.delay)).toBe(1000);
+			expect(Duration.toMillis(result.reconnect.value.maxDelay)).toBe(30000);
+			expect(result.reconnect.value.multiplier).toBe(2);
+		}
+	});
+});

package/src/services/Transport/WebSocketTransportConfig.ts

@@ -0,0 +1,247 @@
+/**
+ * @fileoverview Effect.Config schema for WebSocket transport configuration.
+ *
+ * @module WebSocketTransportConfig
+ * @since 0.0.1
+ *
+ * @description
+ * Provides type-safe configuration for WebSocket transport using Effect.Config.
+ * Supports reading configuration from environment variables with validation,
+ * defaults, and proper duration parsing.
+ *
+ * @example Environment variable configuration
+ * ```typescript
+ * // Set environment variables:
+ * // WS_URL=wss://mainnet.infura.io/ws/v3/YOUR_KEY
+ * // WS_TIMEOUT=60s
+ * // WS_RECONNECT=true
+ * // WS_RECONNECT_MAX_ATTEMPTS=10
+ * // WS_RECONNECT_DELAY=1s
+ * // WS_RECONNECT_MAX_DELAY=30s
+ * // WS_KEEP_ALIVE=30s
+ *
+ * import { Effect, Layer, ConfigProvider } from 'effect'
+ * import { WebSocketTransportFromConfig, TransportService } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const transport = yield* TransportService
+ *   return yield* transport.request('eth_blockNumber')
+ * }).pipe(
+ *   Effect.provide(WebSocketTransportFromConfig),
+ *   Effect.provide(Layer.setConfigProvider(ConfigProvider.fromEnv()))
+ * )
+ * ```
+ *
+ * @see {@link WebSocketTransport} - Plain object configuration API
+ * @see {@link TransportService} - The service interface
+ */
+
+import type * as Socket from "@effect/platform/Socket";
+import * as Config from "effect/Config";
+import type * as ConfigError from "effect/ConfigError";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import type { TransportError } from "./TransportError.js";
+import type { TransportService } from "./TransportService.js";
+import {
+	WebSocketConstructorGlobal,
+	WebSocketTransport,
+} from "./WebSocketTransport.js";
+
+/**
+ * Effect.Config schema for WebSocket reconnection options.
+ *
+ * @since 0.0.1
+ */
+const ReconnectConfigSchema = Config.all({
+	maxAttempts: Config.integer("maxAttempts").pipe(Config.withDefault(10)),
+	delay: Config.duration("delay").pipe(Config.withDefault(Duration.seconds(1))),
+	maxDelay: Config.duration("maxDelay").pipe(
+		Config.withDefault(Duration.seconds(30)),
+	),
+	multiplier: Config.number("multiplier").pipe(Config.withDefault(2)),
+}).pipe(Config.nested("reconnect"));
+
+/**
+ * Effect.Config schema for WebSocket transport configuration.
+ *
+ * @description
+ * Defines a type-safe configuration schema that can be populated from
+ * environment variables, config files, or programmatic sources.
+ *
+ * Environment variables (when using ConfigProvider.fromEnv()):
+ * - `WS_URL` - Required. WebSocket endpoint URL (ws:// or wss://)
+ * - `WS_TIMEOUT` - Optional. Request timeout (e.g., "30s", "1m"). Default: 30s
+ * - `WS_PROTOCOLS` - Optional. Comma-separated WebSocket sub-protocols
+ * - `WS_RECONNECT_ENABLED` - Optional. Enable auto-reconnect. Default: false
+ * - `WS_RECONNECT_MAX_ATTEMPTS` - Optional. Max reconnect attempts. Default: 10
+ * - `WS_RECONNECT_DELAY` - Optional. Initial reconnect delay. Default: 1s
+ * - `WS_RECONNECT_MAX_DELAY` - Optional. Max reconnect delay. Default: 30s
+ * - `WS_RECONNECT_MULTIPLIER` - Optional. Backoff multiplier. Default: 2
+ * - `WS_KEEP_ALIVE` - Optional. Keep-alive ping interval (e.g., "30s")
+ *
+ * @since 0.0.1
+ *
+ * @example
+ * ```typescript
+ * import { Effect, ConfigProvider, Layer } from 'effect'
+ * import { WebSocketTransportConfigSchema } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const config = yield* WebSocketTransportConfigSchema
+ *   console.log('URL:', config.url)
+ *   console.log('Timeout:', Duration.toMillis(config.timeout))
+ * }).pipe(
+ *   Effect.provide(Layer.setConfigProvider(ConfigProvider.fromEnv()))
+ * )
+ * ```
+ */
+export const WebSocketTransportConfigSchema = Config.all({
+	url: Config.string("url").pipe(
+		Config.validate({
+			message: "URL must start with ws:// or wss://",
+			validation: (s) => s.startsWith("ws://") || s.startsWith("wss://"),
+		}),
+	),
+	timeout: Config.duration("timeout").pipe(
+		Config.withDefault(Duration.seconds(30)),
+	),
+	protocols: Config.string("protocols").pipe(Config.option),
+	reconnectEnabled: Config.boolean("reconnectEnabled").pipe(
+		Config.withDefault(false),
+	),
+	reconnect: ReconnectConfigSchema.pipe(Config.option),
+	keepAlive: Config.duration("keepAlive").pipe(Config.option),
+}).pipe(Config.nested("ws"));
+
+/**
+ * Type representing the resolved WebSocket transport configuration.
+ *
+ * @since 0.0.1
+ */
+export type WebSocketTransportConfigType = Config.Config.Success<
+	typeof WebSocketTransportConfigSchema
+>;
+
+/**
+ * Layer that creates a WebSocket transport from Effect.Config.
+ *
+ * @description
+ * Reads configuration from the ConfigProvider (environment, files, etc.)
+ * and creates a WebSocket transport layer.
+ *
+ * @since 0.0.1
+ *
+ * @example Environment variables
+ * ```typescript
+ * import { Effect, Layer, ConfigProvider } from 'effect'
+ * import { WebSocketTransportFromConfig, TransportService, WebSocketConstructorGlobal } from 'voltaire-effect'
+ *
+ * // Set: WS_URL=wss://mainnet.infura.io/ws/v3/KEY
+ *
+ * const program = Effect.gen(function* () {
+ *   const transport = yield* TransportService
+ *   return yield* transport.request('eth_blockNumber')
+ * }).pipe(
+ *   Effect.provide(WebSocketTransportFromConfig),
+ *   Effect.provide(WebSocketConstructorGlobal),
+ *   Effect.provide(Layer.setConfigProvider(ConfigProvider.fromEnv())),
+ *   Effect.scoped
+ * )
+ * ```
+ *
+ * @example Programmatic config
+ * ```typescript
+ * import { Effect, Layer, ConfigProvider } from 'effect'
+ * import { WebSocketTransportFromConfig, TransportService, WebSocketConstructorGlobal } from 'voltaire-effect'
+ *
+ * const configProvider = ConfigProvider.fromMap(new Map([
+ *   ['ws.url', 'wss://mainnet.infura.io/ws/v3/KEY'],
+ *   ['ws.timeout', '60s'],
+ *   ['ws.reconnectEnabled', 'true'],
+ * ]))
+ *
+ * const program = Effect.gen(function* () {
+ *   const transport = yield* TransportService
+ *   return yield* transport.request('eth_blockNumber')
+ * }).pipe(
+ *   Effect.provide(WebSocketTransportFromConfig),
+ *   Effect.provide(WebSocketConstructorGlobal),
+ *   Effect.provide(Layer.setConfigProvider(configProvider)),
+ *   Effect.scoped
+ * )
+ * ```
+ */
+export const WebSocketTransportFromConfig: Layer.Layer<
+	TransportService,
+	ConfigError.ConfigError | TransportError,
+	Socket.WebSocketConstructor
+> = Layer.unwrapScoped(
+	Effect.gen(function* () {
+		const config = yield* WebSocketTransportConfigSchema;
+
+		// Build reconnect options if enabled
+		const reconnect = config.reconnectEnabled
+			? Option.match(config.reconnect, {
+					onNone: () => true as const,
+					onSome: (r) => ({
+						maxAttempts: r.maxAttempts,
+						delay: Duration.toMillis(r.delay),
+						maxDelay: Duration.toMillis(r.maxDelay),
+						multiplier: r.multiplier,
+					}),
+				})
+			: false;
+
+		// Build keep-alive if provided
+		const keepAlive = Option.match(config.keepAlive, {
+			onNone: () => undefined,
+			onSome: (d) => Duration.toMillis(d),
+		});
+
+		// Build protocols if provided
+		const protocols = Option.match(config.protocols, {
+			onNone: () => undefined,
+			onSome: (p) => p.split(",").map((s) => s.trim()),
+		});
+
+		return WebSocketTransport({
+			url: config.url,
+			timeout: Duration.toMillis(config.timeout),
+			protocols,
+			reconnect,
+			keepAlive,
+		});
+	}),
+);
+
+/**
+ * Creates a config-based WebSocket transport with global WebSocket constructor bundled.
+ *
+ * @description
+ * Convenience layer that combines WebSocketTransportFromConfig with the global
+ * WebSocket constructor, so you only need to provide the ConfigProvider.
+ *
+ * @since 0.0.1
+ *
+ * @example
+ * ```typescript
+ * import { Effect, Layer, ConfigProvider } from 'effect'
+ * import { WebSocketTransportFromConfigGlobal, TransportService } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const transport = yield* TransportService
+ *   return yield* transport.request('eth_blockNumber')
+ * }).pipe(
+ *   Effect.provide(WebSocketTransportFromConfigGlobal),
+ *   Effect.provide(Layer.setConfigProvider(ConfigProvider.fromEnv())),
+ *   Effect.scoped
+ * )
+ * ```
+ */
+export const WebSocketTransportFromConfigGlobal: Layer.Layer<
+	TransportService,
+	ConfigError.ConfigError | TransportError
+> = Layer.provide(WebSocketTransportFromConfig, WebSocketConstructorGlobal);

package/src/services/Transport/__testUtils__/mockIpcSocket.ts

@@ -0,0 +1,106 @@
+import * as Effect from "effect/Effect";
+import type { IpcSocket } from "../IpcTransport.js";
+
+type Listener<T> = (event: T) => void;
+
+type MockIpcSocketOptions = {
+	onWrite?: (socket: MockIpcSocket, data: string | Uint8Array) => void;
+	onEnd?: (socket: MockIpcSocket) => void;
+};
+
+type AnyListener =
+	| Listener<Uint8Array | string>
+	| Listener<Error>
+	| Listener<void>;
+
+export class MockIpcSocket implements IpcSocket {
+	readonly index: number;
+	private listeners = new Map<string, Set<AnyListener>>();
+	private options: MockIpcSocketOptions;
+
+	constructor(index: number, options: MockIpcSocketOptions) {
+		this.index = index;
+		this.options = options;
+	}
+
+	on(event: "data", listener: Listener<Uint8Array | string>): this;
+	on(event: "error", listener: Listener<Error>): this;
+	on(event: "close", listener: Listener<void>): this;
+	on(
+		event: string,
+		listener: Listener<Uint8Array | string> | Listener<Error> | Listener<void>,
+	): this {
+		const set = this.listeners.get(event) ?? new Set();
+		set.add(listener);
+		this.listeners.set(event, set);
+		return this;
+	}
+
+	off(event: "data", listener: Listener<Uint8Array | string>): this;
+	off(event: "error", listener: Listener<Error>): this;
+	off(event: "close", listener: Listener<void>): this;
+	off(
+		event: string,
+		listener: Listener<Uint8Array | string> | Listener<Error> | Listener<void>,
+	): this {
+		const set = this.listeners.get(event);
+		if (!set) return this;
+		set.delete(listener);
+		if (set.size === 0) {
+			this.listeners.delete(event);
+		}
+		return this;
+	}
+
+	write(
+		chunk: string | Uint8Array,
+		callback?: (err?: Error | null) => void,
+	): boolean {
+		this.options.onWrite?.(this, chunk);
+		callback?.(null);
+		return true;
+	}
+
+	end(callback?: () => void): void {
+		this.emitClose();
+		this.options.onEnd?.(this);
+		callback?.();
+	}
+
+	emitData(data: string | Uint8Array) {
+		this.emit("data", data);
+	}
+
+	emitMessage(message: unknown) {
+		this.emitData(`${JSON.stringify(message)}\n`);
+	}
+
+	emitError(error: Error) {
+		this.emit("error", error);
+	}
+
+	emitClose() {
+		this.emit("close", undefined);
+	}
+
+	private emit(event: string, value: unknown) {
+		const listeners = this.listeners.get(event);
+		if (!listeners) return;
+		for (const listener of [...listeners]) {
+			(listener as Listener<unknown>)(value);
+		}
+	}
+}
+
+export const makeMockIpcSocket = (options: MockIpcSocketOptions = {}) => {
+	const sockets: MockIpcSocket[] = [];
+
+	const socketFactory = (_path: string) =>
+		Effect.sync(() => {
+			const socket = new MockIpcSocket(sockets.length, options);
+			sockets.push(socket);
+			return socket;
+		});
+
+	return { socketFactory, sockets };
+};

package/src/services/Transport/__testUtils__/mockWebSocket.ts

@@ -0,0 +1,138 @@
+type Listener = {
+	handler: (event: unknown) => void;
+	once: boolean;
+};
+
+export type MockWebSocketOptions = {
+	readyState?: number;
+	autoOpen?: boolean | ((index: number) => boolean);
+	getReadyState?: (index: number) => number;
+	onSend?: (socket: MockWebSocket, data: string | Uint8Array) => void;
+	onClose?: (
+		socket: MockWebSocket,
+		event: { code: number; reason: string },
+	) => void;
+	onError?: (socket: MockWebSocket, event: unknown) => void;
+};
+
+export class MockWebSocket {
+	static readonly CONNECTING = 0;
+	static readonly OPEN = 1;
+	static readonly CLOSING = 2;
+	static readonly CLOSED = 3;
+
+	readonly url: string;
+	readonly protocols?: string | string[];
+	readyState: number;
+
+	/** @internal */
+	_listeners = new Map<string, Set<Listener>>();
+	readonly index: number;
+	/** @internal */
+	readonly _options: MockWebSocketOptions;
+
+	constructor(
+		url: string,
+		protocols: string | string[] | undefined,
+		index: number,
+		options: MockWebSocketOptions,
+	) {
+		this.url = url;
+		this.protocols = protocols;
+		this.index = index;
+		this._options = options;
+		const readyState =
+			options.getReadyState?.(index) ??
+			options.readyState ??
+			MockWebSocket.OPEN;
+		this.readyState = readyState;
+
+		const autoOpen =
+			typeof options.autoOpen === "function"
+				? options.autoOpen(index)
+				: (options.autoOpen ?? true);
+		if (autoOpen) {
+			queueMicrotask(() => this.emitOpen());
+		}
+	}
+
+	addEventListener(
+		type: string,
+		handler: (event: unknown) => void,
+		options?: { once?: boolean },
+	) {
+		const entry: Listener = { handler, once: options?.once ?? false };
+		const listeners = this._listeners.get(type) ?? new Set<Listener>();
+		listeners.add(entry);
+		this._listeners.set(type, listeners);
+	}
+
+	removeEventListener(type: string, handler: (event: unknown) => void) {
+		const listeners = this._listeners.get(type);
+		if (!listeners) return;
+		for (const listener of listeners) {
+			if (listener.handler === handler) {
+				listeners.delete(listener);
+			}
+		}
+		if (listeners.size === 0) {
+			this._listeners.delete(type);
+		}
+	}
+
+	send(data: string | Uint8Array) {
+		this._options.onSend?.(this, data);
+	}
+
+	close(code: number = 1000, reason: string = "") {
+		this.readyState = MockWebSocket.CLOSED;
+		this._emit("close", { code, reason });
+		this._options.onClose?.(this, { code, reason });
+	}
+
+	emitOpen() {
+		this.readyState = MockWebSocket.OPEN;
+		this._emit("open", {});
+	}
+
+	emitMessage(data: string | Uint8Array) {
+		this._emit("message", { data });
+	}
+
+	emitError(event: unknown) {
+		this._emit("error", event);
+		this._options.onError?.(this, event);
+	}
+
+	/** @internal */
+	_emit(type: string, event: unknown) {
+		const listeners = this._listeners.get(type);
+		if (!listeners) return;
+		for (const listener of [...listeners]) {
+			listener.handler(event);
+			if (listener.once) {
+				listeners.delete(listener);
+			}
+		}
+		if (listeners.size === 0) {
+			this._listeners.delete(type);
+		}
+	}
+}
+
+export const makeMockWebSocket = (options: MockWebSocketOptions = {}) => {
+	const sockets: MockWebSocket[] = [];
+	class MockWebSocketConstructor extends MockWebSocket {
+		static readonly CONNECTING = MockWebSocket.CONNECTING;
+		static readonly OPEN = MockWebSocket.OPEN;
+		static readonly CLOSING = MockWebSocket.CLOSING;
+		static readonly CLOSED = MockWebSocket.CLOSED;
+
+		constructor(url: string, protocols?: string | string[]) {
+			super(url, protocols, sockets.length, options);
+			sockets.push(this);
+		}
+	}
+
+	return { MockWebSocket: MockWebSocketConstructor, sockets };
+};