effect 4.0.0-rc.111 → 4.0.0-rc.113

package/src/unstable/cluster/ClusterSchema.ts

@@ -6,12 +6,30 @@
  *
  * @since 4.0.0
  */
+import * as Cause from "../../Cause.ts"
 import * as Context from "../../Context.ts"
-import { constFalse, constTrue, identity } from "../../Function.ts"
+import { constFalse, constTrue, constUndefined, identity } from "../../Function.ts"
 import type * as Rpc from "../rpc/Rpc.ts"
 import type { EntityId } from "./EntityId.ts"
 import type { Request } from "./Envelope.ts"
 
+/**
+ * Annotation carried by an interruption when a persisted cluster request is
+ * abandoned by its current runner and must continue under another owner.
+ *
+ * @category services
+ * @since 4.0.0
+ */
+export class Abandon extends Context.Service<Abandon, true>()("effect/cluster/ClusterSchema/Abandon") {
+  static annotation = this.context(true).pipe(
+    Context.add(Cause.StackTrace, {
+      name: "ClusterAbandon",
+      stack: constUndefined,
+      parent: undefined
+    })
+  )
+}
+
 /**
  * Annotation that marks whether a cluster request should be persisted in mailbox
  * storage.

package/src/unstable/cluster/ClusterWorkflowEngine.ts

@@ -21,6 +21,7 @@ import type * as Record from "../../Record.ts"
 import * as Schedule from "../../Schedule.ts"
 import * as Schema from "../../Schema.ts"
 import type * as Scope from "../../Scope.ts"
+import * as Semaphore from "../../Semaphore.ts"
 import * as Headers from "../http/Headers.ts"
 import * as Rpc from "../rpc/Rpc.ts"
 import { ClientAbort } from "../rpc/RpcSchema.ts"
@@ -36,6 +37,7 @@ import * as EntityAddress from "./EntityAddress.ts"
 import * as EntityId from "./EntityId.ts"
 import * as EntityType from "./EntityType.ts"
 import * as Envelope from "./Envelope.ts"
+import * as ClusterAbandon from "./internal/clusterAbandon.ts"
 import * as Message from "./Message.ts"
 import { MessageStorage } from "./MessageStorage.ts"
 import type { WithExitEncoded } from "./Reply.ts"
@@ -87,7 +89,7 @@ export const make = Effect.gen(function*() {
         >,
         Schema.declare<Workflow.Result<any, any>>
       >
-      | Rpc.Rpc<"resume", Schema.Struct<{}>>
+      | typeof ResumeRpc
     >
   >()
   const partialEntities = new Map<
@@ -100,7 +102,7 @@ export const make = Effect.gen(function*() {
         Schema.Struct<{ name: typeof Schema.String; attempt: typeof Schema.Int }>,
         Schema.declare<Workflow.Result<any, any>>
       >
-      | Rpc.Rpc<"resume">
+      | typeof ResumeRpc
     >
   >()
   const ensureEntity = (workflow: Workflow.Any) => {
@@ -292,23 +294,45 @@ export const make = Effect.gen(function*() {
   const sendResumeParent = Effect.fnUntraced(function*(options: {
     readonly workflowName: string
     readonly executionId: string
-  }) {
+  }, childExecutionId: string) {
     const requestId = yield* requestIdFor({
       workflow: workflows.get(options.workflowName)!,
       entityType: `Workflow/${options.workflowName}`,
       executionId: options.executionId,
       tag: "resume",
-      id: ""
+      id: childExecutionId
     })
     if (Option.isNone(requestId)) {
       const client = (yield* RcMap.get(clientsPartial, options.workflowName))(options.executionId)
-      return yield* client.resume({} as any, { discard: true })
+      return yield* client.resume({ childExecutionId }, { discard: true })
     }
     const reply = yield* replyForRequestId(requestId.value)
     if (Option.isNone(reply)) return
     yield* sharding.reset(requestId.value)
   }, Effect.scoped)
 
+  // A child may complete while its parent run is still unwinding. Subscribe to
+  // the run's reply before reading storage so the wake cannot fall between the
+  // parent's last read and its suspended reply.
+  const waitForRunReply = Effect.fnUntraced(function*(workflow: Workflow.Any, request: Entity.Request<any>) {
+    const waiter = yield* storage.registerReplyHandler(
+      new Message.OutgoingRequest<any>({
+        envelope: request,
+        context: Context.empty() as Context.Context<any>,
+        rpc: ensureEntity(workflow).protocol.requests.get("run")!,
+        lastReceivedReply: Option.none(),
+        respond: () => Effect.void,
+        annotations: Context.empty()
+      })
+    ).pipe(Effect.forkScoped({ startImmediately: true }))
+    const reply = yield* replyForRequestId(request.requestId)
+    if (Option.isSome(reply)) return
+    yield* Fiber.join(waiter).pipe(
+      Effect.catchTag("EntityNotAssignedToRunner", () => ClusterAbandon.interrupt),
+      Effect.catchCause((cause) => ClusterAbandon.isCause(cause) ? ClusterAbandon.interrupt : Effect.failCause(cause))
+    )
+  }, Effect.scoped)
+
   const interrupt = Effect.fnUntraced(
     function*(workflow: Workflow.Any, executionId: string) {
       ensureEntity(workflow)
@@ -357,19 +381,33 @@ export const make = Effect.gen(function*() {
           Effect.gen(function*() {
             const address = yield* Entity.CurrentAddress
             const executionId = address.entityId
+            // Latest run request for this entity; replays reuse its request id.
+            let currentRun: Entity.Request<any> | undefined
+            // Concurrent wakes share one wait for the current run to publish its reply.
+            const resumeGate = Semaphore.makeUnsafe(1)
             return {
               run: (request: Entity.Request<any>) => {
+                currentRun = request
                 const instance = WorkflowEngine.WorkflowInstance.initial(workflow, executionId)
-                const payload = request.payload as any
-                let parent: { workflowName: string; executionId: string } | undefined
-                if (payload[payloadParentKey]) {
-                  parent = payload[payloadParentKey]
-                }
-                return execute(workflow.payloadSchema.make(payload) as object, executionId).pipe(
+                const parent = (request.payload as any)[payloadParentKey] as
+                  | { workflowName: string; executionId: string }
+                  | undefined
+                return execute(workflow.payloadSchema.make(request.payload) as object, executionId).pipe(
                   Effect.onExit((exit) => {
                     const suspendOnFailure = Context.get(workflow.annotations, Workflow.SuspendOnFailure)
-                    if (!instance.suspended && !(suspendOnFailure && exit._tag === "Failure")) {
-                      return parent ? ensureSuccess(sendResumeParent(parent)) : Effect.void
+                    // An annotated cluster abandonment means this owner can no
+                    // longer finish the run. Do not resume the parent, but
+                    // still allow a pending durable interrupt to take effect.
+                    instance.abandoned ||= exit._tag === "Failure" && ClusterAbandon.isCause(exit.cause)
+                    if (instance.abandoned) {
+                      instance.suspended = false
+                    }
+                    if (
+                      !instance.suspended &&
+                      !instance.abandoned &&
+                      !(suspendOnFailure && exit._tag === "Failure")
+                    ) {
+                      return parent ? ensureSuccess(sendResumeParent(parent, executionId)) : Effect.void
                     }
                     return engine.deferredResult(InterruptSignal).pipe(
                       Effect.flatMap((maybeExit) => {
@@ -441,7 +479,16 @@ export const make = Effect.gen(function*() {
                 return payload.exit
               }),
 
-              resume: () => ensureSuccess(resume(workflow, executionId))
+              resume: () =>
+                resumeGate.withPermitsIfAvailable(1)(
+                  currentRun ? waitForRunReply(workflow, currentRun) : Effect.void
+                ).pipe(
+                  // Release the gate before reset can start another parent run, so
+                  // later child completions can wake that replay.
+                  Effect.flatMap((waited) => Option.isSome(waited) ? resume(workflow, executionId) : Effect.void),
+                  ensureSuccess,
+                  Rpc.wrap({ fork: true, uninterruptible: true })
+                )
             }
           }),
           // Reserve a slot for deferred completions to wake the active run.
@@ -695,8 +742,11 @@ const DeferredRpc = Rpc.make("deferred", {
 const decodeDeferredWithExit = Schema.decodeSync(Schema.toCodecJson(Reply.WithExit.schema(DeferredRpc)))
 
 const ResumeRpc = Rpc.make("resume", {
-  payload: {},
-  primaryKey: () => ""
+  // Older persisted resume envelopes have an empty payload and use the empty key.
+  payload: { childExecutionId: Schema.optional(Schema.String) },
+  // Different children must not share an in-flight wake: the parent may have
+  // already started another run when the next child finishes.
+  primaryKey: ({ childExecutionId }) => childExecutionId ?? ""
 })
   .annotate(ClusterSchema.Persisted, true)
   .annotate(ClusterSchema.Uninterruptible, "server")

package/src/unstable/cluster/Entity.ts

@@ -623,6 +623,7 @@ export const makeTestClient: <Type extends string, Rpcs extends Rpc.Any, LA, LE,
       Rpc.ServicesClient<Rpcs> | Rpc.ServicesServer<Rpcs> | Rpc.Middleware<Rpcs> | LR
     >
     readonly concurrency: number | "unbounded"
+    readonly disableFatalDefects: boolean | undefined
     readonly build: Effect.Effect<Context.Context<Rpc.ToHandler<Rpcs>>>
   }>()
   const sharding = shardingTag.of({
@@ -632,6 +633,7 @@ export const makeTestClient: <Type extends string, Rpcs extends Rpc.Any, LA, LE,
         entityMap.set(entity.type, {
           context: context as any,
           concurrency: options?.concurrency ?? 1,
+          disableFatalDefects: options?.disableFatalDefects,
           build: entity.protocol.toHandlers(handlers as any) as any
         })
         return Effect.void
@@ -663,6 +665,7 @@ export const makeTestClient: <Type extends string, Rpcs extends Rpc.Any, LA, LE,
     let client!: Effect.Success<ReturnType<typeof RpcClient.makeNoSerialization<Rpcs, never>>>
     const server = yield* RpcServer.makeNoSerialization(entity.protocol, {
       concurrency: entityEntry.concurrency,
+      disableFatalDefects: entityEntry.disableFatalDefects,
       onFromServer(response) {
         return client.write(response)
       }

package/src/unstable/cluster/EntityProxyServer.ts

@@ -42,7 +42,11 @@ export const layerHttpApi = <
   api: HttpApi.HttpApi<ApiId, Groups>,
   identifier: Identifier,
   entity: Entity.Entity<Type, Rpcs>
-): Layer.Layer<HttpApiGroup.Service<ApiId, Identifier>, never, Sharding | Rpc.ServicesServer<Rpcs>> =>
+): Layer.Layer<
+  HttpApiGroup.Service<ApiId, Identifier>,
+  never,
+  Sharding | Rpc.ServicesServer<Rpcs> | Rpc.ServicesClient<Rpcs>
+> =>
   HttpApiBuilder.group(
     api,
     identifier,
@@ -102,7 +106,7 @@ export const layerRpcHandlers = <
   Rpcs extends Rpc.Any
 >(
   entity: Entity.Entity<Type, Rpcs>
-): Layer.Layer<RpcHandlers<Rpcs, Type>, never, Sharding | Rpc.ServicesServer<Rpcs>> =>
+): Layer.Layer<RpcHandlers<Rpcs, Type>, never, Sharding | Rpc.ServicesServer<Rpcs> | Rpc.ServicesClient<Rpcs>> =>
   Layer.effectContext(Effect.gen(function*() {
     const context = yield* Effect.context<never>()
     const client = yield* entity.client

package/src/unstable/cluster/Envelope.ts

@@ -14,7 +14,7 @@ import * as PrimaryKey from "../../PrimaryKey.ts"
 import type { ReadonlyRecord } from "../../Record.ts"
 import * as Schema from "../../Schema.ts"
 import * as SchemaTransformation from "../../SchemaTransformation.ts"
-import * as Headers from "../http/Headers.ts"
+import type * as Headers from "../http/Headers.ts"
 import type * as Rpc from "../rpc/Rpc.ts"
 import { EntityAddress } from "./EntityAddress.ts"
 import { type Snowflake, SnowflakeFromBigInt } from "./Snowflake.ts"
@@ -27,6 +27,35 @@ import { type Snowflake, SnowflakeFromBigInt } from "./Snowflake.ts"
  */
 export const TypeId = "~effect/cluster/Envelope"
 
