effect 4.0.7 → 4.1.1

package/src/reactivity/AtomRegistry.ts

@@ -553,9 +553,15 @@ class RegistryImpl implements AtomRegistry {
     const node = this.ensureNode(atom)
     if (options?.immediate) {
       f(node.value())
-    } else if (node.state === NodeState.stale) {
-      // a listener hears the next change, which only reaches an up-to-date node
-      node.value()
+    } else {
+      // build the node so the listener hears its next change. A failed build
+      // is left for the next read to report; an error raised after the value
+      // is committed has no later read to report it, so it is rethrown
+      try {
+        node.value()
+      } catch (error) {
+        if ((node.state & NodeFlags.waitingForValue) === 0) throw error
+      }
     }
     const remove = node.subscribe(function() {
       f(node._value)
@@ -587,7 +593,7 @@ class RegistryImpl implements AtomRegistry {
       this.removeNodeTimeout(node)
     }
     if (typeof key === "string" && this.preloadedSerializable.has(key)) {
-      const encoded = this.preloadedSerializable.get(key)
+      const encoded = this.preloadedSerializable.get(key) as Schema.Json
       this.preloadedSerializable.delete(key)
       const serializable = (atom as any as Atom.Serializable<any>)[SerializableTypeId]
       let decoded: A
@@ -842,11 +848,15 @@ class NodeImpl<A> {
   }
 
   build(): void {
-    // a lifetime still attached to a node that needs a value belongs to a
-    // build that failed, or to one that is running and is now superseded
-    this.disposeLifetime()
-    this.invalidatedDuringBuild = false
     const lifetime = makeLifetime(this)
+    // release a failed or superseded build; its finalizers run only once, so
+    // their failure is rethrown once this build commits
+    try {
+      this.disposeLifetime()
+    } catch (error) {
+      lifetime.failure = error
+    }
+    this.invalidatedDuringBuild = false
     this.lifetime = lifetime
     let value: A
     let read = false
@@ -1126,7 +1136,8 @@ interface Lifetime<A> extends Atom.AtomContext {
   readonly node: NodeImpl<A>
   // the parents read so far by the build; `undefined` once the build has returned
   reads: Set<NodeImpl<any>> | undefined
-  // a failure met while reading a parent that still produced its value
+  // rethrown once the build commits: a failure from releasing the previous
+  // lifetime, or from reading a parent that still produced its value
   failure: unknown
   finalizers: Array<() => void> | undefined
   disposed: boolean

package/src/rpc/Rpc.ts

@@ -363,7 +363,9 @@ export type SuccessExit<R> = Success<R> extends infer T ? T extends Stream<infer
  * @category utility types
  * @since 4.0.0
  */
-export type SuccessChunk<R> = Success<R> extends Stream<infer _A, infer _E, infer _Env> ? _A : never
+export type SuccessChunk<R> = R extends Any ?
+  SuccessSchema<R> extends RpcSchema.Stream<infer _A, infer _E> ? _A["Type"] : never
+  : never
 
 /**
  * Extracts the RPC error schema, including error schemas contributed by

package/src/rpc/RpcClient.ts

@@ -107,6 +107,15 @@ 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. A protocol that only delivers requests acknowledges the call
+           * itself once it has delivered the request.
+           */
           readonly discard?: Discard | undefined
         }
     ) => Current extends Rpc.Rpc<
@@ -174,6 +183,15 @@ 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. A protocol that only delivers requests acknowledges the call
+         * itself once it has delivered the request.
+         */
         readonly discard?: Discard | undefined
       }
   ) => Rpcs extends Rpc.Rpc<
@@ -242,7 +260,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 +283,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 +400,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 +413,27 @@ 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) => {
+          let acked = false
           const entry: ClientEntry = {
             _tag: "Effect",
             rpc,
             context,
             resume(exit) {
+              if (discard && exit._tag === "Success") {
+                // A successful acknowledgement waits for the send to finish, as
+                // interrupting the send could cancel the call: an HTTP handler
+                // is scoped to its request. Failures complete the call at once.
+                acked = true
+                if (fiber?.pollUnsafe()) resume(Exit.void)
+                return
+              }
               resume(exit)
               if (fiber && !fiber.pollUnsafe()) {
                 parentFiber.currentDispatcher.scheduleTask(() => {
@@ -433,6 +451,8 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any, E, const Flatten extend
             if (exit._tag === "Failure") {
               entries.delete(id)
               return resume(exit)
+            } else if (acked) {
+              return resume(Exit.void)
             }
           })
         }),
@@ -495,12 +515,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 +587,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)
@@ -591,11 +605,12 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any, E, const Flatten extend
         if (!entry || entry._tag !== "Queue") return Effect.void
         return Queue.offerAll(entry.queue, message.values).pipe(
           supportsAck
-            ? Effect.flatMap(() =>
-              options.onFromClient({
+            ? Effect.flatMap((dropped) =>
+              // values are dropped when the queue was shutdown by an interrupted
+              // consumer, so the server should not be asked for more
+              dropped.length > 0 ? Effect.void : options.onFromClient({
                 message: { _tag: "Ack", requestId: message.requestId },
-                context: entry.context,
-                discard: false
+                context: entry.context
               })
             )
             : identity,
@@ -687,6 +702,7 @@ 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>()
   // Completed before the protocol stops running this client, so requests made
@@ -713,7 +729,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)
 
@@ -795,7 +812,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({
@@ -811,8 +834,10 @@ export const make: <Rpcs extends Rpc.Any, const Flatten extends boolean = false>
       }
       case "ClientProtocolError": {
         const exit = Exit.fail(message.error)
-        const requestIds = Array.from(entries.keys())
-        entries.clear()
+        const requestIds = message.requestIds === undefined
+          ? Array.from(entries.keys())
+          : message.requestIds.map(RequestId).filter((requestId) => entries.has(requestId))
+        for (const requestId of requestIds) entries.delete(requestId)
         return Effect.forEach(
           requestIds,
           (requestId) => write({ _tag: "Exit", clientId: 0, requestId, exit: exit as any })
@@ -839,6 +864,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.
@@ -851,6 +877,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,
@@ -858,7 +886,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
@@ -924,6 +958,16 @@ export const withHeaders: {
  * Use to provide the transport boundary for RPC clients over HTTP, WebSocket,
  * workers, sockets, or custom protocols.
  *
+ * **Details**
+ *
+ * A `Request` that `send` accepts stays pending until a reply names its id: an
+ * `Exit`, or a `ClientProtocolError` that lists it in `requestIds`. Until then
+ * the client keeps the request and the caller's context, unless the caller is
+ * interrupted, the client closes or the connection fails. A transport that
+ * only delivers requests, such as a message queue, writes a void `Exit` for a
+ * `discard` request once the request is delivered, and fails `send` with an
+ * `RpcClientError` for any other request.
+ *
  * @stability unstable
  * @category services
  * @since 4.0.0
@@ -1570,21 +1614,26 @@ export const makeProtocolWorker = (
           undefined
       }).pipe(
         Effect.tapCause((cause) => {
+          const requestIdsByClient = new Map<number, Array<string | number>>()
           for (const [requestId, entry] of entries) {
             if (entry.worker !== backing) continue
             entries.delete(requestId)
             entry.latch.openUnsafe()
+            const requestIds = requestIdsByClient.get(entry.clientId)
+            if (requestIds) requestIds.push(requestId)
+            else requestIdsByClient.set(entry.clientId, [requestId])
           }
-          const error = Cause.findError(cause)
-          return broadcast({
-            _tag: "ClientProtocolError",
-            error: new RpcClientError({
-              reason: Result.isSuccess(error) ? error.success.reason : new RpcClientDefect({
-                message: "Error in worker",
-                cause: Cause.squash(cause)
-              })
+          const found = Cause.findError(cause)
+          const error = new RpcClientError({
+            reason: Result.isSuccess(found) ? found.success.reason : new RpcClientDefect({
+              message: "Error in worker",
+              cause: Cause.squash(cause)
             })
           })
+          return Effect.forEach(
+            requestIdsByClient,
+            ([clientId, requestIds]) => writeResponse(clientId, { _tag: "ClientProtocolError", error, requestIds })
+          )
         }),
         Effect.retry(Schedule.spaced(1000)),
         Effect.annotateLogs({
@@ -1635,7 +1684,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
@@ -317,8 +325,8 @@ export interface ResponseExitEncoded {
 }
 
 /**
- * A server-to-client protocol message reporting a client protocol error to all
- * affected in-flight requests.
+ * A server-to-client protocol message failing in-flight requests with a client
+ * protocol error: those in `requestIds`, or all of them when it is omitted.
  *
  * @stability unstable
  * @category models
@@ -327,6 +335,7 @@ export interface ResponseExitEncoded {
 export interface ClientProtocolError {
   readonly _tag: "ClientProtocolError"
   readonly error: RpcClientError
+  readonly requestIds?: ReadonlyArray<string | number>
 }
 
 /**
@@ -453,6 +462,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

@@ -374,6 +374,7 @@ function decodeJsonRpcMessage(
       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,
@@ -490,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
@@ -560,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