effect 4.1.1 → 4.1.2

package/src/cluster/Sharding.ts

@@ -143,7 +143,20 @@ export class Sharding extends Context.Service<Sharding, {
       readonly concurrency?: number | "unbounded" | undefined
       readonly mailboxCapacity?: number | "unbounded" | undefined
       readonly mailboxMetrics?: boolean | undefined
+      /**
+       * When `true`, a handler defect fails only its request instead of
+       * restarting the entity and replaying its in-flight requests.
+       */
       readonly disableFatalDefects?: boolean | undefined
+      /**
+       * Schedule for restarting an entity after a defect and for retrying failed
+       * handler construction.
+       *
+       * Backoff is tracked per entity and resets once a request completes.
+       * When the policy ends, the default (500 ms growing by 1.5x, capped at 10
+       * seconds) continues, so restarts never stop; use `disableFatalDefects` to
+       * avoid them.
+       */
       readonly defectRetryPolicy?: Schedule.Schedule<any, unknown> | undefined
       readonly spanAttributes?: Record<string, string> | undefined
     }

package/src/cluster/internal/clusterAbandon.ts

@@ -1,14 +1,14 @@
 import type * as Cause from "../../Cause.ts"
 import * as Effect from "../../Effect.ts"
-import * as Fiber from "../../Fiber.ts"
 import { Abandon } from "../ClusterSchema.ts"
 
-export const interrupt: Effect.Effect<never> = Effect.interruptible(
-  Effect.callback<never>(() => {
-    const fiber = Fiber.getCurrent()!
-    fiber.interruptUnsafe(fiber.id, Abandon.annotation)
-  })
-)
+// Annotate before opening the interruptible region. An interrupt already
+// pending on an uninterruptible fiber fires as soon as the region opens, and
+// the annotation is merged into that pending cause instead of being lost.
+export const interrupt: Effect.Effect<never> = Effect.withFiber((fiber) => {
+  fiber.interruptUnsafe(fiber.id, Abandon.annotation)
+  return Effect.interruptible(Effect.never)
+})
 
 export const isCause = (cause: Cause.Cause<unknown>): boolean =>
   cause.reasons.some((reason) => reason._tag === "Interrupt" && reason.annotations.has(Abandon.key))

package/src/cluster/internal/entityManager.ts

@@ -116,6 +116,10 @@ export type EntityState = {
     /** Set when the request should not outlive its caller. */
     callerScope?: Scope.Scope | undefined
     transaction?: RequestTransaction | undefined
+    /** Set when an interrupt arrives while no handlers are ready. */
+    interrupted?: boolean | undefined
+    /** The handler generation the remembered interrupt was last sent to. */
+    interruptSentTo?: EntityState["write"] | undefined
   }>
   lastActiveCheck: number
   write: RpcServer.RpcServer<any>["write"]