+/**
+ * Schema for a value that has already been encoded by the transport's hole
+ * codec.
+ *
+ * **Details**
+ *
+ * Cluster payloads are encoded twice: the entity payload is encoded with the
+ * entity RPC schema, and the result is carried opaquely inside the runner
+ * envelope. This schema names that hole so the outer runner encode leaves it
+ * alone. It is the identity under `Schema.toCodecJson`, so JSON, NDJSON, and
+ * text transports stay wire-compatible. A binary codec compiles it as a
+ * bytes leaf.
+ *
+ * @category schemas
+ * @since 4.0.0
+ */
+export const OpaqueHole: Schema.declare<any> = Schema.declare(
+  (_: unknown): _ is any => true,
+  {
+    expected: "an already-encoded value",
+    toCodecJson: () => undefined,
+    toCodec: () =>
+      Schema.link<any>()(
+        Schema.Uint8Array,
+        SchemaTransformation.passthrough()
+      )
+  }
+)
+
 /**
  * Union of cluster envelopes exchanged for an RPC request.
  *
@@ -103,8 +132,8 @@ export class PartialRequest extends Schema.Opaque<PartialRequest>()(Schema.Struc
   requestId: SnowflakeFromBigInt,
   address: EntityAddress,
   tag: Schema.String,
-  payload: Schema.Any,
-  headers: Headers.HeadersSchema,
+  payload: OpaqueHole,
+  headers: Schema.Headers,
   traceId: Schema.optional(Schema.String),
   spanId: Schema.optional(Schema.String),
   sampled: Schema.optional(Schema.Boolean)

package/src/unstable/cluster/HttpRunner.ts

@@ -18,6 +18,7 @@ import * as HttpRouter from "../http/HttpRouter.ts"
 import type * as HttpServer from "../http/HttpServer.ts"
 import type { HttpServerRequest } from "../http/HttpServerRequest.ts"
 import type { HttpServerResponse } from "../http/HttpServerResponse.ts"
+import * as NetAddress from "../net/NetAddress.ts"
 import * as RpcClient from "../rpc/RpcClient.ts"
 import * as RpcSerialization from "../rpc/RpcSerialization.ts"
 import * as RpcServer from "../rpc/RpcServer.ts"
@@ -56,14 +57,20 @@ export const layerClientProtocolHttp = (options: {
       const serialization = yield* RpcSerialization.RpcSerialization
       const client = yield* HttpClient.HttpClient
       const https = options.https ?? false
-      return (address) => {
-        const clientWithUrl = HttpClient.mapRequest(
-          client,
-          HttpClientRequest.prependUrl(`http${https ? "s" : ""}://${address.host}:${address.port}/${options.path}`)
-        )
-        return RpcClient.makeProtocolHttp(clientWithUrl).pipe(
-          Effect.provideService(RpcSerialization.RpcSerialization, serialization)
-        )
+      const path = options.path.startsWith("/") ? options.path : `/${options.path}`
+      return {
+        codecFor: serialization.codecFor,
+        make: (address) => {
+          const clientWithUrl = HttpClient.mapRequest(
+            client,
+            HttpClientRequest.prependUrl(
+              `http${https ? "s" : ""}://${NetAddress.formatUrlHostString(address.host)}:${address.port}${path}`
+            )
+          )
+          return RpcClient.makeProtocolHttp(clientWithUrl).pipe(
+            Effect.provideService(RpcSerialization.RpcSerialization, serialization)
+          )
+        }
       }
     })
   )
@@ -104,18 +111,22 @@ export const layerClientProtocolWebsocket = (options: {
     Effect.gen(function*() {
       const serialization = yield* RpcSerialization.RpcSerialization
       const https = options.https ?? false
+      const path = options.path.startsWith("/") ? options.path : `/${options.path}`
       const constructor = yield* Socket.WebSocketConstructor
-      return Effect.fnUntraced(function*(address) {
-        const socket = yield* Socket.makeWebSocket(
-          `ws${https ? "s" : ""}://${address.host}:${address.port}/${options.path}`
-        ).pipe(
-          Effect.provideService(Socket.WebSocketConstructor, constructor)
-        )
-        return yield* RpcClient.makeProtocolSocket().pipe(
-          Effect.provideService(Socket.Socket, socket),
-          Effect.provideService(RpcSerialization.RpcSerialization, serialization)
-        )
-      })
+      return {
+        codecFor: serialization.codecFor,
+        make: Effect.fnUntraced(function*(address) {
+          const socket = yield* Socket.makeWebSocket(
+            `ws${https ? "s" : ""}://${NetAddress.formatUrlHostString(address.host)}:${address.port}${path}`
+          ).pipe(
+            Effect.provideService(Socket.WebSocketConstructor, constructor)
+          )
+          return yield* RpcClient.makeProtocolSocket().pipe(
+            Effect.provideService(Socket.Socket, socket),
+            Effect.provideService(RpcSerialization.RpcSerialization, serialization)
+          )
+        })
+      }
     })
   )
 
@@ -147,12 +158,20 @@ export const toHttpEffect: Effect.Effect<
   never,
   Scope | RpcSerialization.RpcSerialization | Sharding.Sharding | MessageStorage
 > = Effect.gen(function*() {
-  const handlers = yield* Layer.build(RunnerServer.layerHandlers)
-  return yield* RpcServer.toHttpEffect(Runners.Rpcs, {
+  const { httpEffect, protocol } = yield* RpcServer.makeProtocolWithHttpEffect()
+  const handlers = yield* Layer.build(RunnerServer.layerHandlers).pipe(
+    Effect.provideService(RpcServer.Protocol, protocol)
+  )
+  yield* RpcServer.make(Runners.Rpcs, {
     spanPrefix: "RunnerServer",
     disableTracing: true,
     disableFatalDefects: true
-  }).pipe(Effect.provideContext(handlers))
+  }).pipe(
+    Effect.provideContext(handlers),
+    Effect.provideService(RpcServer.Protocol, protocol),
+    Effect.forkScoped
+  )
+  return httpEffect
 })
 
 /**
@@ -171,12 +190,20 @@ export const toHttpEffectWebsocket: Effect.Effect<
   never,
   Scope | RpcSerialization.RpcSerialization | Sharding.Sharding | MessageStorage
 > = Effect.gen(function*() {
-  const handlers = yield* Layer.build(RunnerServer.layerHandlers)
-  return yield* RpcServer.toHttpEffectWebsocket(Runners.Rpcs, {
+  const { httpEffect, protocol } = yield* RpcServer.makeProtocolWithHttpEffectWebsocket
+  const handlers = yield* Layer.build(RunnerServer.layerHandlers).pipe(
+    Effect.provideService(RpcServer.Protocol, protocol)
+  )
+  yield* RpcServer.make(Runners.Rpcs, {
     spanPrefix: "RunnerServer",
     disableTracing: true,
     disableFatalDefects: true
-  }).pipe(Effect.provideContext(handlers))
+  }).pipe(
+    Effect.provideContext(handlers),
+    Effect.provideService(RpcServer.Protocol, protocol),
+    Effect.forkScoped
+  )
+  return httpEffect
 })
 
 /**

package/src/unstable/cluster/Message.ts

@@ -15,6 +15,7 @@ import * as Effect from "../../Effect.ts"
 import * as Option from "../../Option.ts"
 import * as Schema from "../../Schema.ts"
 import * as Rpc from "../rpc/Rpc.ts"
+import type * as RpcSerialization from "../rpc/RpcSerialization.ts"
 import type { PersistenceError } from "./ClusterError.ts"
 import { MalformedMessage } from "./ClusterError.ts"
 import * as ClusterSchema from "./ClusterSchema.ts"
@@ -90,6 +91,13 @@ export class IncomingRequest<R extends Rpc.Any> extends Data.TaggedClass("Incomi
   readonly envelope: Envelope.PartialRequest
   readonly lastSentReply: Option.Option<Reply.Encoded>
   readonly respond: (reply: Reply.ReplyWithContext<R>) => Effect.Effect<void, MalformedMessage | PersistenceError>
+  /**
+   * Codec that filled the payload and reply holes of this message.
+   *
+   * Messages read from `MessageStorage` use the JSON codec, while the runner
+   * server sets it to the codec of its transport.
+   */
+  readonly codecFor: RpcSerialization.CodecFor
 }> {}
 
 /**
@@ -153,11 +161,15 @@ export class OutgoingRequest<R extends Rpc.Any> extends Data.TaggedClass("Outgoi
   readonly annotations: Context.Context<never>
 }> {
   /**
-   * Cached encoded envelope payload reused when sending the request.
+   * Cached encoded envelope payload and the codec that produced it. The cache
+   * is reused only when the requested codec is the same function.
    *
    * @since 4.0.0
    */
