hermit-run 0.5.0

Hermit: a deterministic Linux execution engine for reproducible runs, record and replay, and concurrency-race search.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
/*
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 * All rights reserved.
 *
 * This source code is licensed under the BSD-style license found in the
 * LICENSE file in the root directory of this source tree.
 */

#![deny(clippy::all)]

use std::env;
use std::ffi::OsString;
use std::io;
use std::io::Write;
use std::net::TcpListener;
use std::os::fd::AsFd;
use std::os::fd::BorrowedFd;
use std::os::fd::IntoRawFd;
use std::os::unix::process::CommandExt;
use std::path::Path;
use std::path::PathBuf;
use std::process::Command;
use std::process::ExitCode;

const REVERSE_DAP: &str = include_str!("hermit-dap-reverse.py");

#[derive(Debug, PartialEq)]
struct ReplayOptions {
    id: OsString,
    data_dir: Option<OsString>,
    gdbserver_port: u16,
}

#[derive(Debug, PartialEq)]
struct Options {
    gdb: OsString,
    replay: Option<ReplayOptions>,
    listen: Option<Listen>,
}

/// Where `--listen` or `--listen-fd` takes its one client from.
#[derive(Debug, PartialEq)]
enum Listen {
    Address(String),
    Fd(i32),
}

fn usage() {
    println!(
        "Usage: hermit-dap [--gdb PATH] [--listen [HOST:]PORT | --listen-fd FD] [--replay ID [--data-dir DIR] [--gdbserver-port PORT]]\n\n\
         Start a Debug Adapter Protocol server for a Hermit GDB remote target.\n\
         The DAP attach request must include the guest executable as 'program'\n\
         and the Hermit GDB server address as 'target'.\n\n\
         By default the DAP client speaks to hermit-dap on stdin and stdout.\n\
         With --listen, hermit-dap instead waits for one DAP client on a TCP port\n\
         (HOST defaults to 127.0.0.1; port 0 picks a free one), writes\n\
         `hermit-dap: listening on HOST:PORT` to stderr, and serves that client.\n\
         --listen-fd FD does the same on a TCP socket already bound and listening\n\
         on descriptor FD, which `hermit run --dap-listen` uses so that it, not\n\
         hermit-dap, reports an address it cannot listen on.\n\n\
         With --replay, hermit-dap starts and manages `hermit replay --serve-only`,\n\
         enabling source-level stepBack and reverseContinue by replaying from the beginning."
    );
}

fn default_gdb() -> OsString {
    let system_gdb = Path::new("/usr/bin/gdb");
    if system_gdb.is_file() {
        system_gdb.as_os_str().to_owned()
    } else {
        OsString::from("gdb")
    }
}

