diff --git a/SPEC.md b/SPEC.md index c6e10ce..5f50096 100644 --- a/SPEC.md +++ b/SPEC.md @@ -43,6 +43,10 @@ properties: type: string description: A simple text message. + stackTrace: + type: string + description: An optional stack trace that may be emitted in languages that support it. + metadata: type: object additionalProperties: @@ -55,6 +59,10 @@ properties: properties: description: | Additional JSON-serializable structured data. + + cause: + # An optional nested failure structure. + $ref: '#' ``` ### OperationInfo @@ -141,17 +149,9 @@ The body may contain arbitrary data. Headers should specify content type and enc **Headers**: - `Content-Type: application/json` - - `Nexus-Operation-State: failed | canceled` - - **Body**: A JSON-serialized [`Failure`](#failure) object. + - `Nexus-Operation-State: failed | canceled` (DEPRECATED) -- `409 Conflict`: Operation was already started with a different request ID. - - **Headers**: - - - `Content-Type: application/json` - - **Body**: A JSON-serialized [`Failure`](#failure) object. + **Body**: A JSON-serialized [`Failure`](#failure) object representing an [`OperationError`](#operation-error). ### Cancel Operation @@ -178,33 +178,80 @@ The operation token received as a response to the Start Operation method must be **Body**: Empty. -- `404 Not Found`: Operation token not recognized or references deleted. +## Predefined Failure Types - **Headers**: +### `OperationError` - - `Content-Type: application/json` +An Operation Error represents a failed or canceled operation outcome. It may be returned responses to `StartOperation` +requests, and in the body of async completion requests. + +Operation Error [`Failure`](#failure) representation is as follows: - **Body**: A JSON serialized [`Failure`](#failure) object. +```json +{ + "metadata": { + "type": "nexus.OperationError", + }, + "message": "", + "stackTrace": "", + "cause": { /* */ }, + "details": { + "state": "canceled | failed", + // Aribtrary details may be added here as needed. + }, +} +``` + +### `HandlerError` + +A HandlerError represents errors while handling a request. They include an error type as defined +[below](#predefined-handler-errors). Each error type has predefined, overridable, retry semantics. Handler Errors can be +returned responses to any of the methods defined above as well as completion callbacks. + +Handler Error [`Failure`](#failure) representation is as follows: + +```json +{ + "metadata": { + "type": "nexus.HandlerError", + }, + "message": "", + "stackTrace": "", + "cause": { /* */ }, + "details": { + "type": "; type="com.example.MyResource"` -### `Nexus-Request-Retryable` +### `Nexus-Request-Retryable` (DEPRECATED) Handlers may specify the `Nexus-Request-Retryable` header with a value of `true` or `false` to explicitly instruct a caller whether or not to retry a request. Unless specified, retry behavior is determined by the