Merge pull request #532 from wking/tk/restore-hook-lifecycle

Restore hook language removed by create/start split

Author: crosbymichael

config.md

@@ -368,23 +368,18 @@ The [state](runtime.md#state) of the container MUST be passed to hooks over stdi
 
 ### <a name="configHooksPrestart" />Prestart
 
-The pre-start hooks MUST be called after the container has been created, but before the user supplied command is executed.
+The pre-start hooks MUST be called after the [`start`](runtime.md#start) operation is called but [before the user-specified program command is executed](runtime.md#lifecycle).
 On Linux, for example, they are called after the container namespaces are created, so they provide an opportunity to customize the container (e.g. the network namespace could be specified in this hook).
 
-If a hook returns a non-zero exit code, an error including the exit code and the stderr MUST be returned to the caller and the container MUST be destroyed.
-
 ### <a name="configHooksPoststart" />Poststart
 
-The post-start hooks MUST be called after the user process is started.
+The post-start hooks MUST be called [after the user-specified process is executed](runtime#lifecycle) but before the [`start`](runtime.md#start) operation returns.
 For example, this hook can notify the user that the container process is spawned.
 
-If a hook returns a non-zero exit code, then an error MUST be logged and the remaining hooks are executed.
-
 ### <a name="configHooksPoststop" />Poststop
 
-The post-stop hooks MUST be called after the container process is stopped.
+The post-stop hooks MUST be called [after the container is deleted](runtime#lifecycle) but before the [`delete`](runtime.md#delete) operation returns.
 Cleanup or debugging functions are examples of such a hook.
-If a hook returns a non-zero exit code, then an error MUST be logged and the remaining hooks are executed.
 
 ### Example
 

runtime.md

@@ -52,23 +52,34 @@ The lifecycle describes the timeline of events that happen from when a container
 
 1. OCI compliant runtime's [`create`](runtime.md#create) command is invoked with a reference to the location of the bundle and a unique identifier.
 2. The container's runtime environment MUST be created according to the configuration in [`config.json`](config.md).
-   If the runtime is unable to create the environment specified in the [`config.json`](config.md), it MUST generate an error.
+   If the runtime is unable to create the environment specified in the [`config.json`](config.md), it MUST [generate an error](#errors).
    While the resources requested in the [`config.json`](config.md) MUST be created, the user-specified program (from [`process`](config.md#process)) MUST NOT be run at this time.
    Any updates to [`config.json`](config.md) after this step MUST NOT affect the container.
 3. Once the container is created additional actions MAY be performed based on the features the runtime chooses to support.
    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`](runtime.md#start) command is invoked with the unique identifier of the container.
-   The runtime MUST run the user-specified program, as specified by [`process`](config.md#process).
-5. The container process exits.
+5. The [prestart hooks](config.md#prestart) MUST be invoked by the runtime.
+   If any prestart hook fails, the runtime MUST [generate an error](#errors), stop the container, and continue the lifecycle at step 10.
+6. The runtime MUST run the user-specified program, as specified by [`process`](config.md#process).
+7. The [poststart hooks](config.md#poststart) MUST be invoked by the runtime.
+   If any poststart hook fails, the runtime MUST [log a warning](#warnings), but the remaining hooks and lifecycle continue as if the hook had succeeded.
+8. The container process exits.
    This MAY happen due to erroring out, exiting, crashing or the runtime's [`kill`](runtime.md#kill) operation being invoked.
-6. Runtime's [`delete`](runtime.md#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).
+9. Runtime's [`delete`](runtime.md#delete) command is invoked with the unique identifier of the container.
+10. The container MUST be destroyed by undoing the steps performed during create phase (step 2).
+11. The [poststop hooks](config.md#poststop) MUST be invoked by the runtime.
+    If any poststop hook fails, the runtime MUST [log a warning](#warnings), but the remaining hooks and lifecycle continue as if the hook had succeeded.
 
 ## <a name="runtimeErrors" />Errors
 
 In cases where the specified operation generates an error, this specification does not mandate how, or even if, that error is returned or exposed to the user of an implementation.
 Unless otherwise stated, generating an error MUST leave the state of the environment as if the operation were never attempted - modulo any possible trivial ancillary changes such as logging.
 
+## <a name="runtimeWarnings" />Warnings
+
+In cases where the specified operation logs a warning, this specification does not mandate how, or even if, that warning is returned or exposed to the user of an implementation.
+Unless otherwise stated, logging a warning does not change the flow of the operation; it MUST continue as if the warning had not been logged.
+
 ## <a name="runtimeOperations" />Operations
 
 OCI compliant runtimes MUST support the following operations, unless the operation is not supported by the base operating system.
@@ -79,19 +90,19 @@ Note: these operations are not specifying any command-line APIs, and the paramet
 
 `state <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 [generate an error](#errors) if it is not provided the ID of a container.
+Attempting to query a container that does not exist MUST [generate an error](#errors).
 This operation MUST return the state of a container as specified in the [State](#state) section.
 
 ### <a name="runtimeCreate" />Create
 
 `create <container-id> <path-to-bundle>`
 
-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.
+This operation MUST [generate an error](#errors) 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](#errors) and a new container MUST NOT be created.
 Using the data in [`config.json`](config.md), this operation MUST create a new container.
 This means that all of the resources associated with the container MUST be created, however, the user-specified program MUST NOT be run at this time.
-If the runtime cannot create the container as specified in [`config.json`](config.md), it MUST generate an error and a new container MUST NOT be created.
+If the runtime cannot create the container as specified in [`config.json`](config.md), it MUST [generate an error](#errors) and a new container MUST NOT be created.
 
 Upon successful completion of this operation the `status` property of this container MUST be `created`.
 
@@ -103,28 +114,28 @@ Any changes made to the [`config.json`](config.md) file after this operation wil
 ### <a name="runtimeStart" />Start
 `start <container-id>`
 
-This operation MUST generate an error if it is not provided the container ID.
-Attempting to start a container that does not exist MUST generate an error.
-Attempting to start an already started container MUST have no effect on the container and MUST generate an error.
+This operation MUST [generate an error](#errors) if it is not provided the container ID.
+Attempting to start a container that does not exist MUST [generate an error](#errors).
+Attempting to start an already started container MUST have no effect on the container and MUST [generate an error](#errors).
 This operation MUST run the user-specified program as specified by [`process`](config.md#process).
 
 Upon successful completion of this operation the `status` property of this container MUST be `running`.
 
 ### <a name="runtimeKill" />Kill
 `kill <container-id> <signal>`
 
-This operation MUST generate an error if it is not provided the container ID.
-Attempting to send a signal to a container that is not running MUST have no effect on the container and MUST generate an error.
+This operation MUST [generate an error](#errors) if it is not provided the container ID.
+Attempting to send a signal to a container that is not running MUST have no effect on the container and MUST [generate an error](#errors).
 This operation MUST send the specified signal to the process in the container.
 
 When the process in the container is stopped, irrespective of it being as a result of a `kill` operation or any other reason, the `status` property of this container MUST be `stopped`.
 
 ### <a name="runtimeDelete" />Delete
 `delete <container-id>`
 
-This operation MUST generate an error if it is not provided the container ID.
-Attempting to delete a container that does not exist MUST generate an error.
-Attempting to delete a container whose process is still running MUST generate an error.
+This operation MUST [generate an error](#errors) if it is not provided the container ID.
+Attempting to delete a container that does not exist MUST [generate an error](#errors).
+Attempting to delete a container whose process is still running MUST [generate an error](#errors).
 Deleting a container MUST delete the resources that were created during the `create` step.
 Note that resources associated with the container, but not created by this container, MUST NOT be deleted.
 Once a container is deleted its ID MAY be used by a subsequent container.