Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Processes

View as Markdownllms.txt

Sometimes your app needs another program: git to show which version is deployed, mysqldump to export a database, an image tool to shrink an upload. Starting another program from yours creates a process (a running program with its own memory). The program you start is the child process; your app is the parent.

Strutvane’s Process runs child processes the safe way: the program and each argument are passed separately, with no shell in between, so nothing a user typed can turn into a second command. Every run has a time limit, and in tests you swap in a fake that records what would have run.

Show the git commit the server is running:

app/console/commands/version.ts
import { defineCommand, Process } from '@strutvane/framework'
export default defineCommand({
name: 'app:version',
description: 'Show the deployed git commit',
async run({ output }) {
const result = await Process.run(['git', 'rev-parse', '--short', 'HEAD'])
output.line(`Running commit ${result.output().trim()}`)
},
})
Terminal window
node strut app:version

What you’ll see:

Running commit 3f9c2a1

Process.run() starts the program, waits for it to finish, and gives you a result: what it printed, what it printed as errors, and its exit code (a number every program returns when it ends: 0 means success, anything else means something went wrong).

Call Gives you Example
result.successful() true when the exit code is 0 true
result.failed() the opposite false
result.exitCode() the exit code 0
result.output() everything printed on standard output (stdout) '3f9c2a1\n'
result.errorOutput() everything printed on standard error (stderr) ''
result.throw() the result, or throws ProcessFailedError when it failed —

A program that runs but fails doesn’t throw by itself: you get a result with a non-zero exit code, so you decide what a failure means. Call .throw() when any failure should stop your code:

app/services/git-info.ts
import { Process } from '@strutvane/framework'
export async function currentBranch(): Promise<string> {
const result = (await Process.run(['git', 'branch', '--show-current'])).throw()
return result.output().trim()
}

What you’ll see outside a git repository:

ProcessFailedError: The process "git branch --show-current" failed with exit code 128.
fatal: not a git repository (or any of the parent directories): .git

A shell is the program that reads a command line like ls -la; rm -rf / and splits it into commands. Passing user input to a shell is the classic command injection: a file name such as photo.jpg; rm -rf ~ becomes two commands.

With Process, each list item is one argument, delivered to the program exactly as written:

app/services/thumbnails.ts
import { Process } from '@strutvane/framework'
/** Shrinks an uploaded image. `path` may contain spaces, quotes or semicolons: they stay part of the name. */
export async function makeThumbnail(path: string, target: string): Promise<void> {
await (await Process.run(['magick', path, '-resize', '320x320', target], { timeout: 30 })).throw()
}

What you’ll see: a file called holiday; rm -rf ~.jpg is resized like any other, and nothing else runs, because there’s no shell to read the ;.

The trade-off: shell features don’t exist. There’s no |, >, &&, * or $HOME. Use Process.pipe() instead of |, write files from your own code instead of >, and expand paths in TypeScript. It also means a command behaves identically on Windows, macOS and Linux: no quoting rules differ, because nothing is quoted.

app/services/exports.ts
import { Process } from '@strutvane/framework'
const result = await Process.run(['node', 'scripts/build-report.js', '--month=2026-10'], {
cwd: 'storage/app/reports', // the folder the program starts in
timeout: 120, // seconds; then the process is stopped
env: { REPORT_LOCALE: 'en' }, // extra environment variables for the child
input: 'yes\n', // text sent to the program's standard input
})
Option Meaning Default
cwd the working folder, relative to your project root the project root
timeout seconds before the process is stopped a framework default (not decided yet); never “forever”
env extra environment variables, added to the app’s none
input text written to the program’s standard input none
windowsShell Windows only: allow a .cmd or .bat program, started through cmd.exe with every argument safely quoted false

Every run has a time limit, so a hung program can’t hang a request or a worker forever. When it runs out:

app/services/exports.ts
import { Process, ProcessTimedOutError } from '@strutvane/framework'
try {
await Process.run(['node', 'scripts/slow-report.js'], { timeout: 5 })
} catch (error) {
if (error instanceof ProcessTimedOutError) {
// tell the user the report is taking too long; maybe queue it instead
}
throw error
}

What you’ll see:

