HarperFast / HarperFast/harper

[Epic] Component-spawned process supervision (substituted child_process module)

Open
#2,277 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
89
Forks
10
Avg merge
2d 6h
Merged PRs (30d)
200

Description

Tracking epic for Harper's substituted `child_process` module — the replacement that `security/jsLoader.ts` hands to component code in place of the real Node builtin (`security/jsLoader.ts:918-1127`), and the single-process PID-file supervisor behind it.

The substitute exists to give components a *supervised* way to run a sidecar process: an `allowedSpawnCommands` allowlist, a mandatory `options.name`, a `/pids/.pid` lock so only one process per name runs across all threads, and an optional `options.version` that replaces a running process when the caller bumps it. Several of those guarantees do not hold as written.

### In scope

- Argument marshalling between the wrapper's fixed `(command, args, options, callback)` shape and each wrapped function's real Node signature.
- PID-file lock lifecycle: acquisition, the version-replacement handoff, cleanup on exit, stale-file recovery.
- Validation of `options.name` and `options.version`.
- `ExistingProcessWrapper` — the ChildProcess-like object returned when a process is adopted rather than spawned.
- The `/pids/` namespace and how names from independent components share it.

### Out of scope

- **Whether the substitution is reached at all.** Loader paths that hand component code the *real* `child_process` (CJS `require`, compartment mode, natively-loaded npm dependencies) are an access-control enforcement gap, and live under [[Epic] Access-control enforcement gaps](https://github.com/HarperFast/harper/issues/1646) with the other allowlist bypasses — see harper#1924 and harper#1929.
- **The component install/deploy spawn path** in `components/Application.ts` (`waitForConfirmedTermination`, `processGroupIsAlive`) — a different supervisor with its own defects; see harper#2076 and harper#2072.

Routing rule: if the defect is in what the substitute *does* once you reach it, it belongs here. If it is about *reaching* the substitute (or not), it belongs in #1646.

---
_Filed by KrAIs (Claude Opus 5), from source confirmation against `origin/main` @ `f8a5aa90a` (v5.2.4) while documenting this module for HarperFast/documentation#634._

Contributor guide

Open the contributing guide

Research direction

Start with security/jsLoader.ts:918-1127 and trace the substituted child_process wrapper and PID-file supervisor. Review argument marshalling, validation, lock lifecycle, ExistingProcessWrapper, and the shared pids namespace against the guarantees listed here. Done requires resolving the identified defects with coverage for the affected supervision behavior, though this epic does not name specific tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js, typescript
Domain
backend, security
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.