Consider new syntax or a new option for the --dir CLI option

[alexcrichton]

This issue is inspired by discussion on #7301 and Zulip. To summarize a bit, the --dir syntax is inconsistent between Wasmtime and other runtimes, and a notable inconsistency of Wasmtime is the usage of :: as a delimiter as opposed to a single character such as :. I'll also personally note that there's inconsistency with Docker which is another common tool for a similar operatin which uses :.

As of #7301 and Wasmtime 14/15 the CLI for Wasmtime will support:

• --dir foo - opens the host directory foo and mounts it in the guest as foo
• --dir foo::bar - opens the host directory foo and mounts it in the guest as bar

I find the discussion over on Docker's documentation pretty illuminating here. The gist, as it applies to Wasmtime, appears to be:

• Docker's -v is the "old" syntax and is acknowledged to be cryptic and error-prone, and this is basically the same as the --dir syntax Wasmtime has today (and the subject of this comment)
• Docker's --mount is the "new" syntax which uses --mount key=val,key2=val,key3=val which is more verbose but more clear

While I wasn't personally present (@sunfishcode maybe you were?) when this option was originally added to Wasmtime my guess is that the choice of :: delimiter for Wasmtime assists with Windows-style paths which have colons in them with absolute paths such as C:\foo\bar. Such a concern does not affect Docker, however, where Docker appears to support docker run -v z:\foo:c:\dest ... according to its documentation.

With all that in mind, there's a few questions in my mind of what to do with Wasmtime:

1. Should --dir be kept at all? Should this be replaced entirely with a separate option with more obvious syntax to readers? (albeit more verbose to writers)
2. If --dir is kept, can its delimiter be changed to : to be more consistent with Docker? If so how do Windows paths work?
3. If a new option is added, what should it be called? Additionally what should its syntax be? For Docker it's a ,-delimited list of key=value pairs, but I'm also not sure how this handles paths-with-commas in them.

Personally I think that while the CLI was overhauled for Wasmtime 14 we can still perform this change when we want. It's probably not too too hard to have broad messaging of a change in syntax if --dir changes or gets replaced. So in that sense while we can't change anything for Wasmtime 14, I do still think changes should be considered for 15+

[alexcrichton]

According to docker/cli#1480 the Docker CLI uses a CSV parser for --mount which would solve the "what if my path has a comma in it" problem.

[jeffparsons]

According to docker/cli#1480 the Docker CLI uses a CSV parser for --mount which would solve the "what if my path has a comma in it" problem.

I'm not sure that using CSV as a way to reduce ambiguity is a design choice I'd copy... 😜

Jokes aside, though, I do like the k=v,… syntax because it neatly leaves the door open to all kinds of future features like read-only mounts, virtual directories (.tar.gz), etc. without having to anticipate them today.

As for escaping, I'm guessing there's some great art out there from which to draw inspiration, but my gut feeling is that something as simple as possible (like repeating the delimiter if you want it as a literal) would be good to avoid creating exotic corner cases for people to stumble upon.

[sunfishcode]

(Yes, originally Wasmtime used :, and it was switched to :: to better support Windows paths with colons.)

I agree with @jeffparsons ; what if we went with just the --mount syntax? It is a bit more verbose, but "research has shown it to be easier to use". I am also still hoping that in the future we can do something in the space of (optionally) auto-inferring these paths, for when the verbosity of explicit args is inconvenient.

[alexcrichton]

I'm a bit ambivalent myself about only having the --mount syntax vs additionally having today's --dir syntax. I'm too used to -v in Docker and --dir in Wasmtime though so I'm not a good data point and I'd honestly disregard my ambivalence here.

With only the --mount syntax, do y'all think we should use --mount as the option name or repurpose the --dir as-is today?