fn parse_options<I>(arguments: I) -> Result<Option<Options>, String>
where
    I: IntoIterator<Item = OsString>,
{
    let mut gdb = None;
    let mut listen = None;
    let mut replay = None;
    let mut data_dir = None;
    let mut gdbserver_port = 1234;
    let mut gdbserver_port_set = false;
    let mut args = arguments.into_iter();

    while let Some(argument) = args.next() {
        if argument == "--gdb" {
            let path = args
                .next()
                .ok_or_else(|| "--gdb requires a path".to_owned())?;
            if gdb.replace(path).is_some() {
                return Err("--gdb may only be specified once".to_owned());
            }
        } else if argument == "--listen" {
            let address = args
                .next()
                .ok_or_else(|| "--listen requires [HOST:]PORT".to_owned())?;
            let address = listen_address(&address.to_string_lossy())?;
            if listen.replace(Listen::Address(address)).is_some() {
                return Err("--listen and --listen-fd may only be specified once".to_owned());
            }
        } else if argument == "--listen-fd" {
            let fd = args
                .next()
                .ok_or_else(|| "--listen-fd requires a descriptor".to_owned())?
                .to_string_lossy()
                .parse::<i32>()
                .ok()
                .filter(|fd| *fd > 2)
                .ok_or_else(|| "--listen-fd requires a descriptor above 2".to_owned())?;
            if listen.replace(Listen::Fd(fd)).is_some() {
                return Err("--listen and --listen-fd may only be specified once".to_owned());
            }
        } else if argument == "--replay" {
            let id = args
                .next()
                .ok_or_else(|| "--replay requires a recording ID".to_owned())?;
            if replay.replace(id).is_some() {
                return Err("--replay may only be specified once".to_owned());
            }
        } else if argument == "--data-dir" {
            let path = args
                .next()
                .ok_or_else(|| "--data-dir requires a path".to_owned())?;
            if data_dir.replace(path).is_some() {
                return Err("--data-dir may only be specified once".to_owned());
            }
        } else if argument == "--gdbserver-port" {
            let port = args
                .next()
                .ok_or_else(|| "--gdbserver-port requires a port".to_owned())?;
            gdbserver_port_set = true;
            gdbserver_port = port
                .to_string_lossy()
                .parse()
                .map_err(|_| "--gdbserver-port requires a valid port".to_owned())?;
        } else if argument == "-h" || argument == "--help" {
            usage();
            return Ok(None);
        } else {
            return Err(format!(
                "unrecognized argument: {}",
                argument.to_string_lossy()
            ));
        }
    }

    if replay.is_none() && data_dir.is_some() {
        return Err("--data-dir requires --replay".to_owned());
    }
    if replay.is_none() && gdbserver_port_set {
        return Err("--gdbserver-port requires --replay".to_owned());
    }

    Ok(Some(Options {
        gdb: gdb.unwrap_or_else(default_gdb),
        listen,
        replay: replay.map(|id| ReplayOptions {
            id,
            data_dir,
            gdbserver_port,
        }),
    }))
}

/// The socket address `--listen` binds: `PORT` alone means loopback, so the
/// adapter is not reachable from other hosts unless HOST says so.
fn listen_address(argument: &str) -> Result<String, String> {
    let (host, port) = match argument.rsplit_once(':') {
        Some((host, port)) => (host, port),
        None => ("127.0.0.1", argument),
    };
    if host.is_empty() {
        return Err("--listen requires a host before ':'".to_owned());
    }
    let port: u16 = port
        .parse()
        .map_err(|_| "--listen requires a valid port".to_owned())?;
    Ok(format!("{host}:{port}"))
}

/// Waits for one DAP client on `address` and makes its connection this
/// process's stdin and stdout, which GDB's DAP interpreter then serves.
///
/// Only the first client is accepted: GDB serves one session and exits when
/// it ends. The listening socket is closed before GDB starts (it is also
/// close-on-exec), so a second client is refused rather than left waiting.
fn accept_client(listen: &Listen) -> Result<(), String> {
    let listener = match listen {
        Listen::Address(address) => TcpListener::bind(address).map_err(|error| {
            format!(
                "could not listen on {address}: {error}; pass another port, or port 0 \
                 to let the system pick a free one"
            )
        })?,
        Listen::Fd(fd) => {
            // Not inherited by GDB: its duplicate on stdin and stdout is.
            // SAFETY: fcntl on a descriptor number; it touches no memory.
            if unsafe { libc::fcntl(*fd, libc::F_SETFD, libc::FD_CLOEXEC) } == -1 {
                return Err(format!(
                    "--listen-fd {fd} is not a usable descriptor: {}",
                    io::Error::last_os_error()
                ));
            }
            // SAFETY: the caller hands this open descriptor over by
            // --listen-fd and keeps no other use of it in this process.
            unsafe { <TcpListener as std::os::fd::FromRawFd>::from_raw_fd(*fd) }
        }
    };
    let local = listener
        .local_addr()
        .map_err(|error| format!("--listen-fd's descriptor is not a TCP socket: {error}"))?;
    // Tools that pass port 0 read the chosen port from this line, often by
    // polling a file that stderr goes to. One write: `eprintln!` can split a
    // line into several writes, and a reader between them saw a truncated
    // address (test.cli in the validation of 263f7477, 2026-10-17).
    let _ = io::stderr().write_all(format!("hermit-dap: listening on {local}\n").as_bytes());
    let _ = io::stderr().flush();
    let (client, peer) = listener
        .accept()
        .map_err(|error| format!("could not accept a DAP client on {local}: {error}"))?;
    drop(listener);
    nix::unistd::dup2_stdin(&client)
        .and_then(|()| nix::unistd::dup2_stdout(&client))
        .map_err(|error| format!("could not serve the DAP client {peer}: {error}"))?;
    eprintln!("hermit-dap: serving the DAP client at {peer}");
    Ok(())
}

