const std = @import("std"); const builtin = @import("builtin"); const tools = @import("../tools.zig"); const Abort = @import("../abort.zig").Abort; const schema = @import("schema.zig"); pub const definition = .{ .name = "bash", .description = \\Run a command with bash in cwd. Stdin is empty and stdout and stderr are \\merged. timeout is whole seconds; the process group is killed on \\timeout or on user interrupt. The result is the last 2000 lines or 50 KB of \\output, then a status line with the exit code and elapsed time. A non-zero \\exit code is a normal result, not an error. , .Args = Args, .execute = execute, }; pub const Args = struct { command: schema.String(.{ .description = "Command to run with bash." }), timeout: schema.Integer(.{ .description = "Seconds before the process group is killed.", .min = 1, .max = 1800 }), cwd: schema.String(.{ .description = "Working directory for the command." }), }; pub const Details = struct { /// Null unless the process exited on its own. exit_code: ?i32, elapsed_ms: u64, killed: Killed, }; pub const Output = struct { /// The text the model sees. text: []const u8, details: Details, }; pub const Killed = enum(u8) { none, timed_out, aborted }; /// The end of the command output: at least the last `max_output_bytes`. const Tail = struct { buffer: [2 * tools.max_output_bytes]u8 = undefined, length: usize = 0, /// Every byte read, including the bytes no longer in the buffer. total: u64 = 0, fn fill(tail: *Tail, io: std.Io, file: std.Io.File) std.Io.File.Reader.Error!void { while (true) { if (tail.length == tail.buffer.len) { const keep = tail.buffer[tail.buffer.len - tools.max_output_bytes ..]; @memmove(tail.buffer[0..keep.len], keep); tail.length = keep.len; } const size = file.readStreaming(io, &.{tail.buffer[tail.length..]}) catch |err| switch (err) { error.EndOfStream => return, else => |e| return e, }; tail.length += size; tail.total += size; } } }; fn waitForStop(io: std.Io, abort: *Abort, timeout: std.Io.Timeout) Killed { return if (abort.wait(io, timeout)) .aborted else .timed_out; } /// Removes terminal escape sequences: CSI, OSC and the other ESC sequences. fn stripEscapes(arena: std.mem.Allocator, text: []const u8) ![]const u8 { if (std.mem.indexOfScalar(u8, text, 0x1b) == null) { return text; } var out: std.ArrayList(u8) = try .initCapacity(arena, text.len); var i: usize = 0; while (i < text.len) { if (text[i] != 0x1b) { out.appendAssumeCapacity(text[i]); i += 1; continue; } i += 1; if (i == text.len) { break; } switch (text[i]) { // Parameters and intermediates, then one final byte. '[' => { i += 1; while (i < text.len and (text[i] < 0x40 or text[i] > 0x7e)) i += 1; i += 1; }, // Ends with BEL or with ESC backslash. ']' => { i += 1; while (i < text.len and text[i] != 0x07 and !std.mem.startsWith(u8, text[i..], "\x1b\\")) i += 1; i += if (i < text.len and text[i] == 0x1b) 2 else 1; }, // Intermediates, then one final byte. else => { while (i < text.len and text[i] >= 0x20 and text[i] <= 0x2f) i += 1; i += 1; }, } } return out.items; } /// Keeps the text after the last carriage return of each line, as a terminal shows it. fn dropOverwritten(arena: std.mem.Allocator, text: []const u8) ![]const u8 { if (std.mem.indexOfScalar(u8, text, '\r') == null) { return text; } var out: std.ArrayList(u8) = try .initCapacity(arena, text.len); var lines = std.mem.splitScalar(u8, text, '\n'); while (lines.next()) |line| { const shown = std.mem.trimEnd(u8, line, "\r"); out.appendSliceAssumeCapacity(shown[if (std.mem.lastIndexOfScalar(u8, shown, '\r')) |i| i + 1 else 0..]); if (lines.index != null) { out.appendAssumeCapacity('\n'); } } return out.items; } fn lastLines(text: []const u8, max: usize) []const u8 { var end = text.len; for (0..max) |_| end = std.mem.lastIndexOfScalar(u8, text[0..end], '\n') orelse return text; return text[end + 1 ..]; } fn findBash(io: std.Io, arena: std.mem.Allocator, path_env: []const u8) ![:0]const u8 { var dirs = std.mem.tokenizeScalar(u8, path_env, ':'); while (dirs.next()) |dir| { // The child runs in its own cwd, where a relative entry names another directory. if (!std.fs.path.isAbsolute(dir)) { continue; } const path = try std.fmt.allocPrintSentinel(arena, "{s}/bash", .{dir}, 0); std.Io.Dir.cwd().access(io, path, .{ .execute = true }) catch continue; return path; } return error.BashNotFound; } /// Starts `bash -c command` as the leader of a new session, so it has no /// controlling terminal and its pid is its process group id. // std.process.spawn has no setsid option; replace this with std once it does. fn spawnSession(ctx: tools.Context, arena: std.mem.Allocator, command: []const u8, cwd: []const u8, output: std.posix.fd_t) !std.posix.pid_t { const exe = try findBash(ctx.io, arena, ctx.environ.getPosix("PATH") orelse "/usr/bin:/bin"); const argv = [_:null]?[*:0]const u8{ "bash", "-c", try arena.dupeSentinel(u8, command, 0) }; const envp = ctx.environ.block.slice.ptr; var dir = std.Io.Dir.cwd().openDir(ctx.io, cwd, .{}) catch |err| return tools.pathError(ctx, arena, cwd, err); defer dir.close(ctx.io); const null_file = try std.Io.Dir.cwd().openFile(ctx.io, "/dev/null", .{}); defer null_file.close(ctx.io); if (builtin.os.tag.isDarwin()) { const c = std.c; var actions: c.posix_spawn_file_actions_t = undefined; if (c.posix_spawn_file_actions_init(&actions) != 0) { return error.SystemResources; } defer _ = c.posix_spawn_file_actions_destroy(&actions); var attr: c.posix_spawnattr_t = undefined; if (c.posix_spawnattr_init(&attr) != 0) { return error.SystemResources; } defer _ = c.posix_spawnattr_destroy(&attr); if (c.posix_spawnattr_setflags(&attr, .{ .SETSID = true }) != 0 or c.posix_spawn_file_actions_addfchdir_np(&actions, dir.handle) != 0 or c.posix_spawn_file_actions_adddup2(&actions, null_file.handle, 0) != 0 or c.posix_spawn_file_actions_adddup2(&actions, output, 1) != 0 or c.posix_spawn_file_actions_adddup2(&actions, output, 2) != 0) { return error.SystemResources; } var pid: std.posix.pid_t = undefined; const rc = c.posix_spawn(&pid, exe, &actions, &attr, &argv, envp); if (rc != 0) { return switch (@as(std.posix.E, @fromBackingInt(@intCast(rc)))) { .AGAIN, .NOMEM => error.SystemResources, .NOENT => error.FileNotFound, .ACCES => error.AccessDenied, else => |err| std.posix.unexpectedErrno(err), }; } return pid; } const system = std.posix.system; const rc = system.fork(); switch (std.posix.errno(rc)) { .SUCCESS => {}, else => |err| return std.posix.unexpectedErrno(err), } if (rc == 0) { // Only async-signal-safe calls between fork and exec. if (std.posix.errno(system.setsid()) == .SUCCESS and std.posix.errno(system.fchdir(dir.handle)) == .SUCCESS and std.posix.errno(system.dup2(null_file.handle, 0)) == .SUCCESS and std.posix.errno(system.dup2(output, 1)) == .SUCCESS and std.posix.errno(system.dup2(output, 2)) == .SUCCESS) { _ = system.execve(exe, &argv, envp); } if (builtin.link_libc) { std.c._exit(127); } else { std.os.linux.exit_group(127); } } return @intCast(rc); } pub fn execute(ctx: tools.Context, arena: std.mem.Allocator, args: Args) !Output { // One pipe for stdout and stderr keeps their order and keeps all child output off the terminal. const fds = try std.Io.Threaded.pipe2(.{ .CLOEXEC = true }); const stdout: std.Io.File = .{ .handle = fds[0], .flags = .{ .nonblocking = false } }; defer stdout.close(ctx.io); const write_end: std.Io.File = .{ .handle = fds[1], .flags = .{ .nonblocking = false } }; const pid = spawnSession(ctx, arena, args.command.value, args.cwd.value, write_end.handle) catch |err| { write_end.close(ctx.io); return err; }; write_end.close(ctx.io); var child: std.process.Child = .{ .id = pid, .thread_handle = {}, .stdin = null, .stdout = null, .stderr = null, .request_resource_usage_statistics = false }; defer if (child.id != null) { child.kill(ctx.io); }; const start = std.Io.Clock.awake.now(ctx.io); var tail: Tail = .{}; const timeout: std.Io.Timeout = .{ .duration = .{ .raw = .fromSeconds(args.timeout.value), .clock = .awake } }; const Done = union(enum) { output: std.Io.File.Reader.Error!void, exited: std.process.Child.WaitError!std.process.Child.Term, stop: Killed, grace: std.Io.Cancelable!void, }; var done_buffer: [4]Done = undefined; var select: std.Io.Select(Done) = .init(ctx.io, &done_buffer); defer select.cancelDiscard(); var read: ?std.Io.File.Reader.Error!void = null; var exited: ?std.process.Child.WaitError!std.process.Child.Term = null; var waiting = false; var killed: Killed = .none; var graced = false; // Canceling a wait loses the child unreaped, so an error kills the group and lets the wait finish. errdefer { std.posix.kill(-pid, .KILL) catch {}; if (waiting and exited == null) { while (select.await()) |done| { if (done == .exited) { break; } } else |_| {} } } try select.concurrent(.output, Tail.fill, .{ &tail, ctx.io, stdout }); try select.concurrent(.stop, waitForStop, .{ ctx.io, ctx.abort, timeout }); try select.concurrent(.exited, std.process.Child.wait, .{ &child, ctx.io }); waiting = true; // A background job can hold the pipe open after the command exits, so the // read ends a short time after the exit, or at a stop. while (exited == null or (read == null and killed == .none and !graced)) switch (try select.await()) { .output => |result| read = result, .exited => |result| { exited = result; if (read == null) { try select.concurrent(.grace, std.Io.sleep, .{ ctx.io, .fromMilliseconds(200), .awake }); } }, .stop => |why| if (exited == null) { killed = why; std.posix.kill(-pid, .KILL) catch {}; } else { graced = true; }, .grace => graced = true, }; select.cancelDiscard(); const term = try exited.?; if (read) |result| { try result; } const elapsed_ns: u64 = @intCast(start.untilNow(ctx.io, .awake).nanoseconds); const seconds = @as(f64, @floatFromInt(elapsed_ns)) / std.time.ns_per_s; const code: u32 = switch (term) { .exited => |value| value, .signal => |signal| 128 + @as(u32, @intCast(@backingInt(signal))), else => 1, }; const status = switch (killed) { .aborted => try std.fmt.allocPrint(arena, "[aborted by user, elapsed {d:.2}s]", .{seconds}), .timed_out => try std.fmt.allocPrint(arena, "[timed out after {d}s, killed, elapsed {d:.2}s]", .{ args.timeout.value, seconds }), .none => try std.fmt.allocPrint(arena, "[exit code {d}, elapsed {d:.2}s]", .{ code, seconds }), }; var data: []const u8 = tail.buffer[tail.length -| tools.max_output_bytes..tail.length]; const newline = data.len > 0 and data[data.len - 1] == '\n'; if (newline) { data = data[0 .. data.len - 1]; } const kept = lastLines(data, tools.max_output_lines); const omitted = tail.total - kept.len - @intFromBool(newline); const output = try dropOverwritten(arena, try stripEscapes(arena, kept)); var text: std.ArrayList(u8) = .empty; if (omitted > 0) { try text.print(arena, "[{d} earlier bytes omitted", .{omitted}); if (kept.len < data.len) { try text.print(arena, ", last {d} lines kept", .{tools.max_output_lines}); } try text.appendSlice(arena, "]\n"); } if (output.len > 0) { try text.print(arena, "{s}\n", .{output}); } try text.appendSlice(arena, status); return .{ .text = text.items, .details = .{ .exit_code = if (killed == .none) @intCast(code) else null, .elapsed_ms = elapsed_ns / std.time.ns_per_ms, .killed = killed, }, }; } const testing = std.testing; fn bash(dir: *tools.TestDir, command: []const u8, timeout: u32) tools.Result { return dir.call("bash", .{ .command = command, .timeout = timeout, .cwd = dir.root }); } fn setFlagAfter(flag: *Abort, ms: u64) void { std.Io.sleep(std.testing.io, .fromMilliseconds(@intCast(ms)), .awake) catch {}; flag.set(std.testing.io); } /// Checks the bash status line shape `PREFIXs]` and returns the seconds. fn expectStatus(text: []const u8, prefix: []const u8) !f64 { var it = std.mem.splitBackwardsScalar(u8, text, '\n'); const last = it.first(); try std.testing.expect(std.mem.startsWith(u8, last, prefix)); try std.testing.expect(std.mem.endsWith(u8, last, "s]")); return std.fmt.parseFloat(f64, last[prefix.len .. last.len - 2]); } test "bash reports a zero exit code and shows the whole output when expanded" { var dir = try tools.TestDir.init(); defer dir.deinit(); const result = bash(&dir, "echo hi", 10); try testing.expect(!result.is_error); try testing.expect(std.mem.startsWith(u8, result.text, "hi\n[exit code 0, elapsed ")); _ = try expectStatus(result.text, "[exit code 0, elapsed "); try testing.expectStringStartsWith(try tools.content.plain(dir.arena(), result.collapsed), "exit 0, "); try testing.expectEqualStrings(result.text, try tools.content.plain(dir.arena(), result.expanded)); } test "bash returns soon after the command exits while a background job keeps the output open" { var dir = try tools.TestDir.init(); defer dir.deinit(); const started = std.Io.Clock.awake.now(testing.io); const result = bash(&dir, "sleep 5 & echo started", 10); const wall: f64 = @as(f64, @floatFromInt(started.untilNow(testing.io, .awake).nanoseconds)) / std.time.ns_per_s; try testing.expectStringStartsWith(result.text, "started\n[exit code 0, elapsed "); try testing.expect(wall < 2.0); } test "bash reports a non-zero exit code as a normal result" { var dir = try tools.TestDir.init(); defer dir.deinit(); const result = bash(&dir, "exit 3", 10); try testing.expect(!result.is_error); _ = try expectStatus(result.text, "[exit code 3, elapsed "); } test "bash merges stderr into the output in order, including a syntax error on the first line" { var dir = try tools.TestDir.init(); defer dir.deinit(); const merged = bash(&dir, "echo out; echo err 1>&2; echo out2", 10); try testing.expect(!merged.is_error); try testing.expectStringStartsWith(merged.text, "out\nerr\nout2\n[exit code 0, elapsed "); const syntax = bash(&dir, "if then", 10); try testing.expect(std.mem.indexOf(u8, syntax.text, "syntax error") != null); } test "bash runs the command in a session of its own with no terminal" { var dir = try tools.TestDir.init(); defer dir.deinit(); const result = bash(&dir, "python3 -c 'import os; print(os.getsid(0))'; echo $$; exec 3= 0.25); try testing.expect(elapsed <= 5.0); const status = try std.fmt.allocPrint(dir.arena(), "exit 0, {d:.2}s", .{elapsed}); try testing.expectEqualStrings(status, try tools.content.plain(dir.arena(), result.collapsed)); } const Stopped = struct { dir: tools.TestDir, result: tools.Result = undefined, fn run(self: *Stopped, command: []const u8, timeout: u32) void { self.result = bash(&self.dir, command, timeout); } }; /// Whether `pid` is a live process. A killed orphan stays a zombie until /// PID 1 reaps it, and a container's PID 1 may never do so. fn running(pid: std.posix.pid_t) bool { std.posix.kill(pid, @fromBackingInt(@intCast(0))) catch return false; if (builtin.os.tag != .linux) { return true; } var path_buffer: [32]u8 = undefined; var stat_buffer: [512]u8 = undefined; const path = std.fmt.bufPrint(&path_buffer, "/proc/{d}/stat", .{pid}) catch unreachable; const stat = std.Io.Dir.cwd().readFile(testing.io, path, &stat_buffer) catch return false; const state = std.mem.lastIndexOfScalar(u8, stat, ')') orelse return true; return state + 2 >= stat.len or stat[state + 2] != 'Z'; } test "a timeout or an interrupt stops the command, its children and a held output" { const commands = [_][]const u8{ "sleep 30", "exec >&- 2>&-; sleep 30", "yes", "sleep 30 & echo $! > child.pid; wait", "perl -e 'setpgrp(0, 0); open(F, \">holder.pid\"); print F $$; close F; sleep 30' & wait", }; var runs: [2 * commands.len]Stopped = undefined; var ready: usize = 0; defer for (runs[0..ready]) |*run| run.dir.deinit(); for (&runs) |*run| { run.* = .{ .dir = try tools.TestDir.init() }; ready += 1; } // Concurrent runs keep the test as long as one timeout. const started = std.Io.Clock.awake.now(testing.io); var group: std.Io.Group = .init; defer group.cancel(testing.io); for (&runs, 0..) |*run, index| { const interrupt = index >= commands.len; if (interrupt) { try group.concurrent(testing.io, setFlagAfter, .{ &run.dir.abort, 300 }); } try group.concurrent(testing.io, Stopped.run, .{ run, commands[index % commands.len], if (interrupt) 60 else 1 }); } try group.await(testing.io); const wall: f64 = @as(f64, @floatFromInt(started.untilNow(testing.io, .awake).nanoseconds)) / std.time.ns_per_s; defer for (&runs) |*run| { const text = run.dir.read("holder.pid") catch continue; const pid = std.fmt.parseInt(std.posix.pid_t, text, 10) catch continue; std.posix.kill(pid, .KILL) catch {}; }; try testing.expect(wall < 5.0); for (&runs, 0..) |*run, index| { const interrupt = index >= commands.len; try testing.expect(!run.result.is_error); const elapsed = try expectStatus(run.result.text, if (interrupt) "[aborted by user, elapsed " else "[timed out after 1s, killed, elapsed "); const collapsed = try std.fmt.allocPrint(run.dir.arena(), "{s} {d:.2}s", .{ if (interrupt) "aborted after" else "timed out after", elapsed }); try testing.expectEqualStrings(collapsed, try tools.content.plain(run.dir.arena(), run.result.collapsed)); if (index % commands.len != 3) { continue; } const text = try run.dir.read("child.pid"); const pid = try std.fmt.parseInt(std.posix.pid_t, std.mem.trimEnd(u8, text, "\n"), 10); var gone = false; for (0..40) |_| { if (!running(pid)) { gone = true; break; } std.Io.sleep(testing.io, .fromMilliseconds(50), .awake) catch {}; } try testing.expect(gone); } } /// The command and its working directory. pub fn renderCall(arena: std.mem.Allocator, args: Args) std.mem.Allocator.Error!tools.content.Content { const params = try std.fmt.allocPrint(arena, "{s} ({s})", .{ args.command.value, args.cwd.value }); return tools.content.callLine(arena, definition.name, params); } /// The exit status, or why the command was stopped. pub fn renderResult(arena: std.mem.Allocator, output: Output) std.mem.Allocator.Error!tools.Rendered { const details = output.details; const seconds = @as(f64, @floatFromInt(details.elapsed_ms)) / std.time.ms_per_s; const line = switch (details.killed) { .aborted => try std.fmt.allocPrint(arena, "aborted after {d:.2}s", .{seconds}), .timed_out => try std.fmt.allocPrint(arena, "timed out after {d:.2}s", .{seconds}), .none => try std.fmt.allocPrint(arena, "exit {d}, {d:.2}s", .{ details.exit_code orelse 1, seconds }), }; return .{ .collapsed = try tools.content.text(arena, line), .expanded = try tools.content.text(arena, output.text) }; }