Also with --mount syntax I actually don't think CSV is really all that bad of an idea. It's a detail that no one needs to worry about when typing command lines really and if you do need to worry about it then it's well-defined what you need to do. In my experience inventing various syntaxes on CLIs seems to always go awry, and the major use for formats like this are when tools themselves invoke Wasmtime at which point having a CSV encoder (or e.g. a JSON encoder like I've seen in the past) isn't too onerous

[jeffparsons]

I'm a bit ambivalent myself about only having the --mount syntax vs additionally having today's --dir syntax. I'm too used to -v in Docker and --dir in Wasmtime though so I'm not a good data point and I'd honestly disregard my ambivalence here.

I wouldn't disregard your ambivalence. I know my personal preference in things like this sits all the way up one end of the spectrum, and what feels right to me is often perceived as unnecessarily cumbersome to my colleagues. If I try to put on my "everyone else hat" I do feel that having a simple --dir host:guest argument would make most people most happy most of the time. But having an extra totally separate argument with its own name for a more structured/powerful form also feels a bit yucky.

With only the --mount syntax, do y'all think we should use --mount as the option name or repurpose the --dir as-is today?

Tomayto / tomahto. If all functionality was somehow squished into one arg (see below), I figure you could just keep --dir and/or have one as an alias for the other. 🤷

Also with --mount syntax I actually don't think CSV is really all that bad of an idea. It's a detail that no one needs to worry about when typing command lines really and if you do need to worry about it then it's well-defined what you need to do. In my experience inventing various syntaxes on CLIs seems to always go awry, and the major use for formats like this are when tools themselves invoke Wasmtime at which point having a CSV encoder (or e.g. a JSON encoder like I've seen in the past) isn't too onerous

I was taking a shot at CSV specifically because it's so poorly specified/understood. (Ask three people what "CSV" means and you'll get four different answers.) And I've always been irked by tools that say "the format of this is whatever libwhatever accepts, where libwhatever has its own quirks and changes unpredictably over time. I have no such qualms about JSON, especially for the "other tools calling Wasmtime" use case.

Given that the existing --dir syntax already doesn't let you specify all imaginable paths (IINM, no escaping), I reckon it would be reasonable to have it support the shorthand host:guest form and a more powerful structured form in the same argument.

Does Wasmtime support some kind of config file or "response file" as an alternative to passing all options as command line arguments? (I don't recall seeing one.) If so, or if it might in future, what if command line arguments like --dir that have a simple form could also accept a JSON object equivalent to the relevant part of the config schema? E.g. these would be equivalent:

--dir usr.tar.gz:/usr # inferred to be an "archive" mount type

--dir '{"type": "archive", "host": "usr.tar.gz", "guest: "/usr"}' # equivalent to what would come under a `"dirs"` or `"mounts"` key in the config file.

The parsing rule for any such argument would be:

• If it starts with '{', or '[' then it will be parsed as a JSON object/array matching the relevant config subschema, and if it doesn't parse then it is an error.
• Otherwise, we parse it as the shorthand, which may not be able to express all valid paths/options, but probably covers 90%+ of use cases.

Then I imagine interactive users would mostly use the shorthand, people like me would use the JSON format always, and other tools calling Wasmtime would mostly write/pipe a config file instead of passing command line flags.

Is that too weird? I guess it opens a huge can of worms around config/response files, too, so it might be too much to bite off just for the sake of improving the --dir argument!

[tschneidereit]

I think we shouldn't use --mount for this, because it does something subtly different. And full support for a vfs that basically works like Docker's might well be something WASI at some point provides, in which case it'd be unfortunate not to have --mount available to use for it.

[alexcrichton]

I think @jeffparsons makes a compelling argument myself. Coupled with @tschneidereit's thoughts, which I also agree with, I think the proposal at this point is basically adding JSON support to --dir.

[yamt]

i guess it would be nicer to keep it similar among wasi-supporting wasm runtimes.
(in that case, json might not be ideal as it can be a burden for smaller runtimes to parse it.)