effect 4.0.6 → 4.1.0

package/src/rpc/RpcClient.ts

@@ -107,6 +107,14 @@ export declare namespace RpcClient {
         {
           readonly headers?: Headers.Input | undefined
           readonly context?: Context.Context<never> | undefined
+          /**
+           * Completes once the server acknowledges the call as its handler starts,
+           * after the middleware has run, instead of waiting for the result. The
+           * handler's result and error are not returned, but transport errors,
+           * middleware errors and failures before the handler starts still fail the
+           * call. Over HTTP and workers the call completes after the handler has
+           * finished.
+           */
           readonly discard?: Discard | undefined
         }
     ) => Current extends Rpc.Rpc<
@@ -174,6 +182,14 @@ export declare namespace RpcClient {
       {
         readonly headers?: Headers.Input | undefined
         readonly context?: Context.Context<never> | undefined
+        /**
+         * Completes once the server acknowledges the call as its handler starts,
+         * after the middleware has run, instead of waiting for the result. The
+         * handler's result and error are not returned, but transport errors,
+         * middleware errors and failures before the handler starts still fail the
+         * call. Over HTTP and workers the call completes after the handler has
+         * finished.
+         */
         readonly discard?: Discard | undefined
       }
   ) => Rpcs extends Rpc.Rpc<
@@ -242,7 +258,6 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any, E, const Flatten extend
       options: {
         readonly message: FromClient<Rpcs>
         readonly context: Context.Context<never>
-        readonly discard: boolean
       }
     ) => Effect.Effect<void, E>
     readonly supportsAck?: boolean | undefined
@@ -266,7 +281,6 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any, E, const Flatten extend
       options: {
         readonly message: FromClient<Rpcs>
         readonly context: Context.Context<never>
-        readonly discard: boolean
       }
     ) => Effect.Effect<void, E>
     readonly supportsAck?: boolean | undefined
@@ -384,12 +398,7 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any, E, const Flatten extend
       }
       const id = generateRequestId()
       const send = middleware(
-        (message) =>
-          options.onFromClient({
-            message,
-            context,
-            discard
-          }),
+        (message) => options.onFromClient({ message, context }),
         {
           _tag: "Request",
           id,
@@ -402,20 +411,28 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any, E, const Flatten extend
               sampled: span.sampled
             } :
             {}),
-          headers: Headers.merge(parentFiber.getRef(CurrentHeaders), headers)
+          headers: Headers.merge(parentFiber.getRef(CurrentHeaders), headers),
+          ...(discard ? { discard: true as const } : {})
         }
       )
