Skip to content

Instantly share code, notes, and snippets.

@wking
Forked from julz/runtime.md
Last active September 19, 2015 08:25
Show Gist options
  • Save wking/1d69118ba8b750f85bfc to your computer and use it in GitHub Desktop.
Save wking/1d69118ba8b750f85bfc to your computer and use it in GitHub Desktop.
Example Runtime Spec

Operations

A conformant runtime should provide an executable (called funC in the following examples). The template for supported commands is:

$ funC [global-options] <COMMAND> [command-specific-options] <command-specific-arguments>

Global options

None are required, but the runtime may support options that start with at least one hyphen. Global options may take positional arguments (e.g. --log-level debug), but the option parsing must be such that funC <COMMAND> is unambiguously an invocation of <COMMAND> for any <COMMAND> that does not start with a hyphen (including commands not specified in this document).

Commands

version

  • Options None are required, but the runtime may support options.
  • Standard streams
    • stdin: The runtime may not attempt to read from its stdin.
    • stdout: The runtime must print its name, a space, and its version as the first line to its stdout. The name may contain any Unicode characters except a control codes and newlines. The runtime may print additional lines its stdout, and the format for those lines is not specified in this document.
    • stderr: The runtime may print diagnostic messages to stderr, and the format for those lines is not specified in this document.
  • Exit code: The runtime must exit with zero.

Print the runtime version and exit. The version

Example:

$ funC version
funC 1.0.0
Built for x86_64-pc-linux-gnu
$ echo $?
0

start

Starts a container from a bundle directory. It operates by default on the config.json and runtime.json in the current directory.

  • Options
    • --id <ID> Set the container ID when creating or joining a container. If not set, the runtime is free to pick any ID that is not already in use.
    • --config <PATH> Override config.json with an alternative path. The path may not support seeking (e.g. /dev/fd/3).
    • --runtime <PATH> Override runtime.json with an alternative path. The path may not support seeking (e.g. /dev/fd/3).
  • Standard streams: The runtime must attach its standard streams directly to the application process without inspection.
  • Environment variables
    • LISTEN_FDS: The number of file descriptors passed. For example, LISTEN_FDS=2 would mean passing 3 and 4 (in addition to the standard streams) to support socket activation.
  • Exit code: The runtime must exit with the application process's exit code.

Example:

# in a bundle directory with a process that echos "hello" and exits 42
$ funC start --id hello-1
hello
 
$ echo $?
42

exec

Runs a secondary process in the given container.

  • Options
    • --process <PATH> Override process.json with an alternative path. The path may not support seeking (e.g. /dev/fd/3).
  • Arguments
    • <ID> The container ID to join.
  • Standard streams: The runtime must attach its standard streams directly to the application process without inspection.
  • Exit code: The runtime must exit with the application process's exit code.

If the main application (launched by start) dies, all other processes in its container will be killed [TODO: link to lifecycle docs explaining this].

Example:

# in a directory with a process.json that echos "goodbye" and exits 43
$ funC exec hello-1
goodbye
$ echo $?
43

pause

Pause all processes in a container.

  • Options
    • --wait Block until the process is completely paused. Otherwise return immediately after initiating the pause, which may happen before the pause is complete.
  • Arguments
    • <ID> The container ID to join.
  • Exit code: 0 on success, non-zero on error.

Example:

$ funC pause --wait hello-1
$ echo $?
0

resume

Unpause all processes in a container.

  • Options
    • --wait Block until the process is completely unpaused. Otherwise return immediately after initiating the unpause, which may happen before the unpause is complete.
  • Arguments
    • <ID> The container ID to join.
  • Exit code: 0 on success, non-zero on error.

Example:

$ funC resume hello-1
$ echo $?
0

signal

Sends a signal to the container.

  • Options
    • --signal <SIGNAL> The signal to send. This must be one of the valid POSIX signals, although runtimes on non-POSIX systems must translate the POSIX name to their platorm's analogous signal. Defaults to TERM.
  • Arguments
    • <ID> The container ID to join.
  • Exit code: 0 on success, non-zero on error. A 0 exit status does not imply the process has exited (as it may have caught the signal).

Example:

$ funC signal --signal KILL hello-1
$ echo $?
0
@justincormack
Copy link

"Exit code: The runtime must exit with the application process's exit code." - what happens if the command is unable to run the application for start and exec? eg it is not a valid/suitable executable or is missing? Some way of signalling errors before the application is started will be needed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment