runtime: Add an 'event' operation for subscribing to pushes

runtime.md

@@ -7,25 +7,28 @@ Whether other entities using the same, or other, instance of the runtime can see
 
 ## State
 
-The state of a container MUST include, at least, the following properties:
+The state of a container includes the following properties:
 
-* **`ociVersion`**: (string) is the OCI specification version used when creating the container.
-* **`id`**: (string) is the container's ID.
+* **`ociVersion`** (string, required) is the OCI specification version used when creating the container.
+* **`id`** (string, required) is the container's ID.
 This MUST be unique across all containers on this host.
 There is no requirement that it be unique across hosts.
-* **`status`**: (string) is the runtime state of the container.
+* **`status`** (string, required) is the runtime state of the container.
 The value MAY be one of:
-  * `created` : the container has been created but the user-specified code has not yet been executed
-  * `running` : the container has been created and the user-specified code is running
-  * `stopped` : the container has been created and the user-specified code has been executed but is no longer running
+  * `creating` : the container is being created (step 2 in the [lifecycle](#lifecycle))
+  * `created` : the runtime has finished the [create operation](#create) (after step 2 in the [lifecycle](#lifecycle)), and the container process has neither exited nor executed the user-specified code
+  * `running` : the container process has executed the user-specified code but has not exited (after step 4 in the [lifecycle](#lifecycle))
+  * `stopped` : the container process has exited (step 5 in the [lifecycle](#lifecycle))
 
   Additional values MAY be defined by the runtime, however, they MUST be used to represent new runtime states not defined above.
-* **`pid`**: (int) is the ID of the main process within the container, as seen by the host.
-* **`bundlePath`**: (string) is the absolute path to the container's bundle directory.
+* **`pid`** (int, required when `status` is `created` or `running`) is the ID of the main process within the container, as seen by the host.
+* **`bundlePath`**: (string, required) is the absolute path to the container's bundle directory.
 This is provided so that consumers can find the container's configuration and root filesystem on the host.
-* **`annotations`**: (map) contains the list of annotations associated with the container.
+* **`annotations`**: (map, required) contains the list of annotations associated with the container.
 If no annotations were provided then this property MAY either be absent or an empty map.
 
+The state MAY include additional properties.
+
 When serialized in JSON, the format MUST adhere to the following pattern:
 
 ```json
@@ -55,8 +58,8 @@ The lifecycle describes the timeline of events that happen from when a container
    However, some actions might only be available based on the current state of the container (e.g. only available while it is started).
 4. Runtime's `start` command is invoked with the unique identifier of the container.
    The runtime MUST run the user-specified code, as specified by [`process`](config.md#process-configuration).
-5. The container's process is stopped.
-   This MAY happen due to them erroring out, exiting, crashing or the runtime's `kill` operation being invoked.
+5. The container process exits.
+   This MAY happen due to erroring out, exiting, crashing or the runtime's `kill` operation being invoked.
 6. Runtime's `delete` command is invoked with the unique identifier of the container.
    The container MUST be destroyed by undoing the steps performed during create phase (step 2).
 
@@ -79,9 +82,38 @@ This operation MUST generate an error if it is not provided the ID of a containe
 Attempting to query a container that does not exist MUST generate an error.
 This operation MUST return the state of a container as specified in the [State](#state) section.
 
+### Event
+
+`event <container-id>`
+
+This operation MUST generate an error if it is not provided the ID of a container.
+Attempting to query a container that does not exist MUST generate an error.
+This operation MUST subscribe the caller to push-notification about future events in chronological order.
+If the container's [create operation](#create) requested an event buffer, the buffered events MUST be published in chronological order before any future events are published.
+If the runtime could not perform the requested buffering, it MUST generate an error.
+Events MUST be published when the container's [`status`](#state) changes, and MAY be published for additional events.
+Events MUST include, at least, the following properties:
+
+* **`type`** (string, required) The type of the event.
+  For the following [`status`](#state) transitions, the `type` values MUST be:
+
+    * `creating` → `created`: `created`
+    * `created` → `running`: `started`
+    * * → `stopped`: `stopped`
+
+  A `deleted` event MUST be published after a successful [delete operation](#delete), after which further events MUST NOT be generated.
+
+* **`id`** (string, required) The ID of the container which experienced the event.
+* **`timestamp`** (string, required) The time at which the event took place in [`date-time` format as specified by RFC 3339][rfc3339-s5.6].
+
+The `started` and `stopped` transitions happen in the kernel, and there may be a lag before the runtime notices.
+For example, if the container process dies, a runtime which is [waiting][waitid.3p] on it will take some time in the `SIGCHLD` handler before adjusting the [state](#state).
+A runtime that detects transitions by polling the kernel may trail the associated kernel transition by an even longer period.
+So the `timestamp` and event publication may not exactly match the associated kernel transition, but they MUST match the [state](#state) transition.
+
 ### Create
 
-`create <container-id> <path-to-bundle>`
+`create <container-id> <path-to-bundle> <event-buffer>`
 
 This operation MUST generate an error if it is not provided a path to the bundle and the container ID to associate with the container.
 If the ID provided is not unique across all containers within the scope of the runtime, or is not valid in any other way, the implementation MUST generate an error and a new container MUST not be created.
@@ -95,6 +127,8 @@ Runtime callers who are interested in pre-create validation can run [bundle-vali
 
 Any changes made to the [`config.json`](config.md) file after this operation will not have an effect on the container.
 
+Runtime callers MAY request an event buffer, in which case the runtime MUST buffer events associated with the container.
+
 ### Start
 `start <container-id>`
 
@@ -128,3 +162,7 @@ Once a container is deleted its ID MAY be used by a subsequent container.
 ## Hooks
 Many of the operations specified in this specification have "hooks" that allow for additional actions to be taken before or after each operation.
 See [runtime configuration for hooks](./config.md#hooks) for more information.
+
+[rfc3339-s5.6]: https://tools.ietf.org/html/rfc3339#section-5.6
+
+[waitid.3p]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/waitid.html