fn replay_command(options: &ReplayOptions) -> Result<Vec<String>, String> {
    let hermit = env::current_exe()
        .map_err(|error| format!("failed to locate hermit-dap: {error}"))?
        .with_file_name("hermit");
    if !hermit.is_file() {
        return Err(format!(
            "could not find the hermit executable beside hermit-dap: {}",
            hermit.display()
        ));
    }

    let mut args = vec![
        "replay".to_owned(),
        options.id.to_string_lossy().into_owned(),
        "--serve-only".to_owned(),
        format!("--gdbserver-port={}", options.gdbserver_port),
    ];
    if let Some(data_dir) = &options.data_dir {
        args.push("--data-dir".to_owned());
        args.push(data_dir.to_string_lossy().into_owned());
    }

    let mut serialized = vec![hermit.to_string_lossy().into_owned()];
    serialized.extend(args);
    Ok(serialized)
}

/// Inheritable duplicates of this process's stdin, stdout and stderr, as a
/// Python tuple literal, or `None` if any duplicate fails.
///
/// GDB's DAP interpreter redirects its own descriptors 0, 1 and 2 to internal
/// pipes before it runs the replay extension, and drains them only after
/// startup. A startup refusal written through them never reaches the client,
/// so the extension writes it through these duplicates instead. They survive
/// the exec below on purpose; the extension closes them once startup
/// succeeds. Without them the extension can only write a refusal to GDB's own
/// stderr, so a failed duplicate is reported here, while this process's
/// stderr still reaches the client's log.
fn client_fds() -> String {
    let duplicate = |name: &'static str, fd: BorrowedFd<'_>| {
        nix::unistd::dup(fd).map_err(|error| format!("{name} ({error})"))
    };
    match (
        duplicate("stdin", io::stdin().as_fd()),
        duplicate("stdout", io::stdout().as_fd()),
        duplicate("stderr", io::stderr().as_fd()),
    ) {
        (Ok(input), Ok(output), Ok(error)) => format!(
            "({}, {}, {})",
            input.into_raw_fd(),
            output.into_raw_fd(),
            error.into_raw_fd()
        ),
        (input, output, error) => {
            // Dropping the duplicates that did succeed closes them.
            let failed: Vec<String> = [input.err(), output.err(), error.err()]
                .into_iter()
                .flatten()
                .collect();
            eprintln!(
                "hermit-dap: could not duplicate {}; if managed replay refuses to \
                 start, its reason goes only to GDB's stderr, which GDB's DAP \
                 interpreter does not pass to the client",
                failed.join(", ")
            );
            "None".to_string()
        }
    }
}

