effect 4.0.5 → 4.0.7

package/src/persistence/Persistence.ts

@@ -301,6 +301,24 @@ export const layerBackingMemory: Layer.Layer<BackingPersistence> = Layer.sync(Ba
  * Each table is created if needed and stores JSON-encoded values with optional
  * expiration timestamps.
  *
+ * **Gotchas**
+ *
+ * Store ids are used directly in `effect_persistence_${storeId}` table names,
+ * without encoding or collision detection. Choose ids whose full table names
+ * are distinct under the database's identifier rules:
+ *
+ * - Do not use dots: they are interpreted as schema separators.
+ * - Do not rely on case alone to distinguish stores: SQLite treats ASCII-case
+ *   variants such as `Users` and `users` as the same table.
+ * - Stay within the database's identifier length limit, including the prefix.
+ *   PostgreSQL normally truncates identifiers to 63 bytes, leaving 44 bytes
+ *   for the store id. Ids sharing those first 44 bytes can alias the same table.
+ *
+ * Aliased stores share entries: writes can overwrite another store's values,
+ * and clearing one clears the other. For arbitrary store ids, prefer
+ * `layerBackingSql`, which stores ids as row values rather than table names.
+ *
+ * @see layerBackingSql
  * @stability unstable
  * @category layers
  * @since 4.0.0
@@ -397,9 +415,11 @@ export const layerBackingSqlMultiTable: Layer.Layer<
 
       return identity<BackingPersistenceStore>({
         get: (key) =>
-          sql<
-            { value: string }
-          >`SELECT value FROM ${table} WHERE id = ${key} AND (expires IS NULL OR expires > ${clock.currentTimeMillisUnsafe()})`
+          Effect.suspend(() =>
+            sql<
+              { value: string }
+            >`SELECT value FROM ${table} WHERE id = ${key} AND (expires IS NULL OR expires > ${clock.currentTimeMillisUnsafe()})`
+          )
             .pipe(
               Effect.mapError((cause) =>
                 new PersistenceError({
@@ -424,9 +444,11 @@ export const layerBackingSqlMultiTable: Layer.Layer<
               })
             ),
         getMany: (keys) =>
-          sql<{ id: string; value: string }>`SELECT id, value FROM ${table} WHERE ${
-            sql.in("id", keys)
-          } AND (expires IS NULL OR expires > ${clock.currentTimeMillisUnsafe()})`.unprepared.pipe(
+          Effect.suspend(() =>
+            sql<{ id: string; value: string }>`SELECT id, value FROM ${table} WHERE ${
+              sql.in("id", keys)
+            } AND (expires IS NULL OR expires > ${clock.currentTimeMillisUnsafe()})`.unprepared
+          ).pipe(
             Effect.mapError((cause) =>
               new PersistenceError({
                 message: `Failed to getMany from backing store`,
@@ -585,35 +607,33 @@ export const layerBackingSql: Layer.Layer<
     pg: () =>
       sql`CREATE INDEX IF NOT EXISTS effect_persistence_expires_idx ON ${table} (expires) WHERE expires IS NOT NULL`
         .pipe(Effect.orDie, Effect.asVoid),
-    mysql: () =>
-      Effect.gen(function*() {
-        const indexExists = sql<{ readonly count: number }>`
+    mysql: Effect.fnUntraced(function*() {
+      const indexExists = sql<{ readonly count: number }>`
           SELECT COUNT(*) AS count FROM information_schema.statistics
           WHERE table_schema = DATABASE()
             AND table_name = 'effect_persistence'
             AND index_name = 'effect_persistence_expires_idx'
         `.pipe(
-          Effect.map((rows) => Number(rows[0].count) > 0)
-        )
+        Effect.map((rows) => Number(rows[0].count) > 0)
+      )
 
-        yield* sql`CREATE INDEX effect_persistence_expires_idx ON ${table} (expires)`.pipe(
-          Effect.catch((error) => Effect.flatMap(indexExists, (exists) => exists ? Effect.void : Effect.fail(error)))
-        )
-      }).pipe(Effect.orDie),
-    mssql: () =>
-      Effect.gen(function*() {
-        const indexExists = sql<{ readonly count: number }>`
+      yield* sql`CREATE INDEX effect_persistence_expires_idx ON ${table} (expires)`.pipe(
+        Effect.catch((error) => Effect.flatMap(indexExists, (exists) => exists ? Effect.void : Effect.fail(error)))
+      )
+    }, (_) => Effect.orDie(_)),
+    mssql: Effect.fnUntraced(function*() {
+      const indexExists = sql<{ readonly count: number }>`
           SELECT COUNT(*) AS count FROM sys.indexes
           WHERE name = N'effect_persistence_expires_idx'
             AND object_id = OBJECT_ID(N'effect_persistence')
         `.pipe(
-          Effect.map((rows) => Number(rows[0].count) > 0)
-        )
+        Effect.map((rows) => Number(rows[0].count) > 0)
+      )
 
-        yield* sql`CREATE INDEX effect_persistence_expires_idx ON ${table} (expires) WHERE expires IS NOT NULL`.pipe(
-          Effect.catch((error) => Effect.flatMap(indexExists, (exists) => exists ? Effect.void : Effect.fail(error)))
-        )
-      }).pipe(Effect.orDie),
+      yield* sql`CREATE INDEX effect_persistence_expires_idx ON ${table} (expires) WHERE expires IS NOT NULL`.pipe(
+        Effect.catch((error) => Effect.flatMap(indexExists, (exists) => exists ? Effect.void : Effect.fail(error)))
+      )
+    }, (_) => Effect.orDie(_)),
     // sqlite
     orElse: () =>
       sql`CREATE INDEX IF NOT EXISTS effect_persistence_expires_idx ON ${table} (expires) WHERE expires IS NOT NULL`
@@ -738,9 +758,11 @@ export const layerBackingSql: Layer.Layer<
 
       return identity<BackingPersistenceStore>({
         get: (key) =>
-          sql<
-            { value: string }
-          >`SELECT value FROM ${table} WHERE store_id = ${storeId} AND id = ${key} AND (expires IS NULL OR expires > ${clock.currentTimeMillisUnsafe()})`
+          Effect.suspend(() =>
+            sql<
+              { value: string }
+            >`SELECT value FROM ${table} WHERE store_id = ${storeId} AND id = ${key} AND (expires IS NULL OR expires > ${clock.currentTimeMillisUnsafe()})`
+          )
             .pipe(
               Effect.mapError((cause) =>
                 new PersistenceError({
@@ -765,9 +787,11 @@ export const layerBackingSql: Layer.Layer<
               })
             ),
         getMany: (keys) =>
-          sql<{ id: string; value: string }>`SELECT id, value FROM ${table} WHERE store_id = ${storeId} AND ${
-            sql.in("id", keys)
-          } AND (expires IS NULL OR expires > ${clock.currentTimeMillisUnsafe()})`.unprepared.pipe(
+          Effect.suspend(() =>
+            sql<{ id: string; value: string }>`SELECT id, value FROM ${table} WHERE store_id = ${storeId} AND ${
+              sql.in("id", keys)
+            } AND (expires IS NULL OR expires > ${clock.currentTimeMillisUnsafe()})`.unprepared
+          ).pipe(
             Effect.mapError((cause) =>
               new PersistenceError({
                 message: `Failed to getMany from backing store`,
@@ -1172,6 +1196,16 @@ export const layerRedis: Layer.Layer<Persistence, never, Redis.Redis> = layer.pi
 /**
  * Provides `Persistence` backed by SQL with one table per store id.
  *
+ * **Gotchas**
+ *
+ * Store ids become `effect_persistence_${storeId}` table names and must obey
+ * the database's identifier rules. Avoid dots, case-only distinctions, and
+ * names exceeding the database's identifier length limit (including the
+ * prefix). Colliding names share data, including writes and clears.
+ * Prefer `layerSql` for arbitrary store ids.
+ *
+ * @see layerBackingSqlMultiTable for database-specific store-id restrictions
+ * @see layerSql
  * @stability unstable
  * @category layers
  * @since 4.0.0

package/src/persistence/RateLimiter.ts

@@ -109,24 +109,17 @@ export const make: Effect.Effect<
       const refillRate = Duration.divideUnsafe(window, options.limit)
       const refillRateMillis = Duration.toMillis(refillRate)
 
-      if (tokens > options.limit) {
-        return onExceeded === "fail"
-          ? Effect.fail(
-            new RateLimiterError({
-              reason: new RateLimitExceeded({
-                key: options.key,
-                retryAfter: window,
-                limit: options.limit,
-                remaining: 0
-              })
+      if (onExceeded === "fail" && tokens > options.limit) {
+        return Effect.fail(
+          new RateLimiterError({
+            reason: new RateLimitExceeded({
+              key: options.key,
+              retryAfter: window,
+              limit: options.limit,
+              remaining: 0
             })
-          )
-          : Effect.succeed<ConsumeResult>({
-            delay: window,
-            limit: options.limit,
-            remaining: 0,
-            resetAfter: window
           })
+        )
       }
 
       if (algorithm === "fixed-window") {
@@ -959,7 +952,10 @@ export const makeStoreRedis = Effect.fnUntraced(function*(
       const key = `${prefix}${options.key}`
       const refillMillis = Duration.toMillis(options.refillRate)
       return Effect.mapError(
-        fixedWindow(key, options.tokens, refillMillis, options.limit),
+        Effect.map(
+          fixedWindow(key, options.tokens, refillMillis, options.limit),
+          ([currentTokens, nextPttl]) => [Number(currentTokens), nextPttl] as const
+        ),
         (cause) =>
           new RateLimiterError({
             reason: new RateLimitStoreError({
@@ -1063,21 +1059,22 @@ local current = tonumber(redis.call("GET", key))
 if not current then
   local nextpttl = math.max(1, math.ceil(refillms * tokens))
   redis.call("SET", key, tokens, "PX", nextpttl)
-  return { tokens, nextpttl }
+  return { string.format("%.17g", tokens), nextpttl }
 end
 
 local currentpttl = tonumber(redis.call("PTTL", key) or "0")
 local next = current + tokens
 if limit and next > limit then
-  return { next, currentpttl }
+  return { string.format("%.17g", next), currentpttl }
 end
 
 local nextpttl = math.max(1, math.ceil(currentpttl + (refillms * tokens)))
 redis.call("SET", key, next, "PX", nextpttl)
-return { next, nextpttl }
+-- Use 17 significant digits to round-trip fractional token counts.
+return { string.format("%.17g", next), nextpttl }
 `
   }
-).withReturnType<readonly [currentTokens: number, nextPttl: number]>()
+).withReturnType<readonly [currentTokens: string, nextPttl: number]>()
 
 const tokenBucketScript = Redis.script(
   (

package/src/persistence/Redis.ts

@@ -2,16 +2,17 @@
  * Redis support shared by persistence modules.
  *
  * This module defines a `Redis` service that can send Redis commands, subscribe
- * to pub/sub channels, and run Lua scripts. It does not create a Redis client
- * itself; callers provide the client-specific operations. The module also
- * provides helpers for describing Lua scripts, loading them once, and running
- * them later by their cached Redis id.
+ * to pub/sub channels, run Lua scripts, and reserve a dedicated connection from
+ * a pool. It does not create a Redis client itself; callers provide the
+ * client-specific operations. The module also provides helpers for describing
+ * Lua scripts, loading them once, and running them later by their cached Redis
+ * id.
  *
  * @stability unstable
  * @since 4.0.0
  */
 import * as Cache from "../Cache.ts"
-import type * as Cause from "../Cause.ts"
+import * as Cause from "../Cause.ts"
 import * as Context from "../Context.ts"
 import * as Duration from "../Duration.ts"
 import * as Effect from "../Effect.ts"
@@ -19,6 +20,7 @@ import * as Equal from "../Equal.ts"
 import * as Exit from "../Exit.ts"
 import { constant, identity } from "../Function.ts"
 import * as Hash from "../Hash.ts"
+import * as Pool from "../Pool.ts"
 import * as Queue from "../Queue.ts"
 import * as Schema from "../Schema.ts"
 import * as Scope from "../Scope.ts"
@@ -63,8 +65,63 @@ export class Redis extends Context.Service<Redis, {
       readonly result: unknown
     }
   >(script: Script<Config>) => (...params: Config["params"]) => Effect.Effect<Config["result"], RedisError>
+
+  /**
+   * Reserves a pooled connection that no other caller shares for the lifetime
+   * of the current scope.
+   *
+   * Use it for blocking commands such as `XREAD BLOCK`, `XREADGROUP BLOCK`,
+   * `BLPOP`, `BRPOP`, `BLMOVE`, `BLMPOP` and `WAIT`, which would otherwise
+   * hold up every command queued behind them on the shared connection.
+   *
+   * When the scope closes, the connection returns to the pool. If a command on
+   * it failed, was interrupted, or is still running, the connection is closed
+   * instead, because Redis may still be processing the command.
+   */
+  readonly reserve: Effect.Effect<Connection, RedisError, Scope.Scope>
 }>()("effect/persistence/Redis") {}
 
+/**
+ * A dedicated Redis connection obtained from `Redis.reserve`.
+ *
+ * **Details**
+ *
+ * `eval` loads scripts through the shared connection and runs `EVALSHA` on
+ * this connection.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.7
+ */
+export interface Connection {
+  readonly send: Redis["Service"]["send"]
+  readonly eval: Redis["Service"]["eval"]
+}
+
+/**
+ * Options for the pool of connections behind `Redis.reserve`.
+ *
+ * **Details**
+ *
+ * - `maxConnections`: maximum number of reserved connections, default `10`.
+ *   Further `reserve` calls wait for a connection to be released.
+ * - `minConnections`: connections kept open while idle, default `0`.
+ * - `idleTimeout`: how long a connection above `minConnections` stays idle
+ *   before it is closed, default 60 seconds.
+ * - `acquireTimeout`: how long `reserve` waits for a connection before failing
+ *   with a `RedisError`. Unbounded by default.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.7
+ */
+export interface PoolOptions {
+  readonly maxConnections?: number | undefined
+  readonly minConnections?: number | undefined
+  readonly idleTimeout?: Duration.Input | undefined
+  readonly acquireTimeout?: Duration.Input | undefined
+}
+
 /**
  * Creates a `Redis` service from raw command and subscription operations.
  *
@@ -73,6 +130,11 @@ export class Redis extends Context.Service<Redis, {
  * Lua scripts are loaded through `SCRIPT LOAD`, cached, and then invoked with
  * `EVALSHA`.
  *
+ * `connect` opens the dedicated connections behind `reserve`. Its `close` must
+ * fail any command still in flight on that connection. Connections are pooled
+ * according to `pool`, and closing the scope closes every connection,
+ * including reserved ones with a command in flight.
+ *
  * @stability unstable
  * @category constructors
  * @since 4.0.0
@@ -84,6 +146,11 @@ export const make = Effect.fnUntraced(function*(
       channel: string,
       onMessage: (message: RedisMessage) => void
     ) => Effect.Effect<Effect.Effect<void, RedisError>, RedisError, Scope.Scope>
+    readonly connect: Effect.Effect<{
+      readonly send: <A = unknown>(command: string, ...args: ReadonlyArray<string>) => Effect.Effect<A, RedisError>
+      readonly close: Effect.Effect<void>
+    }, RedisError>
+    readonly pool?: PoolOptions | undefined
   }
 ) {
   const scriptCache = yield* Cache.makeWith(
@@ -94,7 +161,8 @@ export const make = Effect.fnUntraced(function*(
     }
   )
 
-  const eval_ = <
+  const makeEval = (send: Redis["Service"]["send"]): Redis["Service"]["eval"] =>
+  <
     Config extends {
       readonly params: ReadonlyArray<unknown>
       readonly result: unknown
@@ -104,7 +172,7 @@ export const make = Effect.fnUntraced(function*(
   ) =>
   (...params: Config["params"]): Effect.Effect<Config["result"], RedisError> => {
     const evalSha = (sha: string) =>
-      options.send<Config["result"]>(
+      send<Config["result"]>(
         "EVALSHA",
         sha,
         script.numberOfKeys(...params).toString(),
@@ -119,6 +187,58 @@ export const make = Effect.fnUntraced(function*(
     )
   }
 
+  // Closing a connection fails its in-flight command, which releases the
+  // reservation. The pool waits for reservations on shutdown, so connections
+  // are closed before it shuts down.
+  const connections = new Set<Effect.Effect<void>>()
+  const pool = yield* Pool.makeWithTTL({
+    acquire: Effect.acquireRelease(
+      Effect.map(options.connect, (connection) => {
+        const close: Effect.Effect<void> = Effect.suspend(() =>
+          connections.delete(close) ? connection.close : Effect.void
+        )
+        connections.add(close)
+        return { send: connection.send, close, healthy: true, active: 0 }
+      }),
+      (connection) => connection.close
+    ),
+    min: options.pool?.minConnections ?? 0,
+    max: options.pool?.maxConnections ?? 10,
+    concurrency: 1,
+    timeToLive: options.pool?.idleTimeout ?? Duration.seconds(60)
+  })
+  yield* Effect.addFinalizer(() => Effect.forEach(connections, identity, { discard: true }))
+
+  const acquireTimeout = options.pool?.acquireTimeout
+  const get = acquireTimeout === undefined ? Pool.get(pool) : Pool.get(pool).pipe(
+    Effect.timeoutOrElse({
+      duration: acquireTimeout,
+      orElse: () =>
+        Effect.fail(
+          new RedisError({ cause: new Cause.TimeoutError("Timed out waiting for a reserved Redis connection") })
+        )
+    })
+  )
+
+  const reserve = Effect.gen(function*() {
+    const connection = yield* get
+    yield* Effect.addFinalizer(() =>
+      connection.healthy && connection.active === 0 ? Effect.void : Pool.invalidate(pool, connection)
+    )
+    const send = <A = unknown>(command: string, ...args: ReadonlyArray<string>) =>
+      Effect.suspend(() => {
+        connection.active++
+        return connection.send<A>(command, ...args).pipe(
+          Effect.onExit((exit) => {
+            connection.active--
+            if (Exit.isFailure(exit)) connection.healthy = false
+            return Effect.void
+          })
+        )
+      })
+    return identity<Connection>({ send, eval: makeEval(send) })
+  })
+
   const subscribe = Effect.fnUntraced(function*(channel: string) {
     const queue = yield* Queue.unbounded<RedisMessage, RedisError>()
     yield* Scope.addFinalizer(yield* Effect.scope, Queue.shutdown(queue))
@@ -135,7 +255,8 @@ export const make = Effect.fnUntraced(function*(
   return identity<Redis["Service"]>({
     send: options.send,
     subscribe,
-    eval: eval_
+    eval: makeEval(options.send),
+    reserve
   })
 })