effect 4.0.5 → 4.0.7

package/src/rpc/RpcSerialization.ts

@@ -95,6 +95,18 @@ export class MaxBufferSizeExceeded extends Data.TaggedError("MaxBufferSizeExceed
   }
 }
 
+/**
+ * Error raised when a non-empty NDJSON frame is not valid JSON.
+ * The `cause` field preserves the original JSON parsing error.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.0.0
+ */
+export class NdjsonDecodeError extends Data.TaggedError("NdjsonDecodeError")<{
+  readonly cause: unknown
+}> {}
+
 /**
  * Options shared by streaming RPC serialization formats.
  *
@@ -150,7 +162,7 @@ export const json: RpcSerialization["Service"] = RpcSerialization.of({
 export const makeNdjson = (options?: StreamOptions): RpcSerialization["Service"] => {
   const maxBufferSize = options?.maxBufferSize ?? defaultMaxBufferSize
   return RpcSerialization.of({
-    contentType: "application/ndjson",
+    contentType: "application/x-ndjson",
     includesFraming: true,
     codecFor: codecForJson,
     makeUnsafe: () => {
@@ -171,11 +183,15 @@ export const makeNdjson = (options?: StreamOptions): RpcSerialization["Service"]
             if (isBufferSizeExceeded(nlIndex - position, maxBufferSize)) {
               failMaxBufferSize(maxBufferSize)
             }
-            const line = buffer.slice(position, nlIndex)
+            const line = buffer.slice(position, buffer[nlIndex - 1] === "\r" ? nlIndex - 1 : nlIndex)
             position = nlIndex + 1
-            try {
-              items.push(JSON.parse(line))
-            } catch {
+            if (line.length > 0) {
+              try {
+                items.push(JSON.parse(line))
+              } catch (cause) {
+                buffer = ""
+                throw new NdjsonDecodeError({ cause })
+              }
             }
             nlIndex = buffer.indexOf("\n", position)
           }
@@ -214,18 +230,25 @@ export const ndjson: RpcSerialization["Service"] = makeNdjson()
  * Creates a JSON-RPC 2.0 serialization for RPC protocol messages without
  * additional message framing.
  *
+ * **Details**
+ *
+ * Set `controlMessages` to `false` for plain JSON-RPC peers, so
+ * `@effect/rpc/*` methods are not decoded as RPC control messages.
+ *
  * @stability unstable
  * @category serialization
  * @since 4.0.0
  */
 export const jsonRpc = (options?: {
   readonly contentType?: string | undefined
+  readonly controlMessages?: boolean | undefined
 }): RpcSerialization["Service"] =>
   RpcSerialization.of({
     contentType: options?.contentType ?? "application/json",
     includesFraming: false,
     codecFor: codecForJson,
     makeUnsafe: () => {
+      const controlMessages = options?.controlMessages ?? true
       const batches = new Map<string | number, {
         readonly size: number
         readonly responses: Map<string | number, RpcMessage.FromServerEncoded>
@@ -235,7 +258,7 @@ export const jsonRpc = (options?: {
           const decoded: unknown = JSON.parse(
             typeof bytes === "string" ? bytes : decodeText(bytes)
           )
-          return decodeJsonRpcRaw(decoded, batches)
+          return decodeJsonRpcRaw(decoded, batches, controlMessages)
         },
         encode: (response) => {
           const encoded = encodeJsonRpcResponse(response as any, batches)
@@ -249,6 +272,11 @@ export const jsonRpc = (options?: {
  * Creates a newline-delimited JSON-RPC 2.0 serialization for RPC protocol
  * messages.
  *
+ * **Details**
+ *
+ * Set `controlMessages` to `false` for plain JSON-RPC peers, so
+ * `@effect/rpc/*` methods are not decoded as RPC control messages.
+ *
  * @stability unstable
  * @category serialization
  * @since 4.0.0
@@ -256,6 +284,7 @@ export const jsonRpc = (options?: {
 export const ndJsonRpc = (options?: {
   readonly contentType?: string | undefined
   readonly maxBufferSize?: number | "unbounded" | undefined
+  readonly controlMessages?: boolean | undefined
 }): RpcSerialization["Service"] =>
   RpcSerialization.of({
     contentType: options?.contentType ?? "application/json-rpc",
@@ -263,6 +292,7 @@ export const ndJsonRpc = (options?: {
     codecFor: codecForJson,
     makeUnsafe: () => {
       const parser = makeNdjson({ maxBufferSize: options?.maxBufferSize }).makeUnsafe()
+      const controlMessages = options?.controlMessages ?? true
       const batches = new Map<string, {
         readonly size: number
         readonly responses: Map<string, RpcMessage.FromServerEncoded>
@@ -273,7 +303,7 @@ export const ndJsonRpc = (options?: {
           if (frames.length === 0) return []
           const messages: Array<RpcMessage.FromClientEncoded | RpcMessage.FromServerEncoded> = []
           for (let i = 0; i < frames.length; i++) {
-            messages.push(...decodeJsonRpcRaw(frames[i], batches))
+            messages.push(...decodeJsonRpcRaw(frames[i], batches, controlMessages))
           }
           return messages
         },
@@ -290,7 +320,8 @@ function decodeJsonRpcRaw(
   batches: Map<string | number, {
     readonly size: number
     readonly responses: Map<string | number, RpcMessage.FromServerEncoded>
-  }>
+  }>,
+  controlMessages: boolean
 ) {
   if (Array.isArray(decoded)) {
     const batch = {
@@ -301,7 +332,7 @@ function decodeJsonRpcRaw(
     for (let i = 0; i < decoded.length; i++) {
       const item = decoded[i]
       if (!Predicate.isObject(item)) continue
-      const message = decodeJsonRpcMessage(item as unknown as JsonRpcMessage)
+      const message = decodeJsonRpcMessage(item as unknown as JsonRpcMessage, controlMessages)
       messages.push(message)
       if (message._tag === "Request" && !message.isNotification) {
         batch.size++
@@ -310,14 +341,20 @@ function decodeJsonRpcRaw(
     }
     return messages
   }
-  return Predicate.isObject(decoded) ? [decodeJsonRpcMessage(decoded as unknown as JsonRpcMessage)] : []
+  return Predicate.isObject(decoded)
+    ? [decodeJsonRpcMessage(decoded as unknown as JsonRpcMessage, controlMessages)]
+    : []
 }
 
-function decodeJsonRpcMessage(decoded: JsonRpcMessage): RpcMessage.FromClientEncoded | RpcMessage.FromServerEncoded {
+function decodeJsonRpcMessage(
+  decoded: JsonRpcMessage,
+  controlMessages: boolean
+): RpcMessage.FromClientEncoded | RpcMessage.FromServerEncoded {
   if (Object.hasOwn(decoded, "method")) {
     const request = decoded as JsonRpcRequest
     if (
-      Predicate.isNullish(request.id) && Predicate.isString(request.method) && request.method.startsWith("@effect/rpc/")
+      controlMessages && Predicate.isNullish(request.id) && Predicate.isString(request.method) &&
+      request.method.startsWith("@effect/rpc/")
     ) {
       const tag = request.method.slice("@effect/rpc/".length) as
         | RpcMessage.FromServerEncoded["_tag"]
@@ -387,13 +424,13 @@ function encodeJsonRpcRaw(
     readonly responses: Map<string | number, RpcMessage.FromServerEncoded>
   }>
 ) {
-  if (!("requestId" in response)) {
+  if (response._tag !== "Exit") {
     return encodeJsonRpcMessage(response)
   }
   const batch = batches.get(response.requestId)
   if (batch) {
     batches.delete(response.requestId)
-    batch.responses.set(response.requestId, response as any)
+    batch.responses.set(response.requestId, response)
     if (batch.size === batch.responses.size) {
       return Array.from(batch.responses.values(), encodeJsonRpcMessage)
     }
@@ -628,6 +665,7 @@ export const layerNdjsonWith = (options?: StreamOptions): Layer.Layer<RpcSeriali
  */
 export const layerJsonRpc = (options?: {
   readonly contentType?: string | undefined
+  readonly controlMessages?: boolean | undefined
 }): Layer.Layer<RpcSerialization> => Layer.succeed(RpcSerialization)(jsonRpc(options))
 
 /**
@@ -641,6 +679,7 @@ export const layerJsonRpc = (options?: {
 export const layerNdJsonRpc = (options?: {
   readonly contentType?: string | undefined
   readonly maxBufferSize?: number | "unbounded" | undefined
+  readonly controlMessages?: boolean | undefined
 }): Layer.Layer<RpcSerialization> => Layer.succeed(RpcSerialization)(ndJsonRpc(options))
 
 /**

package/src/rpc/RpcServer.ts

@@ -12,6 +12,7 @@
  * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "../Array.ts"
+import * as Bytes from "../Bytes.ts"
 import * as Cause from "../Cause.ts"
 import * as Context from "../Context.ts"
 import * as Deferred from "../Deferred.ts"
@@ -277,7 +278,7 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any>(
       headers: request.headers,
       payload: request.payload
     }
-    const result = entry.handler(request.payload, metadata)
+    const result = runHandler(entry, request.payload, metadata)
 
     // if the handler requested forking, then we skip the concurrency control
     const isWrapper = Rpc.isWrapper(result)
@@ -513,14 +514,16 @@ const rpcCodecs = (codecFor: RpcSerialization.CodecFor, rpc: Rpc.AnyWithProps):
   let codecs = shared ? sharedRpcCodecs.get(rpc) : undefined
   if (codecs === undefined) {
     const streamSchemas = RpcSchema.getStreamSchemas(rpc.successSchema)
+    const parseOptions = Context.get(rpc.annotations, Rpc.ParseOptions)
     codecs = {
-      decode: Schema.decodeUnknownEffect(codecFor(rpc.payloadSchema)) as any,
+      decode: Schema.decodeUnknownEffect(codecFor(rpc.payloadSchema), parseOptions) as any,
       encodeChunk: Schema.encodeUnknownEffect(
         codecFor(
           Schema.NonEmptyArray(Option.isSome(streamSchemas) ? streamSchemas.value.success : Schema.Any)
-        )
+        ),
+        parseOptions
       ) as any,
-      encodeExit: Schema.encodeUnknownEffect(codecFor(Rpc.exitSchema(rpc as any))) as any
+      encodeExit: Schema.encodeUnknownEffect(codecFor(Rpc.exitSchema(rpc as any)), parseOptions) as any
     }
     if (shared) sharedRpcCodecs.set(rpc, codecs)
   }
@@ -571,6 +574,21 @@ const handlerContext = (
   return merged
 }
 
+// a synchronous throw is handled like a returned `Effect.die`, so it goes
+// through the request exit handling. Stream handlers may also return an
+// Effect, so a single `Effect.die` covers both kinds of rpc.
+const runHandler = (
+  entry: Rpc.Handler<string>,
+  payload: unknown,
+  metadata: Parameters<Rpc.Handler<string>["handler"]>[1]
+) => {
+  try {
+    return entry.handler(payload, metadata)
+  } catch (defect) {
+    return Effect.die(defect)
+  }
+}
+
 const applyMiddleware = <A, E, R>(
   context: Context.Context<never>,
   handler: Effect.Effect<A, E, R>,
@@ -1246,8 +1264,9 @@ export const makeProtocolWithHttpEffect: (
 
     yield* writeRequest(id, constEof)
 
+    // Allow request aborts during response waits without unmasking response construction.
     if (!includesFraming) {
-      const responses = yield* Queue.collect(queue)
+      const responses = yield* Effect.interruptible(Queue.collect(queue))
       // Notification-only batches encode without a response body.
       const encoded = parser.encode(responses)
       return HttpServerResponse.text(encoded === undefined ? "" : encoded as string, {
@@ -1255,12 +1274,12 @@ export const makeProtocolWithHttpEffect: (
       })
     }
 
-    const initialChunk = yield* Pull.catchDone(
+    const initialChunk = yield* Effect.interruptible(Pull.catchDone(
       Queue.takeAll(queue as Queue.Dequeue<Uint8Array, Cause.Done>),
       () => Effect.succeed([])
-    )
+    ))
     if (queue.state._tag === "Done") {
-      return HttpServerResponse.uint8Array(mergeUint8Arrays(initialChunk), {
+      return HttpServerResponse.uint8Array(initialChunk.length === 1 ? initialChunk[0] : Bytes.concat(initialChunk), {
         contentType: serialization.contentType
       })
     }
@@ -1302,19 +1321,6 @@ export const makeProtocolWithHttpEffect: (
   return { protocol, httpEffect } as const
 })
 
-const mergeUint8Arrays = (arrays: ReadonlyArray<Uint8Array>) => {
-  if (arrays.length === 0) return new Uint8Array(0)
-  if (arrays.length === 1) return arrays[0]
-  const length = arrays.reduce((acc, arr) => acc + arr.length, 0)
-  const result = new Uint8Array(length)
-  let offset = 0
-  for (const arr of arrays) {
-    result.set(arr, offset)
-    offset += arr.length
-  }
-  return result
-}
-
 /**
  * Creates an HTTP server `Protocol` and registers its request handler as a POST
  * route on the current `HttpRouter`.

package/src/rpc/RpcTest.ts

@@ -29,6 +29,7 @@ export const makeClient: <Rpcs extends Rpc.Any, const Flatten extends boolean =
   group: RpcGroup.RpcGroup<Rpcs>,
   options?: {
     readonly flatten?: Flatten | undefined
+    readonly disableFatalDefects?: boolean | undefined
   }
 ) => Effect.Effect<
   Flatten extends true ? RpcClient.RpcClient.Flat<Rpcs> : RpcClient.RpcClient<Rpcs>,
@@ -38,11 +39,13 @@ export const makeClient: <Rpcs extends Rpc.Any, const Flatten extends boolean =
   group: RpcGroup.RpcGroup<Rpcs>,
   options?: {
     readonly flatten?: Flatten | undefined
+    readonly disableFatalDefects?: boolean | undefined
   }
 ) {
   // oxlint-disable-next-line prefer-const
   let client!: Effect.Success<ReturnType<typeof RpcClient.makeNoSerialization<Rpcs, never, Flatten>>>
   const server = yield* RpcServer.makeNoSerialization(group, {
+    disableFatalDefects: options?.disableFatalDefects,
     onFromServer(response) {
       return client.write(response)
     }

package/src/schema/VariantSchema.ts

@@ -241,9 +241,9 @@ const extract: {
     if (options?.isDefault === true && Schema.isSchema(self)) {
       return self as any
     }
-    const cache = options?.isDefault === true
-      ? self[defaultCacheSymbol] ?? (self[defaultCacheSymbol] = Object.create(null))
-      : self[cacheSymbol] ?? (self[cacheSymbol] = Object.create(null))
+    // own caches only, so extended classes never reuse their parent's variants
+    const cacheKey = options?.isDefault === true ? defaultCacheSymbol : cacheSymbol
+    const cache = Object.hasOwn(self, cacheKey) ? self[cacheKey]! : (self[cacheKey] = Object.create(null))
     if (Object.hasOwn(cache, variant)) {
       return cache[variant] as any
     }
@@ -298,8 +298,11 @@ export interface Class<
   Fields extends Struct.Fields,
   S extends Schema.Top & {
     readonly fields: Schema.Struct.Fields
-  }
-> extends Schema.Class<Self, S, {}>, Struct<Struct_.Simplify<Fields>> {
+  },
+  Variants extends string = never,
+  Default extends string = never,
+  Inherited = {}
+> extends Schema.Class<Self, S, Inherited>, Struct<Struct_.Simplify<Fields>> {
   readonly "Type": Self
   readonly "Encoded": S["Encoded"]
   readonly "DecodingServices": S["DecodingServices"]
@@ -313,7 +316,7 @@ export interface Class<
     options?: {
       readonly disableChecks?: boolean
     } | undefined
-  ): S["Type"]
+  ): S["Type"] & Inherited
 
   make<Args extends Array<any>, X>(
     this: { new(...args: Args): X },
@@ -321,8 +324,57 @@ export interface Class<
   ): X
 
   readonly fields: S["fields"]
+
+  /**
+   * Returns a function that creates a variant schema subclass with this
+   * class's fields plus additional fields, regenerating every variant schema
+   * from the merged fields.
+   *
+   * **Gotchas**
+   *
+   * Fields with the same name replace inherited fields in every variant. A
+   * replacement that omits an inherited field from the default variant does
+   * not remove it from the class schema; the caller must ensure replacements
+   * preserve the base class contract.
+   */
+  readonly extend:
+    & (<Extended = never, Static = {}, Brand = {}>(
+      identifier: string
+    ) => {
+      <const NewFields extends Struct.Fields>(
+        fields: NewFields & Struct.Validate<NewFields, Variants>,
+        annotations?:
+          | Schema.Annotations.Declaration<
+            Extended,
+            readonly [Schema.Struct<ExtractFields<Default, Struct_.Assign<Fields, NewFields>, true>>]
+          >
+          | undefined
+      ): ExtendedClass<Extended, Static, Self & Brand, Struct_.Assign<Fields, NewFields>, Variants, Default>
+      <Extension extends Schema.Struct<Schema.Struct.Fields>>(
+        schema: Extension,
+        annotations?:
+          | Schema.Annotations.Declaration<
+            Extended,
+            readonly [Schema.Struct<ExtractFields<Default, Struct_.Assign<Fields, Extension["fields"]>, true>>]
+          >
+          | undefined
+      ): ExtendedClass<Extended, Static, Self & Brand, Struct_.Assign<Fields, Extension["fields"]>, Variants, Default>
+    })
+    & Schema.Class<Self, S, Inherited>["extend"]
 }
 
+type ExtendedClass<
+  Self,
+  Static,
+  Inherited,
+  Fields extends Struct.Fields,
+  Variants extends string,
+  Default extends string
+> = [Self] extends [never] ? "Missing `Self` generic - use `class Self extends Base.extend<Self>(...)`" :
+  & Class<Self, Fields, Schema.Struct<ExtractFields<Default, Fields, true>>, Variants, Default, Inherited>
+  & { readonly [V in Variants]: Extract<V, Struct<Fields>> }
+  & Pick<Static, Exclude<keyof Static, keyof Class<any, any, any> | Variants>>
+
 type MissingSelfGeneric<Params extends string = ""> =
   `Missing \`Self\` generic - use \`class Self extends Class<Self>()(${Params}{ ... })\``
 
@@ -444,7 +496,9 @@ export const make = <
       & Class<
         Self,
         Fields,
-        Schema.Struct<ExtractFields<Default, Fields, true>>
+        Schema.Struct<ExtractFields<Default, Fields, true>>,
+        Variants[number],
+        Default
       >
       & {
         readonly [V in Variants[number]]: Extract<V, Struct<Fields>>
@@ -470,24 +524,34 @@ export const make = <
         readonly [Schema.Struct<ExtractFields<Default, typeof fields, true>>]
       >
     ) {
-      const variantStruct = Struct(fields)
-      const schema = extract(variantStruct, options.defaultVariant, {
-        isDefault: true
-      })
-      const SClass = Schema.Class as any
-      class Base extends SClass(identifier)(schema.fields, annotations) {
-        static [TypeId] = fields
+      return makeClass(fields, (defaultFields) => (Schema.Class as any)(identifier)(defaultFields, annotations))
+    }
+  }
+  function makeClass(fields: Struct.Fields, makeSchemaClass: (defaultFields: Schema.Struct.Fields) => any) {
+    const struct = Struct(fields)
+    const SchemaClass = makeSchemaClass(extract(struct, options.defaultVariant, { isDefault: true }).fields)
+    class Base extends SchemaClass {
+      static [TypeId] = fields
+      static extend(identifier: string) {
+        const extend = super.extend(identifier)
+        return (
+          extension: Struct.Fields | Schema.Struct<Schema.Struct.Fields>,
+          annotations?: Schema.Annotations.Declaration<any, readonly [any]>
+        ) =>
+          Schema.isSchema(extension)
+            ? makeClass({ ...fields, ...extension.fields as Struct.Fields }, () => extend(extension, annotations))
+            : makeClass({ ...fields, ...extension }, (defaultFields) => extend(defaultFields, annotations))
       }
-      for (const variant of options.variants) {
-        Object.defineProperty(Base, variant, {
-          value: extract(variantStruct, variant).annotate({
-            id: `${identifier}.${variant}`,
-            title: `${identifier}.${variant}`
-          })
+    }
+    for (const variant of options.variants) {
+      Object.defineProperty(Base, variant, {
+        value: extract(struct, variant).annotate({
+          id: `${SchemaClass.identifier}.${variant}`,
+          title: `${SchemaClass.identifier}.${variant}`
         })
-      }
-      return Base
+      })
     }
+    return Base
   }
   function FieldOnly<const Keys extends ReadonlyArray<Variants[number]>>(keys: Keys) {
     return function<S extends Schema.Top>(schema: S) {

package/src/socket/Socket.ts

@@ -245,7 +245,17 @@ export const readerBytes = (
  *
  * **Details**
  *
- * The `TextDecoder` is created once per acquisition.
+ * Each acquisition has its own streaming decoder. Characters may span binary
+ * frames and pulls; each frame produces one string, possibly empty. A string
+ * frame flushes incomplete characters as U+FFFD before its text. Close code 1000
+ * flushes remaining text once before propagating the close error; other failures
+ * do not flush.
+ *
+ * **Gotchas**
+ *
+ * Binary WebSocket messages share decoder state: incomplete characters carry
+ * into the next binary frame, and BOM handling resets only after a flush. Use
+ * `readerBytes` and decode each frame separately for per-message decoding.
  *
  * @stability unstable
  * @category combinators
@@ -261,14 +271,31 @@ export const readerString = (
 > =>
   Effect.map(self.reader, ({ pull }) => {
     const decoder = new TextDecoder(encoding)
+    const streamOptions = { stream: true }
+    let needsFlush = false
     return Effect.map(pull, (chunk) => {
       const out = new Array<string>(chunk.length)
       for (let i = 0; i < chunk.length; i++) {
         const item = chunk[i]
-        out[i] = typeof item === "string" ? item : decoder.decode(item)
+        if (typeof item === "string") {
+          out[i] = needsFlush ? decoder.decode() + item : item
+          needsFlush = false
+        } else {
+          out[i] = decoder.decode(item, streamOptions)
+          needsFlush = true
+        }
       }
       return out as unknown as NonEmptyReadonlyArray<string>
-    })
+    }).pipe(
+      Effect.catch((error) => {
+        if (needsFlush && error.reason._tag === "SocketCloseError" && error.reason.code === 1000) {
+          needsFlush = false
+          const last = decoder.decode()
+          if (last.length > 0) return Effect.succeed([last] as const)
+        }
+        return Effect.fail(error)
+      })
+    )
   })
 
 const CloseEventTypeId = "~effect/socket/Socket/CloseEvent"
@@ -642,6 +669,10 @@ export const toChannel = <IE = never>(
  * Converts a `Socket` into a bidirectional string `Channel`, decoding binary
  * frames with the optional text encoding.
  *
+ * **Details**
+ *
+ * Uses `readerString` for decoding and close handling.
+ *
  * @stability unstable
  * @category combinators
  * @since 4.0.0
@@ -651,6 +682,10 @@ export const toChannelString: {
    * Converts a `Socket` into a bidirectional string `Channel`, decoding binary
    * frames with the optional text encoding.
    *
+   * **Details**
+   *
+   * Uses `readerString` for decoding and close handling.
+   *
    * @stability unstable
    * @category combinators
    * @since 4.0.0
@@ -666,6 +701,10 @@ export const toChannelString: {
    * Converts a `Socket` into a bidirectional string `Channel`, decoding binary
    * frames with the optional text encoding.
    *
+   * **Details**
+   *
+   * Uses `readerString` for decoding and close handling.
+   *
    * @stability unstable
    * @category combinators
    * @since 4.0.0
@@ -686,23 +725,7 @@ export const toChannelString: {
   void,
   NonEmptyReadonlyArray<Uint8Array | string | CloseEvent>,
   IE
-> => toChannelWithReader</**
- * Converts a `Socket` into a bidirectional string `Channel`, decoding binary
- * frames with the optional text encoding.
- *
- * @stability unstable
- * @category combinators
- * @since 4.0.0
- */
-string, /**
- * Converts a `Socket` into a bidirectional string `Channel`, decoding binary
- * frames with the optional text encoding.
- *
- * @stability unstable
- * @category combinators
- * @since 4.0.0
- */
-IE>(self, readerString(self, encoding)))
+> => toChannelWithReader<string, IE>(self, readerString(self, encoding)))
 
 /**
  * Creates a `Socket` to binary `Channel` adapter with a fixed upstream error
@@ -1076,6 +1099,8 @@ export const fromWebSocket = <RO, WS extends WebSocketLike>(
           // resume a pull blocked in another fiber before detaching
           fail(closeError(1006))
           ws.removeEventListener("message", onMessage)
+          // Keep late errors handled when release aborts a pending ws handshake.
+          ws.addEventListener("error", constVoid)
           ws.removeEventListener("error", onError)
           ws.removeEventListener("close", onClose)
           // let the close handshake proceed once nothing is pulling

package/src/sql/Migrator.ts

@@ -98,7 +98,8 @@ export class MigrationError extends Data.TaggedError("MigrationError")<{
 /**
  * Creates a migrator that ensures the migrations table exists, runs pending
  * migrations in a transaction, and optionally dumps the schema after successful
- * migrations.
+ * migrations. ClickHouse runs without a transaction and records each migration
+ * only after it succeeds.
  *
  * @stability unstable
  * @category constructors
@@ -139,6 +140,14 @@ export const make = <RD = never>({
   name VARCHAR(255) NOT NULL,
   PRIMARY KEY (migration_id)
 )`,
+      clickhouse: () =>
+        // sqlite's `PRIMARY KEY NOT NULL` is a syntax error here
+        sql`CREATE TABLE IF NOT EXISTS ${sql(table)} (
+  migration_id Int32,
+  created_at DateTime DEFAULT now(),
+  name String
+) ENGINE = MergeTree
+ORDER BY migration_id`,
       pg: () =>
         Effect.flatMap(
           migrationsTableExists(sql, table),
@@ -223,17 +232,21 @@ export const make = <RD = never>({
       name: string,
       effect: Effect.Effect<unknown, unknown, Client.SqlClient>
     ) =>
-      Effect.catch(effect, (error: unknown) =>
-        Effect.die(
-          new MigrationError({
-            cause: error,
-            kind: "Failed",
-            message: `Migration "${id}_${name}" failed`
-          })
-        ))
+      Effect.mapError(effect, (error) =>
+        new MigrationError({
+          cause: error,
+          kind: "Failed",
+          message: `Migration "${id}_${name}" failed`
+        }))
 
     // === run
 
+    // BEGIN is still experimental on clickhouse
+    const transactional = sql.onDialectOrElse({
+      clickhouse: () => false,
+      orElse: () => true
+    })
+
     const run = Effect.gen(function*() {
       yield* sql.onDialectOrElse({
         pg: () => sql`LOCK TABLE ${sql(table)} IN ACCESS EXCLUSIVE MODE`,
@@ -273,7 +286,8 @@ export const make = <RD = never>({
         ])
       }
 
-      if (required.length > 0) {
+      // rows recorded up front are only rolled back inside a transaction
+      if (transactional && required.length > 0) {
         yield* pipe(
           insertMigrations(required.map(([id, name]) => [id, name])),
           Effect.mapError((error): MigrationError | SqlError =>
@@ -292,6 +306,7 @@ export const make = <RD = never>({
         ([id, name, effect]) =>
           Effect.logDebug(`Running migration`).pipe(
             Effect.flatMap(() => runMigration(id, name, effect)),
+            Effect.andThen(transactional ? Effect.void : insertMigrations([[id, name]])),
             Effect.annotateLogs("migration_id", String(id)),
             Effect.annotateLogs("migration_name", name),
             Effect.withSpan(`Migrator ${id}_${name}`)
@@ -319,7 +334,7 @@ export const make = <RD = never>({
     yield* ensureMigrationsTable
 
     const completed = yield* pipe(
-      sql.withTransaction(run),
+      transactional ? sql.withTransaction(run) : run,
       Effect.catchTag("MigrationError", (_) =>
         _.kind === "Locked"
           ? Effect.as(Effect.logDebug(_.message), [])