#![cfg_attr(test, allow(clippy::unwrap_used))]
#![forbid(unsafe_code)]
#![cfg_attr(
test,
allow(
clippy::disallowed_methods,
clippy::disallowed_types,
reason = "tests spawn, join and drain freely; production sites carry their own expectation"
)
)]
use std::{collections::BTreeMap, sync::Arc, time::Duration};
use serde_json::Value;
mod ast;
mod builtins;
mod dispatch;
mod interp;
mod job;
pub use job::{
JOBS_OFF, JobControl, JobId, JobOutcome, JobRefusal, JobSeed, JobState, JobSummary, JobWait,
};
mod jq_worker;
mod lexer;
pub use jq_worker::{run_jq_worker_if_requested, set_jq_worker_executable};
pub mod limits;
mod parser;
mod pipe;
mod proposal;
pub use proposal::{CommandProposal, CommandReport, CommandReportOutcome};
pub mod value;
use dekopon_process::{CallBudget, Limits, TreeContext};
use dekopon_core::{ProviderFailureDetail, SecretUseProposal};
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct CapabilityDescription {
pub capability: String,
pub description: String,
}
#[derive(Debug)]
pub struct Streams {
pub stdin: Option<std::os::fd::OwnedFd>,
pub stdout: std::os::fd::OwnedFd,
}
impl Streams {
#[must_use]
pub fn reply(self, value: &Value) -> CapabilityCallResult {
use std::io::Write;
if value.is_null() {
return CapabilityCallResult::Succeeded;
}
let mut stdout = std::os::unix::net::UnixStream::from(self.stdout);
match writeln!(stdout, "{}", value::display(value)) {
Ok(()) => CapabilityCallResult::Succeeded,
Err(_closed) => CapabilityCallResult::Exited {
status: std::num::NonZeroU8::new(141).unwrap_or(std::num::NonZeroU8::MIN),
stderr: String::new(),
},
}
}
}
#[derive(Clone, Debug, PartialEq)]
pub enum CapabilityCallResult {
Succeeded,
SucceededWithStderr(String),
Exited {
status: std::num::NonZeroU8,
stderr: String,
},
Denied {
reason: String,
},
Failed {
error: String,
detail: Option<ProviderFailureDetail>,
},
NotFound,
}
#[derive(Debug)]
pub enum CommandRun {
Proposed {
capability: String,
input: Value,
secret_use: Option<SecretUseProposal>,
report: Option<CommandReport>,
},
Rendered {
stdout: String,
stderr: String,
status: u8,
},
Failed {
message: String,
},
Errored {
message: String,
},
Denied {
reason: String,
},
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Arg {
Text(String),
Asset(dekopon_core::AssetNumber),
}
impl std::fmt::Display for Arg {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Text(text) => formatter.write_str(text),
Self::Asset(number) => number.fmt(formatter),
}
}
}
pub struct RunCall {
pub word: String,
pub argv: Vec<Arg>,
}
pub enum RunResult {
Invoked {
capability: String,
input: Value,
secret_use: Option<SecretUseProposal>,
result: CapabilityCallResult,
},
Returned(CapabilityCallResult),
Uncertain(CapabilityCallResult),
}
pub fn render_command(streams: Streams, stdout: &str, stderr: String, status: u8) -> RunResult {
use std::io::Write as _;
let mut output = std::os::unix::net::UnixStream::from(streams.stdout);
if let Err(error) = output.write_all(stdout.as_bytes()) {
tracing::warn!(
event = "shell_command_stdout_failed",
error.kind = ?error.kind(),
errno = error.raw_os_error(),
"shell.command_stdout.failed"
);
return RunResult::Returned(CapabilityCallResult::Failed {
error: "command stdout could not be written".to_owned(),
detail: None,
});
}
RunResult::Returned(match std::num::NonZeroU8::new(status) {
Some(status) => CapabilityCallResult::Exited { status, stderr },
None if stderr.is_empty() => CapabilityCallResult::Succeeded,
None => CapabilityCallResult::SucceededWithStderr(stderr),
})
}
pub fn run_parsed<I: CapabilityInvoker + ?Sized>(
invoker: &I,
call: RunCall,
parsed: Option<CommandRun>,
streams: Streams,
tree: &TreeContext,
) -> RunResult {
match parsed {
Some(CommandRun::Proposed {
capability,
input,
secret_use,
report,
}) => {
if !invoker.is_granted(&capability) {
return render_command(
streams,
"",
format!(
"dekopon-shell: {}: requires capability {}, which is not granted in this session\n",
call.word, capability
),
127,
);
}
let mut proposal =
CommandProposal::new(capability.clone(), input.clone(), secret_use.clone());
proposal.report = report;
let result = invoker.invoke(proposal, streams, tree);
RunResult::Invoked {
capability,
input,
secret_use,
result,
}
}
Some(CommandRun::Rendered {
stdout,
stderr,
status,
}) => render_command(streams, &stdout, stderr, status),
Some(CommandRun::Failed { message }) => render_command(streams, "", message, 2),
Some(CommandRun::Errored { message }) => {
RunResult::Returned(CapabilityCallResult::Failed {
error: message,
detail: None,
})
}
Some(CommandRun::Denied { reason }) => {
RunResult::Returned(CapabilityCallResult::Denied { reason })
}
None => render_command(
streams,
"",
format!("dekopon-shell: {}: command not found\n", call.word),
127,
),
}
}
pub trait CapabilityInvoker: Send + Sync {
fn cancel_signals(&self) -> Vec<dekopon_process::CancelSignal> {
Vec::new()
}
fn granted(&self) -> Vec<String>;
fn is_granted(&self, capability: &str) -> bool {
self.granted().iter().any(|granted| granted == capability)
}
fn command_words(&self) -> Vec<String> {
Vec::new()
}
fn command_word_help(&self) -> BTreeMap<String, String> {
BTreeMap::new()
}
fn has_command_word(&self, word: &str) -> bool {
self.command_words()
.iter()
.any(|candidate| candidate == word)
}
fn run_command(&self, word: &str, argv: &[String], stdin_piped: bool) -> Option<CommandRun> {
let _ = (word, argv, stdin_piped);
None
}
fn run(&self, call: RunCall, streams: Streams, tree: &TreeContext) -> RunResult {
let argv = call
.argv
.iter()
.map(ToString::to_string)
.collect::<Vec<_>>();
let parsed = self.run_command(&call.word, &argv, streams.stdin.is_some());
run_parsed(self, call, parsed, streams, tree)
}
fn describe(&self, capability: &str) -> Option<CapabilityDescription> {
let _ = capability;
None
}
fn note(&self, text: &str, eta: Option<Duration>) {
let _ = (text, eta);
}
fn script_started(&self, _tree: &mut TreeContext) {}
fn script_finished(&self) {}
fn job_control(&self) -> Option<&dyn JobControl> {
None
}
fn invoke(
&self,
proposal: CommandProposal,
streams: Streams,
tree: &TreeContext,
) -> CapabilityCallResult;
}
#[must_use]
pub fn secret_use_unsupported() -> CapabilityCallResult {
CapabilityCallResult::Denied {
reason: "secret references require a broker-backed capability".to_owned(),
}
}
impl<T: CapabilityInvoker + ?Sized> CapabilityInvoker for Arc<T> {
fn cancel_signals(&self) -> Vec<dekopon_process::CancelSignal> {
self.as_ref().cancel_signals()
}
fn granted(&self) -> Vec<String> {
self.as_ref().granted()
}
fn is_granted(&self, capability: &str) -> bool {
self.as_ref().is_granted(capability)
}
fn command_words(&self) -> Vec<String> {
self.as_ref().command_words()
}
fn command_word_help(&self) -> BTreeMap<String, String> {
self.as_ref().command_word_help()
}
fn has_command_word(&self, word: &str) -> bool {
self.as_ref().has_command_word(word)
}
fn run_command(&self, word: &str, argv: &[String], stdin_piped: bool) -> Option<CommandRun> {
self.as_ref().run_command(word, argv, stdin_piped)
}
fn run(&self, call: RunCall, streams: Streams, tree: &TreeContext) -> RunResult {
self.as_ref().run(call, streams, tree)
}
fn describe(&self, capability: &str) -> Option<CapabilityDescription> {
self.as_ref().describe(capability)
}
fn note(&self, text: &str, eta: Option<Duration>) {
self.as_ref().note(text, eta);
}
fn script_started(&self, tree: &mut TreeContext) {
self.as_ref().script_started(tree);
}
fn script_finished(&self) {
self.as_ref().script_finished();
}
fn job_control(&self) -> Option<&dyn JobControl> {
self.as_ref().job_control()
}
fn invoke(
&self,
proposal: CommandProposal,
streams: Streams,
tree: &TreeContext,
) -> CapabilityCallResult {
self.as_ref().invoke(proposal, streams, tree)
}
}
#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
pub struct ExitCode(u8);
impl ExitCode {
pub const SUCCESS: Self = Self(0);
pub const FAILURE: Self = Self(1);
pub const SYNTAX: Self = Self(2);
pub const TIMEOUT: Self = Self(124);
pub const CANCELLED: Self = Self(130);
pub const DENIED: Self = Self(126);
pub const NOT_FOUND: Self = Self(127);
#[must_use]
pub fn from_script_exit(status: i64) -> Self {
Self(u8::try_from(status.rem_euclid(256)).unwrap_or(0))
}
#[must_use]
pub const fn get(self) -> u8 {
self.0
}
#[must_use]
pub const fn from_capability_result(result: &CapabilityCallResult) -> Self {
match result {
CapabilityCallResult::Succeeded | CapabilityCallResult::SucceededWithStderr(_) => {
Self::SUCCESS
}
CapabilityCallResult::Exited { status, .. } => Self(status.get()),
CapabilityCallResult::Failed { .. } => Self::FAILURE,
CapabilityCallResult::Denied { .. } => Self::DENIED,
CapabilityCallResult::NotFound => Self::NOT_FOUND,
}
}
}
impl From<ExitCode> for u8 {
fn from(code: ExitCode) -> Self {
code.0
}
}
impl From<u8> for ExitCode {
fn from(code: u8) -> Self {
Self(code)
}
}
impl std::fmt::Display for ExitCode {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(formatter, "{}", self.0)
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ScriptOutcome {
pub output: String,
pub exit_code: ExitCode,
pub truncated: bool,
pub capability_calls: u32,
pub steps: u64,
}
#[derive(Debug)]
pub struct ChildStdin(pipe::PipeReader);
impl ChildStdin {
pub fn adopt(socket: std::os::unix::net::UnixStream) -> std::io::Result<Self> {
pipe::PipeReader::from_socket(socket).map(Self)
}
}
#[derive(Clone, Debug, Default)]
pub struct Interpreter {
limits: Limits,
}
impl Interpreter {
#[must_use]
pub fn new(limits: Limits) -> Self {
Self { limits }
}
#[must_use]
pub fn limits(&self) -> Limits {
self.limits
}
pub fn run(&self, script: &str, invoker: &dyn CapabilityInvoker) -> ScriptOutcome {
self.run_with_tree(
script,
invoker,
&TreeContext::new(
self.limits,
CallBudget::new(self.limits.max_capability_calls),
)
.with_cancel(invoker.cancel_signals()),
)
}
pub fn run_with_tree(
&self,
script: &str,
invoker: &dyn CapabilityInvoker,
tree: &TreeContext,
) -> ScriptOutcome {
interp::run_with_tree(script, None, None, invoker, self.limits, tree)
}
pub fn run_child(
&self,
script: &str,
stdin: Option<ChildStdin>,
invoker: &dyn CapabilityInvoker,
tree: &TreeContext,
) -> ScriptOutcome {
let stdin = stdin.map(|ChildStdin(reader)| reader);
interp::run_with_tree(script, None, stdin, invoker, self.limits, tree)
}
pub fn run_seed(
&self,
seed: JobSeed,
invoker: &dyn CapabilityInvoker,
tree: &TreeContext,
) -> ScriptOutcome {
interp::run_seed(seed, invoker, self.limits, tree)
}
pub fn run_with_prev(
&self,
script: &str,
prev: &str,
invoker: &dyn CapabilityInvoker,
) -> ScriptOutcome {
interp::run(script, Some(prev), invoker, self.limits)
}
}
pub fn run(script: &str, invoker: &dyn CapabilityInvoker) -> ScriptOutcome {
Interpreter::new(Limits::default()).run(script, invoker)
}
#[cfg(test)]
mod tests {
use parking_lot::Mutex;
use std::{
collections::BTreeMap,
sync::{
Arc,
atomic::{AtomicU32, Ordering},
},
time::{Duration, Instant},
};
use dekopon_core::{SecretDrn, SecretUseProposal};
use serde_json::{Value, json};
use super::{
CapabilityCallResult, CapabilityDescription, CapabilityInvoker, CommandRun, ExitCode,
Interpreter,
};
use dekopon_process::{CallBudget, Limits, TreeContext};
#[derive(Default)]
struct RecordingInvoker {
secret_uses: Mutex<Vec<Option<SecretUseProposal>>>,
scripts_finished: AtomicU32,
tree: Option<TreeContext>,
retained: Mutex<Vec<u64>>,
}
impl CapabilityInvoker for RecordingInvoker {
fn granted(&self) -> Vec<String> {
vec!["cli-probe.upper".to_owned()]
}
fn is_granted(&self, capability: &str) -> bool {
capability == "gh.pr-view" || capability == "gh-extra"
}
fn command_words(&self) -> Vec<String> {
vec!["gh".to_owned()]
}
fn command_word_help(&self) -> BTreeMap<String, String> {
BTreeMap::from([("gh".to_owned(), "gh: recorded help".to_owned())])
}
fn has_command_word(&self, word: &str) -> bool {
matches!(word, "gh-extra" | "retained" | "render")
}
fn run_command(
&self,
word: &str,
argv: &[String],
stdin_piped: bool,
) -> Option<CommandRun> {
if matches!(word, "retained" | "render") {
let stdout = if word == "retained" {
self.retained.lock().push(self.tree.as_ref()?.value_bytes());
String::new()
} else {
"abcdefgh".to_owned()
};
return Some(CommandRun::Rendered {
stdout,
stderr: String::new(),
status: 0,
});
}
Some(CommandRun::Proposed {
capability: word.to_owned(),
input: json!({ "argv": argv, "stdin": stdin_piped.then_some("") }),
secret_use: None,
report: None,
})
}
fn describe(&self, capability: &str) -> Option<CapabilityDescription> {
Some(CapabilityDescription {
capability: capability.to_owned(),
description: "recorded".to_owned(),
})
}
fn invoke(
&self,
proposal: super::CommandProposal,
streams: super::Streams,
_tree: &dekopon_process::TreeContext,
) -> CapabilityCallResult {
let input = proposal.input;
let secret_use = proposal.secret_use;
self.secret_uses.lock().push(secret_use);
streams.reply(&input)
}
fn script_finished(&self) {
self.scripts_finished.fetch_add(1, Ordering::Relaxed);
}
}
struct Cancellation(dekopon_process::CancelSignal);
impl CapabilityInvoker for Cancellation {
fn cancel_signals(&self) -> Vec<dekopon_process::CancelSignal> {
vec![self.0.clone()]
}
fn granted(&self) -> Vec<String> {
Vec::new()
}
fn invoke(
&self,
_: super::CommandProposal,
_streams: super::Streams,
_tree: &dekopon_process::TreeContext,
) -> CapabilityCallResult {
CapabilityCallResult::NotFound
}
}
#[test]
fn a_cancelled_loop_stops_before_exhausting_steps() {
let (handle, cancelled) = dekopon_process::CancelSignal::pair();
handle.cancel();
let limits = Limits {
max_steps: 100_000,
..Limits::default()
};
let outcome =
Interpreter::new(limits).run("while true; do :; done", &Cancellation(cancelled));
assert_eq!(outcome.exit_code, ExitCode::CANCELLED);
assert_eq!(
super::interp::telemetry::fatal_outcome(&super::builtins::FatalError::Limit(
dekopon_process::LimitExceeded::Cancelled
)),
"cancelled"
);
assert!(outcome.steps < 100);
}
#[test]
fn run_with_prev_refuses_an_already_cancelled_invoker() {
let (handle, signal) = dekopon_process::CancelSignal::pair();
handle.cancel();
let outcome =
Interpreter::new(Limits::default()).run_with_prev("echo ok", "", &Cancellation(signal));
assert_eq!(outcome.exit_code, ExitCode::CANCELLED);
}
#[test]
fn a_sleep_wakes_for_cancellation_without_waiting_for_the_deadline() {
let (flip, cancelled) = dekopon_process::CancelSignal::pair();
let worker = std::thread::spawn(move || {
std::thread::sleep(Duration::from_millis(200));
flip.cancel();
});
let start = Instant::now();
let outcome = Interpreter::new(Limits {
timeout: Duration::from_secs(310),
..Limits::default()
})
.run("sleep 300", &Cancellation(cancelled));
worker.join().expect("cancel worker");
assert_eq!(outcome.exit_code, ExitCode::CANCELLED);
assert!(start.elapsed() < Duration::from_millis(1500));
}
#[test]
fn interpreters_in_one_tree_share_calls_and_deadline() {
let limits = Limits {
timeout: Duration::from_millis(80),
max_capability_calls: 1,
..Limits::default()
};
let tree = TreeContext::new(limits, CallBudget::new(1));
let invoker = RecordingInvoker::default();
let interpreter = Interpreter::new(limits);
assert_eq!(
interpreter
.run_with_tree("gh-extra one", &invoker, &tree)
.capability_calls,
1
);
let second_interpreter = Interpreter::new(limits);
let second = second_interpreter.run_with_tree("gh-extra two", &invoker, &tree);
assert_eq!(second.exit_code, ExitCode::SYNTAX);
assert_eq!(tree.calls().used(), 1);
std::thread::sleep(Duration::from_millis(100));
assert_eq!(
second_interpreter
.run_with_tree("echo late", &invoker, &tree)
.exit_code,
ExitCode::TIMEOUT
);
}
#[test]
fn replacements_and_scope_drops_refund_retained_bytes() {
let limits = Limits {
max_value_bytes: 128,
..Limits::default()
};
let tree = TreeContext::new(limits, CallBudget::new(1));
let script = "f() { local y=abcdefgh; }; x=abcdefgh; ".to_owned()
+ &"x=ijklmnop; f; echo abcdefgh > buf; ".repeat(20);
let outcome =
Interpreter::new(limits).run_with_tree(&script, &RecordingInvoker::default(), &tree);
assert_eq!(outcome.exit_code, ExitCode::SUCCESS, "{}", outcome.output);
assert_eq!(tree.value_bytes(), 0);
}
#[test]
fn substitution_arguments_keep_their_charges_until_the_command_finishes() {
let invoker = RecordingInvoker::default();
let limits = Limits {
max_value_bytes: 96,
..Limits::default()
};
let tree = TreeContext::new(limits, CallBudget::new(4));
let word = "\"$(printf 12345678901234567890123456789012)\"";
let interpreter = Interpreter::new(limits);
let failed = interpreter.run_with_tree(&format!("gh-extra {word} {word}"), &invoker, &tree);
assert_eq!(failed.exit_code, ExitCode::SYNTAX, "{}", failed.output);
assert!(invoker.secret_uses.lock().is_empty());
assert_eq!(tree.value_bytes(), 0);
let script = format!("gh-extra {word} > /dev/null; gh-extra {word} > /dev/null");
assert_eq!(tree.value_bytes(), 0);
let next = interpreter.run_with_tree(&script, &invoker, &tree);
assert_eq!(next.exit_code, ExitCode::SUCCESS, "{}", next.output);
assert_eq!(tree.value_bytes(), 0);
}
#[test]
fn substitution_refunds_trailing_line_feeds_before_the_next_capture() {
let limits = Limits {
max_value_bytes: 128,
..Limits::default()
};
let tree = TreeContext::new(limits, CallBudget::new(1));
let invoker = RecordingInvoker {
tree: Some(tree.clone()),
..RecordingInvoker::default()
};
let outcome = Interpreter::new(limits).run_with_tree(
"v=$(printf 'x\\n\\n'); retained; w=$(printf 12345678); retained",
&invoker,
&tree,
);
assert_eq!(outcome.exit_code, ExitCode::SUCCESS, "{outcome:?}");
assert_eq!(*invoker.retained.lock(), vec![49, 73]);
assert_eq!(tree.value_bytes(), 0);
}
#[test]
fn local_assignment_in_a_snapshot_does_not_copy_uncharged_globals() {
let limits = Limits {
max_value_bytes: 2 * 1024 * 1024 + 96 * 1024,
..Limits::default()
};
let tree = TreeContext::new(limits, CallBudget::new(1));
let script = format!(
"big={}; f() {{ local n=0; n=1 sleep 1 | cat; }}; f",
"x".repeat(64 * 1024)
);
let outcome =
Interpreter::new(limits).run_with_tree(&script, &RecordingInvoker::default(), &tree);
assert_eq!(outcome.exit_code, ExitCode::SUCCESS, "{outcome:?}");
assert_eq!(tree.value_bytes(), 0);
}
#[test]
fn four_kib_value_headroom_is_enforced_and_streaming_bytes_are_not_retained() {
let limits = Limits {
max_value_bytes: 2 * 1024 * 1024 + 4096,
..Limits::default()
};
let tree = TreeContext::new(limits, CallBudget::new(1));
let interpreter = Interpreter::new(limits);
let invoker = RecordingInvoker::default();
for script in [
"v=$(while true; do printf xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx; done | cat)",
"while true; do printf xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx; done | sort",
"while true; do printf xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx; done | tail -n 200",
] {
let outcome = interpreter.run_with_tree(script, &invoker, &tree);
assert_ne!(
outcome.exit_code,
ExitCode::SUCCESS,
"{script}: {outcome:?}"
);
assert!(
outcome.output.contains("bytes of values"),
"{script}: {outcome:?}"
);
assert_eq!(tree.value_bytes(), 0, "{script}");
}
let streaming_limits = Limits {
max_value_bytes: 2 * 2 * 1024 * 1024 + 4096,
..limits
};
let streaming_tree = TreeContext::new(streaming_limits, CallBudget::new(1));
let script = format!("printf '{}' | cat | wc -c", "x".repeat(1024 * 1024));
let streamed =
Interpreter::new(streaming_limits).run_with_tree(&script, &invoker, &streaming_tree);
assert_eq!(streamed.exit_code, ExitCode::SUCCESS, "{streamed:?}");
assert_eq!(streamed.output, "1048576");
assert_eq!(streaming_tree.value_bytes(), 0);
}
#[test]
fn redirect_keeps_source_charge_while_copying_to_a_buffer() {
let limits = Limits {
max_value_bytes: 15,
..Limits::default()
};
let tree = TreeContext::new(limits, CallBudget::new(1));
let invoker = RecordingInvoker {
tree: Some(tree.clone()),
..RecordingInvoker::default()
};
let outcome = Interpreter::new(limits).run_with_tree("render > buf", &invoker, &tree);
assert_ne!(outcome.exit_code, ExitCode::SUCCESS, "{outcome:?}");
assert!(outcome.output.contains("bytes of values"), "{outcome:?}");
assert_eq!(tree.value_bytes(), 0);
}
#[test]
fn storage_adopts_moved_charges_and_refunds_unset_and_replacement() {
for (maximum, script, expected) in [
(
128,
"x=$(printf abcdefgh); retained; x=a; retained; unset x; retained",
vec![56, 49, 32],
),
(
128,
"printf abcdefgh > buf; retained; : > buf; retained; render >> buf; retained; : > buf; retained",
vec![40, 32, 40, 32],
),
(
128,
"render > buf; retained; render >> buf; retained; : > buf; retained",
vec![40, 48, 32],
),
(
128,
"cat <<EOF\n$(printf abcdefgh)\nEOF\nretained",
vec![32],
),
] {
let limits = Limits {
max_value_bytes: maximum,
..Limits::default()
};
let tree = TreeContext::new(limits, CallBudget::new(1));
let invoker = RecordingInvoker {
tree: Some(tree.clone()),
..RecordingInvoker::default()
};
let outcome = Interpreter::new(limits).run_with_tree(script, &invoker, &tree);
assert_eq!(outcome.exit_code, ExitCode::SUCCESS, "{}", outcome.output);
assert_eq!(*invoker.retained.lock(), expected, "{script}");
assert_eq!(tree.value_bytes(), 0);
}
}
fn streams() -> (super::Streams, std::os::unix::net::UnixStream) {
let (stdout, reader) = std::os::unix::net::UnixStream::pair().expect("socketpair");
let streams = super::Streams {
stdin: None,
stdout: stdout.into(),
};
(streams, reader)
}
fn proposal() -> SecretUseProposal {
SecretUseProposal::HttpBearer {
secret: "drn:com.xrl:secret:prod:api/token"
.parse::<SecretDrn>()
.expect("canonical DRN"),
}
}
#[test]
fn an_arc_hands_a_secret_use_proposal_to_the_invoker_behind_it_unchanged() {
let inner = Arc::new(RecordingInvoker::default());
let shared: Arc<dyn CapabilityInvoker> = Arc::clone(&inner) as Arc<dyn CapabilityInvoker>;
assert_eq!(
shared.invoke(
super::CommandProposal::new("http-probe.fetch", json!({"url": "https://x"}), None),
streams().0,
&dekopon_process::TreeContext::new(
dekopon_process::Limits::default(),
dekopon_process::CallBudget::new(64)
)
),
CapabilityCallResult::Succeeded
);
assert_eq!(
shared.invoke(
super::CommandProposal::new("http-probe.fetch", json!({}), Some(proposal())),
streams().0,
&dekopon_process::TreeContext::new(
dekopon_process::Limits::default(),
dekopon_process::CallBudget::new(64)
)
),
CapabilityCallResult::Succeeded
);
assert_eq!(
*inner.secret_uses.lock(),
vec![None, Some(proposal())],
"the pointer altered a proposal on its way to the invoker behind it"
);
}
#[test]
fn an_arc_forwards_the_defaulted_methods_instead_of_inheriting_their_defaults() {
let inner = Arc::new(RecordingInvoker::default());
let shared: Arc<dyn CapabilityInvoker> = Arc::clone(&inner) as Arc<dyn CapabilityInvoker>;
shared.script_finished();
assert_eq!(inner.scripts_finished.load(Ordering::Relaxed), 1);
assert_eq!(shared.granted(), vec!["cli-probe.upper".to_owned()]);
assert!(shared.is_granted("gh.pr-view"));
assert_eq!(shared.command_words(), vec!["gh".to_owned()]);
assert_eq!(
shared.command_word_help(),
BTreeMap::from([("gh".to_owned(), "gh: recorded help".to_owned())])
);
assert!(shared.has_command_word("gh-extra"));
let Some(CommandRun::Proposed {
capability,
input,
secret_use,
report,
}) = shared.run_command("gh", &["pr".to_owned()], true)
else {
panic!("expected proposal")
};
assert_eq!(capability, "gh");
assert_eq!(input, json!({"argv": ["pr"], "stdin": ""}));
assert!(secret_use.is_none());
assert!(report.is_none());
assert_eq!(
shared.describe("gh.pr-view").map(|it| it.description),
Some("recorded".to_owned())
);
}
struct ProposingInvoker {
secret_use: Option<SecretUseProposal>,
invocations: Mutex<Vec<(String, Value, Option<SecretUseProposal>)>>,
}
impl ProposingInvoker {
fn proposing(secret_use: Option<SecretUseProposal>) -> Self {
Self {
secret_use,
invocations: Mutex::new(Vec::new()),
}
}
}
impl CapabilityInvoker for ProposingInvoker {
fn granted(&self) -> Vec<String> {
vec!["http-probe.fetch".to_owned()]
}
fn command_words(&self) -> Vec<String> {
vec!["httpprobe".to_owned()]
}
fn run_command(
&self,
word: &str,
argv: &[String],
stdin_piped: bool,
) -> Option<CommandRun> {
(word == "httpprobe").then(|| CommandRun::Proposed {
capability: "http-probe.fetch".to_owned(),
input: json!({ "argv": argv, "stdin": stdin_piped.then_some("") }),
secret_use: self.secret_use.clone(),
report: None,
})
}
fn invoke(
&self,
proposal: super::CommandProposal,
streams: super::Streams,
_tree: &dekopon_process::TreeContext,
) -> CapabilityCallResult {
let capability = proposal.capability;
let input = proposal.input;
let secret_use = proposal.secret_use;
self.invocations
.lock()
.push((capability.to_owned(), input, secret_use));
streams.reply(&json!({"status": 200}))
}
}
#[test]
fn a_provider_proposal_hands_its_secret_use_to_invoke() {
for secret_use in [Some(proposal()), None] {
let invoker = ProposingInvoker::proposing(secret_use.clone());
let outcome = Interpreter::new(Limits::default())
.run("httpprobe fetch --url https://x", &invoker);
assert_eq!(outcome.exit_code, ExitCode::SUCCESS, "{}", outcome.output);
assert_eq!(outcome.output, r#"{"status":200}"#);
assert_eq!(outcome.capability_calls, 1);
assert_eq!(
*invoker.invocations.lock(),
vec![(
"http-probe.fetch".to_owned(),
json!({"argv": ["fetch", "--url", "https://x"], "stdin": null}),
secret_use,
)],
"the proposal's secret use did not reach invoke unchanged"
);
}
}
struct ChildInputInvoker {
seen: Mutex<Vec<bool>>,
read: bool,
}
impl CapabilityInvoker for ChildInputInvoker {
fn granted(&self) -> Vec<String> {
vec!["http-probe.fetch".to_owned()]
}
fn command_words(&self) -> Vec<String> {
vec!["httpprobe".to_owned()]
}
fn run_command(
&self,
word: &str,
_argv: &[String],
stdin_piped: bool,
) -> Option<CommandRun> {
self.seen.lock().push(stdin_piped);
(word == "httpprobe").then(|| CommandRun::Proposed {
capability: "http-probe.fetch".to_owned(),
input: serde_json::Value::Null,
secret_use: None,
report: None,
})
}
fn invoke(
&self,
_proposal: super::CommandProposal,
streams: super::Streams,
_tree: &dekopon_process::TreeContext,
) -> CapabilityCallResult {
if self.read {
let Some(fd) = streams.stdin else {
panic!("provider must receive its script stdin");
};
let mut stdin = std::os::unix::net::UnixStream::from(fd);
use std::io::Read as _;
let mut bytes = [0; 64];
let _ = stdin.read(&mut bytes).expect("provider reads stdin");
}
CapabilityCallResult::Succeeded
}
}
fn child_with_input(
script: &str,
invoker: &ChildInputInvoker,
input: &[u8],
) -> super::ScriptOutcome {
use std::io::Write as _;
let (read, mut write) = std::os::unix::net::UnixStream::pair().expect("script stdin");
let stdin = super::ChildStdin::adopt(read).expect("child adopts stdin");
write.write_all(input).expect("input bytes");
drop(write);
let limits = Limits::default();
Interpreter::new(limits).run_child(
script,
Some(stdin),
invoker,
&TreeContext::new(limits, CallBudget::new(16)),
)
}
#[test]
fn compound_and_function_pipes_do_not_pass_input_to_inner_provider() {
let invoker = ChildInputInvoker {
seen: Mutex::new(Vec::new()),
read: false,
};
let output = child_with_input(
"f() { httpprobe; }; printf pipe | f; printf pipe | { httpprobe; }",
&invoker,
b"script input",
);
assert_eq!(output.exit_code, ExitCode::SUCCESS, "{}", output.output);
assert_eq!(*invoker.seen.lock(), [false, false]);
}
#[test]
fn sequential_provider_then_read_share_script_stdin() {
let invoker = ChildInputInvoker {
seen: Mutex::new(Vec::new()),
read: true,
};
let output = child_with_input("httpprobe; read x; echo done", &invoker, b"first\nsecond\n");
assert_eq!(output.exit_code, ExitCode::SUCCESS, "{}", output.output);
assert_eq!(*invoker.seen.lock(), [true]);
}
#[test]
fn provider_that_never_reads_idle_script_stdin_returns_promptly() {
let invoker = ChildInputInvoker {
seen: Mutex::new(Vec::new()),
read: false,
};
let (reader, _writer) = std::os::unix::net::UnixStream::pair().expect("idle stdin");
let limits = Limits::default();
let start = std::time::Instant::now();
let outcome = Interpreter::new(limits).run_child(
"httpprobe",
Some(super::ChildStdin::adopt(reader).expect("child adopts stdin")),
&invoker,
&TreeContext::new(limits, CallBudget::new(16)),
);
assert_eq!(outcome.exit_code, ExitCode::SUCCESS, "{}", outcome.output);
assert!(start.elapsed() < std::time::Duration::from_millis(1500));
assert_eq!(*invoker.seen.lock(), [true]);
}
struct PanickingInputInvoker {
stop: dekopon_process::CancelSignal,
}
impl CapabilityInvoker for PanickingInputInvoker {
fn cancel_signals(&self) -> Vec<dekopon_process::CancelSignal> {
vec![self.stop.clone()]
}
fn granted(&self) -> Vec<String> {
vec!["http-probe.fetch".to_owned()]
}
fn command_words(&self) -> Vec<String> {
vec!["httpprobe".to_owned()]
}
fn run_command(
&self,
word: &str,
_argv: &[String],
stdin_piped: bool,
) -> Option<CommandRun> {
assert!(stdin_piped, "child stage inherits script stdin");
(word == "httpprobe").then(|| CommandRun::Proposed {
capability: "http-probe.fetch".to_owned(),
input: serde_json::Value::Null,
secret_use: None,
report: None,
})
}
fn invoke(
&self,
_proposal: super::CommandProposal,
_streams: super::Streams,
_tree: &dekopon_process::TreeContext,
) -> CapabilityCallResult {
panic!("the provider panicked with idle inherited stdin")
}
}
#[test]
fn panicking_provider_with_idle_inherited_stdin_releases_the_feeder() {
let (stop, stop_for_worker) = dekopon_process::CancelSignal::pair();
let (read, _idle_writer) = std::os::unix::net::UnixStream::pair().expect("idle stdin");
let stdin = super::ChildStdin::adopt(read).expect("adopt before peer closes");
let (finished, result) = std::sync::mpsc::channel();
let worker = std::thread::spawn(move || {
let limits = Limits::default();
let invoker = PanickingInputInvoker {
stop: stop_for_worker,
};
let panicked = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
Interpreter::new(limits).run_child(
"httpprobe",
Some(stdin),
&invoker,
&TreeContext::new(limits, CallBudget::new(16))
.with_cancel(invoker.cancel_signals()),
)
}))
.is_err();
finished.send(panicked).expect("test receives the panic");
});
let answer = result.recv_timeout(std::time::Duration::from_secs(3));
stop.cancel();
if answer.is_err() {
result
.recv_timeout(std::time::Duration::from_secs(3))
.expect("worker cleans up after cancel");
}
worker.join().expect("worker joined before asserting");
assert!(answer.expect("provider panic returns promptly"));
}
#[test]
fn exit_codes_follow_the_documented_mapping() {
assert_eq!(ExitCode::SUCCESS.get(), 0);
assert_eq!(ExitCode::FAILURE.get(), 1);
assert_eq!(ExitCode::SYNTAX.get(), 2);
assert_eq!(ExitCode::TIMEOUT.get(), 124);
assert_eq!(ExitCode::DENIED.get(), 126);
assert_eq!(ExitCode::NOT_FOUND.get(), 127);
}
#[test]
fn capability_results_map_onto_distinct_codes() {
assert_eq!(
ExitCode::from_capability_result(&CapabilityCallResult::Succeeded),
ExitCode::SUCCESS
);
assert_eq!(
ExitCode::from_capability_result(&CapabilityCallResult::Failed {
error: "boom".to_owned(),
detail: None
}),
ExitCode::FAILURE
);
assert_eq!(
ExitCode::from_capability_result(&CapabilityCallResult::Denied {
reason: "policy".to_owned()
}),
ExitCode::DENIED
);
assert_eq!(
ExitCode::from_capability_result(&CapabilityCallResult::NotFound),
ExitCode::NOT_FOUND
);
}
#[test]
fn script_exit_wraps_like_bash() {
assert_eq!(ExitCode::from_script_exit(0).get(), 0);
assert_eq!(ExitCode::from_script_exit(7).get(), 7);
assert_eq!(ExitCode::from_script_exit(256).get(), 0);
assert_eq!(ExitCode::from_script_exit(257).get(), 1);
assert_eq!(ExitCode::from_script_exit(-1).get(), 255);
}
}
#[cfg(test)]
mod asset_tests;