effect 4.0.2 → 4.0.4

package/src/net/index.ts

@@ -5,6 +5,24 @@
 
 // @barrel: Auto-generated exports. Do not edit manually.
 
+/**
+ * @stability experimental
+ * @since 4.0.0
+ */
+export * as AddressResolver from "./AddressResolver.ts"
+
+/**
+ * @stability experimental
+ * @since 4.0.0
+ */
+export * as Dns from "./Dns.ts"
+
+/**
+ * @stability experimental
+ * @since 4.0.0
+ */
+export * as Host from "./Host.ts"
+
 /**
  * @stability unstable
  * @since 4.0.0

package/src/observability/OtlpMetrics.ts

@@ -12,7 +12,6 @@
  * @stability unstable
  * @since 4.0.0
  */
-import * as Arr from "../Array.ts"
 import { Clock } from "../Clock.ts"
 import * as Config from "../Config.ts"
 import * as Duration from "../Duration.ts"
@@ -228,27 +227,24 @@ export const make: (options: {
           break
         }
         case "Histogram": {
-          const size = state.state.buckets.length
           const currentBuckets = {
-            boundaries: Arr.allocate(size - 1) as Array<number>,
-            counts: Arr.allocate(size) as Array<number>
+            boundaries: [] as Array<number>,
+            counts: [] as Array<number>
           }
-          let idx = 0
           let prev = 0
           for (const [boundary, value] of state.state.buckets) {
-            if (idx < size - 1) {
-              currentBuckets.boundaries[idx] = boundary
-            }
-            currentBuckets.counts[idx] = value - prev
+            if (boundary === Number.POSITIVE_INFINITY) break
+            currentBuckets.boundaries.push(boundary)
+            currentBuckets.counts.push(value - prev)
             prev = value
-            idx++
           }
+          // Derive overflow from the total count, whether or not boundaries include Infinity.
+          currentBuckets.counts.push(state.state.count - prev)
 
           let reportCount = state.state.count
           let reportSum = state.state.sum
           let reportBucketCounts = currentBuckets.counts
-          const reportMin = state.state.min
-          const reportMax = state.state.max
+          let reportExtrema = true
 
           if (isDelta) {
             const previousState = previousHistogramState.get(metricKey)
@@ -258,17 +254,13 @@ export const make: (options: {
               reportBucketCounts = currentBuckets.counts.map((c, i) =>
                 Math.max(0, c - (previousState.bucketCounts[i] ?? 0))
               )
-              // For delta, min/max represent the interval's min/max
-              // We can't compute these from cumulative state, so we use current values
-              // Note: This is a limitation - true delta min/max would require tracking
-              // observations within each interval
+              // Cumulative extrema cannot describe a later delta interval.
+              reportExtrema = false
             }
             nextHistogramState.set(metricKey, {
               count: state.state.count,
               sum: state.state.sum,
-              bucketCounts: currentBuckets.counts.slice(),
-              min: state.state.min,
-              max: state.state.max
+              bucketCounts: currentBuckets.counts.slice()
             })
           }
 
@@ -277,8 +269,7 @@ export const make: (options: {
             startTimeUnixNano: intervalStartTime,
             timeUnixNano: nowTime,
             count: reportCount,
-            min: reportMin,
-            max: reportMax,
+            ...(reportExtrema ? { min: state.state.min, max: state.state.max } : undefined),
             sum: reportSum,
             bucketCounts: reportBucketCounts,
             explicitBounds: currentBuckets.boundaries
@@ -519,8 +510,6 @@ interface PreviousHistogramState {
   readonly count: number
   readonly sum: number
   readonly bucketCounts: Array<number>
-  readonly min: number
-  readonly max: number
 }
 
 /** Properties of an InstrumentationScope. */

package/src/observability/PrometheusMetrics.ts

@@ -425,6 +425,7 @@ const formatHistogram = (
   // Effect buckets are [boundary, cumulativeCount] pairs
   for (let i = 0; i < state.buckets.length; i++) {
     const [boundary, cumulativeCount] = state.buckets[i]
+    if (boundary === Number.POSITIVE_INFINITY) continue
     const bucketLabels = formatLabels(metric.attributes, [["le", boundary.toString()]])
     lines.push(`${name}_bucket${bucketLabels} ${cumulativeCount}`)
   }

package/src/persistence/PersistedQueue.ts

@@ -34,6 +34,7 @@ import * as Scope from "../Scope.ts"
 import * as Migrator from "../sql/Migrator.ts"
 import * as SqlClient from "../sql/SqlClient.ts"
 import type { SqlError } from "../sql/SqlError.ts"
+import type { Fragment } from "../sql/Statement.ts"
 import * as Redis from "./Redis.ts"
 
 /**
@@ -80,11 +81,27 @@ export interface PersistedQueue<in out A, out R = never> {
    * **Details**
    *
    * If an element with the same id already exists in the queue, it will not be
-   * added again. De-duplication survives completion until the id is removed by
+   * added again, and the `delay` of the duplicate offer is ignored.
+   * De-duplication survives completion until the id is removed by
    * `layerCleanup`.
+   *
+   * `delay` postpones the first delivery. Measured by the store's clock, the
+   * element is never delivered before the delay elapses, and is typically
+   * delivered within the store's `pollInterval` after. The SQL store uses the
+   * database clock and rounds delays up to whole seconds. The Redis store
+   * compares the offering process's clock with the polling worker's, so it
+   * relies on those clocks agreeing.
+   * Retries still use the queue's `retrySchedule`, and the delay does not
+   * count an attempt. A zero, negative or omitted delay enqueues the element
+   * immediately.
+   *
+   * An infinite delay does nothing: the id is returned, but nothing is stored
+   * and no de-duplication record is written, so the same id can be offered
+   * again later.
    */
   readonly offer: (value: A, options?: {
-    readonly id: string | undefined
+    readonly id?: string | undefined
+    readonly delay?: Duration.Input | undefined
   }) => Effect.Effect<string, PersistedQueueError | Schema.SchemaError, R>
 
   /**
@@ -232,21 +249,27 @@ export const makeFactory = Effect.gen(function*() {
       return Effect.succeed<PersistedQueue<S["Type"], S["EncodingServices"] | S["DecodingServices"]>>({
         [TypeId]: TypeId,
         offer: (value, opts) =>
-          Effect.flatMap(
-            encodeUnknown(value),
-            (element) => {
-              const id = opts?.id ?? crypto.randomUUID()
-              return Effect.as(
-                store.offer({
-                  name: options.name,
-                  id,
-                  element,
-                  isCustomId: opts?.id !== undefined
-                }),
-                id
-              )
+          Effect.suspend(() => {
+            const id = opts?.id ?? crypto.randomUUID()
+            const delay = positiveDelay(opts?.delay)
+            if (delay !== undefined && !Duration.isFinite(delay)) {
+              return Effect.succeed(id)
             }
-          ),
+            return Effect.flatMap(
+              encodeUnknown(value),
+              (element) =>
+                Effect.as(
+                  store.offer({
+                    name: options.name,
+                    id,
+                    element,
+                    isCustomId: opts?.id !== undefined,
+                    delay
+                  }),
+                  id
+                )
+            )
+          }),
         take: <XA, XE, XR>(
           f: (value: S["Type"], metadata: {
             readonly id: string
@@ -430,6 +453,13 @@ class DeadLetter {
 const isDeadLetter = (u: unknown): u is DeadLetter =>
   Predicate.isTagged(u, "~effect/persistence/PersistedQueue/DeadLetter")
 
+// stores only see a positive delay, so a zero or negative one is dropped here
+const positiveDelay = (input: Duration.Input | undefined): Duration.Duration | undefined => {
+  if (input === undefined) return undefined
+  const delay = Duration.fromInputUnsafe(input)
+  return Duration.isPositive(delay) ? delay : undefined
+}
+
 const deadLetterFromCause = (cause: Cause.Cause<unknown>): DeadLetter | undefined => {
   for (const reason of cause.reasons) {
     if (Cause.isFailReason(reason) && isDeadLetter(reason.error)) {
@@ -452,6 +482,9 @@ const deadLetterFromCause = (cause: Cause.Cause<unknown>): DeadLetter | undefine
  * The store persists offered elements and returns taken elements in a scope so
  * the finalizer can complete or retry them based on the processing exit.
  *
+ * An offered `delay` is always finite and positive, and the element must not
+ * be taken before it elapses. It is `undefined` for immediate elements.
+ *
  * Claiming an element counts an attempt, so the `attempts` returned by `take`
  * is 1-based. When the take scope closes with a success the element is marked
  * completed; a failure retries it according to `retryDelay` or marks it failed
@@ -471,6 +504,7 @@ export class PersistedQueueStore extends Context.Service<
         readonly id: string
         readonly element: unknown
         readonly isCustomId: boolean
+        readonly delay?: Duration.Duration | undefined
       }
     ) => Effect.Effect<void, PersistedQueueError>
 
@@ -509,6 +543,9 @@ export class PersistedQueueStore extends Context.Service<
  * queue's retry schedule until the configured maximum attempts is reached,
  * after which the element is marked as failed.
  *
+ * Delayed elements are scanned on every take loop, so the store is meant for
+ * development and tests rather than large delayed backlogs.
+ *
  * @stability unstable
  * @category layers
  * @since 4.0.0
@@ -558,7 +595,7 @@ export const layerStoreMemory: Layer.Layer<
             element: options.element,
             attempts: 0,
             state: "pending",
-            visibleAt: now,
+            visibleAt: options.delay === undefined ? now : now + Duration.toMillis(options.delay),
             stateChangedAt: now
           }
           queue.entries.set(options.id, entry)
@@ -655,7 +692,9 @@ export const layerStoreMemory: Layer.Layer<
  * The store uses Redis lists, hashes, and sorted sets with worker locks,
  * periodically refreshes locks while items are being processed, delays retried
  * items with the queue's retry schedule, and moves exhausted items to a failed
- * queue.
+ * queue. Delayed offers share the retry sorted set: they are scored with the
+ * offering process's clock and released by the polling worker's clock, so
+ * clock skew between hosts shifts their delivery.
  *
  * @stability unstable
  * @category constructors
@@ -716,6 +755,7 @@ export const makeStoreRedis = Effect.fnUntraced(function*(
   const retry = redis.eval(retryRedis)
   const resetQueue = redis.eval(resetQueueRedis)
   const offer = redis.eval(offerRedis)
+  const offerDelayed = redis.eval(offerDelayedRedis)
   const take = redis.eval(takeRedis)
   const expireAll = redis.eval(expireAllRedis)
   const trimFailed = redis.eval(trimFailedRedis)
@@ -856,24 +896,33 @@ export const makeStoreRedis = Effect.fnUntraced(function*(
     })
 
   return PersistedQueueStore.of({
-    offer: ({ element, id, isCustomId, name }) => {
+    offer: ({ delay, element, id, isCustomId, name }) => {
       const keys = keysFor(name)
       const payload = JSON.stringify({ id, element })
-      return (isCustomId
-        ? offer(keys.queue, keys.ids, id, payload)
-        : redis.send("RPUSH", keys.queue, payload)).pipe(
-          Effect.mapError(({ cause }) =>
-            new PersistedQueueError({
-              message: "Failed to offer element to persisted queue",
-              cause
-            })
-          ),
-          Effect.tap(() =>
-            Effect.sync(() => {
-              queueStates.peek(name)?.nudge.openUnsafe()
-            })
-          )
+      const send = Effect.suspend(() => {
+        if (delay === undefined) {
+          return isCustomId
+            ? offer(keys.queue, keys.ids, id, payload)
+            : redis.send("RPUSH", keys.queue, payload)
+        }
+        const visibleAt = clock.currentTimeMillisUnsafe() + Duration.toMillis(delay)
+        return isCustomId
+          ? offerDelayed(keys.delayed, keys.ids, id, payload, visibleAt)
+          : redis.send("ZADD", keys.delayed, visibleAt.toString(), payload)
+      })
+      return send.pipe(
+        Effect.mapError(({ cause }) =>
+          new PersistedQueueError({
+            message: "Failed to offer element to persisted queue",
+            cause
+          })
+        ),
+        Effect.tap(() =>
+          Effect.sync(() => {
+            queueStates.peek(name)?.nudge.openUnsafe()
+          })
         )
+      )
     },
     take: (options) =>
       Effect.uninterruptibleMask((restore) => {
@@ -1009,6 +1058,25 @@ end
   }
 )
 
+const offerDelayedRedis = Redis.script(
+  (...args: [keyDelayed: string, keyIds: string, id: string, payload: string, visibleAt: number]) => args,
+  {
+    lua: `
+local key_delayed = KEYS[1]
+local key_ids = KEYS[2]
+local id = ARGV[1]
+local payload = ARGV[2]
+local visible_at = ARGV[3]
+
+local result = redis.call("ZADD", key_ids, "NX", "+inf", id)
+if result == 1 then
+  redis.call("ZADD", key_delayed, visible_at, payload)
+end
+`,
+    numberOfKeys: 2
+  }
+)
+
 const resetQueueRedis = Redis.script(
   (
     ...args: [
@@ -1296,6 +1364,9 @@ export const layerStoreRedis: (
  * per-worker locks, refreshes active locks while scoped takes are running, and
  * retries or completes rows according to the processing exit.
  *
+ * Offer and retry delays are measured with the database clock and rounded up
+ * to whole seconds.
+ *
  * @stability unstable
  * @category constructors
  * @since 4.0.0
@@ -1360,34 +1431,46 @@ export const makeStoreSql: (
   }
   const secondsAgo = (seconds: number) => secondsOffset(-Math.max(Math.ceil(seconds), 0))
   const secondsFromNow = (seconds: number) => secondsOffset(Math.max(Math.ceil(seconds), 0))
+  // Deadline for a delayed offer, which must never land before the delay
+  // elapses. pg reads clock_timestamp() since NOW() is fixed at transaction
+  // start. mysql and sqlite clocks drop the fraction of the current second, so
+  // they get a whole extra second to cover it.
+  const delayedVisibleAt = (delay: Duration.Duration) => {
+    const seconds = Math.ceil(Duration.toSeconds(delay))
+    return sql.onDialectOrElse({
+      pg: () => sql`clock_timestamp() + INTERVAL '${sql.literal(seconds.toString())} seconds'`,
+      mssql: () => secondsOffset(seconds),
+      orElse: () => secondsOffset(seconds + 1)
+    })
+  }
   const expiresAt = secondsAgo(Duration.toSeconds(lockExpiration))
 
   const offer = sql.onDialectOrElse({
-    pg: () => (id: string, name: string, element: string) =>
+    pg: () => (id: string, name: string, element: string, visibleAt: Fragment) =>
       sql`
         INSERT INTO ${tableNameSql} (id, queue_name, element, state, attempts, visible_at, created_at, updated_at)
-        VALUES (${id}, ${name}, ${element}, 'pending', 0, ${sqlNow}, ${sqlNow}, ${sqlNow})
+        VALUES (${id}, ${name}, ${element}, 'pending', 0, ${visibleAt}, ${sqlNow}, ${sqlNow})
         ON CONFLICT (id, queue_name) DO NOTHING
       `,
-    mysql: () => (id: string, name: string, element: string) =>
+    mysql: () => (id: string, name: string, element: string, visibleAt: Fragment) =>
       sql`
         INSERT IGNORE INTO ${tableNameSql} (id, queue_name, element, state, attempts, visible_at, created_at, updated_at)
-        VALUES (${id}, ${name}, ${element}, 'pending', 0, ${sqlNow}, ${sqlNow}, ${sqlNow})
+        VALUES (${id}, ${name}, ${element}, 'pending', 0, ${visibleAt}, ${sqlNow}, ${sqlNow})
       `,
-    mssql: () => (id: string, name: string, element: string) =>
+    mssql: () => (id: string, name: string, element: string, visibleAt: Fragment) =>
       sql`
         MERGE ${tableNameSql} WITH (HOLDLOCK) AS target
         USING (SELECT ${id} AS id, ${name} AS queue_name) AS source
         ON target.id = source.id AND target.queue_name = source.queue_name
         WHEN NOT MATCHED THEN
           INSERT (id, queue_name, element, state, attempts, visible_at, created_at, updated_at)
-          VALUES (source.id, source.queue_name, ${element}, 'pending', 0, ${sqlNow}, ${sqlNow}, ${sqlNow});
+          VALUES (source.id, source.queue_name, ${element}, 'pending', 0, ${visibleAt}, ${sqlNow}, ${sqlNow});
       `,
     // sqlite
-    orElse: () => (id: string, name: string, element: string) =>
+    orElse: () => (id: string, name: string, element: string, visibleAt: Fragment) =>
       sql`
         INSERT OR IGNORE INTO ${tableNameSql} (id, queue_name, element, state, attempts, visible_at, created_at, updated_at)
-        VALUES (${id}, ${name}, ${element}, 'pending', 0, ${sqlNow}, ${sqlNow}, ${sqlNow})
+        VALUES (${id}, ${name}, ${element}, 'pending', 0, ${visibleAt}, ${sqlNow}, ${sqlNow})
       `
   })
 
@@ -1696,20 +1779,30 @@ export const makeStoreSql: (
     )
 
   return PersistedQueueStore.of({
-    offer: ({ element, id, name }) =>
-      Effect.catchCause(Effect.suspend(() => offer(id, name, JSON.stringify(element))), (cause) =>
-        Effect.fail(
-          new PersistedQueueError({
-            message: "Failed to offer element to persisted queue",
-            cause
-          })
-        )).pipe(
-          Effect.tap(() =>
-            Effect.sync(() => {
-              queueStates.peek(name)?.nudge.openUnsafe()
-            })
+    offer: ({ delay, element, id, name }) =>
+      Effect.catchCause(
+        Effect.suspend(() =>
+          offer(
+            id,
+            name,
+            JSON.stringify(element),
+            delay === undefined ? sqlNow : delayedVisibleAt(delay)
           )
         ),
+        (cause) =>
+          Effect.fail(
+            new PersistedQueueError({
+              message: "Failed to offer element to persisted queue",
+              cause
+            })
+          )
+      ).pipe(
+        Effect.tap(() =>
+          Effect.sync(() => {
+            queueStates.peek(name)?.nudge.openUnsafe()
+          })
+        )
+      ),
     take: (options) => {
       queueStates.get(options.name).maxAttempts = options.maxAttempts
       const loop: Effect.Effect<

package/src/rpc/RpcClient.ts

@@ -1066,11 +1066,19 @@ export const makeProtocolSocket = (options?: {
   readonly retryPolicy?: Schedule.Schedule<any, Socket.SocketError> | undefined
   /**
    * Runs for each retried `SocketOpenError` when `retryTransientErrors` is enabled.
-   * A ping timeout fails in-flight calls and is not reported through this hook.
-   * The returned `Effect<void>` cannot fail with a typed error or require
-   * services; defects are logged and ignored so retries can continue.
+   * A ping timeout fails in-flight calls and is reported through `onPingTimeout`
+   * instead. The returned `Effect<void>` cannot fail with a typed error or
+   * require services; defects are logged and ignored so retries can continue.
    */
   readonly onTransientError?: ((error: RpcClientError) => Effect.Effect<void>) | undefined
+  /**
+   * Runs when an open connection is dropped because no server frame arrived
+   * within `pingTimeout`, before `ConnectionHooks.onDisconnect` and before
+   * in-flight calls fail with a `SocketReadError`. Defects are logged and ignored.
+   *
+   * @since 4.0.3
+   */
+  readonly onPingTimeout?: Effect.Effect<void> | undefined
 }): Effect.Effect<
   Protocol["Service"],
   never,
@@ -1086,10 +1094,12 @@ export const makeProtocolSocket = (options?: {
 
     let parser = serialization.makeUnsafe()
 
-    // `parser` is replaced on every connect, and a stateful serialization
-    // encodes against the connection it is writing to, so the ping is encoded
-    // when it is sent rather than once up front.
+    // Encode each ping with the current connection's parser.
     const pinger = yield* makePinger(Effect.suspend(() => writer.write(parser.encode(constPing)!)), options)
+    const onPingTimeout = Effect.ignoreCause(options?.onPingTimeout ?? Effect.void, {
+      log: true,
+      message: "RpcClient onPingTimeout hook failed"
+    })
     let currentError: RpcClientError | undefined
 
     const broadcast = (response: FromServerEncoded) =>
@@ -1143,9 +1153,11 @@ export const makeProtocolSocket = (options?: {
     yield* Effect.suspend(() => {
       parser = serialization.makeUnsafe()
       pinger.reset()
+      let connected = false
       return Effect.gen(function*() {
         const { pull } = yield* socket.reader
         currentError = undefined
+        connected = true
         if (Option.isSome(hooks)) {
           yield* hooks.value.onConnect
         }
@@ -1157,17 +1169,19 @@ export const makeProtocolSocket = (options?: {
         }
       }).pipe(
         Effect.scoped,
-        Effect.raceFirst(Effect.flatMap(
-          pinger.timeout,
-          () =>
-            Effect.fail(
-              new Socket.SocketError({
-                reason: new Socket.SocketReadError({
-                  cause: new Error("ping timeout")
-                })
+        // The read loop never succeeds, so the race only succeeds on a ping
+        // timeout, after the socket has been cleaned up.
+        Effect.raceFirst(pinger.timeout),
+        Effect.andThen(() => connected ? onPingTimeout : Effect.void),
+        Effect.andThen(() =>
+          Effect.fail(
+            new Socket.SocketError({
+              reason: new Socket.SocketReadError({
+                cause: new Error("ping timeout")
               })
-            )
-        ))
+            })
+          )
+        )
       )
     }).pipe(
       Option.isSome(hooks) ? Effect.ensuring(hooks.value.onDisconnect) : identity,
@@ -1278,11 +1292,19 @@ export const layerProtocolSocket = (options?: {
   readonly retryPolicy?: Schedule.Schedule<any, Socket.SocketError> | undefined
   /**
    * Runs for each retried `SocketOpenError` when `retryTransientErrors` is enabled.
-   * A ping timeout fails in-flight calls and is not reported through this hook.
-   * The returned `Effect<void>` cannot fail with a typed error or require
-   * services; defects are logged and ignored so retries can continue.
+   * A ping timeout fails in-flight calls and is reported through `onPingTimeout`
+   * instead. The returned `Effect<void>` cannot fail with a typed error or
+   * require services; defects are logged and ignored so retries can continue.
    */
   readonly onTransientError?: ((error: RpcClientError) => Effect.Effect<void>) | undefined
+  /**
+   * Runs when an open connection is dropped because no server frame arrived
+   * within `pingTimeout`, before `ConnectionHooks.onDisconnect` and before
+   * in-flight calls fail with a `SocketReadError`. Defects are logged and ignored.
+   *
+   * @since 4.0.3
+   */
+  readonly onPingTimeout?: Effect.Effect<void> | undefined
 }): Layer.Layer<
   Protocol,
   never,