alchemy 2.0.0-beta.65 → 2.0.0-beta.67

package/src/Cloudflare/Workflows/WorkflowBridge.ts

@@ -1,8 +1,10 @@
 import * as Cause from "effect/Cause";
+import type * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Layer from "effect/Layer";
 import * as Scope from "effect/Scope";
+import { buildEventTelemetry } from "../../Telemetry.ts";
 import { isScopeEjected } from "../Workers/HttpServer.ts";
 import { getWorkerExport } from "../Workers/WorkerBridge.ts";
 import {
@@ -49,18 +51,31 @@ export const makeWorkflowBridge =
     });
 
     return class WorkflowBridge extends WorkflowEntrypoint {
-      readonly fn: Promise<WorkflowImpl<unknown, unknown>>;
+      readonly build: Promise<{
+        readonly context: Context.Context<never>;
+        readonly fn: WorkflowImpl<unknown, unknown>;
+        readonly telemetry: () => Layer.Layer<never, any, any> | undefined;
+      }>;
 
       constructor(ctx: unknown, env: unknown) {
         super(ctx, env);
 
-        this.fn = build(() => {}).then(({ context, export: wf }) =>
-          wf.make(env).pipe(Effect.provideContext(context), Effect.runPromise),
-        ) as Promise<WorkflowImpl<unknown, unknown>>;
+        this.build = build(() => {}).then(
+          ({ context, export: wf, telemetry }) =>
+            wf.make(env).pipe(
+              Effect.provideContext(context),
+              Effect.map((fn) => ({
+                context,
+                fn: fn as WorkflowImpl<unknown, unknown>,
+                telemetry,
+              })),
+              Effect.runPromise,
+            ),
+        );
       }
 
       async run(event: any, step: any): Promise<unknown> {
-        const fn = await this.fn;
+        const { context, fn, telemetry } = await this.build;
         // Each run-invocation gets a fresh `Scope`, following the same
         // per-invocation-scope pattern as `WorkerBridge.processEvent`. `task`
         // threads it into every step via the surrounding body context, so
@@ -71,15 +86,18 @@ export const makeWorkflowBridge =
         const exit = await Effect.runPromiseExit(
           fn(event.payload).pipe(
             Effect.provide(
-              Layer.succeed(
-                WorkflowEventService,
-                wrapWorkflowEvent(event),
-              ).pipe(
-                Layer.provideMerge(
-                  Layer.succeed(WorkflowStep, wrapWorkflowStep(step)),
+              Layer.mergeAll(
+                Layer.succeed(WorkflowEventService, wrapWorkflowEvent(event)),
+                Layer.succeed(WorkflowStep, wrapWorkflowStep(step)),
+                Layer.succeed(Scope.Scope, scope),
+                // The configured telemetry exporters, attached to the run's
+                // scope by `buildEventTelemetry` so buffered telemetry
+                // flushes when the scope closes at the end of the
+                // run-invocation.
+                Layer.effectContext(
+                  buildEventTelemetry(context, scope, telemetry()),
                 ),
-                Layer.provideMerge(Layer.succeed(Scope.Scope, scope)),
-              ),
+              ).pipe(Layer.provideMerge(Layer.succeedContext(context))),
             ),
           ) as Effect.Effect<unknown>,
         );

package/src/Command/Build.ts

@@ -8,14 +8,14 @@ import * as Provider from "../Provider.ts";
 import { Resource } from "../Resource.ts";
 import { sha256Object } from "../Util/sha256.ts";
 import {
-  CommandError,
   CommandExecutor,
   OutputNotFound,
-  type CommandProps,
+  makeCommandError,
+  type CommandRunProps,
 } from "./Command.ts";
 import { hashDirectory, type MemoOptions } from "./Memo.ts";
 
-export interface BuildProps extends CommandProps {
+export interface BuildProps extends CommandRunProps {
   /**
    * The output path (file or directory) produced by the build.
    * This path is relative to the working directory.
@@ -116,7 +116,7 @@ export const Build = Resource<Build>("Command.Build");
  * secret's value still busts the memo hash (the hash is one-way, so the secret
  * itself is never recoverable from state).
  */
-const resolveEnv = (env: CommandProps["env"]) =>
+const resolveEnv = (env: CommandRunProps["env"]) =>
   env
     ? Object.fromEntries(
         Object.entries(env).map(([key, value]) => [
@@ -138,12 +138,12 @@ export const BuildProvider = () =>
         const cwd = path.resolve(props.cwd ?? process.cwd());
         const outdir = path.resolve(cwd, props.outdir);
         if (!(yield* fs.exists(outdir))) {
-          return yield* new CommandError({
-            command: props.command,
-            reason: new OutputNotFound({
+          return yield* makeCommandError(
+            props,
+            new OutputNotFound({
               outdir: props.outdir,
             }),
-          });
+          );
         }
         return {
           outdir: path.relative(process.cwd(), outdir),

package/src/Command/Command.ts

@@ -5,12 +5,15 @@
 
 import * as Context from "effect/Context";
 import * as Data from "effect/Data";
+import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
 import { flow } from "effect/Function";
 import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
 import * as Path from "effect/Path";
-import type { PlatformError, SystemError } from "effect/PlatformError";
-import { BadArgument } from "effect/PlatformError";
+import type { PlatformError } from "effect/PlatformError";
+import { BadArgument, SystemError } from "effect/PlatformError";
 import * as Predicate from "effect/Predicate";
 import * as Redacted from "effect/Redacted";
 import type * as Scope from "effect/Scope";
@@ -20,6 +23,11 @@ import * as ChildProcess from "effect/unstable/process/ChildProcess";
 import * as ChildProcessSpawner from "effect/unstable/process/ChildProcessSpawner";
 import type { ScopedPlanStatusSession } from "../Cli/Cli.ts";
 import { isNonInteractive } from "../Util/interactive.ts";
+import {
+  makeCommandRedactor,
+  redactPlatformReason,
+  type CommandRedactor,
+} from "./Redaction.ts";
 
 /**
  * Base properties for a command resource.
@@ -46,6 +54,24 @@ export interface CommandProps {
   env?: Record<string, string | Redacted.Redacted<string>>;
 }
 
+/**
+ * Properties shared by finite commands such as {@link Build} and
+ * {@link Exec}.
+ */
+export interface CommandRunProps extends CommandProps {
+  /**
+   * Maximum time the command may run. When exceeded, Alchemy sends `SIGTERM`
+   * to the command's process group, waits a bounded grace period, and then
+   * sends `SIGKILL` to ensure no descendants survive.
+   *
+   * Numbers are interpreted as milliseconds. Effect duration strings and
+   * `Duration` values are also accepted.
+   *
+   * @example "5 minutes"
+   */
+  timeout?: Duration.Input;
+}
+
 export class CommandExecutor extends Context.Service<
   CommandExecutor,
   {
@@ -64,7 +90,7 @@ export class CommandExecutor extends Context.Service<
      * Throws a {@link CommandError} if the command exits with a non-zero exit code.
      */
     readonly run: (
-      props: CommandProps,
+      props: CommandRunProps,
       session: ScopedPlanStatusSession,
     ) => Effect.Effect<
       { exitCode: number; stdout: string; stderr: string },
@@ -78,7 +104,12 @@ export class CommandExecutor extends Context.Service<
  */
 export class CommandError extends Data.TaggedError("CommandError")<{
   command: string;
-  reason: SystemError | BadArgument | UnexpectedExit | OutputNotFound;
+  reason:
+    | SystemError
+    | BadArgument
+    | UnexpectedExit
+    | OutputNotFound
+    | CommandTimedOut;
   cause?: unknown;
 }> {
   constructor({
@@ -115,6 +146,17 @@ export class UnexpectedExit extends Data.TaggedError("UnexpectedExit")<{
   }
 }
 
+/**
+ * Represents when a finite command exceeds its configured timeout.
+ */
+export class CommandTimedOut extends Data.TaggedError("CommandTimedOut")<{
+  timeout: string;
+}> {
+  override get message() {
+    return `The command timed out after ${this.timeout}; its process group was terminated.`;
+  }
+}
+
 /**
  * Represents when the output directory does not exist.
  */
@@ -126,6 +168,109 @@ export class OutputNotFound extends Data.TaggedError("OutputNotFound")<{
   }
 }
 
+/** @internal */
+export const makeCommandError = (
+  props: Pick<CommandProps, "command" | "env">,
+  reason: CommandError["reason"],
+): CommandError => {
+  const redactor = makeCommandRedactor(props.env);
+  const safeReason =
+    reason instanceof BadArgument || reason instanceof SystemError
+      ? redactPlatformReason(reason, redactor)
+      : reason._tag === "UnexpectedExit"
+        ? new UnexpectedExit({
+            exitCode: reason.exitCode,
+            stderr: redactor.redact(reason.stderr),
+          })
+        : reason._tag === "OutputNotFound"
+          ? new OutputNotFound({ outdir: redactor.redact(reason.outdir) })
+          : new CommandTimedOut({
+              timeout: redactor.redact(reason.timeout),
+            });
+
+  return new CommandError({
+    command: redactor.redact(props.command),
+    reason: safeReason,
+  });
+};
+
+const TERMINATION_GRACE_PERIOD = Duration.seconds(1);
+const TERMINATION_SIGNAL_DISPATCH_TIMEOUT = Duration.millis(25);
+
+const parseExecutionTimeout = (
+  props: CommandRunProps,
+): Effect.Effect<Duration.Duration | undefined, CommandError> => {
+  if (props.timeout === undefined) return Effect.succeed(undefined);
+  const decoded = Duration.fromInput(props.timeout);
+  if (
+    Option.isNone(decoded) ||
+    !Duration.isFinite(decoded.value) ||
+    Duration.isZero(decoded.value) ||
+    Duration.isNegative(decoded.value)
+  ) {
+    return Effect.fail(
+      makeCommandError(
+        props,
+        new BadArgument({
+          module: "Command",
+          method: "run",
+          description: "timeout must be a positive finite duration",
+        }),
+      ),
+    );
+  }
+  return Effect.succeed(decoded.value);
+};
+
+const terminateProcessGroup = (child: ChildProcessSpawner.ChildProcessHandle) =>
+  Effect.gen(function* () {
+    // Dispatch SIGTERM without waiting indefinitely for the root process. The
+    // Effect process runtime targets the detached process group on POSIX and
+    // the full process tree on Windows.
+    yield* child
+      .kill({ killSignal: "SIGTERM" })
+      .pipe(
+        Effect.timeoutOption(TERMINATION_SIGNAL_DISPATCH_TIMEOUT),
+        Effect.ignore,
+      );
+    yield* Effect.sleep(TERMINATION_GRACE_PERIOD);
+
+    // Always signal the group again: the root may have exited promptly while
+    // a descendant ignored SIGTERM. The hard-kill wait is itself bounded.
+    yield* child
+      .kill({ killSignal: "SIGKILL" })
+      .pipe(Effect.timeoutOption(TERMINATION_GRACE_PERIOD), Effect.ignore);
+  });
+
+const redactChildProcessHandle = (
+  child: ChildProcessSpawner.ChildProcessHandle,
+  redactor: CommandRedactor,
+): ChildProcessSpawner.ChildProcessHandle => {
+  const stdout = child.stdout.pipe(
+    Stream.decodeText,
+    redactor.stream,
+    Stream.encodeText,
+  );
+  const stderr = child.stderr.pipe(
+    Stream.decodeText,
+    redactor.stream,
+    Stream.encodeText,
+  );
+  return ChildProcessSpawner.makeHandle({
+    pid: child.pid,
+    exitCode: child.exitCode,
+    isRunning: child.isRunning,
+    kill: child.kill,
+    stdin: child.stdin,
+    stdout,
+    stderr,
+    all: Stream.merge(stdout, stderr),
+    getInputFd: child.getInputFd,
+    getOutputFd: child.getOutputFd,
+    unref: child.unref,
+  });
+};
+
 export const CommandExecutorLive = () =>
   Layer.effect(
     CommandExecutor,
@@ -145,14 +290,14 @@ export const CommandExecutorLive = () =>
           .filter((part) => !!part.trim());
         if (!bin) {
           return Effect.fail(
-            new CommandError({
-              command: props.command,
-              reason: new BadArgument({
+            makeCommandError(
+              props,
+              new BadArgument({
                 module: "Command",
                 method: "parseCommand",
                 description: "Command is empty",
               }),
-            }),
+            ),
           );
         }
         return Effect.succeed({ bin, args });
@@ -176,20 +321,28 @@ export const CommandExecutorLive = () =>
                 stdin: isNonInteractive() ? "ignore" : "inherit",
                 stdout: "pipe",
                 stderr: "pipe",
-                detached: false,
+                // The Effect process runtime creates a detached process group
+                // by default on POSIX. Preserve that default so timeouts and
+                // scoped interruption can terminate every descendant.
+                killSignal: "SIGKILL",
               }),
             ),
           ),
-          mapError(props.command),
+          Effect.map((child) =>
+            redactChildProcessHandle(child, makeCommandRedactor(props.env)),
+          ),
+          mapError(props),
         );
 
       /** Collects the output of a stream, tapping each line to a sink. */
       const collect = (
         stream: Stream.Stream<Uint8Array, PlatformError>,
         tap: (chunk: string) => Effect.Effect<void>,
+        redactor: CommandRedactor,
       ) =>
         stream.pipe(
           Stream.decodeText,
+          redactor.stream,
           Stream.tapSink(
             Sink.make<string>()(
               flow(Stream.splitLines, Stream.runForEach(tap)),
@@ -199,46 +352,68 @@ export const CommandExecutorLive = () =>
         );
 
       /** Maps a PlatformError to a CommandError. */
-      const mapError = (command: string) =>
+      const mapError = (props: CommandProps) =>
         Effect.mapError((error: PlatformError | CommandError) =>
           error._tag === "CommandError"
             ? error
-            : new CommandError({
-                command,
-                reason: error.reason,
-              }),
+            : makeCommandError(props, error.reason),
         );
 
       return CommandExecutor.of({
         spawn,
         /** Executes a command, returning the exit code, stdout, and stderr. */
-        run: (props: CommandProps, session: ScopedPlanStatusSession) =>
-          spawn(props).pipe(
-            Effect.flatMap((child) =>
-              Effect.all(
-                {
-                  exitCode: child.exitCode,
-                  stdout: collect(child.stdout, session.note),
-                  stderr: collect(child.stderr, session.note),
-                },
-                { concurrency: "unbounded" },
-              ).pipe(mapError(props.command)),
-            ),
-            Effect.tap(({ exitCode, stderr }) =>
-              exitCode !== 0
-                ? Effect.fail(
-                    new CommandError({
-                      command: props.command,
-                      reason: new UnexpectedExit({
-                        exitCode,
-                        stderr,
-                      }),
-                    }),
-                  )
-                : Effect.void,
-            ),
-            Effect.scoped,
-          ),
+        run: (props: CommandRunProps, session: ScopedPlanStatusSession) =>
+          Effect.gen(function* () {
+            const timeout = yield* parseExecutionTimeout(props);
+            const redactor = makeCommandRedactor(props.env);
+            const child = yield* spawn(props);
+            const execution = Effect.all(
+              {
+                exitCode: child.exitCode,
+                stdout: collect(child.stdout, session.note, redactor),
+                stderr: collect(child.stderr, session.note, redactor),
+              },
+              { concurrency: "unbounded" },
+            ).pipe(mapError(props));
+
+            const result =
+              timeout === undefined
+                ? yield* execution
+                : yield* Effect.gen(function* () {
+                    const fiber = yield* Effect.forkScoped(execution);
+                    const completed = yield* Fiber.join(fiber).pipe(
+                      Effect.timeoutOption(timeout),
+                    );
+                    if (Option.isSome(completed)) return completed.value;
+
+                    yield* terminateProcessGroup(child);
+                    yield* Fiber.interrupt(fiber).pipe(
+                      Effect.timeoutOption(TERMINATION_GRACE_PERIOD),
+                      Effect.ignore,
+                    );
+                    return yield* Effect.fail(
+                      makeCommandError(
+                        props,
+                        new CommandTimedOut({
+                          timeout: Duration.format(timeout),
+                        }),
+                      ),
+                    );
+                  });
+
+            if (result.exitCode !== 0) {
+              return yield* Effect.fail(
+                makeCommandError(
+                  props,
+                  new UnexpectedExit({
+                    exitCode: result.exitCode,
+                    stderr: result.stderr,
+                  }),
+                ),
+              );
+            }
+            return result;
+          }).pipe(Effect.scoped),
       });
     }),
   );