-  public encodedCache?: Envelope.PartialRequest
+  public encodedCache?: {
+    readonly codecFor: RpcSerialization.CodecFor
+    readonly envelope: Envelope.PartialRequest
+  }
 }
 
 /**
@@ -192,6 +204,8 @@ export class OutgoingEnvelope extends Data.TaggedClass("OutgoingEnvelope")<{
   }
 }
 
+const codecForJson = Schema.toCodecJson as RpcSerialization.CodecFor
+
 const neverRpc = Rpc.make("Never", {
   success: Schema.Never as any,
   error: Schema.Never,
@@ -210,16 +224,22 @@ const neverRpc = Rpc.make("Never", {
  * @since 4.0.0
  */
 export const serialize = <Rpc extends Rpc.Any>(
-  message: Outgoing<Rpc>
+  message: Outgoing<Rpc>,
+  codecFor: RpcSerialization.CodecFor
 ): Effect.Effect<Envelope.Partial, MalformedMessage> => {
   if (message._tag !== "OutgoingRequest") {
     return Effect.succeed(message.envelope)
   }
-  return Effect.suspend(() =>
-    message.encodedCache
-      ? Effect.succeed(message.encodedCache)
-      : serializeRequest(message)
-  )
+  return Effect.suspend(() => {
+    const cached = message.encodedCache
+    if (cached?.codecFor === codecFor) {
+      return Effect.succeed(cached.envelope)
+    }
+    return Effect.tap(serializeRequest(message, codecFor), (envelope) =>
+      Effect.sync(() => {
+        message.encodedCache = { codecFor, envelope }
+      }))
+  })
 }
 
 /**
@@ -236,7 +256,7 @@ export const serializeEnvelope = <Rpc extends Rpc.Any>(
   message: Outgoing<Rpc>
 ): Effect.Effect<Envelope.Encoded, MalformedMessage, never> =>
   Effect.flatMap(
-    serialize(message),
+    serialize(message, codecForJson),
     (envelope) => MalformedMessage.refail(Schema.encodeEffect(Envelope.PartialJson)(envelope))
   )
 
@@ -252,10 +272,11 @@ export const serializeEnvelope = <Rpc extends Rpc.Any>(
  * @since 4.0.0
  */
 export const serializeRequest = <Rpc extends Rpc.Any>(
-  self: OutgoingRequest<Rpc>
+  self: OutgoingRequest<Rpc>,
+  codecFor: RpcSerialization.CodecFor
 ): Effect.Effect<Envelope.PartialRequest, MalformedMessage> => {
   const rpc = self.rpc as any as Rpc.AnyWithProps
-  return Schema.encodeEffect(Schema.toCodecJson(rpc.payloadSchema))(self.envelope.payload).pipe(
+  return Schema.encodeEffect(codecFor(rpc.payloadSchema))(self.envelope.payload).pipe(
     Effect.provideContext(self.context),
     MalformedMessage.refail,
     Effect.map((payload) => ({
@@ -279,7 +300,8 @@ export const serializeRequest = <Rpc extends Rpc.Any>(
  */
 export const deserializeLocal = <Rpc extends Rpc.Any>(
   self: Outgoing<Rpc>,
-  encoded: Envelope.Partial
+  encoded: Envelope.Partial,
+  codecFor: RpcSerialization.CodecFor
 ): Effect.Effect<
   IncomingLocal<Rpc>,
   MalformedMessage
@@ -292,7 +314,7 @@ export const deserializeLocal = <Rpc extends Rpc.Any>(
     )
   }
   const rpc = self.rpc as any as Rpc.AnyWithProps
-  return Schema.decodeEffect(Schema.toCodecJson(rpc.payloadSchema))(encoded.payload).pipe(
+  return Schema.decodeEffect(codecFor(rpc.payloadSchema))(encoded.payload).pipe(
     Effect.provideContext(self.context),
     MalformedMessage.refail,
     Effect.map((payload) => {