Open History to see the last commit
1/**
2 * Deno implementation of the child process spawner service.
3 *
4 * This module uses `Deno.Command` and Web Streams directly. Deno cannot create
5 * detached process groups, so killing a handle terminates only its direct child;
6 * descendants spawned by that child are left running.
7 *
8 * @stability unstable
9 * @since 4.0.0
10 */
11import type * as Arr from "effect/Array"
12import * as Deferred from "effect/Deferred"
13import * as Effect from "effect/Effect"
14import * as Exit from "effect/Exit"
15import * as Layer from "effect/Layer"
16import * as Path from "effect/Path"
17import * as PlatformError from "effect/PlatformError"
18import * as Predicate from "effect/Predicate"
19import * as ChildProcess from "effect/process/ChildProcess"
20import type { ChildProcessHandle } from "effect/process/ChildProcessSpawner"
21import {
22 ChildProcessSpawner,
23 ExitCode,
24 make as makeSpawner,
25 makeHandle,
26 ProcessId
27} from "effect/process/ChildProcessSpawner"
28import * as CommandLine from "effect/process/CommandLine"
29import * as Redacted from "effect/Redacted"
30import type * as Scope from "effect/Scope"
31import * as Sink from "effect/Sink"
32import * as Stream from "effect/Stream"
33
34const unwrap = (value: string | Redacted.Redacted<string>): string =>
35 Redacted.isRedacted(value) ? Redacted.value(value) : value
36
37// Deno cannot pass NUL characters to a process. They are rejected before
38// spawning so that the error does not depend on Deno's message.
39const findNulCharacter = (command: ChildProcess.StandardCommand): string | undefined => {
40 if (command.command.includes("\0")) return "The command contains a NUL character"
41 const index = command.args.findIndex((arg) => unwrap(arg).includes("\0"))
42 if (index !== -1) return `Argument ${index + 1} contains a NUL character`
43 for (const [name, value] of Object.entries(command.options.env ?? {})) {
44 if (value !== undefined && unwrap(value).includes("\0")) {
45 return `The environment variable ${name} contains a NUL character`
46 }
47 }
48 return undefined
49}
50
51const commandString = (command: ChildProcess.Command): string => {
52 const { commands } = flattenCommand(command)
53 const format = Deno.build.os === "windows" ? "windows" : "posix"
54 return commands.map((command) => CommandLine.display([command.command, ...command.args], { format })).join(" | ")
55}
56
57const toPlatformError = (
58 method: string,
59 cause: unknown,
60 command: ChildProcess.Command
61): PlatformError.PlatformError => {
62 const errorName = Predicate.hasProperty(cause, "name") ? cause.name : undefined
63 const tag = errorName === "NotFound" ?
64 "NotFound" :
65 errorName === "PermissionDenied" ?
66 "PermissionDenied" :
67 errorName === "TimedOut"
68 ? "TimedOut"
69 : "Unknown"
70 return PlatformError.systemError({
71 _tag: tag,
72 module: "ChildProcess",
73 method,
74 pathOrDescriptor: commandString(command),
75 syscall: `${method} ${commandString(command)}`,
76 cause
77 })
78}
79
80const unsupported = (option: "additionalFds" | "detached") =>
81 PlatformError.badArgument({
82 module: "ChildProcessSpawner",
83 method: "spawn",
84 description: `The ${option} option is unsupported because Deno has no equivalent`
85 })
86
87const make = Effect.gen(function*() {
88 const path = yield* Path.Path
89
90 const resolveWorkingDirectory = (options: ChildProcess.CommandOptions) =>
91 options.cwd === undefined ? undefined : path.resolve(options.cwd)
92
93 const resolveEnvironment = (
94 options: ChildProcess.CommandOptions
95 ): { readonly env: Record<string, string>; readonly clearEnv: boolean } | undefined => {
96 if (options.env === undefined) return undefined
97 const extend = options.extendEnv === true
98 // Deno can only add variables to the inherited environment, so removing
99 // one needs the whole environment.
100 const removes = Object.values(options.env).some((value) => value === undefined)
101 const env: Record<string, string> = extend && removes ? Deno.env.toObject() : {}
102 for (const [key, value] of Object.entries(options.env)) {
103 if (value === undefined) delete env[key]
104 else env[key] = unwrap(value)
105 }
106 return { env, clearEnv: !extend || removes }
107 }
108
109 const resolveStdinOption = (options: ChildProcess.CommandOptions): ChildProcess.StdinConfig => {
110 const defaultConfig: ChildProcess.StdinConfig = { stream: "pipe", encoding: "utf-8", endOnDone: true }
111 if (options.stdin === undefined) {
112 return defaultConfig
113 }
114 if (typeof options.stdin === "string") {
115 return { ...defaultConfig, stream: options.stdin }
116 }
117 if (Stream.isStream(options.stdin)) {
118 return { ...defaultConfig, stream: options.stdin }
119 }
120 return {
121 stream: options.stdin.stream,
122 encoding: options.stdin.encoding ?? defaultConfig.encoding,
123 endOnDone: options.stdin.endOnDone ?? defaultConfig.endOnDone
124 }
125 }
126
127 const resolveOutputOption = (
128 options: ChildProcess.CommandOptions,
129 streamName: "stdout" | "stderr"
130 ): ChildProcess.StdoutConfig => {
131 const option = options[streamName]
132 if (option === undefined) return { stream: "pipe" }
133 if (typeof option === "string" || Sink.isSink(option)) return { stream: option }
134 return { stream: option.stream }
135 }
136
137 const inputToStdioOption = (
138 input: ChildProcess.CommandInput
139 ): "piped" | "inherit" | "null" =>
140 Stream.isStream(input) || input === "pipe" || input === "overlapped" ?
141 "piped" :
142 input === "ignore"
143 ? "null"
144 : "inherit"
145
146 const outputToStdioOption = (
147 output: ChildProcess.CommandOutput | undefined
148 ): "piped" | "inherit" | "null" =>
149 Sink.isSink(output) || output === "pipe" || output === "overlapped" || output === undefined ?
150 "piped" :
151 output === "ignore"
152 ? "null"
153 : "inherit"
154
155 const setupChildStdin = (
156 command: ChildProcess.StandardCommand,
157 childProcess: Deno.ChildProcess,
158 config: ChildProcess.StdinConfig,
159 inputFailure: Deferred.Deferred<never, PlatformError.PlatformError>
160 ) =>
161 Effect.suspend(() => {
162 if (inputToStdioOption(config.stream) !== "piped") return Effect.succeed(Sink.drain)
163 const sink = Sink.fromWritableStream({
164 evaluate: () => childProcess.stdin,
165 onError: (cause) => toPlatformError("fromWritable(stdin)", cause, command),
166 closeOnDone: config.endOnDone
167 })
168 return Stream.isStream(config.stream)
169 ? Effect.as(
170 Effect.forkScoped(
171 // Record a failure of the source stream so that it can be surfaced
172 // by the process exit code
173 Stream.run(Stream.tapError(config.stream, (error) => Deferred.fail(inputFailure, error)), sink)
174 ),
175 sink
176 )
177 : Effect.succeed(sink)
178 })
179
180 const setupChildOutputStreams = (
181 command: ChildProcess.StandardCommand,
182 childProcess: Deno.ChildProcess,
183 stdoutConfig: ChildProcess.StdoutConfig,
184 stderrConfig: ChildProcess.StderrConfig
185 ) => {
186 let stdout: Stream.Stream<Uint8Array, PlatformError.PlatformError> =
187 outputToStdioOption(stdoutConfig.stream) === "piped"
188 ? Stream.fromReadableStream({
189 evaluate: () => childProcess.stdout,
190 onError: (cause) => toPlatformError("fromReadable(stdout)", cause, command)
191 })
192 : Stream.empty
193 let stderr: Stream.Stream<Uint8Array, PlatformError.PlatformError> =
194 outputToStdioOption(stderrConfig.stream) === "piped"
195 ? Stream.fromReadableStream({
196 evaluate: () => childProcess.stderr,
197 onError: (cause) => toPlatformError("fromReadable(stderr)", cause, command)
198 })
199 : Stream.empty
200
201 if (Sink.isSink(stdoutConfig.stream)) stdout = Stream.transduce(stdout, stdoutConfig.stream)
202 if (Sink.isSink(stderrConfig.stream)) stderr = Stream.transduce(stderr, stderrConfig.stream)
203
204 return { stdout, stderr, all: Stream.merge(stdout, stderr) }
205 }
206
207 const spawn = (
208 command: ChildProcess.StandardCommand,
209 executable: string,
210 args: ReadonlyArray<string>,
211 options: Deno.CommandOptions
212 ) =>
213 Effect.try({
214 try: () => {
215 const childProcess = new Deno.Command(executable, { ...options, args: [...args] }).spawn()
216 const exitSignal = Deferred.makeUnsafe<Deno.CommandStatus, PlatformError.PlatformError>()
217 childProcess.status.then(
218 (status) => Deferred.doneUnsafe(exitSignal, Exit.succeed(status)),
219 (cause) => Deferred.doneUnsafe(exitSignal, Exit.fail(toPlatformError("status", cause, command)))
220 )
221 return [childProcess, exitSignal] as const
222 },
223 catch: (cause) => toPlatformError("spawn", cause, command)
224 })
225
226 const killProcess = (
227 command: ChildProcess.StandardCommand,
228 childProcess: Deno.ChildProcess,
229 signal: ChildProcess.Signal
230 ) =>
231 Effect.try({
232 try: () => childProcess.kill(signal as Deno.Signal),
233 catch: (cause) => toPlatformError("kill", cause, command)
234 })
235
236 const withTimeout = (
237 childProcess: Deno.ChildProcess,
238 command: ChildProcess.StandardCommand,
239 options: ChildProcess.KillOptions | undefined
240 ) =>
241 <A, E, R>(
242 kill: (
243 command: ChildProcess.StandardCommand,
244 childProcess: Deno.ChildProcess,
245 signal: ChildProcess.Signal
246 ) => Effect.Effect<A, E, R>
247 ) => {
248 const killSignal = options?.killSignal ?? "SIGTERM"
249 return options?.forceKillAfter === undefined
250 ? kill(command, childProcess, killSignal)
251 : Effect.timeoutOrElse(kill(command, childProcess, killSignal), {
252 duration: options.forceKillAfter,
253 orElse: () => kill(command, childProcess, "SIGKILL")
254 })
255 }
256
257 const getSourceStream = (
258 handle: ChildProcessHandle,
259 from: "stdout" | "stderr" | "all"
260 ): Stream.Stream<Uint8Array, PlatformError.PlatformError> => {
261 switch (from) {
262 case "stdout":
263 return handle.stdout
264 case "stderr":
265 return handle.stderr
266 case "all":
267 return handle.all
268 }
269 }
270
271 const spawnCommand: (
272 command: ChildProcess.Command
273 ) => Effect.Effect<ChildProcessHandle, PlatformError.PlatformError, Scope.Scope> = Effect.fnUntraced(function*(cmd) {
274 switch (cmd._tag) {
275 case "StandardCommand": {
276 if (cmd.options.additionalFds !== undefined) {
277 return yield* Effect.fail(unsupported("additionalFds"))
278 }
279 if (cmd.options.detached !== undefined) {
280 return yield* Effect.fail(unsupported("detached"))
281 }
282
283 const stdinConfig = resolveStdinOption(cmd.options)
284 const stdoutConfig = resolveOutputOption(cmd.options, "stdout")
285 const stderrConfig = resolveOutputOption(cmd.options, "stderr")
286 let isReferenced = true
287
288 if (cmd.options.shell !== undefined && cmd.options.shell !== false && cmd.args.length > 0) {
289 return yield* Effect.fail(PlatformError.badArgument({
290 module: "ChildProcess",
291 method: "spawn",
292 description: "The shell option cannot be combined with arguments; pass the whole script as the command"
293 }))
294 }
295 const nulCharacter = findNulCharacter(cmd)
296 if (nulCharacter !== undefined) {
297 return yield* Effect.fail(PlatformError.badArgument({
298 module: "ChildProcess",
299 method: "spawn",
300 description: nulCharacter
301 }))
302 }
303
304 let executable = cmd.command
305 let args: ReadonlyArray<string> = cmd.args.map(unwrap)
306 let windowsRawArguments = false
307 if (cmd.options.shell) {
308 const shellCommand = cmd.command
309 if (Deno.build.os === "windows") {
310 executable = typeof cmd.options.shell === "string" ? cmd.options.shell : "cmd.exe"
311 args = ["/d", "/s", "/c", shellCommand]
312 windowsRawArguments = true
313 } else {
314 executable = typeof cmd.options.shell === "string" ? cmd.options.shell : "/bin/sh"
315 args = ["-c", shellCommand]
316 }
317 }
318
319 const cwd = resolveWorkingDirectory(cmd.options)
320 const env = resolveEnvironment(cmd.options)
321 const [childProcess, exitSignal] = yield* Effect.acquireRelease(
322 spawn(cmd, executable, args, {
323 ...(cwd === undefined ? undefined : { cwd }),
324 ...(env === undefined ? undefined : { env: env.env }),
325 clearEnv: env?.clearEnv ?? false,
326 stdin: inputToStdioOption(stdinConfig.stream),
327 stdout: outputToStdioOption(stdoutConfig.stream),
328 stderr: outputToStdioOption(stderrConfig.stream),
329 windowsRawArguments
330 }),
331 Effect.fnUntraced(function*([childProcess, exitSignal]) {
332 const exited = yield* Deferred.isDone(exitSignal)
333 if (exited || !isReferenced) return
334 const killWithTimeout = withTimeout(childProcess, cmd, cmd.options)
335 yield* killWithTimeout((command, childProcess, signal) =>
336 killProcess(command, childProcess, signal).pipe(
337 Effect.andThen(Deferred.await(exitSignal))
338 )
339 ).pipe(Effect.ignore)
340 })
341 )
342
343 const reref = Effect.sync(() => {
344 if (!isReferenced) {
345 childProcess.ref()
346 isReferenced = true
347 }
348 })
349 const unref = Effect.sync(() => {
350 if (isReferenced) {
351 childProcess.unref()
352 isReferenced = false
353 }
354 return reref
355 })
356 const inputFailure = Deferred.makeUnsafe<never, PlatformError.PlatformError>()
357 const stdin = yield* setupChildStdin(cmd, childProcess, stdinConfig, inputFailure)
358 const { all, stderr, stdout } = setupChildOutputStreams(cmd, childProcess, stdoutConfig, stderrConfig)
359 const isRunning = Effect.map(Deferred.isDone(exitSignal), (done) => !done)
360 // A failed input stream truncates the input of the child process, so
361 // its failure takes precedence over the exit status and is surfaced
362 // without waiting for the child process to exit
363 const exitCode = Effect.flatMap(
364 Effect.raceFirst(Deferred.await(exitSignal), Deferred.await(inputFailure)),
365 (status) => {
366 if (Deferred.isDoneUnsafe(inputFailure)) {
367 return Deferred.await(inputFailure)
368 }
369 if (Predicate.isNull(status.signal)) {
370 return Effect.succeed(ExitCode(status.code))
371 }
372 const error = new globalThis.Error(`Process interrupted due to receipt of signal: '${status.signal}'`)
373 return Effect.fail(toPlatformError("exitCode", error, cmd))
374 }
375 )
376 const kill = (options?: ChildProcess.KillOptions | undefined) => {
377 const killWithTimeout = withTimeout(childProcess, cmd, options)
378 return killWithTimeout((command, childProcess, signal) =>
379 killProcess(command, childProcess, signal).pipe(
380 Effect.andThen(Deferred.await(exitSignal))
381 )
382 ).pipe(Effect.asVoid)
383 }
384
385 return makeHandle({
386 pid: ProcessId(childProcess.pid),
387 exitCode,
388 isRunning,
389 kill,
390 stdin,
391 stdout,
392 stderr,
393 all,
394 getInputFd: () => Sink.drain,
395 getOutputFd: () => Stream.empty,
396 unref
397 })
398 }
399 case "PipedCommand": {
400 const { commands, pipeOptions } = flattenCommand(cmd)
401 const [root, ...pipeline] = commands
402 const handles = [yield* spawnCommand(root)]
403
404 for (let i = 0; i < pipeline.length; i++) {
405 const command = pipeline[i]
406 const options = pipeOptions[i] ?? {}
407 const stdinConfig = resolveStdinOption(command.options)
408 const from = options.from ?? "stdout"
409
410 if (
411 (from !== "stdout" && from !== "stderr" && from !== "all") ||
412 (options.to ?? "stdin") !== "stdin"
413 ) {
414 return yield* Effect.fail(unsupported("additionalFds"))
415 }
416 const sourceStream = getSourceStream(handles[handles.length - 1], from)
417 handles.push(
418 yield* spawnCommand(ChildProcess.make(command.command, command.args, {
419 ...command.options,
420 stdin: { ...stdinConfig, stream: sourceStream }
421 }))
422 )
423 }
424
425 const handle = handles[handles.length - 1]
426 const kill = (options?: ChildProcess.KillOptions | undefined) =>
427 Effect.forEach([...handles].reverse(), (handle) => Effect.ignore(handle.kill(options)), { discard: true })
428 const unref = Effect.gen(function*() {
429 const rerefs: Array<Effect.Effect<void, PlatformError.PlatformError>> = []
430 for (const handle of handles) rerefs.push(yield* handle.unref)
431 return Effect.forEach([...rerefs].reverse(), (reref) => reref, { discard: true })
432 })
433
434 return makeHandle({
435 pid: handle.pid,
436 exitCode: handle.exitCode,
437 isRunning: handle.isRunning,
438 kill,
439 stdin: handle.stdin,
440 stdout: handle.stdout,
441 stderr: handle.stderr,
442 all: handle.all,
443 getInputFd: handle.getInputFd,
444 getOutputFd: handle.getOutputFd,
445 unref
446 })
447 }
448 }
449 })
450
451 return makeSpawner(spawnCommand)
452})
453
454/**
455 * Layer that provides the Deno child process spawner.
456 *
457 * @stability unstable
458 * @category layers
459 * @since 4.0.0
460 */
461export const layer: Layer.Layer<ChildProcessSpawner, never, Path.Path> = Layer.effect(ChildProcessSpawner, make)
462
463/**
464 * Result of flattening a pipeline of commands.
465 *
466 * @stability unstable
467 * @category models
468 * @since 4.0.0
469 */
470export interface FlattenedPipeline {
471 readonly commands: Arr.NonEmptyReadonlyArray<ChildProcess.StandardCommand>
472 readonly pipeOptions: ReadonlyArray<ChildProcess.PipeOptions>
473}
474
475/**
476 * Flattens a command into standard commands and their pipe options.
477 *
478 * @stability unstable
479 * @category transforming
480 * @since 4.0.0
481 */
482export const flattenCommand = (command: ChildProcess.Command): FlattenedPipeline => {
483 const commands: Array<ChildProcess.StandardCommand> = []
484 const pipeOptions: Array<ChildProcess.PipeOptions> = []
485
486 const flatten = (command: ChildProcess.Command): void => {
487 switch (command._tag) {
488 case "StandardCommand":
489 commands.push(command)
490 break
491 case "PipedCommand":
492 flatten(command.left)
493 pipeOptions.push(command.options)
494 flatten(command.right)
495 break
496 }
497 }
498 flatten(command)
499
500 const [first, ...rest] = commands
501 if (first === undefined) throw new Error("flattenCommand produced empty commands array")
502 return { commands: [first, ...rest], pipeOptions }
503}