effect 4.0.4 → 4.0.6

package/src/rpc/RpcClient.ts

@@ -15,6 +15,7 @@ import type { NonEmptyReadonlyArray } from "../Array.ts"
 import * as Cause from "../Cause.ts"
 import * as Clock from "../Clock.ts"
 import * as Context from "../Context.ts"
+import * as Deferred from "../Deferred.ts"
 import * as Duration from "../Duration.ts"
 import * as Effect from "../Effect.ts"
 import * as Exit from "../Exit.ts"
@@ -47,7 +48,14 @@ import * as RpcTracing from "./internal/tracing.ts"
 import * as Rpc from "./Rpc.ts"
 import { RpcClientDefect, RpcClientError } from "./RpcClientError.ts"
 import type * as RpcGroup from "./RpcGroup.ts"
-import type { FromClient, FromClientEncoded, FromServer, FromServerEncoded, Request } from "./RpcMessage.ts"
+import type {
+  FromClient,
+  FromClientEncoded,
+  FromServer,
+  FromServerEncoded,
+  Request,
+  RequestEncoded
+} from "./RpcMessage.ts"
 import { constPing, isTerminalResponse, RequestId } from "./RpcMessage.ts"
 import type * as RpcMiddleware from "./RpcMiddleware.ts"
 import * as RpcSchema from "./RpcSchema.ts"
@@ -301,8 +309,11 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any, E, const Flatten extend
   )
 
   const clearEntries = Effect.fnUntraced(function*(exit: Exit.Exit<never>) {
-    for (const [id, entry] of entries) {
-      entries.delete(id)
+    // Resuming callers can synchronously start new requests.
+    const pending = Array.from(entries.values())
+    entries.clear()
+    // Once detached, every entry must complete even if delivery is interrupted.
+    for (const entry of pending) {
       if (entry._tag === "Queue") {
         yield* (exit._tag === "Success"
           ? Queue.end(entry.queue as any)
@@ -311,7 +322,7 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any, E, const Flatten extend
         entry.resume(exit)
       }
     }
-  })
+  }, Effect.uninterruptible)
 
   const onRequest = (rpc: Rpc.AnyWithProps) => {
     const isStream = RpcSchema.isStreamSchema(rpc.successSchema)
@@ -420,6 +431,7 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any, E, const Flatten extend
           )
           fiber.addObserver((exit) => {
             if (exit._tag === "Failure") {
+              entries.delete(id)
               return resume(exit)
             }
           })
@@ -505,7 +517,10 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any, E, const Flatten extend
       }
     ).pipe(
       span ? Effect.withParentSpan(span, { captureStackTrace: false }) : identity,
-      Effect.onError((cause) => Queue.failCause(queue, cause)),
+      Effect.onError((cause) => {
+        if (!Cause.hasInterruptsOnly(cause)) entries.delete(id)
+        return Queue.failCause(queue, cause)
+      }),
       Effect.interruptible,
       Effect.forkIn(scope, { startImmediately: true })
     )
@@ -674,6 +689,9 @@ export const make: <Rpcs extends Rpc.Any, const Flatten extends boolean = false>
     readonly schemas: RpcSchemas
   }
   const entries = new Map<RequestId, ClientEntry>()
