Command improvements for ergonomics and error handling #3362

ijackson · 2023-01-03T20:34:18Z

text/0000-command-ergonomics.md

Co-authored-by: Lucius Hu <[email protected]>

Noratrieb · 2023-01-04T19:44:39Z

I agree with the motivation that Command is not very ergonomic, especially around the common "return error containing stderr on error" workflow.
But this RFC is a little too opinionated about stderr in my opinion. It strictly treats it as the "error output", which is just often not true in practice. Even cargo logs all its output to stderr. Therefore, considering any output to stderr an error is a bad idea.
Also, if I read this correctly, there's no way to get stdout when the command failed using these methods except with the existing .output(), but this plans to deprecate that.

ijackson · 2023-01-04T20:10:49Z

I agree with the motivation that Command is not very ergonomic, especially around the common "return error containing stderr on error" workflow. But this RFC is a little too opinionated about stderr in my opinion. It strictly treats it as the "error output",

Um? That's not true. In my RFC, by default, error output is sent to the Rust program's stderr (inherit).

which is just often not true in practice. Even cargo logs all its output to stderr. Therefore, considering any output to stderr an error is a bad idea.

I think this depends what program you're running. I don't think it is wrong to have the option to treat stderr output as an error, as a non-default mode.

Also, if I read this correctly, there's no way to get stdout when the command failed using these methods except with the existing .output(), but this plans to deprecate that.

No, that's not true either. If you have a SubprocessError, you can call the .stdout_bytes() method on it. (It will only be Some if you called one of the .get_output* methods, obviously; otherwise the stdout went to wherever you configured the Command to send it.)

Noratrieb · 2023-01-04T20:36:23Z

Ah, I seem to have overlooked that, sorry.

text/0000-command-ergonomics.md

joshtriplett · 2023-01-12T03:58:36Z

text/0000-command-ergonomics.md

+
+   Runs the command and collects its stdout.
+   Decodes the stdout as UTF-8, and fails if that's not possible.
+   Fails unless the output is a single line (with or without line ending).


Please specify the behavior if the program has no output. Does this fail in that case, or is the requirement "at most one line"?

I think it should succeed and give an empty string. Will write that into the RFC.

It seems like this helper would commonly be used for programs for which you expect to parse the output, in which case having to separately check for empty string seems to defeat part of the ergonomic win of using the helper.

But in any case, this isn't a blocker as you've split this helper out into possible future work.

joshtriplett · 2023-01-12T04:05:31Z

text/0000-command-ergonomics.md