ProcessTimedOutError: The process "node scripts/slow-report.js" exceeded the timeout of 5 seconds.

The child process is stopped, so nothing keeps running in the background after the error.

Pass passwords and API keys in env, never as arguments. On most systems anyone on the server can list running processes with their arguments, and errors such as ProcessFailedError repeat the command line.

app/services/database-dump.ts
import { Process } from '@strutvane/framework'
export async function dumpDatabase(target: string): Promise<void> {
const result = await Process.run(
['mysqldump', '--host', process.env.DB_HOST ?? '127.0.0.1', '--user', process.env.DB_USERNAME ?? 'root', '--result-file', target, process.env.DB_DATABASE ?? 'app'],
{
timeout: 600,
env: { MYSQL_PWD: process.env.DB_PASSWORD ?? '' }, // the password never appears in the command line
},
)
result.throw()
}

Strutvane’s log redaction hides values under secret-looking keys (passwords, tokens, keys), but it can’t know that the fourth argument of your command is a password. Keep secrets out of arguments.

Running in the background and waiting later

Section titled “Running in the background and waiting later”

Process.start() starts a program and returns at once, so you can do other work and wait later:

app/console/commands/rebuild-search.ts
import { defineCommand, Process } from '@strutvane/framework'
export default defineCommand({
name: 'search:rebuild',
description: 'Rebuild the search index with the external indexer',
async run({ output }) {
const running = Process.start(['node', 'scripts/indexer.js', '--all'], { timeout: 900 })
output.line('Indexer started…')
const result = await running.wait()
output.line(result.successful() ? 'Index rebuilt.' : `Indexer failed: ${result.errorOutput()}`)
},
})

A pool runs several processes at the same time and waits for all of them. Useful for independent work, like making three image sizes:

app/services/thumbnails.ts
import { Process } from '@strutvane/framework'
export async function makeAllSizes(path: string): Promise<void> {
const results = await Process.pool([
['magick', path, '-resize', '160x160', `${path}.small.jpg`],
['magick', path, '-resize', '320x320', `${path}.medium.jpg`],
['magick', path, '-resize', '1280x1280', `${path}.large.jpg`],
], { timeout: 60 })
const failed = results.filter((result) => result.failed())
if (failed.length > 0) throw new Error(`${failed.length} of 3 sizes failed`)
}

What you’ll see: the three run side by side, so the whole thing takes about as long as the slowest one, not the sum. One failure doesn’t stop the others; you get every result and decide.

A pipe sends one program’s output into the next program’s input, what | does in a shell, without a shell:

app/services/database-dump.ts
import { Process } from '@strutvane/framework'
/** mysqldump | gzip, written to a file by your own code. */
export async function compressedDump(): Promise<Buffer> {
const result = await Process.pipe([
['mysqldump', '--single-transaction', process.env.DB_DATABASE ?? 'app'],
['gzip', '-9'],
], { timeout: 600, env: { MYSQL_PWD: process.env.DB_PASSWORD ?? '' } })
return result.throw().outputBuffer()
}

What you’ll see: the compressed dump as bytes. If any program in the pipe fails, the pipe’s result fails, with that program’s error output.

Starting a program is slow compared to a normal request (often tens of milliseconds just to start, more for the work). Two guidelines:

  • In a request, keep it short and give it a small timeout. For anything that may take seconds, dispatch a queued job and run the process there.
  • In a job, set the job’s own timeout a little longer than the process’s, so the process is stopped (cleanly) before the worker gives up on the job.

The program you run must exist where your app runs:

  • With Docker, your app runs inside the app container, so Process.run(['mysqldump', …]) needs mysqldump inside the container, not on your computer. Try it with node strut shell, then which mysqldump.
  • Without Docker, it needs the program on your computer’s PATH.
  • In production containers, the image the installer writes starts from a slim Node image. Add the tools your app runs to your Dockerfile (for example with apt-get install in the final stage), or run that work elsewhere.