+  // Set before the protocol stops running this client, so requests made while
+  // it shuts down are not handed to a transport that is being torn down.
+  let isClosing = false
 
   const interruptRequest = (requestId: RequestId): Effect.Effect<void, RpcClientError> => {
     if (!entries.has(requestId)) return Effect.void
@@ -702,13 +720,23 @@ export const make: <Rpcs extends Rpc.Any, const Flatten extends boolean = false>
           return entry.schemas.encodePayload(message.payload).pipe(
             Effect.provideContext(entry.context),
             Effect.orDie,
-            Effect.flatMap((payload) =>
-              send(clientId, {
+            Effect.flatMap((payload) => {
+              // Checked after encoding, which can suspend while the client
+              // starts shutting down.
+              if (isClosing) {
+                entries.delete(message.id)
+                return Effect.interrupt
+              }
+              return send(clientId, {
                 ...message,
                 id: message.id,
                 payload,
                 headers: Object.entries(message.headers)
               }, collector && collector.readUnsafe())
+            }),
+            // An interrupted request keeps its entry until the interrupt is sent.
+            Effect.onError((cause) =>
+              Cause.hasInterruptsOnly(cause) ? Effect.void : Effect.sync(() => entries.delete(message.id))
             )
           ) as Effect.Effect<void, RpcClientError>
         }
@@ -769,15 +797,19 @@ export const make: <Rpcs extends Rpc.Any, const Flatten extends boolean = false>
           })
         ) as Effect.Effect<void>
       }
+      // Clear entries before resuming callers, as they can start new requests
       case "Defect": {
+        entries.clear()
         return write({ _tag: "Defect", clientId: 0, defect: decodeDefect(message.defect as any) })
       }
       case "ClientProtocolError": {
         const exit = Exit.fail(message.error)
+        const requestIds = Array.from(entries.keys())
+        entries.clear()
         return Effect.forEach(
-          Array.from(entries.keys()),
+          requestIds,
           (requestId) => write({ _tag: "Exit", clientId: 0, requestId, exit: exit as any })
-        )
+        ).pipe(Effect.uninterruptible)
       }
       default: {
         return Effect.void
@@ -788,6 +820,12 @@ export const make: <Rpcs extends Rpc.Any, const Flatten extends boolean = false>
     Effect.interruptible,
     Effect.forkScoped
   )
+  // Finalizers run in reverse order, so this runs before `run` is interrupted.
+  yield* Effect.addFinalizer(() =>
+    Effect.sync(() => {
+      isClosing = true
+    })
+  )
 
   return client
 })
@@ -809,13 +847,15 @@ const makeRpcSchemas = (codecFor: RpcSerialization.CodecFor) => {
       return entry
     }
     const streamSchemas = RpcSchema.getStreamSchemas(rpc.successSchema)
+    const parseOptions = Context.get(rpc.annotations, Rpc.ParseOptions)
     entry = {
       decodeChunk: Option.map(
         streamSchemas,
-        (streamSchemas) => Schema.decodeUnknownEffect(codecFor(Schema.NonEmptyArray(streamSchemas.success)))
+        (streamSchemas) =>
+          Schema.decodeUnknownEffect(codecFor(Schema.NonEmptyArray(streamSchemas.success)), parseOptions)
       ),
-      encodePayload: Schema.encodeEffect(codecFor(rpc.payloadSchema)),
-      decodeExit: Schema.decodeUnknownEffect(codecFor(Rpc.exitSchema(rpc as any)))
+      encodePayload: Schema.encodeEffect(codecFor(rpc.payloadSchema), parseOptions),
+      decodeExit: Schema.decodeUnknownEffect(codecFor(Rpc.exitSchema(rpc as any)), parseOptions)
     }
     cache.set(rpc, entry)
     return entry
@@ -913,119 +953,240 @@ export class Protocol extends Context.Service<Protocol, {
 }
 
 /**
- * Creates a client `Protocol` that sends each RPC request through the supplied
+ * Creates a client `Protocol` that sends RPC requests through the supplied
  * `HttpClient` and decodes responses with the current `RpcSerialization`.
  *
+ * **Details**
+ *
+ * Each request is sent as its own HTTP request unless `batch` is set. With
+ * `batch`, the first request for a client opens a batch. Requests from the
+ * same client made before `window` elapses join it, and the batch is sent once
+ * the window elapses or it reaches `maxSize` requests, whichever comes first.
+ *
  * @stability unstable
  * @category protocols
  * @since 4.0.0
  */