fn main() -> ExitCode {
    let options = match parse_options(env::args_os().skip(1)) {
        Ok(Some(options)) => options,
        Ok(None) => return ExitCode::SUCCESS,
        Err(error) => {
            eprintln!("hermit-dap: {error}");
            eprintln!("Try 'hermit-dap --help' for more information.");
            return ExitCode::FAILURE;
        }
    };

    if let Some(listen) = &options.listen {
        // Before client_fds() below, which duplicates the client's stdin
        // and stdout for managed replay's refusals.
        if let Err(error) = accept_client(listen) {
            eprintln!("hermit-dap: {error}");
            return ExitCode::FAILURE;
        }
    }

    let mut gdb_command = Command::new(&options.gdb);
    gdb_command
        .arg("--quiet")
        .arg("--nx")
        .arg("--init-eval-command=set debuginfod enabled off")
        .arg("--init-eval-command=set sysroot /");

    if let Some(replay) = &options.replay {
        let replay_command = match replay_command(replay).and_then(|command| {
            serde_json::to_string(&command)
                .map_err(|error| format!("failed to encode hermit replay command: {error}"))
        }) {
            Ok(command) => command,
            Err(error) => {
                eprintln!("hermit-dap: {error}");
                return ExitCode::FAILURE;
            }
        };
        let replay_target = format!("127.0.0.1:{}", replay.gdbserver_port);
        let client_fds = client_fds();
        let extension = format!(
            "python HERMIT_REPLAY_COMMAND = {replay_command}; \
             HERMIT_REPLAY_TARGET = {replay_target:?}; \
             HERMIT_CLIENT_FDS = {client_fds}; exec({REVERSE_DAP:?})"
        );
        gdb_command.arg(format!("--init-eval-command={extension}"));
    }

    let error = gdb_command.arg("--interpreter=dap").exec();
    eprintln!(
        "hermit-dap: failed to execute {}: {error}",
        PathBuf::from(&options.gdb).display()
    );
    ExitCode::FAILURE
}
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn replay_options_use_existing_command_vocabulary() {
        let options = parse_options([
            "--replay".into(),
            "recording-id".into(),
            "--data-dir".into(),
            "/tmp/recordings".into(),
            "--gdbserver-port".into(),
            "2345".into(),
        ])
        .unwrap()
        .unwrap();

        assert_eq!(
            options.replay,
            Some(ReplayOptions {
                id: "recording-id".into(),
                data_dir: Some("/tmp/recordings".into()),
                gdbserver_port: 2345,
            })
        );
    }

    #[test]
    fn listen_defaults_to_loopback() {
        let listen = |argument: &str| {
            parse_options(["--listen".into(), argument.into()])
                .map(|options| options.unwrap().listen)
        };
        let address = |text: &str| Ok(Some(Listen::Address(text.to_owned())));
        assert_eq!(listen("4711"), address("127.0.0.1:4711"));
        assert_eq!(listen("0.0.0.0:0"), address("0.0.0.0:0"));
        assert_eq!(listen("[::1]:4711"), address("[::1]:4711"));
        assert_eq!(
            listen(":4711"),
            Err("--listen requires a host before ':'".to_owned())
        );
        assert_eq!(
            listen("70000"),
            Err("--listen requires a valid port".to_owned())
        );
        assert_eq!(
            parse_options(["--listen".into(), "1".into(), "--listen".into(), "2".into()]),
            Err("--listen and --listen-fd may only be specified once".to_owned())
        );
        let listen_fd = |argument: &str| {
            parse_options(["--listen-fd".into(), argument.into()])
                .map(|options| options.unwrap().listen)
        };
        assert_eq!(listen_fd("7"), Ok(Some(Listen::Fd(7))));
        for refused in ["1", "x", "-3"] {
            assert_eq!(
                listen_fd(refused),
                Err("--listen-fd requires a descriptor above 2".to_owned())
            );
        }
        assert_eq!(
            parse_options([
                "--listen".into(),
                "1".into(),
                "--listen-fd".into(),
                "7".into()
            ]),
            Err("--listen and --listen-fd may only be specified once".to_owned())
        );
    }

    #[test]
    fn gdbserver_port_without_replay_is_rejected() {
        let error = parse_options(["--gdbserver-port".into(), "2345".into()]).unwrap_err();
        assert_eq!(error, "--gdbserver-port requires --replay");
    }

    #[test]
    fn data_dir_without_replay_is_rejected() {
        let error = parse_options(["--data-dir".into(), "/tmp/recordings".into()]).unwrap_err();
        assert_eq!(error, "--data-dir requires --replay");
    }
}