run-bounded 0.1.2__py3-none-win_amd64.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- bounded_run/__init__.py +266 -0
- run_bounded-0.1.2.data/scripts/run-bounded.exe +0 -0
- run_bounded-0.1.2.dist-info/METADATA +153 -0
- run_bounded-0.1.2.dist-info/RECORD +7 -0
- run_bounded-0.1.2.dist-info/WHEEL +4 -0
- run_bounded-0.1.2.dist-info/licenses/LICENSE +21 -0
- run_bounded-0.1.2.dist-info/sboms/bounded-run.cyclonedx.json +51 -0
bounded_run/__init__.py
ADDED
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
"""Run a child command with wall-time, idle-time, output, and tree limits."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import os
|
|
5
|
+
import shutil
|
|
6
|
+
import signal
|
|
7
|
+
import subprocess
|
|
8
|
+
import threading
|
|
9
|
+
import time
|
|
10
|
+
from dataclasses import dataclass
|
|
11
|
+
from typing import Sequence
|
|
12
|
+
|
|
13
|
+
@dataclass(frozen=True)
|
|
14
|
+
class RunResult:
|
|
15
|
+
classification: str
|
|
16
|
+
duration: float
|
|
17
|
+
returncode: int | None
|
|
18
|
+
stdout: bytes
|
|
19
|
+
stderr: bytes
|
|
20
|
+
stdout_truncated: bool
|
|
21
|
+
stderr_truncated: bool
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
# After a deadline kill, a descendant outside the process group may still hold a
|
|
25
|
+
# stream open. Forward for this long, then report the limit instead of waiting.
|
|
26
|
+
DRAIN_GRACE = 0.1
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class _Stopped(BaseException):
|
|
30
|
+
"""Raised in the main thread when the process receives SIGINT, SIGTERM or SIGHUP."""
|
|
31
|
+
|
|
32
|
+
def __init__(self, signum):
|
|
33
|
+
self.signum = signum
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _install_stop_handlers():
|
|
37
|
+
"""Temporarily turn stop signals into an exception so the child tree can be killed."""
|
|
38
|
+
if os.name != "posix" or threading.current_thread() is not threading.main_thread():
|
|
39
|
+
return {}
|
|
40
|
+
previous = {}
|
|
41
|
+
|
|
42
|
+
def stop(signum, _frame):
|
|
43
|
+
raise _Stopped(signum)
|
|
44
|
+
|
|
45
|
+
for signum in (signal.SIGINT, signal.SIGTERM, signal.SIGHUP):
|
|
46
|
+
try:
|
|
47
|
+
previous[signum] = signal.signal(signum, stop)
|
|
48
|
+
except (OSError, ValueError):
|
|
49
|
+
pass
|
|
50
|
+
return previous
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _restore_stop_handlers(previous) -> None:
|
|
54
|
+
for signum, handler in previous.items():
|
|
55
|
+
try:
|
|
56
|
+
signal.signal(signum, handler)
|
|
57
|
+
except (OSError, ValueError):
|
|
58
|
+
pass
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def run(command: Sequence[str], *, timeout: float = 60, idle: float = 20,
|
|
62
|
+
max_output: int = 1_048_576, env: dict[str, str] | None = None) -> RunResult:
|
|
63
|
+
"""Execute an absolute or PATH-resolved command with independent stream caps."""
|
|
64
|
+
if not command:
|
|
65
|
+
raise ValueError("command must not be empty")
|
|
66
|
+
if timeout < 0 or idle < 0 or max_output < 0:
|
|
67
|
+
raise ValueError("limits must be nonnegative")
|
|
68
|
+
start = time.monotonic()
|
|
69
|
+
minimal = {k: v for k, v in os.environ.items() if k in {"PATH", "HOME", "TMPDIR", "LANG", "LC_ALL", "SYSTEMROOT", "WINDIR", "TEMP", "TMP"}}
|
|
70
|
+
if env is not None: minimal.update(env)
|
|
71
|
+
executable = command[0]
|
|
72
|
+
if not os.path.isabs(executable):
|
|
73
|
+
if "/" in executable or "\\" in executable:
|
|
74
|
+
raise ValueError("relative command paths with a separator are not accepted; use a bare PATH name or an absolute path")
|
|
75
|
+
executable = shutil.which(executable, path=minimal.get("PATH"))
|
|
76
|
+
if executable is None:
|
|
77
|
+
raise FileNotFoundError(f"command not found on PATH: {command[0]}")
|
|
78
|
+
command = (executable, *command[1:])
|
|
79
|
+
proc = subprocess.Popen(command, stdin=None, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
|
|
80
|
+
env=minimal, start_new_session=(os.name == "posix"))
|
|
81
|
+
job = None
|
|
82
|
+
if os.name == "nt":
|
|
83
|
+
try:
|
|
84
|
+
job = _create_windows_job(proc)
|
|
85
|
+
except OSError:
|
|
86
|
+
proc.kill()
|
|
87
|
+
proc.wait()
|
|
88
|
+
raise
|
|
89
|
+
last_output = [start]
|
|
90
|
+
lock = threading.Lock()
|
|
91
|
+
wake = threading.Event()
|
|
92
|
+
child_done = threading.Event()
|
|
93
|
+
reader_done = [False, False]
|
|
94
|
+
streams: list[tuple[bytearray, bool]] = [(bytearray(), False), (bytearray(), False)]
|
|
95
|
+
def drain(pipe, index):
|
|
96
|
+
try:
|
|
97
|
+
while True:
|
|
98
|
+
chunk = os.read(pipe.fileno(), 8192)
|
|
99
|
+
if not chunk:
|
|
100
|
+
return
|
|
101
|
+
with lock:
|
|
102
|
+
last_output[0] = time.monotonic()
|
|
103
|
+
buf, _ = streams[index]
|
|
104
|
+
room = max_output - len(buf)
|
|
105
|
+
buf.extend(chunk[:max(room, 0)])
|
|
106
|
+
if len(chunk) > room:
|
|
107
|
+
streams[index] = (buf, True)
|
|
108
|
+
wake.set()
|
|
109
|
+
finally:
|
|
110
|
+
with lock:
|
|
111
|
+
reader_done[index] = True
|
|
112
|
+
wake.set()
|
|
113
|
+
threads = [threading.Thread(target=drain, args=(proc.stdout, 0), daemon=True),
|
|
114
|
+
threading.Thread(target=drain, args=(proc.stderr, 1), daemon=True)]
|
|
115
|
+
for t in threads: t.start()
|
|
116
|
+
def wait_child():
|
|
117
|
+
proc.wait()
|
|
118
|
+
child_done.set()
|
|
119
|
+
wake.set()
|
|
120
|
+
waiter = threading.Thread(target=wait_child, daemon=True)
|
|
121
|
+
waiter.start()
|
|
122
|
+
classification = "ok"
|
|
123
|
+
killed = False
|
|
124
|
+
drain_until = None
|
|
125
|
+
stopped = None
|
|
126
|
+
handlers = _install_stop_handlers()
|
|
127
|
+
try:
|
|
128
|
+
while True:
|
|
129
|
+
wake.clear()
|
|
130
|
+
with lock:
|
|
131
|
+
complete = child_done.is_set() and all(reader_done)
|
|
132
|
+
last = last_output[0]
|
|
133
|
+
if complete:
|
|
134
|
+
code = proc.returncode
|
|
135
|
+
if not killed:
|
|
136
|
+
classification = "ok" if code == 0 else ("signal" if code < 0 else "failed")
|
|
137
|
+
break
|
|
138
|
+
now = time.monotonic()
|
|
139
|
+
if not killed and timeout and now - start >= timeout:
|
|
140
|
+
classification = "timeout"; _terminate(proc, job); killed = True
|
|
141
|
+
drain_until = now + DRAIN_GRACE
|
|
142
|
+
elif not killed and idle and now - last >= idle:
|
|
143
|
+
classification = "idle"; _terminate(proc, job); killed = True
|
|
144
|
+
drain_until = now + DRAIN_GRACE
|
|
145
|
+
if killed:
|
|
146
|
+
if drain_until is None:
|
|
147
|
+
drain_until = time.monotonic() + DRAIN_GRACE
|
|
148
|
+
if time.monotonic() >= drain_until:
|
|
149
|
+
break
|
|
150
|
+
wake.wait(drain_until - time.monotonic())
|
|
151
|
+
else:
|
|
152
|
+
remaining = []
|
|
153
|
+
if timeout: remaining.append(start + timeout - now)
|
|
154
|
+
if idle: remaining.append(last + idle - now)
|
|
155
|
+
wake.wait(max(0, min(remaining)) if remaining else None)
|
|
156
|
+
except _Stopped as interrupt:
|
|
157
|
+
stopped = interrupt
|
|
158
|
+
finally:
|
|
159
|
+
_restore_stop_handlers(handlers)
|
|
160
|
+
if not child_done.is_set():
|
|
161
|
+
_terminate(proc, job)
|
|
162
|
+
grace_end = time.monotonic() + DRAIN_GRACE
|
|
163
|
+
for t in threads:
|
|
164
|
+
t.join(max(0, grace_end - time.monotonic()))
|
|
165
|
+
waiter.join(DRAIN_GRACE)
|
|
166
|
+
with lock: out, out_truncated = streams[0]; err, err_truncated = streams[1]
|
|
167
|
+
if job is not None: _close_windows_job(job)
|
|
168
|
+
if stopped is not None:
|
|
169
|
+
signal.signal(stopped.signum, signal.SIG_DFL)
|
|
170
|
+
os.kill(os.getpid(), stopped.signum)
|
|
171
|
+
raise stopped
|
|
172
|
+
return RunResult(classification, time.monotonic()-start, proc.returncode, bytes(out), bytes(err), out_truncated, err_truncated)
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
def _windows_api():
|
|
176
|
+
import ctypes
|
|
177
|
+
from ctypes import wintypes
|
|
178
|
+
kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
|
|
179
|
+
kernel32.CreateJobObjectW.argtypes = (ctypes.c_void_p, wintypes.LPCWSTR)
|
|
180
|
+
kernel32.CreateJobObjectW.restype = wintypes.HANDLE
|
|
181
|
+
kernel32.AssignProcessToJobObject.argtypes = (wintypes.HANDLE, wintypes.HANDLE)
|
|
182
|
+
kernel32.AssignProcessToJobObject.restype = wintypes.BOOL
|
|
183
|
+
kernel32.SetInformationJobObject.argtypes = (wintypes.HANDLE, ctypes.c_int, ctypes.c_void_p, wintypes.DWORD)
|
|
184
|
+
kernel32.SetInformationJobObject.restype = wintypes.BOOL
|
|
185
|
+
kernel32.TerminateJobObject.argtypes = (wintypes.HANDLE, wintypes.UINT)
|
|
186
|
+
kernel32.TerminateJobObject.restype = wintypes.BOOL
|
|
187
|
+
kernel32.CloseHandle.argtypes = (wintypes.HANDLE,)
|
|
188
|
+
kernel32.CloseHandle.restype = wintypes.BOOL
|
|
189
|
+
return kernel32
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
def _job_limit_information(ctypes):
|
|
193
|
+
"""JOBOBJECT_EXTENDED_LIMIT_INFORMATION with JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE."""
|
|
194
|
+
class BasicLimitInformation(ctypes.Structure):
|
|
195
|
+
_fields_ = [
|
|
196
|
+
("PerProcessUserTimeLimit", ctypes.c_int64),
|
|
197
|
+
("PerJobUserTimeLimit", ctypes.c_int64),
|
|
198
|
+
("LimitFlags", ctypes.c_uint32),
|
|
199
|
+
("MinimumWorkingSetSize", ctypes.c_size_t),
|
|
200
|
+
("MaximumWorkingSetSize", ctypes.c_size_t),
|
|
201
|
+
("ActiveProcessLimit", ctypes.c_uint32),
|
|
202
|
+
("Affinity", ctypes.c_size_t),
|
|
203
|
+
("PriorityClass", ctypes.c_uint32),
|
|
204
|
+
("SchedulingClass", ctypes.c_uint32),
|
|
205
|
+
]
|
|
206
|
+
|
|
207
|
+
class IoCounters(ctypes.Structure):
|
|
208
|
+
_fields_ = [(name, ctypes.c_uint64) for name in (
|
|
209
|
+
"ReadOperationCount", "WriteOperationCount", "OtherOperationCount",
|
|
210
|
+
"ReadTransferCount", "WriteTransferCount", "OtherTransferCount")]
|
|
211
|
+
|
|
212
|
+
class ExtendedLimitInformation(ctypes.Structure):
|
|
213
|
+
_fields_ = [
|
|
214
|
+
("BasicLimitInformation", BasicLimitInformation),
|
|
215
|
+
("IoInfo", IoCounters),
|
|
216
|
+
("ProcessMemoryLimit", ctypes.c_size_t),
|
|
217
|
+
("JobMemoryLimit", ctypes.c_size_t),
|
|
218
|
+
("PeakProcessMemoryUsed", ctypes.c_size_t),
|
|
219
|
+
("PeakJobMemoryUsed", ctypes.c_size_t),
|
|
220
|
+
]
|
|
221
|
+
|
|
222
|
+
information = ExtendedLimitInformation()
|
|
223
|
+
information.BasicLimitInformation.LimitFlags = 0x2000
|
|
224
|
+
return information
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
def _create_windows_job(proc: subprocess.Popen):
|
|
228
|
+
import ctypes
|
|
229
|
+
kernel32 = _windows_api()
|
|
230
|
+
job = kernel32.CreateJobObjectW(None, None)
|
|
231
|
+
if not job:
|
|
232
|
+
raise ctypes.WinError(ctypes.get_last_error())
|
|
233
|
+
information = _job_limit_information(ctypes)
|
|
234
|
+
if not kernel32.SetInformationJobObject(job, 9, ctypes.byref(information), ctypes.sizeof(information)):
|
|
235
|
+
error = ctypes.WinError(ctypes.get_last_error())
|
|
236
|
+
kernel32.CloseHandle(job)
|
|
237
|
+
raise error
|
|
238
|
+
if not kernel32.AssignProcessToJobObject(job, ctypes.c_void_p(proc._handle)):
|
|
239
|
+
error = ctypes.WinError(ctypes.get_last_error())
|
|
240
|
+
kernel32.CloseHandle(job)
|
|
241
|
+
raise error
|
|
242
|
+
return job
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
def _close_windows_job(job) -> None:
|
|
246
|
+
_windows_api().CloseHandle(job)
|
|
247
|
+
|
|
248
|
+
|
|
249
|
+
def _terminate(proc: subprocess.Popen, job=None) -> None:
|
|
250
|
+
if os.name == "posix":
|
|
251
|
+
try: os.killpg(proc.pid, signal.SIGTERM)
|
|
252
|
+
except ProcessLookupError: return
|
|
253
|
+
deadline = time.monotonic() + .2
|
|
254
|
+
while time.monotonic() < deadline:
|
|
255
|
+
try: os.killpg(proc.pid, 0)
|
|
256
|
+
except ProcessLookupError: return
|
|
257
|
+
time.sleep(.005)
|
|
258
|
+
try: os.killpg(proc.pid, signal.SIGKILL)
|
|
259
|
+
except ProcessLookupError: pass
|
|
260
|
+
else:
|
|
261
|
+
if job is None:
|
|
262
|
+
proc.kill()
|
|
263
|
+
else:
|
|
264
|
+
_windows_api().TerminateJobObject(job, 1)
|
|
265
|
+
|
|
266
|
+
__all__ = ["RunResult", "run"]
|
|
Binary file
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: run-bounded
|
|
3
|
+
Version: 0.1.2
|
|
4
|
+
Classifier: Development Status :: 4 - Beta
|
|
5
|
+
Classifier: Environment :: Console
|
|
6
|
+
Classifier: Intended Audience :: Developers
|
|
7
|
+
Classifier: Operating System :: MacOS
|
|
8
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
9
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
10
|
+
Classifier: Programming Language :: Python :: 3
|
|
11
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
12
|
+
Classifier: Topic :: System :: Systems Administration
|
|
13
|
+
License-File: LICENSE
|
|
14
|
+
Summary: A command-line tool and Python library for running commands with time, output, and process-tree limits.
|
|
15
|
+
Keywords: cli,process,timeout,subprocess,process-tree,rust,python
|
|
16
|
+
Author: El Fenomeno
|
|
17
|
+
License-Expression: MIT
|
|
18
|
+
Requires-Python: >=3.10
|
|
19
|
+
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
|
|
20
|
+
Project-URL: Issues, https://github.com/elfenomenokim/run-bounded/issues
|
|
21
|
+
Project-URL: Repository, https://github.com/elfenomenokim/run-bounded
|
|
22
|
+
|
|
23
|
+
<div align="center">
|
|
24
|
+
|
|
25
|
+
<img src="https://raw.githubusercontent.com/elfenomenokim/run-bounded/main/docs/logo.svg" width="96" height="96" alt="run-bounded: a command arrow stopped by a limit">
|
|
26
|
+
|
|
27
|
+
# run-bounded
|
|
28
|
+
[한국어](README.ko.md)
|
|
29
|
+
|
|
30
|
+
A command-line tool and Python library for running commands with time, output, and process-tree limits.
|
|
31
|
+
|
|
32
|
+
Rust 1.82+ · Python 3.10+
|
|
33
|
+
|
|
34
|
+
[](https://github.com/elfenomenokim/run-bounded/blob/main/Cargo.toml)
|
|
35
|
+
[](https://github.com/elfenomenokim/run-bounded/blob/main/LICENSE)
|
|
36
|
+
|
|
37
|
+
5.3 ms per run; a Python `subprocess.run` call to the same command takes 37.9 ms. Both from the saved 30-run `hyperfine` file.
|
|
38
|
+
|
|
39
|
+
[Install](#install) · [Quick start](#quick-start) · [Why](#why)
|
|
40
|
+
|
|
41
|
+
</div>
|
|
42
|
+
|
|
43
|
+
<p align="center">
|
|
44
|
+
<picture>
|
|
45
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/run-bounded/main/docs/demo/run-bounded-dark.gif">
|
|
46
|
+
<img src="https://raw.githubusercontent.com/elfenomenokim/run-bounded/main/docs/demo/run-bounded.gif" alt="The run-bounded CLI prints child output and a JSON result" width="1200">
|
|
47
|
+
</picture>
|
|
48
|
+
</p>
|
|
49
|
+
|
|
50
|
+
The demo uses `printf` with fixed text. It shows command output, not a benchmark.
|
|
51
|
+
|
|
52
|
+
## Install
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
git clone https://github.com/elfenomenokim/run-bounded
|
|
56
|
+
cd run-bounded
|
|
57
|
+
cargo install --locked --path .
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`cargo install` puts the `run-bounded` binary in `~/.cargo/bin`. For the Python library, build the
|
|
61
|
+
wheel from the same checkout: `python3 -m pip wheel --no-deps -w dist .` and install the file in
|
|
62
|
+
`dist/`. The package is not on PyPI yet.
|
|
63
|
+
|
|
64
|
+
Rust 1.82 or newer is needed; the wheel installs the same binary and the importable Python package
|
|
65
|
+
`bounded_run`.
|
|
66
|
+
|
|
67
|
+
## Quick start
|
|
68
|
+
|
|
69
|
+
```sh
|
|
70
|
+
run-bounded --timeout 5 --idle 2 --max-output 1K -- printf 'bounded output\n'
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
`printf` resolves through `PATH`. Absolute executable paths also work. Relative paths containing `/` or `\` are rejected.
|
|
74
|
+
|
|
75
|
+
The child keeps stdout and stderr. The command writes one JSON result line to stderr:
|
|
76
|
+
|
|
77
|
+
```text
|
|
78
|
+
bounded output
|
|
79
|
+
{"class":"ok","duration_ms":6,"exit_code":0,"stdout_truncated":false,"stderr_truncated":false}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`--timeout` sets wall seconds. `--idle` sets seconds without output. `--max-output` sets a per-stream byte cap; K, M, and G use powers of 1024. Zero disables a time limit. The child receives a small environment with PATH, locale, home, temporary-directory, and Windows system variables.
|
|
83
|
+
|
|
84
|
+
## Why
|
|
85
|
+
|
|
86
|
+
`run-bounded` drains stdout and stderr independently and limits each stream. On Unix, it starts a new process group and sends TERM followed by KILL when a limit expires. Windows assigns the child to a Job Object and terminates the job on timeout. The Rust CLI is one binary; the Python edition is importable without a native extension. feno-cli keeps its existing `run_process_group` API.
|
|
87
|
+
|
|
88
|
+
| Tool | Wall timeout | Output cap | Grandchild after timeout |
|
|
89
|
+
|---|---|---|---|
|
|
90
|
+
| run-bounded | yes | per stream | terminated on macOS, Linux, and Windows checks |
|
|
91
|
+
| coreutils `gtimeout` | yes | no | remained alive in the macOS check |
|
|
92
|
+
| Python `subprocess.run(timeout=...)` | yes | no | remained alive in the macOS check |
|
|
93
|
+
|
|
94
|
+
## How it works
|
|
95
|
+
|
|
96
|
+
<picture>
|
|
97
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/run-bounded/main/docs/diagrams/flow.dark.svg">
|
|
98
|
+
<img src="https://raw.githubusercontent.com/elfenomenokim/run-bounded/main/docs/diagrams/flow.light.svg" alt="The runner starts a child, drains both streams, waits for exit or a deadline, and terminates the process tree on timeout">
|
|
99
|
+
</picture>
|
|
100
|
+
|
|
101
|
+
The source is [`flow.mmd`](docs/diagrams/flow.mmd); the Korean README has Korean labels.
|
|
102
|
+
|
|
103
|
+
## Measurements
|
|
104
|
+
|
|
105
|
+
These are `hyperfine` 2.0.0 wall-time means and standard deviations for `/usr/bin/true`. The host was macOS 27.0 on arm64. Each command ran 3 warmups and 30 measured runs. Python command rows include starting the Python interpreter for each run.
|
|
106
|
+
|
|
107
|
+
<picture>
|
|
108
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/run-bounded/main/docs/diagrams/bench.dark.svg">
|
|
109
|
+
<img src="https://raw.githubusercontent.com/elfenomenokim/run-bounded/main/docs/diagrams/bench.light.svg" alt="Mean wall time: run-bounded 5.3 milliseconds, gtimeout 6.2, Python subprocess.run 37.9, Python library command 61.7">
|
|
110
|
+
</picture>
|
|
111
|
+
|
|
112
|
+
| Command | Mean ± standard deviation |
|
|
113
|
+
|---|---:|
|
|
114
|
+
| run-bounded CLI | 5.3 ± 0.8 ms |
|
|
115
|
+
| `gtimeout` | 6.2 ± 0.7 ms |
|
|
116
|
+
| Python `subprocess.run` | 37.9 ± 3.5 ms |
|
|
117
|
+
| Python library command | 61.7 ± 15.4 ms |
|
|
118
|
+
|
|
119
|
+
Re-run from the CCH repository root. The saved measurements are in [`macos-27-arm64-20261117.json`](docs/bench/macos-27-arm64-20261117.json).
|
|
120
|
+
|
|
121
|
+
```sh
|
|
122
|
+
cargo build --locked --release --manifest-path docs/products/feno-cli/bounded-run/Cargo.toml
|
|
123
|
+
hyperfine --shell=none --warmup 3 --runs 30 \
|
|
124
|
+
--export-json docs/products/feno-cli/bounded-run/docs/bench/macos-27-arm64-20261117.json \
|
|
125
|
+
--command-name 'run-bounded' './docs/products/feno-cli/bounded-run/target/release/run-bounded --timeout 5 --idle 2 -- /usr/bin/true' \
|
|
126
|
+
--command-name 'gtimeout' '/opt/homebrew/bin/gtimeout 5 /usr/bin/true' \
|
|
127
|
+
--command-name 'Python subprocess.run' '/usr/bin/python3 -c "import subprocess; subprocess.run([\"/usr/bin/true\"], check=True)"' \
|
|
128
|
+
--command-name 'Python library' '/usr/bin/python3 -c "import sys; sys.path.insert(0, \"docs/products/feno-cli/bounded-run/python\"); from bounded_run import run; run([\"/usr/bin/true\"])'
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Inside an already-started Python interpreter, `bounded_run.run()` had a 3.5 ms median over 30 calls; [the saved samples](docs/bench/python-in-process-20261117.json) include the command and host details. The grandchild comparison used a child that ignored TERM and slept for 30 seconds. `run-bounded` removed it; `gtimeout` and `subprocess.run(timeout=...)` left it alive.
|
|
132
|
+
|
|
133
|
+
## Reference
|
|
134
|
+
|
|
135
|
+
```text
|
|
136
|
+
run-bounded [--timeout SEC] [--idle SEC] [--max-output BYTES] -- COMMAND [ARGS...]
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
`COMMAND` can be an absolute executable path or a bare name found on PATH. The library is `bounded_run.run(command, timeout=60, idle=20, max_output=1048576)`. It returns a `RunResult` with `classification`, `duration`, `returncode`, captured `stdout` and `stderr` bytes, and one truncation flag per stream. Classifications are `ok`, `failed`, `timeout`, `idle`, or `signal`.
|
|
140
|
+
|
|
141
|
+
## Platforms
|
|
142
|
+
|
|
143
|
+
The CLI was built and exercised on macOS 27.0 arm64, Ubuntu 24.04 arm64 on A1, and Windows build 26340 x64 (reported OS version 10.0.26340.0). The Python library was exercised on macOS and Windows. The Windows Rust build used the laptop's existing Rust 1.100 GNU toolchain. Timeout and idle return 124, CLI errors return 125, and normal child failures retain the child's exit code. A child terminated by a signal returns 128 plus the signal number, and its JSON `exit_code` is null. A consumer that stops reading its output cannot delay a timeout result: once a limit terminates the child, both editions report the timeout without waiting for the blocked output write or for a descendant that left the process group. When the runner itself receives SIGINT, SIGTERM or SIGHUP, it stops the child tree first; a Windows job also ends its children when the runner closes it.
|
|
144
|
+
|
|
145
|
+
## Contributing
|
|
146
|
+
|
|
147
|
+
Run `cargo build --locked` from this directory. Issues and platform reports are welcome.
|
|
148
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for the tests and the review process.
|
|
149
|
+
|
|
150
|
+
## License
|
|
151
|
+
|
|
152
|
+
MIT. See [LICENSE](LICENSE).
|
|
153
|
+
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
bounded_run/__init__.py,sha256=JYFURQKelmZ49l3uPvDC4j5WAc_ycK1hKg_HVErIpkA,10425
|
|
2
|
+
run_bounded-0.1.2.data/scripts/run-bounded.exe,sha256=avI26TopDduZfGVXiIaPmAhu63pcyp1fD1JP7k7Qatc,356864
|
|
3
|
+
run_bounded-0.1.2.dist-info/METADATA,sha256=CEFu6SRp2OBii1m_Fw19L4i0vlTn8F6XYLLsg2RIVnc,8603
|
|
4
|
+
run_bounded-0.1.2.dist-info/WHEEL,sha256=Uvw7WSmy7Kj2FBk8Va4L_dq4MDW8X5Ynby-pOX3ZNS0,94
|
|
5
|
+
run_bounded-0.1.2.dist-info/licenses/LICENSE,sha256=ixsGgeHQOqBTjt6IOLNETQfAZltgkNsaoVulFr_1p4c,1089
|
|
6
|
+
run_bounded-0.1.2.dist-info/sboms/bounded-run.cyclonedx.json,sha256=vfIpOnTkPKP2v4uADlkiOp6jTn1e_7WbyovdON3yzdY,1388
|
|
7
|
+
run_bounded-0.1.2.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 El Fenomeno
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
{
|
|
2
|
+
"bomFormat": "CycloneDX",
|
|
3
|
+
"specVersion": "1.5",
|
|
4
|
+
"version": 1,
|
|
5
|
+
"serialNumber": "urn:uuid:4f342e54-dfd1-4cc3-a040-eca40aa67fe7",
|
|
6
|
+
"metadata": {
|
|
7
|
+
"timestamp": "2026-11-18T07:14:24.835391900Z",
|
|
8
|
+
"tools": [
|
|
9
|
+
{
|
|
10
|
+
"vendor": "CycloneDX",
|
|
11
|
+
"name": "cargo-cyclonedx",
|
|
12
|
+
"version": "0.5.9"
|
|
13
|
+
}
|
|
14
|
+
],
|
|
15
|
+
"component": {
|
|
16
|
+
"type": "application",
|
|
17
|
+
"bom-ref": "path+file:///D:/a/run-bounded/run-bounded#bounded-run@0.1.2",
|
|
18
|
+
"name": "bounded-run",
|
|
19
|
+
"version": "0.1.2",
|
|
20
|
+
"description": "A command-line tool for running commands with time, output, and process-tree limits.",
|
|
21
|
+
"scope": "required",
|
|
22
|
+
"licenses": [
|
|
23
|
+
{
|
|
24
|
+
"expression": "MIT"
|
|
25
|
+
}
|
|
26
|
+
],
|
|
27
|
+
"purl": "pkg:cargo/bounded-run@0.1.2?download_url=file://.",
|
|
28
|
+
"components": [
|
|
29
|
+
{
|
|
30
|
+
"type": "application",
|
|
31
|
+
"bom-ref": "path+file:///D:/a/run-bounded/run-bounded#bounded-run@0.1.2 bin-target-0",
|
|
32
|
+
"name": "run-bounded",
|
|
33
|
+
"version": "0.1.2",
|
|
34
|
+
"purl": "pkg:cargo/bounded-run@0.1.2?download_url=file://.#src/main.rs"
|
|
35
|
+
}
|
|
36
|
+
]
|
|
37
|
+
},
|
|
38
|
+
"properties": [
|
|
39
|
+
{
|
|
40
|
+
"name": "cdx:rustc:sbom:target:all_targets",
|
|
41
|
+
"value": "true"
|
|
42
|
+
}
|
|
43
|
+
]
|
|
44
|
+
},
|
|
45
|
+
"components": [],
|
|
46
|
+
"dependencies": [
|
|
47
|
+
{
|
|
48
|
+
"ref": "path+file:///D:/a/run-bounded/run-bounded#bounded-run@0.1.2"
|
|
49
|
+
}
|
|
50
|
+
]
|
|
51
|
+
}
|