-export const makeProtocolHttp = (client: HttpClient.HttpClient): Effect.Effect<
+export const makeProtocolHttp = (client: HttpClient.HttpClient, options?: {
+  readonly batch?: {
+    readonly window: Duration.Input
+    readonly maxSize?: number | undefined
+  } | undefined
+}): Effect.Effect<
   Protocol["Service"],
   never,
   RpcSerialization.RpcSerialization
-> =>
+> => options?.batch ? makeProtocolHttpBatched(client, options.batch) : makeProtocolHttpUnbatched(client)
+
+const makeProtocolHttpUnbatched = (client: HttpClient.HttpClient) =>
   Protocol.make(Effect.fnUntraced(function*(writeResponse) {
     const serialization = yield* RpcSerialization.RpcSerialization
-    const isFramed = serialization.includesFraming
-    const httpClientError = (cause: any) =>
-      new RpcClientError({
-        reason: HttpClientErrorSchema.fromHttpClientError(cause)
-      })
-    const protocolDefect = (message: string, cause: unknown) =>
-      new RpcClientError({
-        reason: new RpcClientDefect({ message, cause })
-      })
-    const emptyResponseError = (request: FromClientEncoded) =>
-      protocolDefect("Received empty HTTP response from RPC server", request)
-    const incompleteResponseError = (request: FromClientEncoded) =>
-      protocolDefect("HTTP response ended before RPC request completed", request)
-
-    const send = Effect.fnUntraced(function*(clientId: number, request: FromClientEncoded) {
-      if (request._tag !== "Request") {
-        return
-      }
-
-      const parser = serialization.makeUnsafe()
+    const exchange = makeHttpExchange(client, serialization, writeResponse)
+    return {
+      send: (clientId, request) =>
+        request._tag === "Request"
+          ? Effect.flatMap(exchange.send(clientId, [request]), (pending) => exchange.requestExit(request, pending))
+          : Effect.void,
+      supportsAck: false,
+      supportsTransferables: false,
+      codecFor: serialization.codecFor
+    }
+  }))
 
-      const encoded = parser.encode(request)!
-      const body = typeof encoded === "string" ?
-        HttpBody.text(encoded, serialization.contentType) :
-        HttpBody.uint8Array(encoded, serialization.contentType)
+const makeProtocolHttpBatched = Effect.fnUntraced(function*(client: HttpClient.HttpClient, options: {
+  readonly window: Duration.Input
+  readonly maxSize?: number | undefined
+}) {
+  const { maxSize, window } = options
+
+  // Batches of a client run in its own scope, which is closed when the client
+  // stops running.
+  const scopes = new Map<number, Scope.Closeable>()
+  const closeScope = (clientId: number) => {
+    const scope = scopes.get(clientId)
+    if (scope === undefined) return Effect.void
+    scopes.delete(clientId)
+    return Scope.close(scope, Exit.void)
+  }
 
-      const response = yield* client.post("", { body }).pipe(Effect.mapError(httpClientError))
+  const protocol = yield* Protocol.make(Effect.fnUntraced(function*(writeResponse) {
+    const serialization = yield* RpcSerialization.RpcSerialization
+    const exchange = makeHttpExchange(client, serialization, writeResponse)
 
-      if (!isFramed) {
-        const text = yield* response.text.pipe(Effect.mapError(httpClientError))
-        const responses = yield* Effect.try({
-          try: () => parser.decode(text),
-          catch: (cause) => protocolDefect("Error decoding HTTP response", cause)
+    interface Batch {
+      readonly requests: Array<RequestEncoded>
+      readonly full: Latch.Latch
+      readonly done: Deferred.Deferred<ReadonlySet<string> | undefined, RpcClientError>
+    }
+    const batches = new Map<number, Batch>()
+    const closeBatch = (clientId: number, batch: Batch) => {
+      if (batches.get(clientId) === batch) {
+        batches.delete(clientId)
+      }
+    }
+    // Runs in the client scope rather than in a caller, so interrupting one
+    // caller does not cancel the HTTP request for the rest of the batch.
+    const runBatch = (clientId: number, batch: Batch) =>
+      Effect.raceFirst(Effect.sleep(window), batch.full.await).pipe(
+        Effect.andThen(Effect.suspend(() => {
+          closeBatch(clientId, batch)
+          return exchange.send(clientId, batch.requests)
+        })),
+        Effect.onExit((exit) => {
+          closeBatch(clientId, batch)
+          return Deferred.done(batch.done, exit)
         })
-        if (!Array.isArray(responses)) {
-          return yield* protocolDefect("Expected an array of responses", responses)
-        }
-        if (responses.length === 0) {
-          return yield* emptyResponseError(request)
-        }
-        let completed = false
-        for (let i = 0; i < responses.length; i++) {
-          const response = responses[i]
-          if (isTerminalResponse(response)) {
-            completed = true
-          }
-          yield* writeResponse(clientId, response)
-        }
-        if (!completed) {
-          return yield* incompleteResponseError(request)
+      )
+    const send = Effect.fnUntraced(function*(clientId: number, request: RequestEncoded) {
+      let batch = batches.get(clientId)
+      if (batch === undefined) {
+        batch = { requests: [request], full: Latch.makeUnsafe(), done: Deferred.makeUnsafe() }
+        batches.set(clientId, batch)
+        let scope = scopes.get(clientId)
+        if (scope === undefined) {
+          scope = Scope.makeUnsafe()
+          scopes.set(clientId, scope)
         }
-        return
+        yield* Effect.forkIn(runBatch(clientId, batch), scope, { startImmediately: true })
+      } else {
+        batch.requests.push(request)
       }
-
-      let hasResponse = false
-      let completed = false
-      yield* Stream.runForEachArray(response.stream, (chunk) =>
-        Effect.try({
-          try: () => chunk.flatMap(parser.decode) as Array<FromServerEncoded>,
-          catch: (cause) => protocolDefect("Error decoding HTTP response", cause)
-        }).pipe(
-          Effect.flatMap((responses) => {
-            if (responses.length === 0) return Effect.void
-            hasResponse = true
-            let i = 0
-            return Effect.whileLoop({
-              while: () => i < responses.length,
-              body: () => {
-                const response = responses[i++]
-                if (isTerminalResponse(response)) {
-                  completed = true
-                }
-                return writeResponse(clientId, response)
-              },
-              step: constVoid
-            })
-          })
-        )).pipe(
-          Effect.mapError((cause) => isRpcClientError(cause) ? cause : httpClientError(cause))
-        )
-      if (!hasResponse) {
-        return yield* emptyResponseError(request)
-      } else if (!completed) {
-        return yield* incompleteResponseError(request)
+      if (batch.requests.length === maxSize) {
+        closeBatch(clientId, batch)
+        batch.full.openUnsafe()
       }
+      return yield* exchange.requestExit(request, yield* Deferred.await(batch.done))
     })
 
     return {
-      send,
+      send: (clientId, request) => request._tag === "Request" ? send(clientId, request) : Effect.void,
       supportsAck: false,
       supportsTransferables: false,
       codecFor: serialization.codecFor
     }
   }))
 
+  return Protocol.of({
+    ...protocol,
+    run: (clientId, f) => Effect.onExit(protocol.run(clientId, f), () => closeScope(clientId))
+  })
+})
+
+// Sends RPC requests in one HTTP request, shared by the batched and unbatched
+// HTTP protocols.
+const makeHttpExchange = (
+  client: HttpClient.HttpClient,
+  serialization: RpcSerialization.RpcSerialization["Service"],
+  writeResponse: (clientId: number, response: FromServerEncoded) => Effect.Effect<void>
+) => {
+  const isFramed = serialization.includesFraming
+  const httpClientError = (cause: any) =>
+    new RpcClientError({
+      reason: HttpClientErrorSchema.fromHttpClientError(cause)
+    })
+  const protocolDefect = (message: string, cause: unknown) =>
+    new RpcClientError({
+      reason: new RpcClientDefect({ message, cause })
+    })
+
+  // Writes each response as it is decoded. Returns the ids of the requests left
+  // without a terminal response, or `undefined` when the server sent no
+  // responses.
+  const send = Effect.fnUntraced(function*(
+    clientId: number,
+    requests: ReadonlyArray<RequestEncoded>
+  ) {
+    const parser = serialization.makeUnsafe()
+
+    const encoded = parser.encode(requests.length === 1 ? requests[0] : requests)!
+    const body = typeof encoded === "string" ?
+      HttpBody.text(encoded, serialization.contentType) :
+      HttpBody.uint8Array(encoded, serialization.contentType)
+
+    const response = yield* client.post("", { body }).pipe(Effect.mapError(httpClientError))
+
+    const pending = new Set<string>()
+    for (let i = 0; i < requests.length; i++) {
+      pending.add(String(requests[i].id))
+    }
+    const onResponse = (response: FromServerEncoded) => {
+      if (response._tag === "Exit") {
+        pending.delete(String(response.requestId))
+      } else if (isTerminalResponse(response)) {
+        // defects and protocol errors end every request of the client
+        pending.clear()
+      }
+      return writeResponse(clientId, response)
+    }
+
+    if (!isFramed) {
+      const text = yield* response.text.pipe(Effect.mapError(httpClientError))
+      const responses = yield* Effect.try({
+        try: () => parser.decode(text),
+        catch: (cause) => protocolDefect("Error decoding HTTP response", cause)
+      })
+      if (!Array.isArray(responses)) {
+        return yield* protocolDefect("Expected an array of responses", responses)
+      }
+      if (responses.length === 0) {
+        return undefined
+      }
+      for (let i = 0; i < responses.length; i++) {
+        yield* onResponse(responses[i])
+      }
+      return pending
+    }
+
+    let hasResponse = false
+    yield* Stream.runForEachArray(response.stream, (chunk) =>
+      Effect.try({
+        try: () => chunk.flatMap(parser.decode) as Array<FromServerEncoded>,
+        catch: (cause) => protocolDefect("Error decoding HTTP response", cause)
+      }).pipe(
+        Effect.flatMap((responses) => {
+          if (responses.length === 0) return Effect.void
+          hasResponse = true
+          let i = 0
+          return Effect.whileLoop({
+            while: () => i < responses.length,
+            body: () => onResponse(responses[i++]),
+            step: constVoid
+          })
+        })
+      )).pipe(
+        Effect.mapError((cause) => isRpcClientError(cause) ? cause : httpClientError(cause))
+      )
+    return hasResponse ? pending : undefined
+  })
+
+  // Completes one request from the result of the exchange that carried it.
+  const requestExit = (
+    request: RequestEncoded,
+    pending: ReadonlySet<string> | undefined
+  ): Exit.Exit<void, RpcClientError> => {
+    if (pending === undefined) {
+      return Exit.fail(protocolDefect("Received empty HTTP response from RPC server", request))
+    } else if (pending.has(String(request.id))) {
+      return Exit.fail(protocolDefect("HTTP response ended before RPC request completed", request))
+    }
+    return Exit.void
+  }
+
+  return { send, requestExit } as const
+}
+
 /**
  * Provides a client `Protocol` backed by `HttpClient`, targeting the configured
  * URL and optionally transforming the client before use.
  *
+ * **Details**
+ *
+ * Set `batch` to send concurrent requests from the same client in a single
+ * HTTP request. The first request for a client opens a batch. Requests from
+ * the same client made before `window` elapses join it, and the batch is sent
+ * once the window elapses or it reaches `maxSize` requests, whichever comes
+ * first.
+ *
  * @stability unstable
  * @category layers
  * @since 4.0.0
@@ -1033,13 +1194,19 @@ export const makeProtocolHttp = (client: HttpClient.HttpClient): Effect.Effect<
 export const layerProtocolHttp = (options: {
   readonly url: string
   readonly transformClient?: <E, R>(client: HttpClient.HttpClient.With<E, R>) => HttpClient.HttpClient.With<E, R>
+  readonly batch?: {
+    readonly window: Duration.Input
+    readonly maxSize?: number | undefined
+  } | undefined
 }): Layer.Layer<Protocol, never, RpcSerialization.RpcSerialization | HttpClient.HttpClient> =>
   Layer.effect(Protocol)(
     Effect.flatMap(
       HttpClient.HttpClient,
       (client) => {
         client = HttpClient.mapRequest(client, HttpClientRequest.prependUrl(options.url))
-        return makeProtocolHttp(options.transformClient ? options.transformClient(client) : client)
+        return makeProtocolHttp(options.transformClient ? options.transformClient(client) : client, {
+          batch: options.batch
+        })
       }
     )
   )
@@ -1102,8 +1269,13 @@ export const makeProtocolSocket = (options?: {
     })
     let currentError: RpcClientError | undefined
 
-    const broadcast = (response: FromServerEncoded) =>
-      Effect.forEach(clientIds, (clientId) => writeResponse(clientId, response))
+    const broadcast = (response: FromServerEncoded) => {
+      const deliver = Effect.forEach(Array.from(clientIds), (clientId) => writeResponse(clientId, response))
+      if (response._tag !== "Defect" && response._tag !== "ClientProtocolError") return deliver
+      // A terminal response ends every request; clear routing before callers can start new ones
+      requestClientMap.clear()
+      return Effect.uninterruptible(deliver)
+    }
     const broadcastError = (error: RpcClientError) => {
       currentError = error
       return broadcast({
@@ -1218,17 +1390,21 @@ export const makeProtocolSocket = (options?: {
       Effect.forkScoped
     )
 
+    const write = (request: FromClientEncoded) =>
+      Effect.suspend(() => {
+        const encoded = parser.encode(request)
+        return encoded === undefined ? Effect.void : Effect.orDie(writer.write(encoded))
+      })
+
     return {
       send(clientId, request) {
         if (currentError) {
           return Effect.fail(currentError)
         }
-        if (request._tag === "Request") {
-          requestClientMap.set(request.id, clientId)
-        }
-        const encoded = parser.encode(request)
-        if (encoded === undefined) return Effect.void
-        return Effect.orDie(writer.write(encoded))
+        if (request._tag === "Interrupt") requestClientMap.delete(request.requestId)
+        if (request._tag !== "Request") return write(request)
+        requestClientMap.set(request.id, clientId)
+        return Effect.onError(write(request), () => Effect.sync(() => requestClientMap.delete(request.id)))
       },
       supportsAck: true,
       supportsTransferables: false,
@@ -1249,16 +1425,21 @@ const makePinger = Effect.fnUntraced(function*<A, E, R>(writePing: Effect.Effect
   const interval = options?.pingInterval ?? "5 seconds"
   const timeoutMillis = Duration.toMillis(options?.pingTimeout ?? interval)
   let lastSeen = clock.currentTimeMillisUnsafe()
+  let awaitingResponse = false
   const latch = Latch.makeUnsafe()
   const onFrame = () => {
     lastSeen = clock.currentTimeMillisUnsafe()
+    awaitingResponse = false
   }
   const reset = () => {
     onFrame()
     latch.closeUnsafe()
   }
   yield* Effect.suspend((): Effect.Effect<void, E, R> => {
-    if (clock.currentTimeMillisUnsafe() - lastSeen > timeoutMillis) return latch.open
+    // A late tick must send a ping before it can declare the connection silent.
+    // Keep the timeout measured from the last frame, including for custom timeouts.
+    if (awaitingResponse && clock.currentTimeMillisUnsafe() - lastSeen > timeoutMillis) return latch.open
+    awaitingResponse = true
     return writePing
   }).pipe(
     Effect.delay(interval),

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)
           }