-      if (discard) {
-        return send
-      }
       let fiber: Fiber.Fiber<any, any>
       return Effect.onInterrupt(
         Effect.callback<any, any>((resume) => {
+          // the acknowledgement of a discarded call, held until its send has finished
+          let ack: Exit.Exit<any, any> | undefined
           const entry: ClientEntry = {
             _tag: "Effect",
             rpc,
             context,
             resume(exit) {
+              if (discard) {
+                // Interrupting the send could cancel the call, as an HTTP
+                // handler is scoped to its request, so the call completes
+                // once the send has finished too.
+                ack = exit._tag === "Success" ? Exit.void : exit
+                if (fiber?.pollUnsafe()) resume(ack)
+                return
+              }
               resume(exit)
               if (fiber && !fiber.pollUnsafe()) {
                 parentFiber.currentDispatcher.scheduleTask(() => {
@@ -433,6 +450,8 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any, E, const Flatten extend
             if (exit._tag === "Failure") {
               entries.delete(id)
               return resume(exit)
+            } else if (ack) {
+              return resume(ack)
             }
           })
         }),
@@ -495,12 +514,7 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any, E, const Flatten extend
     })
 
     yield* middleware(
-      (message) =>
-        options.onFromClient({
-          message,
-          context,
-          discard: false
-        }),
+      (message) => options.onFromClient({ message, context }),
       {
         _tag: "Request",
         id,
@@ -572,8 +586,7 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any, E, const Flatten extend
       const parentFiber = Fiber.getCurrent()!
       const fiber = options.onFromClient({
         message: { _tag: "Interrupt", requestId, interruptors },
-        context,
-        discard: false
+        context
       }).pipe(
         Effect.timeout(1000),
         Effect.runForkWith(parentFiber.context)
@@ -594,8 +607,7 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any, E, const Flatten extend
             ? Effect.flatMap(() =>
               options.onFromClient({
                 message: { _tag: "Ack", requestId: message.requestId },
-                context: entry.context,
-                discard: false
+                context: entry.context
               })
             )
             : identity,
@@ -687,11 +699,12 @@ export const make: <Rpcs extends Rpc.Any, const Flatten extends boolean = false>
     readonly rpc: Rpc.AnyWithProps
     readonly context: Context.Context<never>
     readonly schemas: RpcSchemas
+    readonly discard: boolean
   }
   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
+  // Completed 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.
+  const closing = Deferred.makeUnsafe<void>()
 
   const interruptRequest = (requestId: RequestId): Effect.Effect<void, RpcClientError> => {
     if (!entries.has(requestId)) return Effect.void
@@ -713,7 +726,8 @@ export const make: <Rpcs extends Rpc.Any, const Flatten extends boolean = false>
           const entry: ClientEntry = {
             rpc,
             context: collector ? Context.add(fiber.context, Transferable.Collector, collector) : fiber.context,
-            schemas: rpcSchemas(rpc)
+            schemas: rpcSchemas(rpc),
+            discard: message.discard === true
           }
           entries.set(message.id, entry)
 
@@ -723,7 +737,7 @@ export const make: <Rpcs extends Rpc.Any, const Flatten extends boolean = false>
             Effect.flatMap((payload) => {
               // Checked after encoding, which can suspend while the client
               // starts shutting down.
-              if (isClosing) {
+              if (Deferred.isDoneUnsafe(closing)) {
                 entries.delete(message.id)
                 return Effect.interrupt
               }
@@ -775,7 +789,14 @@ export const make: <Rpcs extends Rpc.Any, const Flatten extends boolean = false>
           ).pipe(
             Effect.onError((cause) =>
               write({ _tag: "Exit", clientId: 0, requestId, exit: Exit.failCause(cause) }).pipe(
-                Effect.andThen(Cause.hasInterrupts(cause) ? Effect.void : Effect.ignore(interruptRequest(requestId)))
+                Effect.andThen(
+                  Cause.hasInterrupts(cause) ? Effect.void : Effect.raceFirst(
+                    Effect.ignore(interruptRequest(requestId)),
+                    // Best-effort once the client closes: a disconnected transport
+                    // can wait for a reconnect that never comes.
+                    Deferred.await(closing)
+                  )
+                )
               )
             ),
             // a decode failure only ends its own request; interruption still propagates
@@ -788,7 +809,13 @@ export const make: <Rpcs extends Rpc.Any, const Flatten extends boolean = false>
         const entry = entries.get(requestId)
         if (!entry) return Effect.void
         entries.delete(requestId)
-        return entry.schemas.decodeExit(message.exit).pipe(
+        // the success of a discarded call is its acknowledgement, which has no
+        // value, and an older server may send the handler result instead
+        if (entry.discard && message.exit._tag === "Success") {
+          return write({ _tag: "Exit", clientId: 0, requestId, exit: Exit.void as any })
+        }
+        const decodeExit = entry.discard ? entry.schemas.decodeDiscardExit : entry.schemas.decodeExit
+        return decodeExit(message.exit).pipe(
           Effect.provideContext(entry.context),
           Effect.orDie,
           Effect.matchCauseEffect({
@@ -821,11 +848,7 @@ export const make: <Rpcs extends Rpc.Any, const Flatten extends boolean = false>
     Effect.forkScoped
   )
   // Finalizers run in reverse order, so this runs before `run` is interrupted.
-  yield* Effect.addFinalizer(() =>
-    Effect.sync(() => {
-      isClosing = true
-    })
-  )
+  yield* Effect.addFinalizer(() => Deferred.succeed(closing, void 0))
 
   return client
 })
@@ -836,6 +859,7 @@ interface RpcSchemas {
   >
   readonly encodePayload: (payload: any) => Effect.Effect<any, Schema.SchemaError, unknown>
   readonly decodeExit: (encoded: unknown) => Effect.Effect<Exit.Exit<any, any>, Schema.SchemaError, unknown>
+  readonly decodeDiscardExit: (encoded: unknown) => Effect.Effect<Exit.Exit<any, any>, Schema.SchemaError, unknown>
 }
 // Codecs are compiled per client, because two protocols can fill the message
 // holes with different codecs.
@@ -848,6 +872,8 @@ const makeRpcSchemas = (codecFor: RpcSerialization.CodecFor) => {
     }
     const streamSchemas = RpcSchema.getStreamSchemas(rpc.successSchema)
     const parseOptions = Context.get(rpc.annotations, Rpc.ParseOptions)
+    const exitSchema = Rpc.exitSchema(rpc as any)
+    let decodeDiscardExit: RpcSchemas["decodeDiscardExit"] | undefined
     entry = {
       decodeChunk: Option.map(
         streamSchemas,
@@ -855,7 +881,13 @@ const makeRpcSchemas = (codecFor: RpcSerialization.CodecFor) => {
           Schema.decodeUnknownEffect(codecFor(Schema.NonEmptyArray(streamSchemas.success)), parseOptions)
       ),
       encodePayload: Schema.encodeEffect(codecFor(rpc.payloadSchema), parseOptions),
-      decodeExit: Schema.decodeUnknownEffect(codecFor(Rpc.exitSchema(rpc as any)), parseOptions)
+      decodeExit: Schema.decodeUnknownEffect(codecFor(exitSchema), parseOptions),
+      // the server encodes the Exits of a discarded call with a void success
+      decodeDiscardExit: (encoded) =>
+        (decodeDiscardExit ??= Schema.decodeUnknownEffect(
+          codecFor(Schema.Exit(Schema.Void, exitSchema.error, exitSchema.defect)),
+          parseOptions
+        ))(encoded)
     }
     cache.set(rpc, entry)
     return entry
@@ -1632,7 +1664,14 @@ export const makeProtocolWorker = (
             Effect.flatMap((worker) => {
               const latch = Latch.makeUnsafe(false)
               entries.set(request.id, { clientId, worker, latch })
-              return Effect.flatMap(worker.send(request, transferables), () => latch.await)
+              // the pool counts a worker as busy until the Exit arrives, so a
+              // discarded call is sent without its marker to get the handler Exit
+              let message = request
+              if (request.discard === true) {
+                const { discard: _, ...rest } = request
+                message = rest
+              }
+              return Effect.flatMap(worker.send(message, transferables), () => latch.await)
             }),
             Effect.scoped,
             Effect.orDie

package/src/rpc/RpcMessage.ts

@@ -62,7 +62,12 @@ export const RequestId = (id: string | number): RequestId => id as RequestId
  * **Details**
  *
  * Requests flow in both directions: servers use them for server-originated
- * requests and, with `isNotification` set, for server notifications.
+ * requests and, with `isNotification` set, for requests that get no reply,
+ * such as server notifications and inbound JSON-RPC notifications.
+ *
+ * A client call made with `discard` sets `discard` instead. It keeps its id,
+ * and the server acknowledges it with a successful `Exit` once the handler
+ * starts, then sends nothing more for it.
  *
  * @stability unstable
  * @category models
@@ -75,6 +80,7 @@ export interface RequestEncoded {
   readonly payload: unknown
   readonly headers: ReadonlyArray<[string, string]>
   readonly isNotification?: true
+  readonly discard?: true
   readonly traceId?: string
   readonly spanId?: string
   readonly sampled?: boolean
@@ -94,6 +100,8 @@ export interface Request<A extends Rpc.Any> {
   readonly tag: Rpc.Tag<A>
   readonly payload: Rpc.Payload<A>
   readonly headers: Headers
+  readonly isNotification?: true
+  readonly discard?: true
   readonly traceId?: string
   readonly spanId?: string
   readonly sampled?: boolean
@@ -453,6 +461,7 @@ const RequestEncodedSchema = Schema.Struct({
   payload: Schema.Uint8Array,
   headers: Schema.Array(Schema.Tuple([Schema.String, Schema.String])),
   isNotification: Schema.optional(Schema.Literal(true)),
+  discard: Schema.optional(Schema.Literal(true)),
   traceId: Schema.optional(Schema.String),
   spanId: Schema.optional(Schema.String),
   sampled: Schema.optional(Schema.Boolean)

package/src/rpc/RpcSerialization.ts

@@ -230,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>
@@ -251,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)
@@ -265,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
@@ -272,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",
@@ -279,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>
@@ -289,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
         },
@@ -306,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 = {
@@ -317,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++
@@ -326,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"]
@@ -353,6 +374,7 @@ function decodeJsonRpcMessage(decoded: JsonRpcMessage): RpcMessage.FromClientEnc
       payload: request.params ?? null,
       headers: request.headers ?? [],
       ...(Predicate.hasProperty(request, "id") ? {} : { isNotification: true as const }),
+      ...(request.discard === true ? { discard: true as const } : {}),
       ...(request.spanId ?
         {
           traceId: request.traceId,
@@ -403,13 +425,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)
     }
@@ -469,6 +491,7 @@ function encodeJsonRpcMessage(response: RpcMessage.FromServerEncoded | RpcMessag
         // a JSON-RPC notification is a request without an id
         ...(response.isNotification ? {} : { id: response.id }),
         ...(response.headers?.length > 0 ? { headers: response.headers } : {}),
+        ...(response.discard ? { discard: true } : {}),
         traceId: response.traceId,
         spanId: response.spanId,
         sampled: response.sampled
@@ -539,6 +562,7 @@ interface JsonRpcRequest {
   readonly method: string
   readonly params?: unknown
   readonly headers?: ReadonlyArray<[string, string]>
+  readonly discard?: true
   readonly traceId?: string
   readonly spanId?: string
   readonly sampled?: boolean
@@ -644,6 +668,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))
 
 /**
@@ -657,6 +682,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))
 
 /**