+   This API cannot be fixed;
+   see [#73126](https://github.com/rust-lang/rust/issues/73126).
+
+ * Apply `#[must_use]` to `Command` and `Child`.


🎉 🎉 🎉

Would it be possible to make this change without an RFC? Seems somewhat unfortunate to tie this together with the API additions.

text/0000-command-ergonomics.md

joshtriplett · 2023-01-12T04:30:28Z

text/0000-command-ergonomics.md

+   Starts the command, allowing the caller to
+   read the stdout in a streaming way.
+   Neither EOF nor an error will be reported by `ChildOutputStream`
+   until the child has exited, *and* the stdout pipe reports EOF.
+   (This includes errors due to nonempty stderr,
+   if stderr was set to `piped`.)


This description makes me wonder about the semantics of the other functions in this family. Do they wait for process exit, or for process exit and EOF? (I'm hoping the former, or possibly "process exit and then a non-blocking read saying it would block".)

This is stated explicitly in the docs for what I am now calling read_stdout_bytes. All of these functions wait for both EOF and process exit. I will add a short xref note to the other two functions. In the real docs the spec text should probably be cut and pasted instead.

text/0000-command-ergonomics.md

joshtriplett · 2023-01-12T04:45:13Z

In a broad sense, I think the approach of this RFC seems mostly reasonable, and I'd like to see something along these lines.

There are two categories of issues I'd like to raise. I think both are addressable, and I'm hoping it'll be possible to address them and merge the resulting RFC.

One family of issues are largely bikeshed-painting, where the functionality seems perfectly fine but I think the names are unintuitive. For those, I want to be clear that I'm not attached to any particular names, and primarily want to express some desired properties of a name that I think the proposed names don't have. I'd like to align on those properties and then I don't especially care what name we pick that meets those properties.

The other family of issues are those of functionality, where I think the proposal makes a common use case more challenging.

First, the bikesheds:

Bikeshed: We currently have programs using a method called output that retrieves both stdout and stderr, merged. I don't think we can switch from that to methods named get_output* that only return stdout without leading to some confusion. I would propose a name that makes it clear that these only return stdout, such as get_stdout. (Arguably that may mean it needs to be called read_stdout or similar, because get_stdout might imply "get the previously set standard output device"; in that case, we could also have stdout_reader for the reader method to avoid read_stdout_reader.)
Bikeshed (minor): Perhaps ProcessError rather than SubprocessError? We currently use the term "process" in various places, and not "subprocess". Plus, this error type seems useful for any kind of process.
Bikeshed: s/ChildOutputRead/ChildOutputReader/, and likewise s/_read/_reader/ for the method returning it. "reader" seems to be the ecosystem convention for "things that implement Read", and Stream is something else entirely. (Regarding the item in the "Drawbacks" section, though, I'm completely in favor of having this function and type.)

Next, the semantics:

Semantic: Please spell out exactly how you're expecting people to retrieve stdout-and-stderr interleaved, as they can currently do with output. If this isn't as simple as "call a single non-deprecated method", I think that needs improving. I think the proposal is that if you route stderr to the same place you route stdout, rather than capturing it in a separate pipe, then you'll get the combined output and stderr won't get treated as a failure? In any case, that needs documenting and needs to be simple. (Common use case: spawning a compiler-like tool.)
Semantic: We should not encourage developers to fail on non-UTF-8 in the common case. I think get_stdout should return bytes, and we should offer a get_stdout_string that returns a UTF-8 String. Similarly, the error type should have methods stdout and stderr rather than stdout_bytes and stderr_bytes.
Semantic (exotic): I have some use cases (involving UNIX sockets in datagram mode) for which I cannot keep reading stdout until EOF, and instead I have to stop reading stdout as soon as 1) the process exits and 2) a non-blocking read returns nothing. Would it be possible (either in-std or outside std) to implement a reader with that semantic atop these APIs?
Semantic: Please document that we need impl Error for ProcessError. Also, that implementation is going to have a little trouble implementing the cause method, unless there's a semantic guarantee that only one of the types of error can happen. This seems like it'd be guaranteed for errors produced by the standard library, but the APIs for building a ProcessError don't statically guarantee that, nor do the accessor methods for ProcessError. If we could maintain that guarantee, such that there's only one chained error, that seems ideal.
Semantic: I think we should show the command-line arguments in the default case, even though they might be verbose. However, sometimes the command-line arguments might be sensitive. For convenience for such applications, perhaps a hide_args() method that avoids including the args in the error. (We could get more exotic with a .masked_arg() method that supplies and masks one argument to the command, but that's much more complex and I don't think that should be in this RFC. hide_args() seems simple enough though.)
Semantic: I can imagine the convenience value of the _line variant, but could you give some examples of code that would benefit from it? I'm also wondering if it'd be reasonably convenient to call read_stdout_string and then have a convenience method on String for "fail if not exactly one line", which seems useful in other contexts too.
Semantic (minor): Please add a note to the "Further necessary APIs for SubprocessError" section that these APIs could be under a separate feature gate and stabilized separately; that'll make it easier to potentially do a partial stabilization.

afetisov · 2023-01-12T12:07:20Z

I think get_stdout should return bytes,

Shouldn't it be OsString?

However, sometimes the command-line arguments might be sensitive. For convenience for such applications, perhaps a hide_args() method that avoids including the args in the error.

Sensitive things should not be passed as command line arguments, since those can leave traces in arbitrary places around the OS. For example, they may be included in ps output. We should not encourage half-baked security practices.

joshtriplett · 2023-01-12T23:25:21Z

Shouldn't it be OsString?

No. On Windows that would be WTF-8, not raw bytes.

tmccombs · 2023-01-13T08:02:53Z

I agree with the motivation that Command is not very ergonomic, especially around the common "return error containing stderr on error" workflow. But this RFC is a little too opinionated about stderr in my opinion. It strictly treats it as the "error output",

Um? That's not true. In my RFC, by default, error output is sent to the Rust program's stderr (inherit).

But what if you also want to capture stderr?

As @joshtriplett mentioned output currently gives you interleaved stdout/stderr, and if that is deprecated, there isn't a way to get that. Perhaps one way to do that would be to add a new constructor to Stdio that would allow you to redirect stderr to stdout or vice versa?

And should there be functions for getting stdout and stderr as separate Strings or Vec<u8>s? Of course it is possible to implement that using spawn and Child, but that is true of all these other more ergonomic functions as well.

thomcc

I think this is well-motivated broadly, however needs some work:

I think deprecating Command::output is probably too aggressive, or at least needs a lot more justification.
I agree with @joshtriplett in that there's a lot bikeshed-painting to be done about the naming here -- most of these names don't follow the conventions of the ecosystem/stdlib that well.
I think the mutable/constructable SubprocessError portion of the API needs more work -- Ideally it could be a lot smaller and have fewer moving pieces. Perhaps it's trying to be too much at once?

thomcc · 2023-01-13T12:27:41Z

text/0000-command-ergonomics.md

+
+## Deprecations
+
+ * Deprecate `std::process::Command::output()`.


It's not clear to me that Command::output is that bad. It's slightly awkward and requires manually checking errors, but I'm not convinced this is worth deprecating a extremely widely-used function and causing a large amount of ecosystem churn (which many users will respond to with #[allow(deprecated)], due to MSRV+the existing method not being broken).

I think you need to make a much clearer case for why this needs deprecation, and document the downside of ecosystem and educational churn as folks move to the new API(s).

I think you and Josh are right about this. I have moved the deprecation to Future possibilities.

thomcc · 2023-01-13T12:36:57Z

text/0000-command-ergonomics.md

+    fn communication_error() -> Option<&io::Error>;
+
+    /// If trouble included failed UTF-8 conversion.
+    fn utf8_error(&self) -> Option<&std::str::FromUtf8Error>;


Which UTF-8 conversion does this refer to? I think this probably should be pushed down to whatever getter would return something UTF-8 validated rather than having this stored as a field on the error.

If this is stored (and almost certainly if it is not), we should use std::std::Utf8Error rather than a &std::string::FromUtf8Error in order to avoid needing to store the invalid UTF8 twice (and to avoid forcing us to convert eagerly).

I'm using std::str::FromUtf8Error which doesn't contain or reference the string, but does contain the offset. I think this doesn't suffer from the problem you describe?

thomcc · 2023-01-13T12:39:26Z

text/0000-command-ergonomics.md

+    fn set_stderr_bytes(&mut self, stderr: impl Into<Box<u8>>);
+    fn set_spawn_error(&mut self, error: Option<io::Error>);
+    fn set_communication_error(&mut self, error: Option<io::Error>);
+    fn set_utf8_error(&mut self, error: Option<std::str::FromUtf8Error>);


I think too much of this is mutable -- either we should just make these be public fields (we have get_ and set_ methods for them...) or we should just allow constructing one of these from parts.

Additionally it's not clear to me how these interact. Up until now, I had imagined that there was an internal enumeration

enum SubprocessErrorCause { Spawn(io::Error), Communication(io::Error), // Actually, I don't think we want this one, but anyway Utf8(str::Utf8Error), // ... }

but this API has individual setters for each one, which implies it either is not that way, or they have perhaps-confusing interactions.

Does it make any sense for there to be more than one error here anway? Which would gets reported in std::error::Error::source?

I have made this a transparent struct. Making it opaque was indeed confusing.

thomcc · 2023-01-13T12:43:17Z

text/0000-command-ergonomics.md

+    fn has_problem(&self) -> bool;
+}
+impl Default for SubprocessError { ... }
+impl Clone for SubprocessError { ... } // contained io:Errors are in Arcs


I think we should instead ask users who need a Cloneable SubprocessError to use Arc<SubprocessError>, rather than imposing that requirement on the internals.

Fair enough, I have changed this.

Co-authored-by: Josh Triplett <[email protected]>

joshtriplett · 2023-01-19T09:44:07Z

text/0000-command-ergonomics.md

+    ////
+    /// Use this if you want to to tolerate some exit statuses,
+    /// but still fail if there were other problems.
+    pub fn just_status(self) -> Result<ExitStatus, SubprocessError>;


This feels a little awkward to use: if you call this to filter out some exit statuses, you lose the rest of the error, which means you don't have stdout_bytes anymore. What code pattern would you suggest for code that wants to run diff, check the exit code for 0/1 to determine if there was a difference, bail on >1, and capture the patch output?

I wonder if this (straw proposal) might be easier to use:

/// If the process is only considered to have errored due /// to its exit code, calls the provided filter, returning /// `Ok(Self)` if it returns `true`, or `Err(Self)` if it /// returns `false`. pub fn permit_statuses(self, f: impl FnOnce(ExitStatus) -> bool) -> Result<ProcessError, ProcessError>

This would make it relatively straightforward to say "allow 0 or 1, reject everything else". (Still mildly annoying due to code() returning Option, but doable.)

I quite like this idea. I wasn't sure people would like the notion of returning Ok(ProcessError), but if you think that's OK it seems OK to me.

mildly annoying due to code() returning Option

I wondered whether the closure should receive ExitCode (so would only be called if the process exited rather than was killed). But then you can't use this to ignore (say) SIGPIPE.

I do kind of hate booleans. Would impl FnOnce(ExitStatus) -> Result<(), ()> be too awful?

joshtriplett · 2023-01-19T09:48:01Z

Nit (emphatically not a blocker): your commit message "Rename to ChildOutputStream" seems inaccurate (specifically the "to"), as it renames ChildOutputStream to ChildOutputReader.

joshtriplett · 2023-01-19T09:50:42Z

text/0000-command-ergonomics.md

+Because maybe several things went wrong, ever providing a `Some` `cause`
+would involve prioritising multiple possible problems.


Can you give an example where multiple different things could simultaneously go wrong? It seems like spawn_error, communication_error, and utf8_error should be mutually exclusive.

The only things that seem like they could simultaneously go wrong would be "exit status was nonzero" and one of the errors processing output. And I think in that case, exit status should be printed by ProcessError, and the other error should be in cause.

I think the following can all occur in the same execution:

The application calls .stderr(piped) and .read_stdout()

Spawn succeeds

The subprocess produces some invalid-UTF output

Then, something in the kernel goes very badly awry (or, some other thing in our Rust program wrecks our fd) and read() on one of the pipes fails

The subprocess prints some stderr (which the application has said to treat as an error)

The subprocess then crashes.

We must report at least all of: the error from read; the stderr output (which might well be very helpful for diagnosis); and the process's exit status.

I think we should eagerly do a unicode validity check whenever we captured the stdout, and record the unicode conversion error in the ProcessError. That way a caller who calls your .permit_status() and gets Ok can know that the stdout output is UTF-8; conversely, if the command unexpectedly printed non-UTF-8, the caller can conveniently report the command line etc.

Or to put it another way, we shouldn't "short circuit" some checks and report only a subset of the errors.

joshtriplett · 2023-01-19T09:53:12Z

text/0000-command-ergonomics.md

+and we should print only the command name.
+
+Sometimes people pass sensitive information (such ass passwords) in command line arguments.
+This is not a good idea, because command line arguments are generally public on Unix.


Suggested change

This is not a good idea, because command line arguments are generally public on Unix.

This is not a good idea in portable software, because command line arguments are often public on Unix targets.

text/0000-command-ergonomics.md

joshtriplett · 2023-01-19T10:03:19Z

text/0000-command-ergonomics.md

+### Further APIs for `ProcessError`
+
+A `ProcessError` is a transparent `Default` struct so it can be
+constructed outside std, for example by async frameworks.


Suggested change

constructed outside std, for example by async frameworks.

constructed outside std, such as by async frameworks or other

code launching processes and handling errors from them.

joshtriplett · 2023-01-19T10:15:27Z

I've nominated this for the next libs-api meeting. I anticipate proposing FCP on it, unless folks raise any other issues before then.

Co-authored-by: Josh Triplett <[email protected]>

ijackson · 2023-01-19T13:25:10Z

I had been thinking about this, and in particular the implementation, and felt that communication_error: Option<io:Error> was suboptimal, because it makes handling of subprocess communication errors less correct (the kind() isn't very useful). See the reasoning I have left in the comment there.

I'm not 100% sure whether this is better than my previous proposal. One option woudl be to leave this one way or the other for now, and let the implementor decide.

text/0000-command-ergonomics.md

joshtriplett · 2023-02-07T16:37:31Z

text/0000-command-ergonomics.md

+However,
+avoiding deadlocks when reading subprocess output,
+and also doing error checks properly,
+is rather subtle.


Could you clarify how stdout_reader makes avoiding this deadlock easier?

Is this just that you need to interleave .write calls to the process stdin with .read calls to the reader, rather than calling .write_all and then reading all the output at once?

The deadlocks that stdout_reader avoids completely are ones ike: waiting for the command's stdout EOF, and child termination, in the wrong order; waiting for stderr EOF (which can sometimes block forever for complicated reasons).

It helps only a little with deadlocks resulting from piping both into and out of the same Command. (I think it may still help in those use cases, but it doesn't help with "you wrote too much to the command's input while it's trying to write output to you".)

…omcc Make ExitStatus implement Default And, necessarily, make it inhabited even on platforms without processes. I noticed while preparing rust-lang/rfcs#3362 that there was no way for anyone to construct an `ExitStatus`. This would be insta-stable so needs an FCP.

…olnay Make ExitStatus implement Default And, necessarily, make it inhabited even on platforms without processes. I noticed while preparing rust-lang/rfcs#3362 that there was no way for anyone to construct an `ExitStatus`. This would be insta-stable so needs an FCP.

Make ExitStatus implement Default And, necessarily, make it inhabited even on platforms without processes. I noticed while preparing rust-lang/rfcs#3362 that there was no way for anyone to construct an `ExitStatus`. This would be insta-stable so needs an FCP.

Twey · 2024-11-25T15:20:25Z

text/0000-command-ergonomics.md

+Then,
+if the stderr output is nonempty, this is considered an error,
+and reported in the `ProcessError`.


I'm a bit uncertain about this semantics. It's popular in command-line applications to use stderr to collect running commentary about what the program is doing (for example log::info under env_logger) in ways that definitely shouldn't be considered errors.

I have an experience report that erroring out on non-empty stderr is wrong! One common case here is when you run something like rustc --version, but that thing is rustup managed, so, before you get to rustc --version output, you have printout from rustup on the stderr that it downloads the appropriate version.

Propose Command improvements

2a26454

ehuss added the T-libs-api Relevant to the library API team, which will review and decide on the RFC. label Jan 4, 2023

lebensterben reviewed Jan 4, 2023

View reviewed changes

text/0000-command-ergonomics.md Outdated Show resolved Hide resolved

Apply rust tag to example

9a4fc34

Co-authored-by: Lucius Hu <[email protected]>

ijackson mentioned this pull request Jan 4, 2023

impl Default for ExitStatus rust-lang/libs-team#158

Closed

ijackson added 2 commits January 4, 2023 10:44

Discuss some alternatives around SubprocessError

89705df

Add rust tags to many other code blocks

38b9c2a

joshtriplett reviewed Jan 12, 2023

View reviewed changes

text/0000-command-ergonomics.md Outdated Show resolved Hide resolved

text/0000-command-ergonomics.md Outdated Show resolved Hide resolved

text/0000-command-ergonomics.md Outdated Show resolved Hide resolved

joshtriplett reviewed Jan 12, 2023

View reviewed changes

text/0000-command-ergonomics.md Outdated Show resolved Hide resolved

joshtriplett reviewed Jan 12, 2023

View reviewed changes

text/0000-command-ergonomics.md Outdated Show resolved Hide resolved

joshtriplett reviewed Jan 12, 2023

View reviewed changes

text/0000-command-ergonomics.md Show resolved Hide resolved

joshtriplett reviewed Jan 12, 2023

View reviewed changes

text/0000-command-ergonomics.md Outdated Show resolved Hide resolved

thomcc reviewed Jan 13, 2023

View reviewed changes

Use /nonexistent rather than /dev/enoent

2ff775e

Co-authored-by: Josh Triplett <[email protected]>

Propose adding a docs warning to Command.output()

732e555

joshtriplett reviewed Jan 19, 2023

View reviewed changes