@@ -172,7 +176,7 @@ export const make = Effect.fnUntraced(function*<
   const defectRetryPolicy = options.defectRetryPolicy
     ? Schedule.concat(options.defectRetryPolicy, defaultRetryPolicy)
     : defaultRetryPolicy
-  const retryDriver = yield* Schedule.toStepWithSleep(defectRetryPolicy)
+  const newRestartStep = Schedule.toStepWithSleep(defectRetryPolicy)
   const entityRpcs = new Map(entity.protocol.requests)
 
   // The series reads the mailbox size on snapshot, so delivery does no extra work.
@@ -294,13 +298,38 @@ export const make = Effect.fnUntraced(function*<
     const retired = Latch.makeUnsafe()
     const isActive = () => !retired.isOpen()
 
+    // Per-activation restart backoff, reset when a request completes.
+    let restartStep: Effect.Success<typeof newRestartStep> | undefined
+    const restartDelay = Effect.gen(function*() {
+      restartStep ??= yield* newRestartStep
+      yield* restartStep(void 0)
+    })
+
+    // An interrupted request is not run again. The server answers the
+    // interrupt as it would for a request without a running handler. Each
+    // generation receives it at most once, and the flag stays so a later
+    // generation still applies it if this one fails first.
+    const writeInterrupt = (
+      request: {
+        readonly message: Message.IncomingRequestLocal<any>
+        interruptSentTo?: EntityState["write"] | undefined
+      },
+      write: EntityState["write"]
+    ): Effect.Effect<void> => {
+      if (request.interruptSentTo === write) return Effect.void
+      request.interruptSentTo = write
+      return write(0, interruptEnvelope(request))
+    }
+
     // Replay previously dispatched requests before admitting new work.
     const replay = Effect.fnUntraced(function*(write: EntityState["write"]) {
       if (!isActive()) return
       for (const request of activeRequests.values()) {
         if (!request.delivered) continue
         request.sentExit = false
-        yield* write(0, requestEnvelope(request), requestWriteOptions(request))
+        yield* request.interrupted
+          ? writeInterrupt(request, write)
+          : write(0, requestEnvelope(request), requestWriteOptions(request))
       }
     })
 
@@ -405,6 +434,7 @@ export const make = Effect.fnUntraced(function*<
                   )
                 })
                 const complete = Effect.sync(() => {
+                  restartStep = undefined
                   if (storageEnabled) {
                     processedRequestIds.add(request.message.envelope.requestId)
                   }
@@ -527,10 +557,22 @@ export const make = Effect.fnUntraced(function*<
       address
     )
 
+    // Forward interrupts remembered after their request was replayed, which
+    // the replacement handlers have not seen yet.
+    const forwardInterrupts = Effect.suspend(() => {
+      const write = writeRef.getUnsafe()
+      if (write === undefined) return Effect.void
+      const interrupts: Array<Effect.Effect<void>> = []
+      for (const request of activeRequests.values()) {
+        if (request.interrupted) interrupts.push(writeInterrupt(request, write))
+      }
+      return Effect.all(interrupts, { discard: true })
+    })
+
     function restart(cause: Cause.Cause<unknown>, rebuild: Effect.Effect<void>): Effect.Effect<void> {
       return Effect.logError("Defect in entity, restarting", cause).pipe(
-        Effect.andThen(Effect.ignore(retryDriver(void 0))),
-        Effect.flatMap(() => isActive() ? rebuild : endLatch.open),
+        Effect.andThen(Effect.ignore(restartDelay)),
+        Effect.flatMap(() => isActive() ? Effect.andThen(rebuild, forwardInterrupts) : endLatch.open),
         Effect.annotateLogs({
           module: "EntityManager",
           address,
@@ -552,6 +594,16 @@ export const make = Effect.fnUntraced(function*<
           if (message._tag !== "Request") {
             // Interrupts, acks and EOF reach the handlers even during shutdown.
             const write = writeRef.getUnsafe()
+            if (write === undefined && message._tag === "Interrupt") {
+              // Waiting could stall the sender indefinitely if every rebuild
+              // fails, so remember the interrupt for the next generation.
+              // Uninterruptible requests ignore it.
+              const request = activeRequests.get(Snowflake.Snowflake(message.requestId))
+              if (request && !isUninterruptibleForServer(request.message.annotations)) {
+                request.interrupted = true
+              }
+              return Effect.void
+            }
             return write
               ? write(clientId, message, writeOptions)
               : Effect.flatMap(writeRef.await, (write) => write(clientId, message, writeOptions))
@@ -567,7 +619,7 @@ export const make = Effect.fnUntraced(function*<
           const request = activeRequests.get(Snowflake.Snowflake(message.id))
           if (!request) return Effect.void
           request.delivered = true
-          return write(clientId, message, writeOptions)
+          return request.interrupted ? writeInterrupt(request, write) : write(clientId, message, writeOptions)
         })
       },
       activeRequests,
@@ -1016,6 +1068,14 @@ const requestEnvelope = (entry: {
   } as any) as any
 })
 
+const interruptEnvelope = (entry: {
+  readonly message: Message.IncomingRequestLocal<any>
+}): Parameters<EntityState["write"]>[1] => ({
+  _tag: "Interrupt",
+  requestId: entry.message.envelope.requestId as any,
+  interruptors: []
+})
+
 const retryRespond = <A, E, R>(times: number, effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
   times === 0 ?
     effect :

package/src/cluster/internal/transactionNotifications.ts

@@ -0,0 +1,7 @@
+import * as Context from "../../Context.ts"
+import type * as Effect from "../../Effect.ts"
+import type { MalformedMessage, PersistenceError } from "../ClusterError.ts"
+
+export const TransactionNotifications = Context.Reference<
+  Array<Effect.Effect<void, PersistenceError | MalformedMessage>> | undefined
+>("effect/cluster/MessageStorage/TransactionNotifications", { defaultValue: () => undefined })

package/src/encoding/Json5.ts

@@ -0,0 +1,59 @@
+/**
+ * Parses JSON5 configuration files without external dependencies.
+ *
+ * The compatibility target is [JSON5 1.0.0](https://spec.json5.org/) and the
+ * value-parsing behavior of `json5` 2.2.3, without its optional reviver.
+ * Identifier names use the runtime's Unicode property tables.
+ *
+ * @stability unstable
+ * @since 4.1.2
+ */
+
+import * as internal from "../internal/jsonParser.ts"
+import * as Result from "../Result.ts"
+import { EncodingError } from "./EncodingError.ts"
+
+/**
+ * Parses a JSON5 document into a JavaScript value.
+ *
+ * **Details**
+ *
+ * Returns `Result.succeed` with the parsed value, or `Result.fail` with an
+ * `EncodingError` when the input is not valid JSON5. Accepts comments,
+ * trailing commas, unquoted identifier keys, single-quoted strings,
+ * hexadecimal numbers, `Infinity`, and `NaN`. Duplicate keys use the last
+ * value; `__proto__` is preserved as an own data property.
+ *
+ * **Gotchas**
+ *
+ * Error messages give a line and column but do not include the input text.
+ * Unlike `JSON.parse`, this function has no reviver.
+ *
+ * **Example** (Parsing a JSON5 document)
+ *
+ * ```ts import.meta.vitest
+ * import { Result } from "effect"
+ * import { Json5 } from "effect/encoding"
+ *
+ * Json5.parse("{ port: 8080, }") // => Result.succeed({ port: 8080 })
+ * Result.isFailure(Json5.parse("{ port: }")) // => true
+ * ```
+ *
+ * @stability unstable
+ * @category decoding
+ * @since 4.1.2
+ */
+export const parse = (input: string): Result.Result<unknown, EncodingError> => {
+  try {
+    return Result.succeed(internal.parse(input, "JSON5"))
+  } catch (e) {
+    return Result.fail(
+      new EncodingError({
+        module: "Json5",
+        kind: "Decode",
+        input,
+        message: e instanceof Error ? e.message : "Invalid input"
+      })
+    )
+  }
+}

package/src/encoding/Jsonc.ts

@@ -0,0 +1,126 @@
+/**
+ * Parses JSON with JavaScript-style comments without external dependencies.
+ *
+ * The syntax target is the [JSONC draft specification](https://jsonc.org/)
+ * with `jsonc-parser` 3.3.1's default profile: JSON plus line and block comments,
+ * with trailing commas disabled. One leading BOM is accepted, matching the
+ * TOML and YAML parsers. Decoded values follow `JSON.parse` semantics; invalid
+ * documents fail instead of returning a partial result.
+ *
+ * @stability unstable
+ * @since 4.1.2
+ */
+
+import * as internal from "../internal/jsonParser.ts"
+import * as Result from "../Result.ts"
+import { EncodingError } from "./EncodingError.ts"
+
+const fail = (input: string): never => {
+  // Native errors differ across engines and may quote the input, so the strict parser
+  // locates the error. It accepts exactly what JSON.parse accepts once comments are
+  // removed; the final throw only guards against an engine that disagrees.
+  internal.parse(input, "JSONC")
+  throw internal.syntaxError(input, input.length, "JSONC")
+}
+
+const lineEnd = /[\r\n]/g
+
+const parseUnsafe = (input: string): unknown => {
+  // Ignore one leading BOM without shifting original-input error positions.
+  if (input.charCodeAt(0) === 0xfeff) input = " " + input.slice(1)
+  let slash = input.indexOf("/")
+  let json = input
+  if (slash !== -1) {
+    let stripped = ""
+    let start = 0
+    let quote = input.indexOf("\"")
+    while (slash !== -1) {
+      if (quote !== -1 && quote < slash) {
+        // Skip the string; a quote after an odd run of backslashes is escaped.
+        let end = quote
+        for (;;) {
+          end = input.indexOf("\"", end + 1)
+          if (end === -1) break
+          let backslash = end - 1
+          while (input.charCodeAt(backslash) === 92) backslash--
+          if ((end - backslash) % 2 === 1) break
+        }
+        if (end === -1) break
+        quote = input.indexOf("\"", end + 1)
+        if (slash < end) slash = input.indexOf("/", end + 1)
+        continue
+      }
+      const next = input.charCodeAt(slash + 1)
+      let index: number
+      if (next === 47) {
+        lineEnd.lastIndex = slash + 2
+        index = lineEnd.test(input) ? lineEnd.lastIndex - 1 : input.length
+      } else if (next === 42) {
+        const end = input.indexOf("*/", slash + 2)
+        if (end === -1) fail(input)
+        index = end + 2
+      } else {
+        // Not a comment; JSON.parse rejects it below.
+        slash = input.indexOf("/", slash + 1)
+        continue
+      }
+      // A space prevents comments inside invalid tokens from joining those tokens.
+      stripped += input.slice(start, slash) + " "
+      start = index
+      slash = input.indexOf("/", index)
+      if (quote !== -1 && quote < index) quote = input.indexOf("\"", index)
+    }
+    json = stripped + input.slice(start)
+  }
+  try {
+    return JSON.parse(json)
+  } catch {
+    return fail(input)
+  }
+}
+
+/**
+ * Parses a JSONC document into a JavaScript value.
+ *
+ * **Details**
+ *
+ * Returns `Result.succeed` with the parsed value, or `Result.fail` with an
+ * `EncodingError` when the input is not valid JSONC. Accepts one leading BOM
+ * and line and block comments wherever JSON permits whitespace. All other
+ * syntax follows `JSON.parse`, including duplicate keys and `__proto__`
+ * handling.
+ *
+ * **Gotchas**
+ *
+ * Error messages give a 1-based line and column, counted in UTF-16 code units,
+ * but do not include the input text. Trailing commas and JSON5 extensions are
+ * not accepted. Unlike `JSON.parse`, this function has no reviver.
+ *
+ * **Example** (Parsing a JSONC document)
+ *
+ * ```ts import.meta.vitest
+ * import { Result } from "effect"
+ * import { Jsonc } from "effect/encoding"
+ *
+ * Jsonc.parse("{ \"port\": 8080 } // comment") // => Result.succeed({ port: 8080 })
+ * Result.isFailure(Jsonc.parse("{ \"port\": 8080, }")) // => true
+ * ```
+ *
+ * @stability unstable
+ * @category decoding
+ * @since 4.1.2
+ */
+export const parse = (input: string): Result.Result<unknown, EncodingError> => {
+  try {
+    return Result.succeed(parseUnsafe(input))
+  } catch (e) {
+    return Result.fail(
+      new EncodingError({
+        module: "Jsonc",
+        kind: "Decode",
+        input,
+        message: e instanceof Error ? e.message : "Invalid input"
+      })
+    )
+  }
+}