feat(cli): Allow referencing json files when submitting

The `submit` subcommand now accepts JSON array (old behavior)
OR JSON array file prefixed with `@`
OR `--` followed by individual parameters encoded as JSON, supporting
`@`-prefixed files as well.

Author: tomasol

crates/executor/src/executor.rs

@@ -331,7 +331,6 @@ impl<C: ClockFn + 'static> ExecTask<C> {
         }
     }
 
-    // FIXME: On a slow execution: race between `expired_timers_watcher` this if retry_exp_backoff is 0.
     /// Map the `WorkerError` to an temporary or a permanent failure.
     fn worker_result_to_execution_event(
         execution_id: ExecutionId,

src/args.rs

@@ -136,11 +136,8 @@ pub(crate) enum Execution {
     /// Submit new execution and optionally follow its status stream until the it finishes.
     Submit {
         /// Function in the fully qualified format
-        #[arg(value_name = "FUNCTION")]
+        #[arg(value_name = "function")]
         ffqn: FunctionFqn,
-        /// Parameters encoded as an JSON
-        #[arg(value_name = "PARAMS")]
-        params: String,
         /// Follow the stream of events until the execution finishes
         #[arg(short, long)]
         follow: bool,
@@ -149,9 +146,21 @@ pub(crate) enum Execution {
         no_reconnect: bool,
         /// Print output as JSON
         #[arg(long)]
-        json: bool,
+        json: bool, // TODO: output=json|jsonl|plain
+        /// Parameters for the function. Accepts one of the following formats:
+        ///
+        /// - A single argument containing a JSON array string (e.g., '["a", "b"]')
+        ///
+        /// - A single argument prefixed with '@' referencing a file that contains the JSON array
+        ///
+        /// - Multiple individual arguments following '--' (e.g., -- "a" @secondparam.json null 1)
+        #[expect(clippy::doc_link_with_quotes)] // Intentional use of '
+        #[arg(name = "parameters")]
+        params: Vec<String>,
     },
+    /// Write a return value or an execution error to an already created stubbed execution.
     Stub(Stub),
+    /// Get the current state of an execution.
     Get {
         /// Follow the status stream until the execution finishes.
         #[arg(short, long)]
@@ -169,6 +178,80 @@ pub(crate) enum Execution {
     },
 }
 
+pub(crate) mod params {
+    use clap::error::ErrorKind;
+    use serde_json::Value;
+
+    pub(crate) fn parse_params(params: Vec<String>) -> Result<Vec<u8>, clap::Error> {
+        if params.is_empty() {
+            Ok("[]".to_string().into_bytes()) // no params, does not matter if `--` was present.
+        } else if params.len() == 1 && !dashdash() {
+            let mut params = params;
+            let json_array = params.pop().expect("checked that len == 1");
+            // Single JSON Array, or a `@`-prefixed file containing the array.
+            let json_array = if let Some(file_path) = json_array.strip_prefix('@') {
+                std::fs::read_to_string(file_path).map_err(|err| {
+                    clap::Error::raw(
+                        ErrorKind::Io,
+                        format!(
+                            "parameter parsing failed: failed to read file '{file_path}': {err}"
+                        ),
+                    )
+                })?
+            } else {
+                json_array
+            };
+            let json_value = serde_json::from_str(&json_array).map_err(|err| {
+                clap::Error::raw(
+                    ErrorKind::ValueValidation,
+                    format!("Invalid JSON array for parameters: {err}"),
+                )
+            })?;
+            let Value::Array(_) = &json_value else {
+                return Err(clap::Error::raw(
+                    ErrorKind::ValueValidation,
+                    "Parameter provided as JSON must be a JSON array.",
+                ));
+            };
+            Ok(json_value.to_string().into_bytes())
+        } else {
+            // Fallback to raw arguments. Each argument is interpreted as a JSON value or a file starting with `@` that contains the JSON.
+            let mut parsed_params: Vec<Value> = Vec::new();
+            for (idx, arg) in params.into_iter().enumerate() {
+                let arg = if let Some(file_path) = arg.strip_prefix('@') {
+                    std::fs::read_to_string(file_path).map_err(|err| {
+                        clap::Error::raw(
+                            ErrorKind::Io,
+                            format!(
+                                "{idx}-th parameter parsing failed: failed to read file '{file_path}': {err}"
+                            ),
+                        )
+                    })?
+                } else {
+                    arg
+                };
+                let json = serde_json::from_str(&arg).map_err(|err| {
+                    clap::Error::raw(
+                        ErrorKind::ValueValidation,
+                        format!("{idx}-th parameter parsing failed: cannot parse as JSON: {err}"),
+                    )
+                })?;
+                parsed_params.push(json);
+            }
+            Ok(Value::Array(parsed_params).to_string().into_bytes())
+        }
+    }
+
+    fn dashdash() -> bool {
+        // Ambigous: Either the single JSON Array representing all parameters,
+        // OR `-- "first-and-only-json-param"`
+        let mut rev_arg_iter = std::env::args().rev();
+        rev_arg_iter.next().expect("last arg must be present");
+        let maybe_separator = rev_arg_iter.next().expect("last-1 arg must be present");
+        maybe_separator == "--"
+    }
+}
+
 #[derive(Debug, clap::Args)]
 #[command(group(
     ArgGroup::new("result")

src/command/execution.rs

@@ -4,7 +4,6 @@ use crate::grpc_util::grpc_gen;
 use crate::grpc_util::grpc_gen::execution_status::BlockedByJoinSet;
 use crate::grpc_util::grpc_gen::execution_status::Finished;
 use anyhow::Context as _;
-use anyhow::bail;
 use chrono::DateTime;
 use concepts::JOIN_SET_ID_INFIX;
 use concepts::JoinSetKind;
@@ -26,22 +25,17 @@ pub(crate) enum SubmitOutputOpts {
 pub(crate) async fn submit(
     mut client: ExecutionRepositoryClient,
     ffqn: FunctionFqn,
-    params: String,
+    params: Vec<u8>,
     follow: bool,
     opts: SubmitOutputOpts,
 ) -> anyhow::Result<()> {
     let execution_id = ExecutionId::generate();
-    // Verify params are string parseable as JSON array.
-    match serde_json::from_str(&params).context("PARAMS must be a JSON-encoded string")? {
-        serde_json::Value::Array(_) => {}
-        _ => bail!("PARAMS must be a JSON-encoded array"),
-    }
     client
         .submit(tonic::Request::new(grpc_gen::SubmitRequest {
             execution_id: Some(execution_id.clone().into()),
             params: Some(prost_wkt_types::Any {
                 type_url: format!("urn:obelisk:json:params:{ffqn}"),
-                value: params.into_bytes(),
+                value: params,
             }),
             function_name: Some(ffqn.into()),
         }))

src/main.rs

@@ -6,7 +6,7 @@ mod grpc_util;
 mod init;
 mod oci;
 
-use args::{Args, Client, ClientSubcommand, Generate, Server, Subcommand};
+use args::{Args, Client, ClientSubcommand, Generate, Server, Subcommand, params::parse_params};
 use clap::Parser;
 use command::{
     execution::{GetStatusOptions, SubmitOutputOpts},
@@ -116,7 +116,7 @@ async fn main() -> Result<(), anyhow::Error> {
                 } else {
                     SubmitOutputOpts::PlainFollow { no_reconnect }
                 };
-                command::execution::submit(client, ffqn, params, follow, opts).await
+                command::execution::submit(client, ffqn, parse_params(params)?, follow, opts).await
             }
             ClientSubcommand::Execution(args::Execution::Stub(args::Stub {
                 execution_id,