Windows: many command-line tools are installed as .cmd or .bat files instead of real programs, and Node refuses to start those without a shell (since its April 2024 security releases, CVE-2024-27980). Process.run() handles this for you:

  • npm and npx just work. Process.run(['npm', 'run', 'build']) is started as node <npm-cli.js> run build, the same way the installer runs npm, so there’s no shell and no quoting on any system.
  • Real programs (node, git, anything ending in .exe) start directly, as on macOS and Linux.
  • Any other .cmd or .bat file is refused with a friendly error that says what to do, because it could only run through a shell. If you trust it, opt in for that one call with { windowsShell: true }: Strutvane then starts it through cmd.exe and quotes every argument safely, so a & or | in an argument still can’t start a second command.
app/services/legacy-tool.ts
import { Process } from '@strutvane/framework'
// npm: no option needed, on every system.
await Process.run(['npm', 'run', 'build'], { timeout: 300 })
// A vendor's tool that only exists as a .cmd file on Windows: opt in explicitly.
await Process.run(['vendor-export.cmd', '--month', '2026-10'], { timeout: 60, windowsShell: true })

On macOS and Linux windowsShell does nothing, so the same code runs everywhere.

macOS / Linux: programs are found on PATH as usual. A program that works in your terminal may not be on the PATH of a cron job or a service; pass the full path (/usr/bin/mysqldump) when in doubt.

In tests you don’t want to really run mysqldump. Process.fake() records every call and answers with what you tell it:

tests/unit/git-info.test.ts
import { describe, expect, it } from 'vitest'
import { Process } from '@strutvane/framework'
import { currentBranch } from '../../app/services/git-info.ts'
describe('currentBranch', () => {
it('reads the branch from git', async () => {
const processes = Process.fake({
'git branch --show-current': Process.result({ output: 'main\n' }),
})
expect(await currentBranch()).toBe('main')
processes.assertRan(['git', 'branch', '--show-current'])
})
it('fails clearly outside a repository', async () => {
Process.fake({ 'git branch --show-current': Process.result({ exitCode: 128, errorOutput: 'fatal: not a git repository' }) })
await expect(currentBranch()).rejects.toThrow('exit code 128')
})
})

What you’ll see: both tests pass without git being involved. A process that isn’t listed in the fake fails the test, so a test can’t start a real program by accident. See Mocking.

“No such file or directory” for a command that works in my terminal

Section titled ““No such file or directory” for a command that works in my terminal”
ProcessFailedError: The process "pg_dump app" could not be started: spawn pg_dump ENOENT

Why: the program isn’t on the PATH where the app runs: inside the Docker container, in a cron job, or in the production image. Fix: install it there, or use its full path:

await Process.run(['/usr/bin/pg_dump', 'app'])

Why: ['ls', '|', 'grep', 'x'] passes | to ls as a file name. There’s no shell to understand it. Fix: use Process.pipe(), and write files from your own code:

await Process.pipe([['ls'], ['grep', 'report']])

A request hangs until the browser gives up

Section titled “A request hangs until the browser gives up”

Why: the program waits for input or never finishes, and the timeout is too long for a request. Fix: give it a short timeout and input if it asks a question, or move it to a queued job:

await Process.run(['node', 'scripts/report.js'], { timeout: 10, input: 'y\n' })

The database password showed up in an error message

Section titled “The database password showed up in an error message”

Why: it was passed as an argument, and errors repeat the command line. Fix: pass it through env:

await Process.run(['mysqldump', 'app'], { env: { MYSQL_PWD: process.env.DB_PASSWORD ?? '' } })

A .cmd tool works on macOS but is refused on Windows

Section titled “A .cmd tool works on macOS but is refused on Windows”

Something like this:

ProcessFailedError: "vendor-export.cmd" is a Windows batch file, which can only run through a shell.
→ Call the real program instead, or pass { windowsShell: true } to run it through cmd.exe with safe quoting.

Why: on Windows the tool is a .cmd file, and Strutvane never starts a shell unless you ask. (npm and npx are the exception: they’re started as node <npm-cli.js>, so they always work.) Fix: call the real program if there is one, or opt in for that call:

await Process.run(['vendor-export.cmd', '--month', '2026-10'], { windowsShell: true })
  • Concurrency: run your own TypeScript functions in parallel, not other programs.
  • Queues: run slow processes in the background.
  • Console Commands: write the node strut commands that call them.
  • Mocking: every fake for tests.