Capsule command specification

[sirnewton01]

In certain contexts, such as browsers, a template for all capsule commands will add a measure of safety and act as a guide to keep client side scripting for capsules at a minimum with well defined methods for providing input parameters, paths and content types. In the same way that JSON is a well defined and strict subset of Javascript this might help to establish certain conventions for client-capsule interaction that can create better user familiarity and tooling. It will also help in cross-platform support.

Usage:
ssh $(capsule <host>) <capsule-command> [capsule-path.ext] [<<EOF
<param1> <value1>
...
EOF]
[# .ext]

Exit codes:
0 - Success
>0 - Failure
30 - Redirection (replacement ssh command is provided on stderr)
40 - Try again later

The above usage patterns will work in a typical Unix command prompt. The simplified syntax without the here document stdin (ie. EOF portion) can easily be formed in a single line, much like a hyperlink, but it can be actually run on a command line. The expected output format is based on the provided file extension at the end of the command and preceded by at least one '.'. Otherwise, the client may assume a simple text output (maybe gemini) with safeguards and limits in place to prevent overwhelming the user with large or binary payload. Stderr is always assumed to be simple text or gemini as it is not subject to any content negotiation.

When parameters are provided to a remote command using the here document syntax they are provided one on each line for ease of editing them with a simple space separating the parameter name and the value, which can run to the end of the line, itself with spaces in it.

Note that the use of $ is not permitted in any host, command parameter, or value unless it is first escaped with a . This helps to prevent accidental leakage of the client environment to an untrusted host.

Note that tools may opt to support other commands, such as scp, git, rsync and others with their own usages and limitations. The restricting of these commands is intentionally left out of scope, however new capsule commands should attempt to follow similar usage patterns, output, exit codes and either output format hinting with file extension at the end or just simple text that can be rendered easily.