Repository navigation
Expand file tree
/
Copy pathexec.rs
More file actions
1372 lines (1283 loc) · 53.6 KB
/
Copy pathexec.rs
File metadata and controls
1372 lines (1283 loc) · 53.6 KB
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
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
//! SSH `exec` request handling: Launching tasks defined in the session,
//! git recieve-pack, and launching side ops.
//!
//! Process spawning is abstracted via the [`Exec`] / [`Process`] traits
//! so the bridge logic can be exercised with a mock in tests without
//! going through `tokio::process` or russh.
use std::collections::{BTreeMap, BTreeSet};
use std::fmt::Display;
use std::io;
use std::process::Stdio;
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
use std::time::Duration;
use boxes::SessionId;
use futures::{
StreamExt,
stream::{self, BoxStream, Stream},
};
use paths::DaemonAbsPath;
use russh::{
Channel, ChannelId,
server::{Msg, Session},
};
use std::collections::VecDeque;
use tempfile::TempDir;
use tokio::net::unix::pipe;
use tokio::sync::{mpsc, watch};
use tokio::task::JoinHandle;
use tokio::{
io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt},
process::{Child, ChildStderr, ChildStdin, ChildStdout, Command},
};
use tokio_util::sync::CancellationToken;
use tracing::Instrument as _;
// Every task this module spawns carries the caller's span (TEL-022): the
// clippy `disallowed-methods` for the crate names tokio's own spawn.
use crate::traced::spawn;
use diagnostics::redact::scrub_secrets;
use minimald_rpc::exec::{ExecId, ExecMode};
use crate::{
ChannelConfig, MINIMAL_SESSION_ID_ENV,
box_actor::BoxHandle,
box_manager::BoxKeyPredicate,
connection::{ConnectionError, ConnectionHandle},
server::ServerStateHandle,
};
mod bridge;
mod git;
mod process;
mod run;
pub(crate) use bridge::*;
use git::*;
pub use process::*;
use run::*;
/// "What to run." Turns into a [`Stream`] of one or more process
/// spawns, run back-to-back.
///
/// Modelling as a `Stream` rather than a two-trait `IntoIter`/`Iter`
/// split is a deliberate choice: some impls (notably [`TaskExec`]) need
/// stateful resources to outlive every spawned process — that state has
/// no honest home in a separate "resolution" step, so we let it live on
/// the stack frame of the impl's producer (or on the stream's state
/// directly). Trivial impls like [`TokioExec`] use [`stream::once`].
///
/// Setup errors and per-spawn errors both surface as `Err` items in the
/// stream; the bridge handles them uniformly.
pub trait Exec: Send + 'static {
/// What the bridge does with input arriving after the current command
/// closed its stdin: dropped for a single program, kept for the next in
/// a sequence (the default).
fn unread_stdin(&self) -> UnreadStdin {
UnreadStdin::Keep
}
type Process: Process;
/// Whether a destroy of the box ends this exec's process. True for a
/// process inside the box, which the destroy's host teardown stops.
/// False for a process outside the box — on the daemon's host, or in a
/// task's own sandbox — which outlives it.
const ENDED_BY_BOX_DESTROY: bool = true;
fn exec(self, session: BoxHandle) -> BoxStream<'static, io::Result<Self::Process>>;
}
/// A handle to one spawned process: stdio plus lifecycle controls.
///
/// `wait` MUST be cancel-safe — callers poll it inside `tokio::select!`,
/// so the future may be dropped and re-awaited across loop iterations.
pub trait Process: Send + 'static {
type Stdin: AsyncWrite + Unpin + Send + 'static;
type Stdout: AsyncRead + Unpin + Send + 'static;
type Stderr: AsyncRead + Unpin + Send + 'static;
/// Returns all three stdio handles the first time it's called,
/// `None` thereafter (per-handle `Option::take` semantics, matching
/// `tokio::process::Child`).
fn take_stdio(&mut self) -> Option<(Self::Stdin, Self::Stdout, Self::Stderr)>;
/// Resolves when the process exits. `Ok(None)` means the process
/// was terminated by a signal rather than exiting with a numeric
/// code.
async fn wait(&mut self) -> io::Result<Option<i32>>;
/// Request termination. Idempotent. Returns immediately — the
/// caller is expected to follow up with `wait` for the actual exit.
fn start_kill(&mut self) -> io::Result<()>;
/// A line for the client's stderr about why the process ended, once
/// `wait` has returned. `None` (the default) when the process's own
/// output says all there is: it ran and exited, or was signalled.
fn exit_notice(&mut self) -> Option<String> {
None
}
}
/// Handles a request to run a program on an SSH channel.
///
/// Looks up the target session via the `MINIMAL_SESSION_ID` env var the
/// client previously set on this channel, fetches its workspace, accepts the
/// request, and spawns an async task to take over the
/// channel for the lifetime of the conversation.
///
/// Accepted forms are:
/// * `git-receive-pack min://<session ID>` - handles a git receive-pack, routing
/// with the trailing session ID. Matched before the vocabulary below, and
/// not part of it: git speaks the pack protocol, not exec requests.
/// * `git-upload-pack min://<session ID>` - handles a git upload-pack, routing
/// with the trailing session ID the same way.
/// * a [`minimald_rpc::exec::ExecRequest`], which is where the rest of the
/// vocabulary is defined. The daemon-serviced forms — `min://task/run`,
/// `min://package/build` and `min://check` — are each routed via a
/// `MINIMAL_SESSION_ID` env var that must be set on the channel by the
/// client. `min://shell` and `min://argv` are handed to the session.
/// * anything else: a shell command for the session. Nothing about a
/// command's text routes it, so a session command can never be mistaken
/// for one of the daemon's own (gominimal/inbox#558).
pub(crate) async fn handle_exec(
argv: &[u8],
serv: ServerStateHandle,
conn: ConnectionHandle,
id: ChannelId,
session: &mut Session,
) -> Result<(), ConnectionError> {
let argv = match String::from_utf8(argv.to_vec()) {
Ok(argv) => argv,
Err(e) => {
tracing::warn!("channel {id}: argv was not utf8: {e}");
session.channel_failure(id)?;
return Ok(());
}
};
let mut conn_lock = conn.lock().await;
let Some((channel, config)) = conn_lock.take(id) else {
session.channel_failure(id)?;
return Ok(());
};
let conn_username = conn_lock.ssh_username.clone().unwrap_or_default();
drop(conn_lock);
if let Some(ident) = argv.strip_prefix("git-receive-pack min://") {
return handle_git_receive(ident, serv, conn, id, session, channel, config).await;
}
if let Some(ident) = argv.strip_prefix("git-upload-pack min://") {
return handle_git_upload(ident, serv, conn, id, session, channel, config).await;
}
let Some(session_id_str) = config.env_vars.get(MINIMAL_SESSION_ID_ENV) else {
tracing::warn!(
"execution request rejected on channel {id}: missing {MINIMAL_SESSION_ID_ENV}",
);
session.channel_failure(id)?;
return Ok(());
};
let Ok(session_id) = SessionId::parse_str(session_id_str) else {
tracing::warn!(
value = %session_id_str,
"execution request rejected on channel {id}: {MINIMAL_SESSION_ID_ENV} is not a uuid",
);
session.channel_failure(id)?;
return Ok(());
};
// The exec span (which adopts the client's TRACEPARENT) is opened before
// the session lookup, so the manager's GetSession is a child of the
// caller's trace instead of a root of its own.
let (span, traceparent) = exec_span(&config, session_id, &argv);
let trace_env = minimald_rpc::taskenv::trace_env(
mlog::otel::exporting(),
traceparent,
minimald_rpc::trace::opted_out(&config.env_vars),
);
let mngr = serv.sessions_manager().await;
let session_handle = match mngr
.get_session(BoxKeyPredicate::Id(session_id))
.instrument(span.clone())
.await
{
Ok(Some(h)) => h,
Ok(None) => {
tracing::warn!(%session_id, "execution request rejected: unknown session");
session.channel_failure(id)?;
return Ok(());
}
Err(e) => {
tracing::warn!(%session_id, error = %e, "execution request rejected: lookup failed");
session.channel_failure(id)?;
return Ok(());
}
};
// Logged for every accepted form, before the dispatch that decides which
// one it is: an operator reading the log should see what a client asked to
// run, whether it was serviced by the daemon, handed to the session, or
// refused below. The command is scrubbed so a credential passed as an
// argument never lands in the log verbatim. For a client that opted out
// of telemetry the line says so and carries no command at all: the log
// exporter would otherwise ship the one record of what it ran.
if minimald_rpc::trace::opted_out(&config.env_vars) {
tracing::info!(%session_id, telemetry = OPT_OUT, "exec request (command not recorded)");
} else {
tracing::info!(%session_id, command = %scrub_secrets(&argv), "exec request");
}
// Parsed, never sniffed. The vocabulary in `minimald_rpc::exec` is the only
// way to ask for one of the daemon's own forms, so a session command can no
// longer be mistaken for one — `min --version` names the session's `min`
// and reaches it, where the old `strip_prefix("min ")` claimed and refused
// it (gominimal/inbox#558).
let request = match minimald_rpc::exec::ExecRequest::parse(&argv) {
Ok(request) => request,
Err(e) => {
tracing::warn!(%session_id, error = %e, "execution request rejected");
// Accept-then-report, as the bad-flag path does: a bare
// `channel_failure` would reach the client as an opaque "exec
// request failed" with none of the detail the error carries.
session.channel_success(id)?;
spawn(async move {
reject_unsupported_exec(channel, e.to_string()).await;
});
return Ok(());
}
};
use minimald_rpc::exec::ExecRequest;
// A channel terminal serves only the forms that relay a terminal: a tty
// exec takes its size, and an attach resumes one. Every other form has
// pipes for stdio, as before.
let takes_terminal = match &request {
ExecRequest::Exec(spec) => spec.mode == ExecMode::Tty,
ExecRequest::ExecAttach(_) => true,
_ => false,
};
if config.pty.is_some() && !takes_terminal {
tracing::warn!("channel {id}: pty requested but not yet supported",);
session.channel_failure(id)?;
return Ok(());
}
// A command for the box runs only in a running box, and every one gets
// an exec id, whatever its mode (BOX-149). The id and the mode ride on
// the exec span, so every record the exec emits names them.
let mode = match &request {
ExecRequest::Shell(_) | ExecRequest::Argv(_) => Some(ExecMode::Attached),
ExecRequest::Exec(spec) => Some(spec.mode),
_ => None,
};
let exec_id = if let Some(mode) = mode {
let record = match session_handle.record().instrument(span.clone()).await {
Ok(record) => record,
Err(e) => {
tracing::warn!(%session_id, error = %e, "execution request rejected: the box is gone");
session.channel_failure(id)?;
return Ok(());
}
};
if record.status != boxes::BoxState::Active {
tracing::warn!(
parent: &span,
%session_id,
state = box_state_word(record.status),
"execution request refused: the box is not running"
);
let label = record
.name
.clone()
.unwrap_or_else(|| session_id.to_string());
let message = not_running_message(&label, record.status);
session.channel_success(id)?;
spawn(async move {
answer_exec(channel, b"", message.as_bytes(), NOT_RUNNING_STATUS).await;
});
return Ok(());
}
// BOX-153: a box whose stored spec sets `[io] exec_enabled = false`
// takes no command, in any mode.
let gate = match ExecBox::of(&session_handle).instrument(span.clone()).await {
Ok(exec_box) => exec_box.exec_gate(),
Err(e) => {
tracing::warn!(%session_id, error = %e, "execution request rejected: the box is gone");
session.channel_failure(id)?;
return Ok(());
}
};
if gate != ExecGate::Enabled {
let label = record
.name
.clone()
.unwrap_or_else(|| session_id.to_string());
let message = if gate == ExecGate::Disabled {
tracing::warn!(
parent: &span,
%session_id,
"execution request refused: the box's spec sets io.exec_enabled = false"
);
exec_disabled_message(&label)
} else {
tracing::warn!(
parent: &span,
%session_id,
"execution request refused: the box's stored spec cannot be read"
);
exec_spec_unreadable_message(&label)
};
session.channel_success(id)?;
spawn(async move {
answer_exec(channel, b"", message.as_bytes(), EXEC_DISABLED_STATUS).await;
});
return Ok(());
}
let exec_id = mint_exec_id();
span.record("exec_id", exec_id.as_str());
span.record("exec_mode", mode.name());
tracing::info!(parent: &span, %session_id, %exec_id, mode = mode.name(), "exec accepted");
Some(exec_id)
} else {
None
};
match request {
ExecRequest::Shell(_) | ExecRequest::Argv(_) => {
let program = match request {
ExecRequest::Shell(cmd) => BoxProgram::Shell(cmd),
ExecRequest::Argv(words) => BoxProgram::Argv(words),
_ => unreachable!("the match arm admits only Shell and Argv"),
};
let span = span.clone();
session.channel_success(id)?;
spawn(
run_in_session(
serv,
conn,
session_handle,
id,
channel,
program,
conn_username,
trace_env,
)
.instrument(span),
);
}
ExecRequest::TaskRun {
task,
owns_box,
args,
cwd,
} => {
let task = task.trim().to_string();
if task.is_empty() {
tracing::warn!(%session_id, "execution request rejected: task/run names no task");
session.channel_failure(id)?;
return Ok(());
}
// A task's `env_vars`, resolved by the client against the invoking
// shell and carried on the channel environment (#585). Empty from a
// client that predates it — in which case the task path resolves
// them the old way, daemon-side.
// Plus the exec span's TRACEPARENT on opt-in (TEL-023):
// a `min` the task runs joins the caller's trace.
let task_env = minimald_rpc::taskenv::with_trace(
minimald_rpc::taskenv::from_channel_env(&config.env_vars),
trace_env.clone(),
);
let drop_env = minimald_rpc::taskenv::drops_from_channel_env(&config.env_vars);
// `min session run` resolved them all, and says so (inbox#778).
let client_resolved =
minimald_rpc::taskenv::resolved_from_channel_env(&config.env_vars);
let span = span.clone();
session.channel_success(id)?;
spawn(tracing::Instrument::instrument(
async move {
// `ExecTask::run` consumes the server handle; the box's end
// needs one after the bridge returns.
let end_serv = serv.clone();
let exec_task = ExecTask {
conn,
serv,
session: session_handle,
channel_id: id,
exec: TaskExec {
args,
// The name stays behind for the run-box-end log line.
task: task.clone(),
env: task_env,
drop_env,
client_resolved,
cwd,
},
};
let exit_status = exec_task.run(channel).await;
// The exit status is on the wire and the channel closed: the
// run is over whether or not its client is still here, so a
// box created for it ends now (NET-131).
if owns_box {
end_run_box(&end_serv, session_id, &task, exit_status).await;
}
},
span,
));
}
ExecRequest::PackageBuild(args) => {
let span = span.clone();
session.channel_success(id)?;
let build_args = args.trim().to_string();
spawn(tracing::Instrument::instrument(
async move {
run_build_exec(session_handle, id, channel, build_args).await;
},
span,
));
}
ExecRequest::Check(args) => {
session.channel_success(id)?;
let check_args = args.trim().to_string();
spawn(tracing::Instrument::instrument(
async move {
run_check_exec(session_handle, id, channel, check_args).await;
},
span,
));
}
ExecRequest::Exec(spec) => {
let exec_id = exec_id.expect("an exec form always gets an exec id above");
let timeout = spec.timeout_secs.map(Duration::from_secs);
session.channel_success(id)?;
if spec.mode == ExecMode::Attached {
spawn(
run_attached_exec(
serv,
conn,
session_handle,
id,
channel,
exec_id,
spec.argv,
timeout,
conn_username,
trace_env,
)
.instrument(span),
);
} else {
let winsize = config.pty.as_ref().map_or((24, 80), |pty| {
let (cols, rows) = pty.char_sizes;
let clamp = |n: u32, default: u16| match u16::try_from(n) {
Ok(0) => default,
Ok(n) => n,
Err(_) => u16::MAX,
};
(clamp(rows, 24), clamp(cols, 80))
});
let start = ManagedRequest {
exec_id,
mode: spec.mode,
argv: spec.argv,
timeout,
winsize,
conn_username,
extra_env: trace_env,
};
spawn(start_and_answer(session_handle, channel, start).instrument(span));
}
}
ExecRequest::ExecAttach(exec_id) => {
session.channel_success(id)?;
// The keys the client negotiated, as a box attach reads them
// (BCLI-068). A client that sent none gets the default keys.
let keys = boxes::keys::SessionKeys::from_env(&config.env_vars).validated_or_default();
spawn(
serve_exec_attach(channel, session_handle, session_id, exec_id, keys)
.instrument(span),
);
}
ExecRequest::ExecOutput(exec_id) => {
session.channel_success(id)?;
spawn(serve_exec_output(channel, session_handle, exec_id).instrument(span));
}
ExecRequest::ExecWait(exec_id) => {
session.channel_success(id)?;
spawn(serve_exec_wait(channel, session_handle, exec_id).instrument(span));
}
}
Ok(())
}
/// The exit status of an exec that the box's spec refuses (BOX-153).
pub(crate) const EXEC_DISABLED_STATUS: u32 = 5;
/// The refusal of an exec into a box whose spec turns exec off (BOX-153).
pub(crate) fn exec_disabled_message(box_label: &str) -> String {
format!("box {box_label} does not run commands: its spec sets [io] exec_enabled = false.\n")
}
/// The refusal of an exec into a box whose stored spec cannot be read or
/// parsed, so the exec gate fails closed (BOX-153).
pub(crate) fn exec_spec_unreadable_message(box_label: &str) -> String {
format!(
"box {box_label} does not run commands: its stored spec cannot be read, so the daemon cannot check [io] exec_enabled.\n"
)
}
/// Runs an attached `min://exec`: an argv in the box with no shell, its stdio
/// on the channel's pipes, under its own timeout when it has one (BOX-149).
/// Its events and its end name its exec id.
#[expect(
clippy::too_many_arguments,
reason = "the channel's wiring and the exec's own facts, from one call site"
)]
async fn run_attached_exec(
serv: ServerStateHandle,
conn: ConnectionHandle,
session: BoxHandle,
channel_id: ChannelId,
channel: Channel<Msg>,
exec_id: ExecId,
argv: Vec<String>,
timeout: Option<Duration>,
conn_username: String,
extra_env: BTreeMap<String, String>,
) {
let exec_box = match ExecBox::of(&session).await {
Ok(exec_box) => Some(exec_box),
Err(error) => {
tracing::warn!(%exec_id, %error, "exec: could not read the box to write the exec's events");
None
}
};
let facts = ExecFacts {
principal: conn_username.clone(),
argv: argv.clone(),
};
// BOX-151: an attached exec is known by its id while it runs, so a stop
// or a wait by that id finds it. It has no transcript. The path only
// ties the entry to the box's directory, which a reap removes.
// The stop is registered before the entry, and both before
// `exec_started`. A stop of the id that a follower of the events sees
// first then finds the exec and ends it (BOX-151).
let stop = register_stop(&exec_id);
let entry = exec_box.as_ref().map(|exec_box| {
let transcript = boxes::store::exec_transcript_path(&exec_box.dir, exec_id.as_str());
if let Some(dir) = transcript.parent()
&& let Err(error) = std::fs::create_dir_all(dir)
{
tracing::warn!(%exec_id, %error, "exec: could not create the box's execs directory");
}
let entry = Arc::new(ExecEntry::new(
exec_id.clone(),
exec_box.record.id,
ExecMode::Attached,
facts.argv.clone(),
transcript,
None,
));
register_exec(Arc::clone(&entry));
entry
});
if let Some(exec_box) = &exec_box {
exec_box.write_event(
boxes::events::BoxEventType::ExecStarted,
&exec_id,
ExecMode::Attached,
&facts,
None,
);
}
let timed_out = Arc::new(AtomicBool::new(false));
let task = ExecTask {
conn,
serv,
session,
channel_id,
exec: TimedBoxExec {
inner: BoxExec {
program: BoxProgram::Argv(argv),
extra_env,
conn_username,
},
timeout,
timed_out: Arc::clone(&timed_out),
stop,
},
};
let status = task.run(channel).await;
forget_stop(&exec_id);
let reason = if timed_out.load(Ordering::SeqCst) {
ExecExitReason::Timeout
} else {
ExecExitReason::Exited
};
let exit = ExecExit {
code: i32::try_from(status).ok(),
reason,
};
if let Some(exec_box) = &exec_box {
exec_box.write_event(
boxes::events::BoxEventType::ExecExited,
&exec_id,
ExecMode::Attached,
&facts,
Some(exit),
);
}
if let Some(entry) = &entry {
entry.finish(exit);
}
tracing::info!(
%exec_id,
mode = ExecMode::Attached.name(),
exit_code = status,
reason = reason.name(),
"exec ended"
);
}
/// A tty or a detached `min://exec`, as [`start_and_answer`] starts it.
struct ManagedRequest {
exec_id: ExecId,
mode: ExecMode,
argv: Vec<String>,
timeout: Option<Duration>,
winsize: (u16, u16),
conn_username: String,
extra_env: BTreeMap<String, String>,
}
/// Starts a tty or a detached exec in the box and answers with its exec id
/// on stdout (BOX-149). The exec runs on after the channel closes.
async fn start_and_answer(session: BoxHandle, channel: Channel<Msg>, request: ManagedRequest) {
let ManagedRequest {
exec_id,
mode,
argv,
timeout,
winsize,
conn_username,
extra_env,
} = request;
let facts = ExecFacts {
principal: conn_username.clone(),
argv: argv.clone(),
};
let started = async {
let exec_box = ExecBox::of(&session).await?;
let host = session
.ensure_host(conn_username)
.await
.map_err(|e| io::Error::other(format!("{e}")))?;
let (program, args) = exec_argv(argv);
let command = host
.command_in_session_env(&program, &args, extra_env)
.await?;
start_managed_exec(
ManagedStart {
id: exec_id.clone(),
mode,
exec_box,
timeout,
winsize,
facts,
},
command,
true,
)
}
.await;
match started {
Ok(entry) => answer_exec(channel, format!("{}\n", entry.id).as_bytes(), b"", 0).await,
Err(error) => {
tracing::warn!(%exec_id, mode = mode.name(), %error, "exec: the command could not start");
let message = format!("the command could not start in the box: {error}\n");
answer_exec(channel, b"", message.as_bytes(), 1).await;
}
}
}
/// Accepts the channel and reports an exec request the daemon cannot serve on
/// the SSH stderr stream, then exits non-zero. A bare `channel_failure` would
/// reach the client only as an opaque "exec request failed", so — mirroring the
/// accept-then-report shape `run_check_exec` uses for a bad flag — this relays
/// the parse error, which already names the form asked for and lists the ones
/// this daemon serves. The command is still refused; nothing is spawned.
async fn reject_unsupported_exec(channel: Channel<Msg>, reason: String) {
let (_rs, ws) = channel.split();
let mut e = ws.make_writer_ext(Some(1));
let _ = e
.write_all(unsupported_command_message(&reason).as_bytes())
.await;
let _ = e.flush().await;
let _ = ws.eof().await;
let _ = ws.exit_status(1).await; // otherwise considered -1
let _ = ws.close().await; // needed to release the remote
}
/// The stderr copy for an exec request the daemon cannot serve. The reason
/// comes from [`minimald_rpc::exec::ExecParseError`], which already names the
/// form that was asked for and the ones this daemon serves.
fn unsupported_command_message(reason: &str) -> String {
format!("minimald: {reason}\n")
}
/// The tracing span an in-session exec runs under, mirroring the `rpc` span in
/// [`crate::rpc::handle_ssh_rpc`].
///
/// The client's propagated trace context is adopted — same trace id, fresh span
/// id, the client's span as parent — so one `trace_id` grep joins the CLI's log
/// with the daemon's. A missing or malformed value mints a fresh context:
/// propagation is a diagnostic aid and must never fail a request. The command
/// rides on the span, so every record the exec emits names what was asked for.
/// The exec span, and its context as a `TRACEPARENT` (what a box gets on
/// opt-in, so a `min` run inside joins this trace) — `None` unless the span
/// is actually recorded (see [`box_traceparent`]).
fn exec_span(
config: &ChannelConfig,
session_id: SessionId,
argv: &str,
) -> (tracing::Span, Option<String>) {
// Two callsites, not one span with a recorded field: the opted-out
// request's span never carries the command, not even in the file log's
// span fields, and the recorded one is what the exec-span tests read
// at creation.
let span = if minimald_rpc::trace::opted_out(&config.env_vars) {
tracing::info_span!(
"exec",
%session_id,
command = tracing::field::Empty,
exec_id = tracing::field::Empty,
exec_mode = tracing::field::Empty,
telemetry = OPT_OUT,
trace_id = tracing::field::Empty,
span_id = tracing::field::Empty,
parent_span_id = tracing::field::Empty,
)
} else {
tracing::info_span!(
"exec",
%session_id,
command = %scrub_secrets(argv),
exec_id = tracing::field::Empty,
exec_mode = tracing::field::Empty,
telemetry = tracing::field::Empty,
trace_id = tracing::field::Empty,
span_id = tracing::field::Empty,
parent_span_id = tracing::field::Empty,
)
};
let adopted = adopt_client_trace(&span, config);
let tp = box_traceparent(&adopted);
(span, tp)
}
/// The value of a request span's `telemetry` field when its client opted
/// out: the one mark the file log keeps of such a request (the span is
/// recorded nowhere else).
pub(crate) const OPT_OUT: &str = "opt-out";
/// A span's trace context, and whether that span is recorded by the export
/// (its ids are the exported span's ids).
pub(crate) struct AdoptedTrace {
ctx: minimald_rpc::trace::TraceContext,
/// False with export off, and with the export filter not admitting the
/// span (`MINIMAL_OTEL_FILTER=warn` against an info-level span): the ids
/// were minted for the file log only, and no exporter or spool ever sees
/// a span with them.
recorded: bool,
}
/// The `TRACEPARENT` a box may be given for `adopted`: only one that names a
/// recorded span. Under `MINIMAL_OTEL_FILTER=warn`
/// the daemon handed the box a `TRACEPARENT` whose span id was spooled and
/// exported nowhere, so a `min` run inside parented itself to an orphan. A
/// trace nobody can follow is worse than a fresh one: hand the box nothing.
pub(crate) fn box_traceparent(adopted: &AdoptedTrace) -> Option<String> {
adopted.recorded.then(|| adopted.ctx.traceparent())
}
/// Makes `span` a child of the client's `TRACEPARENT` (channel env) and
/// records its ids. With OTel export on and the span admitted, the exported
/// span's ids are the ids; otherwise adopt-or-mint exactly as before. The
/// span must declare the `trace_id`, `span_id` and `parent_span_id` fields.
pub(crate) fn adopt_client_trace(span: &tracing::Span, config: &ChannelConfig) -> AdoptedTrace {
use minimald_rpc::trace::{TRACEPARENT_ENV, TraceContext};
if minimald_rpc::trace::opted_out(&config.env_vars) {
return adopt_opt_out(span);
}
let client_ctx = config
.env_vars
.get(TRACEPARENT_ENV)
.and_then(|v| TraceContext::parse_traceparent(v));
adopt_trace(span, client_ctx)
}
/// The client opted out of telemetry (`MINIMAL_OTEL=off` on the channel,
/// or in a forward's originator field): make `span`, and every span under
/// it, non-recording ([`mlog::otel::opt_out`]), mark it `telemetry =
/// opt-out`, and give it ids for the file log only. Nothing is adopted: an
/// opted-out client sends no `TRACEPARENT`, and one that did would still
/// get no span in its trace. The result is never `recorded`, so the box
/// gets no `TRACEPARENT` either ([`box_traceparent`]). The span must
/// declare the `trace_id`, `span_id`, `parent_span_id` and `telemetry`
/// fields.
pub(crate) fn adopt_opt_out(span: &tracing::Span) -> AdoptedTrace {
use minimald_rpc::trace::TraceContext;
// `record` drops a field the span did not declare without a word, and
// the opt-out mark would be lost (the `git_receive`/`git_upload` spans
// once lacked it): fail loudly in tests instead.
debug_assert!(
span.metadata()
.is_none_or(|m| m.fields().field("telemetry").is_some()),
"span {:?} must declare `telemetry` to be opted out",
span.metadata().map(tracing::Metadata::name)
);
let ctx = mlog::otel::opt_out(span)
.map(|(t, s, f)| TraceContext::from_parts(t, s, f))
.unwrap_or_else(|| TraceContext::mint().unsampled());
span.record("telemetry", OPT_OUT);
span.record("trace_id", tracing::field::display(ctx.trace_id_hex()));
span.record("span_id", tracing::field::display(ctx.span_id_hex()));
// The mailbox messages sent from inside carry these unsampled ids, so
// the `*.message` spans they open are opted out too (`adopt_trace`
// aligns them under a flags-00 parent).
crate::traced::remember(span, ctx);
AdoptedTrace {
ctx,
recorded: false,
}
}
/// Makes `span` a child of `client_ctx` — the client's context however it
/// travelled (the channel env for session channels and RPCs, the open
/// request's originator field for a direct-tcpip forward) — and records its
/// ids. With OTel export on and the span admitted, the exported span's ids
/// are the ids; otherwise adopt-or-mint exactly as before. The span must
/// declare the `trace_id`, `span_id` and `parent_span_id` fields.
pub(crate) fn adopt_trace(
span: &tracing::Span,
client_ctx: Option<minimald_rpc::trace::TraceContext>,
) -> AdoptedTrace {
use minimald_rpc::trace::TraceContext;
let aligned = mlog::otel::align(span, client_ctx.as_ref().map(TraceContext::parts))
.map(|(t, s, f)| TraceContext::from_parts(t, s, f));
let recorded = aligned.is_some();
let ctx = aligned.unwrap_or_else(|| {
client_ctx
.as_ref()
.map(TraceContext::child)
.unwrap_or_else(TraceContext::mint)
});
span.record("trace_id", tracing::field::display(ctx.trace_id_hex()));
span.record("span_id", tracing::field::display(ctx.span_id_hex()));
if let Some(client_ctx) = &client_ctx {
span.record(
"parent_span_id",
tracing::field::display(client_ctx.span_id_hex()),
);
}
// For a mailbox message sent from inside this span (or anything it
// encloses) to carry these ids: see `traced::caller_context`.
crate::traced::remember(span, ctx);
AdoptedTrace { ctx, recorded }
}
#[cfg(test)]
mod box_traceparent_tests {
use super::{AdoptedTrace, box_traceparent};
/// A box gets a `TRACEPARENT` only for a recorded span: with export off,
/// or the export filter not admitting the exec span, the context exists
/// (the file log uses it) but names a span no exporter or spool sees.
#[test]
fn an_unrecorded_exec_span_gives_the_box_no_traceparent() {
let ctx = minimald_rpc::trace::TraceContext::mint();
assert_eq!(
box_traceparent(&AdoptedTrace {
ctx,
recorded: false
}),
None
);
assert_eq!(
box_traceparent(&AdoptedTrace {
ctx,
recorded: true
}),
Some(ctx.traceparent())
);
}
/// Without an exporter installed (this test process), `align` admits
/// nothing, so the adopted trace is never marked recorded.
#[test]
fn without_an_exporter_nothing_is_recorded() {
assert!(!mlog::otel::exporting());
let span = tracing::info_span!("exec");
assert!(mlog::otel::align(&span, None).is_none());
}
}
#[cfg(test)]
pub(crate) mod testing {
//! Mock `Process` for testing the exec bridge without spawning a
//! real subprocess. The test side holds a [`MockController`] for
//! driving exit and observing `start_kill`, plus duplex endpoints
//! mirroring each stdio stream.
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use futures::stream::{self, BoxStream, StreamExt};
use tokio::io::{DuplexStream, duplex};
use tokio::sync::{Mutex, Notify};
use super::Process;
/// Stdio buffer size. Chosen well above the bridge's 8 KiB read
/// buffer so a single test write never blocks on backpressure.
const PIPE_CAPACITY: usize = 64 * 1024;
#[derive(Default)]
struct MockInner {
exit: Mutex<Option<i32>>,
notify: Notify,
kill_requested: AtomicBool,
exit_on_kill: Mutex<Option<i32>>,
}
/// Test-side handle for driving and observing a [`MockProcess`].
/// Cheaply cloneable — both sides share the same `Arc`.
#[derive(Clone, Default)]
pub struct MockController {
inner: Arc<MockInner>,
}
impl MockController {
/// Signal that the mock process has exited with this code. Wakes
/// any pending `wait` future.
pub async fn signal_exit(&self, code: i32) {
*self.inner.exit.lock().await = Some(code);
// notify_one stores a permit if no waiter is parked yet,
// which sidesteps the "set exit before bridge polls wait"
// race that would otherwise leave the bridge hanging.
self.inner.notify.notify_one();
}
/// Set the code the mock process reports once `start_kill` is
/// called. Without it a killed mock reports no numeric code.
pub async fn exit_on_kill(&self, code: i32) {
*self.inner.exit_on_kill.lock().await = Some(code);
}
/// Whether the bridge has called `start_kill` on the process.
pub fn was_killed(&self) -> bool {
self.inner.kill_requested.load(Ordering::SeqCst)
}
}
/// Test-side endpoints — counterparts to the streams the bridge
/// owns after `take_stdio`.
pub struct MockEndpoints {
/// Reads bytes the bridge wrote to "child stdin".
pub stdin_reader: DuplexStream,
/// Writes bytes the bridge will read as "child stdout".
pub stdout_writer: DuplexStream,
/// Writes bytes the bridge will read as "child stderr".