effect 4.0.0-beta.102 → 4.0.0-beta.103

package/src/unstable/rpc/RpcSerialization.ts

@@ -11,6 +11,7 @@
  */
 import * as Msgpackr from "msgpackr"
 import * as Context from "../../Context.ts"
+import * as Data from "../../Data.ts"
 import * as Layer from "../../Layer.ts"
 import * as Predicate from "../../Predicate.ts"
 import { hasProperty } from "../../Predicate.ts"
@@ -26,7 +27,7 @@ import type * as RpcMessage from "./RpcMessage.ts"
  * Use to provide the serialization boundary shared by RPC clients and servers
  * for a chosen wire format.
  *
- * @category serialization
+ * @category services
  * @since 4.0.0
  */
 export class RpcSerialization extends Context.Service<RpcSerialization, {
@@ -47,6 +48,42 @@ export interface Parser {
   readonly encode: (response: unknown) => Uint8Array | string | undefined
 }
 
+/**
+ * Error raised when a streaming parser retains more data than its configured
+ * buffer limit.
+ *
+ * @category errors
+ * @since 4.0.0
+ */
+export class MaxBufferSizeExceeded extends Data.TaggedError("MaxBufferSizeExceeded")<{
+  readonly maxBufferSize: number
+}> {
+  override get message() {
+    return `RPC serialization buffer exceeded the maximum size of ${this.maxBufferSize}`
+  }
+}
+
+/**
+ * Options shared by streaming RPC serialization formats.
+ *
+ * @category serialization
+ * @since 4.0.0
+ */
+export interface StreamOptions {
+  /**
+   * Maximum number of bytes or string code units retained for an incomplete frame.
+   * The default is 16 MiB. Use `"unbounded"` to disable the limit.
+   */
+  readonly maxBufferSize?: number | "unbounded" | undefined
+}
+
+const defaultMaxBufferSize = 16 * 1024 * 1024
+
+const isBufferSizeExceeded = (
+  bufferSize: number,
+  maxBufferSize: number | "unbounded"
+): maxBufferSize is number => maxBufferSize !== "unbounded" && bufferSize > maxBufferSize
+
 /**
  * JSON RPC serialization for whole message payloads. It does not include
  * message framing, so it is intended for transports that frame responses
@@ -77,41 +114,62 @@ export const json: RpcSerialization["Service"] = RpcSerialization.of({
  * @category serialization
  * @since 4.0.0
  */
-export const ndjson: RpcSerialization["Service"] = RpcSerialization.of({
-  contentType: "application/ndjson",
-  includesFraming: true,
-  makeUnsafe: () => {
-    const decoder = new TextDecoder()
-    let buffer = ""
-    return ({
-      decode: (bytes) => {
-        buffer += typeof bytes === "string" ? bytes : decoder.decode(bytes)
-        let position = 0
-        let nlIndex = buffer.indexOf("\n", position)
-        const items: Array<unknown> = []
-        while (nlIndex !== -1) {
-          const item = JSON.parse(buffer.slice(position, nlIndex))
-          items.push(item)
-          position = nlIndex + 1
-          nlIndex = buffer.indexOf("\n", position)
-        }
-        buffer = buffer.slice(position)
-        return items
-      },
-      encode: (response) => {
-        if (Array.isArray(response)) {
-          if (response.length === 0) return undefined
-          let data = ""
-          for (let i = 0; i < response.length; i++) {
-            data += JSON.stringify(response[i]) + "\n"
+export const makeNdjson = (options?: StreamOptions): RpcSerialization["Service"] => {
+  const maxBufferSize = options?.maxBufferSize ?? defaultMaxBufferSize
+  return RpcSerialization.of({
+    contentType: "application/ndjson",
+    includesFraming: true,
+    makeUnsafe: () => {
+      const decoder = new TextDecoder()
+      let buffer = ""
+      const failMaxBufferSize = (maxBufferSize: number): never => {
+        buffer = ""
+        throw new MaxBufferSizeExceeded({ maxBufferSize })
+      }
+      return ({
+        decode: (bytes) => {
+          buffer += typeof bytes === "string" ? bytes : decoder.decode(bytes)
+          let position = 0
+          let nlIndex = buffer.indexOf("\n", position)
+          const items: Array<unknown> = []
+          while (nlIndex !== -1) {
+            if (isBufferSizeExceeded(nlIndex - position, maxBufferSize)) {
+              failMaxBufferSize(maxBufferSize)
+            }
+            const item = JSON.parse(buffer.slice(position, nlIndex))
+            items.push(item)
+            position = nlIndex + 1
+            nlIndex = buffer.indexOf("\n", position)
+          }
+          buffer = buffer.slice(position)
+          if (isBufferSizeExceeded(buffer.length, maxBufferSize)) {
+            failMaxBufferSize(maxBufferSize)
+          }
+          return items
+        },
+        encode: (response) => {
+          if (Array.isArray(response)) {
+            if (response.length === 0) return undefined
+            let data = ""
+            for (let i = 0; i < response.length; i++) {
+              data += JSON.stringify(response[i]) + "\n"
+            }
+            return data
           }
-          return data
+          return JSON.stringify(response) + "\n"
         }
-        return JSON.stringify(response) + "\n"
-      }
-    })
-  }
-})
+      })
+    }
+  })
+}
+
+/**
+ * Default newline-delimited JSON RPC serialization.
+ *
+ * @category serialization
+ * @since 4.0.0
+ */
+export const ndjson: RpcSerialization["Service"] = makeNdjson()
 
 /**
  * Creates a JSON-RPC 2.0 serialization for RPC protocol messages without
@@ -156,12 +214,13 @@ export const jsonRpc = (options?: {
  */
 export const ndJsonRpc = (options?: {
   readonly contentType?: string | undefined
+  readonly maxBufferSize?: number | "unbounded" | undefined
 }): RpcSerialization["Service"] =>
   RpcSerialization.of({
     contentType: options?.contentType ?? "application/json-rpc",
     includesFraming: true,
     makeUnsafe: () => {
-      const parser = ndjson.makeUnsafe()
+      const parser = makeNdjson({ maxBufferSize: options?.maxBufferSize }).makeUnsafe()
       const batches = new Map<string, {
         readonly size: number
         readonly responses: Map<string, RpcMessage.FromServerEncoded>
@@ -212,12 +271,13 @@ function decodeJsonRpcRaw(
 }
 
 function decodeJsonRpcMessage(decoded: JsonRpcMessage): RpcMessage.FromClientEncoded | RpcMessage.FromServerEncoded {
-  if ("method" in decoded) {
-    if (Predicate.isNullish(decoded.id) && decoded.method.startsWith("@effect/rpc/")) {
-      const tag = decoded.method.slice("@effect/rpc/".length) as
+  if (Object.hasOwn(decoded, "method")) {
+    const request = decoded as JsonRpcRequest
+    if (Predicate.isNullish(request.id) && request.method.startsWith("@effect/rpc/")) {
+      const tag = request.method.slice("@effect/rpc/".length) as
         | RpcMessage.FromServerEncoded["_tag"]
         | Exclude<RpcMessage.FromClientEncoded["_tag"], "Request">
-      const requestId = (decoded as any).params?.requestId
+      const requestId = (request as any).params?.requestId
       return requestId ?
         {
           _tag: tag,
@@ -227,46 +287,50 @@ function decodeJsonRpcMessage(decoded: JsonRpcMessage): RpcMessage.FromClientEnc
     }
     return {
       _tag: "Request",
-      id: decoded.id ?? "",
-      tag: decoded.method,
-      payload: decoded.params ?? null,
-      headers: decoded.headers ?? [],
-      ...(decoded.spanId ?
+      id: request.id ?? "",
+      tag: request.method,
+      payload: request.params ?? null,
+      headers: request.headers ?? [],
+      ...(Predicate.hasProperty(request, "id") ? {} : { isNotification: true as const }),
+      ...(request.spanId ?
         {
-          traceId: decoded.traceId,
-          spanId: decoded.spanId!,
-          sampled: decoded.sampled!
+          traceId: request.traceId,
+          spanId: request.spanId!,
+          sampled: request.sampled!
         } :
         {})
     }
-  } else if (decoded.error && decoded.error._tag === "Defect") {
+  }
+  const response = decoded as JsonRpcResponse
+  const hasError = Object.hasOwn(response, "error")
+  if (hasError && response.error && response.error._tag === "Defect") {
     return {
       _tag: "Defect",
-      defect: decoded.error.data
+      defect: response.error.data
     }
-  } else if (decoded.chunk === true) {
+  } else if (Object.hasOwn(response, "chunk") && response.chunk === true) {
     return {
       _tag: "Chunk",
-      requestId: decoded.id ?? "",
-      values: decoded.result as any
+      requestId: response.id ?? "",
+      values: response.result as any
     }
   }
   return {
     _tag: "Exit",
-    requestId: decoded.id ?? "",
-    exit: decoded.error != null ?
+    requestId: response.id ?? "",
+    exit: hasError && response.error != null ?
       {
         _tag: "Failure",
-        cause: decoded.error._tag === "Cause" ?
-          decoded.error.data as any :
+        cause: response.error._tag === "Cause" ?
+          response.error.data as any :
           [{
             _tag: "Die",
-            defect: decoded.error
+            defect: response.error
           }]
       } :
       {
         _tag: "Success",
-        value: decoded.result
+        value: response.result
       }
   }
 }
@@ -372,7 +436,8 @@ function encodeJsonRpcMessage(response: RpcMessage.FromServerEncoded | RpcMessag
           result: response.exit.value
         } as any
       }
-      const error = response.exit.cause.find((failure) => failure._tag === "Fail")
+      const failure = response.exit.cause.find((failure) => failure._tag === "Fail")
+      const error = failure?._tag === "Fail" ? failure.error : undefined
       return {
         jsonrpc: "2.0",
         id: response.requestId ?? undefined,
@@ -438,19 +503,29 @@ type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse
  * @category serialization
  * @since 4.0.0
  */
-export const makeMsgPack = (options?: Msgpackr.Options | undefined): RpcSerialization["Service"] =>
-  RpcSerialization.of({
+export const makeMsgPack = (
+  options?: (Msgpackr.Options & StreamOptions) | undefined
+): RpcSerialization["Service"] => {
+  const { maxBufferSize = defaultMaxBufferSize, ...msgpackOptions } = options ?? {}
+  return RpcSerialization.of({
     contentType: "application/msgpack",
     includesFraming: true,
     makeUnsafe: () => {
-      const unpackr = new Msgpackr.Unpackr(options)
-      const packr = new Msgpackr.Packr(options)
+      const unpackr = new Msgpackr.Unpackr(msgpackOptions)
+      const packr = new Msgpackr.Packr(msgpackOptions)
       const encoder = new TextEncoder()
       let incomplete: Uint8Array | undefined = undefined
+      const failMaxBufferSize = (maxBufferSize: number): never => {
+        incomplete = undefined
+        throw new MaxBufferSizeExceeded({ maxBufferSize })
+      }
       return {
         decode(bytes) {
           let buf = typeof bytes === "string" ? encoder.encode(bytes) : bytes
           if (incomplete !== undefined) {
+            if (isBufferSizeExceeded(incomplete.length + buf.length, maxBufferSize)) {
+              failMaxBufferSize(maxBufferSize)
+            }
             const prev = buf
             bytes = new Uint8Array(incomplete.length + buf.length)
             bytes.set(incomplete)
@@ -464,6 +539,9 @@ export const makeMsgPack = (options?: Msgpackr.Options | undefined): RpcSerializ
             const error = error_ as any
             if (error.incomplete) {
               incomplete = buf.subarray(error.lastPosition)
+              if (isBufferSizeExceeded(incomplete.length, maxBufferSize)) {
+                failMaxBufferSize(maxBufferSize)
+              }
               return error.values ?? []
             }
             throw error_
@@ -473,6 +551,7 @@ export const makeMsgPack = (options?: Msgpackr.Options | undefined): RpcSerializ
       }
     }
   })
+}
 
 /**
  * Default MessagePack RPC serialization using record support and built-in
@@ -492,7 +571,7 @@ export const msgPack: RpcSerialization["Service"] = makeMsgPack({ useRecords: tr
  *
  * @see {@link layerNdjson} for transports that need newline-delimited framing
  *
- * @category serialization
+ * @category layers
  * @since 4.0.0
  */
 export const layerJson: Layer.Layer<RpcSerialization> = Layer.succeed(RpcSerialization)(json)
@@ -506,15 +585,24 @@ export const layerJson: Layer.Layer<RpcSerialization> = Layer.succeed(RpcSeriali
  *
  * @see {@link layerJson} for transports that already provide message framing
  *
- * @category serialization
+ * @category layers
  * @since 4.0.0
  */
 export const layerNdjson: Layer.Layer<RpcSerialization> = Layer.succeed(RpcSerialization)(ndjson)
 
+/**
+ * RPC serialization layer that uses NDJSON with custom streaming options.
+ *
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerNdjsonWith = (options?: StreamOptions): Layer.Layer<RpcSerialization> =>
+  Layer.succeed(RpcSerialization)(makeNdjson(options))
+
 /**
  * RPC serialization layer that uses JSON-RPC for serialization.
  *
- * @category serialization
+ * @category layers
  * @since 4.0.0
  */
 export const layerJsonRpc = (options?: {
@@ -525,11 +613,12 @@ export const layerJsonRpc = (options?: {
  * RPC serialization layer that uses newline-delimited JSON-RPC for
  * serialization.
  *
- * @category serialization
+ * @category layers
  * @since 4.0.0
  */
 export const layerNdJsonRpc = (options?: {
   readonly contentType?: string | undefined
+  readonly maxBufferSize?: number | "unbounded" | undefined
 }): Layer.Layer<RpcSerialization> => Layer.succeed(RpcSerialization)(ndJsonRpc(options))
 
 /**
@@ -540,7 +629,17 @@ export const layerNdJsonRpc = (options?: {
  * MessagePack has a more compact binary format compared to JSON and NDJSON. It
  * also has better support for binary data.
  *
- * @category serialization
+ * @category layers
  * @since 4.0.0
  */
 export const layerMsgPack: Layer.Layer<RpcSerialization> = Layer.succeed(RpcSerialization)(msgPack)
+
+/**
+ * RPC serialization layer that uses MessagePack with custom options.
+ *
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerMsgPackWith = (
+  options?: (Msgpackr.Options & StreamOptions) | undefined
+): Layer.Layer<RpcSerialization> => Layer.succeed(RpcSerialization)(makeMsgPack(options))

package/src/unstable/rpc/RpcServer.ts

@@ -37,7 +37,7 @@ import * as Headers from "../http/Headers.ts"
 import * as HttpRouter from "../http/HttpRouter.ts"
 import * as HttpServerRequest from "../http/HttpServerRequest.ts"
 import * as HttpServerResponse from "../http/HttpServerResponse.ts"
-import type * as Socket from "../socket/Socket.ts"
+import * as Socket from "../socket/Socket.ts"
 import * as SocketServer from "../socket/SocketServer.ts"
 import * as Transferable from "../workers/Transferable.ts"
 import type { WorkerError } from "../workers/WorkerError.ts"
@@ -63,7 +63,7 @@ import { withRun } from "./Utils.ts"
  * The decoded RPC server boundary, accepting client messages for a client id
  * and allowing that client to be disconnected.
  *
- * @category server
+ * @category models
  * @since 4.0.0
  */
 export interface RpcServer<A extends Rpc.Any> {
@@ -78,7 +78,7 @@ export interface RpcServer<A extends Rpc.Any> {
  * handlers for a group and sending decoded server responses through
  * `onFromServer`.
  *
- * @category server
+ * @category constructors
  * @since 4.0.0
  */
 export const makeNoSerialization: <Rpcs extends Rpc.Any>(
@@ -483,7 +483,7 @@ const applyMiddleware = <A, E, R>(
  * requests, invoking handlers, encoding responses, and managing in-flight
  * request lifetime.
  *
- * @category server
+ * @category running
  * @since 4.0.0
  */
 export const make: <Rpcs extends Rpc.Any>(
@@ -688,7 +688,7 @@ export const make: <Rpcs extends Rpc.Any>(
 
     switch (request._tag) {
       case "Request": {
-        const tag = Predicate.hasProperty(request, "tag") ? (request.tag as string) : ""
+        const tag = Object.hasOwn(request, "tag") ? (request.tag as string) : ""
         let requestId: RequestId
         switch (typeof request.id) {
           case "number":
@@ -762,7 +762,7 @@ export const make: <Rpcs extends Rpc.Any>(
  * Provides a scoped layer that starts an RPC server for a group using the
  * current server `Protocol`.
  *
- * @category server
+ * @category layers
  * @since 4.0.0
  */
 export const layer = <Rpcs extends Rpc.Any>(
@@ -791,7 +791,7 @@ export const layer = <Rpcs extends Rpc.Any>(
  * Defaults to using websockets for communication, but can be configured to use
  * HTTP.
  *
- * @category protocols
+ * @category layers
  * @since 4.0.0
  */
 export const layerHttp = <Rpcs extends Rpc.Any>(options: {
@@ -830,7 +830,7 @@ export const layerHttp = <Rpcs extends Rpc.Any>(options: {
  * Use to provide the transport boundary for RPC servers over HTTP, WebSocket,
  * workers, sockets, or custom protocols.
  *
- * @category protocols
+ * @category services
  * @since 4.0.0
  */
 export class Protocol extends Context.Service<
@@ -880,7 +880,7 @@ export const makeProtocolSocketServer = Effect.gen(function*() {
 /**
  * RPC protocol that uses `SocketServer` for communication.
  *
- * @category protocols
+ * @category layers
  * @since 4.0.0
  */
 export const layerProtocolSocketServer: Layer.Layer<
@@ -947,7 +947,7 @@ export const makeProtocolWebsocket: (options: {
 /**
  * RPC protocol that uses WebSockets for communication.
  *
- * @category protocols
+ * @category layers
  * @since 4.0.0
  */
 export const layerProtocolWebsocket = (options: {
@@ -1152,7 +1152,7 @@ export const makeProtocolHttp: (options: {
  * Provides a server `Protocol` that uses HTTP POST requests for RPC
  * communication.
  *
- * @category protocols
+ * @category layers
  * @since 4.0.0
  */
 export const layerProtocolHttp = (options: {
@@ -1165,7 +1165,7 @@ export const layerProtocolHttp = (options: {
  * Starts an RPC server for a group and returns the HTTP request/response effect
  * that serves the non-websocket HTTP RPC protocol.
  *
- * @category http app
+ * @category running
  * @since 4.0.0
  */
 export const toHttpEffect: <Rpcs extends Rpc.Any>(
@@ -1206,7 +1206,7 @@ export const toHttpEffect: <Rpcs extends Rpc.Any>(
  * Starts an RPC server for a group and returns the HTTP effect that upgrades
  * requests to the websocket RPC protocol.
  *
- * @category http app
+ * @category running
  * @since 4.0.0
  */
 export const toHttpEffectWebsocket: <Rpcs extends Rpc.Any>(
@@ -1308,7 +1308,7 @@ export const makeProtocolStdio = Effect.gen(function*() {
  * Provides a server `Protocol` that reads RPC messages from `Stdio.stdin` and
  * writes encoded responses to `Stdio.stdout`.
  *
- * @category protocols
+ * @category layers
  * @since 4.0.0
  */
 export const layerProtocolStdio: Layer.Layer<
@@ -1379,7 +1379,7 @@ export const makeProtocolWorkerRunner: Effect.Effect<
 /**
  * Provides a server `Protocol` backed by the current `WorkerRunnerPlatform`.
  *
- * @category protocols
+ * @category layers
  * @since 4.0.0
  */
 export const layerProtocolWorkerRunner: Layer.Layer<
@@ -1466,6 +1466,9 @@ const makeSocketProtocol: Effect.Effect<
           step: constVoid
         })
       } catch (cause) {
+        if (Predicate.isTagged(cause, "MaxBufferSizeExceeded")) {
+          return writeRaw(new Socket.CloseEvent(1009, String(cause)))
+        }
         return writeRaw(parser.encode(ResponseDefectEncoded(cause))!)
       }
     }).pipe(

package/src/unstable/rpc/RpcWorker.ts

@@ -21,7 +21,7 @@ import type { Protocol } from "./RpcServer.ts"
  * Context service that supplies the initial RPC worker message as encoded data
  * paired with any transferables that should be posted with it.
  *
- * @category initial message
+ * @category services
  * @since 4.0.0
  */
 export class InitialMessage extends Context.Service<
@@ -44,7 +44,7 @@ export declare namespace InitialMessage {
    * Tagged wire representation of an RPC worker initial message after schema
    * encoding.
    *
-   * @category initial message
+   * @category models
    * @since 4.0.0
    */
   export interface Encoded {
@@ -61,7 +61,7 @@ const ProtocolTag = Context.Service<Protocol, Protocol["Service"]>(
  * Runs an effect, encodes its result with the schema's JSON codec, and returns
  * the encoded value together with collected transferables.
  *
- * @category initial message
+ * @category encoding
  * @since 4.0.0
  */
 export const makeInitialMessage = <S extends Schema.Constraint, E, R2>(
@@ -86,7 +86,7 @@ export const makeInitialMessage = <S extends Schema.Constraint, E, R2>(
  * Provides the `InitialMessage` service from a schema and build effect,
  * capturing the layer context and dying if schema encoding fails.
  *
- * @category initial message
+ * @category layers
  * @since 4.0.0
  */
 export const layerInitialMessage = <S extends Schema.Constraint, R2>(
@@ -105,7 +105,7 @@ export const layerInitialMessage = <S extends Schema.Constraint, R2>(
  * Reads the protocol initial message and decodes it with the supplied schema,
  * failing if no initial message is available or decoding fails.
  *
- * @category initial message
+ * @category decoding
  * @since 4.0.0
  */
 export const initialMessage = <S extends Schema.Constraint>(