effect 4.0.0-rc.112 → 4.0.0-rc.113

package/src/unstable/cli/internal/completions/descriptor.ts

@@ -20,10 +20,10 @@ const toFlagType = (single: Param.Single<"flag", unknown>): Completions.FlagType
   switch (tag) {
     case "Boolean":
       return { _tag: "Boolean" }
-    case "Integer":
-      return { _tag: "Integer" }
-    case "Float":
-      return { _tag: "Float" }
+    case "Int":
+      return { _tag: "Int" }
+    case "Finite":
+      return { _tag: "Finite" }
     case "Date":
       return { _tag: "Date" }
     case "Choice": {
@@ -44,10 +44,10 @@ const toFlagType = (single: Param.Single<"flag", unknown>): Completions.FlagType
 const toArgumentType = (single: Param.Single<"argument", unknown>): Completions.ArgumentType => {
   const tag = single.primitiveType._tag
   switch (tag) {
-    case "Integer":
-      return { _tag: "Integer" }
-    case "Float":
-      return { _tag: "Float" }
+    case "Int":
+      return { _tag: "Int" }
+    case "Finite":
+      return { _tag: "Finite" }
     case "Date":
       return { _tag: "Date" }
     case "Choice": {
@@ -70,18 +70,25 @@ const toArgumentType = (single: Param.Single<"argument", unknown>): Completions.
 // ---------------------------------------------------------------------------
 
 /** @internal */
-export const fromCommand = (cmd: Command.Any): Completions.CommandDescriptor => {
+export const fromCommand = (
+  cmd: Command.Any,
+  inheritedFlags: ReadonlyArray<Param.AnyFlag> = []
+): Completions.CommandDescriptor => {
   const impl = toImpl(cmd)
   const config = impl.config
 
   const flags: Array<Completions.FlagDescriptor> = []
-  for (const flag of config.flags) {
+  const seen = new Set<string>()
+  // Match help's precedence: local flags first, then ancestors root to leaf.
+  for (const [index, flag] of [...config.flags, ...inheritedFlags].entries()) {
     const singles = Param.extractSingleParams(flag)
     for (const single of singles) {
       if (single.kind !== "flag") continue
       // Omit hidden flags from completion scripts so tab-completion in the
       // shell does not advertise flags that are absent from --help.
       if (single.hidden) continue
+      if (index >= config.flags.length && seen.has(single.name)) continue
+      seen.add(single.name)
       flags.push({
         name: single.name,
         aliases: single.aliases,
@@ -108,12 +115,17 @@ export const fromCommand = (cmd: Command.Any): Completions.CommandDescriptor =>
   }
 
   const subcommands: Array<Completions.CommandDescriptor> = []
+  const sharedFlags = [...inheritedFlags, ...impl.contextConfig.flags]
   for (const group of cmd.subcommands) {
     for (const subcommand of group.commands) {
       // Omit unlisted subcommands from completion scripts so tab-completion in
       // the shell does not advertise commands that are absent from --help.
       if (subcommand.unlisted) continue
-      subcommands.push(fromCommand(subcommand))
+      const descriptor = fromCommand(subcommand, sharedFlags)
+      subcommands.push(descriptor)
+      if (subcommand.alias && subcommand.alias !== subcommand.name) {
+        subcommands.push({ ...descriptor, name: subcommand.alias })
+      }
     }
   }
 

package/src/unstable/cli/internal/completions/zsh.ts

@@ -41,9 +41,9 @@ const valueAction = (type: Completions.FlagType): string => {
       return `:value:(${type.values.map(escapeZshChoice).join(" ")})`
     case "Path":
       return type.pathType === "directory" ? `:directory:_directories` : `:file:_files`
-    case "Integer":
+    case "Int":
       return `:integer:`
-    case "Float":
+    case "Finite":
       return `:float:`
     case "Date":
       return `:date:`

package/src/unstable/cli/internal/config.ts

@@ -15,12 +15,12 @@
  * ```ts
  * // User declares:
  * const config = {
- *   verbose: Flag.boolean("verbose").pipe(Flag.withDefault(false)),
+ *   verbose: Flag.Boolean("verbose").pipe(Flag.withDefault(false)),
  *   server: {
- *     host: Flag.string("host"),
- *     port: Flag.integer("port")
+ *     host: Flag.String("host"),
+ *     port: Flag.Int("port")
  *   },
- *   files: Argument.string("files").pipe(Argument.variadic)
+ *   files: Argument.String("files").pipe(Argument.variadic)
  * }
  *
  * // Becomes Config.Internal:

package/src/unstable/cli/internal/parser.ts

@@ -408,7 +408,7 @@ const missingFlagValue = (spec: FlagParam): CliError.InvalidValue => {
  * Recognizes: true/false, yes/no, on/off, 1/0
  */
 const asBooleanLiteral = (token: Token | undefined): string | undefined =>
-  token?._tag === "Value" && (Primitive.isTrueValue(token.value) || Primitive.isFalseValue(token.value))
+  token?._tag === "Value" && (Primitive.isTrueLiteral(token.value) || Primitive.isFalseLiteral(token.value))
     ? token.value
     : undefined
 

package/src/unstable/cli/internal/wizard.ts

@@ -94,7 +94,7 @@ const promptCommand: (
       return
     }
 
-    const child = yield* Prompt.run(Prompt.select({
+    const child = yield* Prompt.run(Prompt.Select({
       message: "Command",
       choices: visibleSubcommands.map((command) => ({
         title: command.name,
@@ -130,7 +130,7 @@ const promptParam = Effect.fnUntraced(
     const metadata = Param.getParamMetadata(param)
 
     if (metadata.isOptional) {
-      const include = yield* Prompt.run(Prompt.confirm({
+      const include = yield* Prompt.run(Prompt.Confirm({
         message: `Set ${renderParamLabel(single)}?`,
         initial: false
       }))
@@ -142,7 +142,7 @@ const promptParam = Effect.fnUntraced(
 
     const count = !metadata.isVariadic
       ? 1
-      : yield* Prompt.run(Prompt.integer({
+      : yield* Prompt.run(Prompt.Int({
         message: `${renderParamLabel(single)} count`,
         default: Option.getOrElse(metadata.variadicMin, () => 0),
         min: Option.getOrElse(metadata.variadicMin, () => 0),
@@ -168,7 +168,12 @@ const promptParam = Effect.fnUntraced(
     if (single.kind === Param.argumentKind) {
       return values
     }
-    return values.flatMap((value) => [commandLineArg(`--${single.name}`), value])
+    // Inline option-looking values so the lexer cannot interpret them as flags or the -- delimiter.
+    return values.flatMap((value) =>
+      value.value.startsWith("-") && value.value.length > 1
+        ? [commandLineArg(`--${single.name}=${value.value}`, `--${single.name}=${value.displayValue}`)]
+        : [commandLineArg(`--${single.name}`), value]
+    )
   }
 )
 
@@ -179,7 +184,7 @@ const promptSingle = (
   switch (single.primitiveType._tag) {
     case "Boolean":
       return Effect.map(
-        Prompt.run(Prompt.confirm({
+        Prompt.run(Prompt.Confirm({
           message,
           label: {
             confirm: "true",
@@ -195,7 +200,7 @@ const promptSingle = (
     case "Choice": {
       const choices = Primitive.getChoiceKeys(single.primitiveType) ?? []
       return Effect.map(
-        Prompt.run(Prompt.select({
+        Prompt.run(Prompt.Select({
           message,
           choices: choices.map((choice) => ({ title: choice, value: choice }))
         })),
@@ -203,18 +208,18 @@ const promptSingle = (
       )
     }
     case "Date":
-      return Effect.map(Prompt.run(Prompt.date({ message })), (date) => commandLineArg(date.toISOString()))
-    case "Float":
-      return Effect.map(Prompt.run(Prompt.float({ message })), (value) => commandLineArg(String(value)))
-    case "Integer":
-      return Effect.map(Prompt.run(Prompt.integer({ message })), (value) => commandLineArg(String(value)))
+      return Effect.map(Prompt.run(Prompt.Date({ message })), (date) => commandLineArg(date.toISOString()))
+    case "Finite":
+      return Effect.map(Prompt.run(Prompt.Number({ message })), (value) => commandLineArg(String(value)))
+    case "Int":
+      return Effect.map(Prompt.run(Prompt.Int({ message })), (value) => commandLineArg(String(value)))
     case "Redacted":
       return Effect.map(
-        Prompt.run(Prompt.password({ message })),
+        Prompt.run(Prompt.Password({ message })),
         (value) => commandLineArg(Redacted.value(value), "<redacted>")
       )
     default:
-      return Effect.map(Prompt.run(Prompt.text({ message })), commandLineArg)
+      return Effect.map(Prompt.run(Prompt.String({ message })), commandLineArg)
   }
 }
 

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"
@@ -37,7 +37,7 @@ export const TypeId = "~effect/cluster/Envelope"
  * 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
- * MessagePack transports stay wire-compatible. A binary codec compiles it as a
+ * text transports stay wire-compatible. A binary codec compiles it as a
  * bytes leaf.
  *
  * @category schemas
@@ -133,7 +133,7 @@ export class PartialRequest extends Schema.Opaque<PartialRequest>()(Schema.Struc
   address: EntityAddress,
   tag: Schema.String,
   payload: OpaqueHole,
-  headers: Headers.HeadersSchema,
+  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,12 +57,15 @@ export const layerClientProtocolHttp = (options: {
       const serialization = yield* RpcSerialization.RpcSerialization
       const client = yield* HttpClient.HttpClient
       const https = options.https ?? false
+      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" : ""}://${address.host}:${address.port}/${options.path}`)
+            HttpClientRequest.prependUrl(
+              `http${https ? "s" : ""}://${NetAddress.formatUrlHostString(address.host)}:${address.port}${path}`
+            )
           )
           return RpcClient.makeProtocolHttp(clientWithUrl).pipe(
             Effect.provideService(RpcSerialization.RpcSerialization, serialization)
@@ -107,12 +111,13 @@ 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 {
         codecFor: serialization.codecFor,
         make: Effect.fnUntraced(function*(address) {
           const socket = yield* Socket.makeWebSocket(
-            `ws${https ? "s" : ""}://${address.host}:${address.port}/${options.path}`
+            `ws${https ? "s" : ""}://${NetAddress.formatUrlHostString(address.host)}:${address.port}${path}`
           ).pipe(
             Effect.provideService(Socket.WebSocketConstructor, constructor)
           )