From f9177b872d8fab320b100c4c82a0e32351146047 Mon Sep 17 00:00:00 2001 From: Roey Berman Date: Mon, 4 Aug 2025 17:34:30 -0700 Subject: [PATCH 1/3] Add more failure attributes and specific errors --- SPEC.md | 113 +++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 83 insertions(+), 30 deletions(-) diff --git a/SPEC.md b/SPEC.md index c6e10ce..69505ff 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. - -- `409 Conflict`: Operation was already started with a different request ID. - - **Headers**: - - - `Content-Type: application/json` + - `Nexus-Operation-State: failed | canceled` (DEPRECATED) - **Body**: A JSON-serialized [`Failure`](#failure) object. + **Body**: A JSON-serialized [`Failure`](#failure) object representing an [`OperationError`](#operation-error). ### Cancel Operation @@ -178,33 +178,79 @@ 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. - **Body**: A JSON serialized [`Failure`](#failure) object. +Operation Error [`Failure`](#failure) representation is as follows: -## Predefined Handler Errors +```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 @@ -234,6 +280,13 @@ a response. Format of this header value is number + unit, where unit can be `ms` for milliseconds, `s` for seconds, and `m` for minutes. +## General Purpose Response Codes + +### `408 Request Timeout` + +Returned by the server to when it has given up handling a request. The may occur by enforcing a client provided +`Request-Timeout` or for any arbitrary reason such as enforcing some configurable limit. + ## Callback URLs Any HTTP URL can be used to deliver operation completions. From a2addbd1665cd7bd5903fdd44d296705a0fede74 Mon Sep 17 00:00:00 2001 From: Roey Berman Date: Fri, 10 Oct 2025 11:54:07 -0700 Subject: [PATCH 2/3] Add REQUEST_TIMEOUT handler error --- SPEC.md | 32 +++++++++++++------------------- 1 file changed, 13 insertions(+), 19 deletions(-) diff --git a/SPEC.md b/SPEC.md index 69505ff..26d63f5 100644 --- a/SPEC.md +++ b/SPEC.md @@ -231,18 +231,19 @@ Handler Error [`Failure`](#failure) representation is as follows: For compatiblity of this HTTP spec with future transports, when a handler fails a request, it **should** use one of the following predefined error codes. -| Name | Status Code | Description | -| -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `BAD_REQUEST` | 400 | The handler cannot or will not process the request due to an apparent client error. Clients should not retry this request unless advised otherwise. | -| `UNAUTHENTICATED` | 401 | The client did not supply valid authentication credentials for this request. Clients should not retry this request unless advised otherwise. | -| `UNAUTHORIZED` | 403 | The caller does not have permission to execute the specified operation. Clients should not retry this request unless advised otherwise. | -| `NOT_FOUND` | 404 | The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible but not advised. | -| `CONFLICT` | 409 | The request could not be made due to a conflict. The may happen when trying to create an operation that has already been started. Clients should not retry this request unless advised otherwise. | -| `RESOURCE_EXHAUSTED` | 429 | Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. Subsequent requests by the client are permissible. | -| `INTERNAL` | 500 | An internal error occured. Subsequent requests by the client are permissible. | -| `NOT_IMPLEMENTED` | 501 | The handler either does not recognize the request method, or it lacks the ability to fulfill the request. Clients should not retry this request unless advised otherwise. | -| `UNAVAILABLE` | 503 | The service is currently unavailable. Subsequent requests by the client are permissible. | -| `UPSTREAM_TIMEOUT` | 520 | Used by gateways to report that a request to an upstream handler has timed out. Subsequent requests by the client are permissible. | +| Name | Status Code | Description | +| -------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `BAD_REQUEST` | 400 | The handler cannot or will not process the request due to an apparent client error. Clients should not retry this request unless advised otherwise. | +| `UNAUTHENTICATED` | 401 | The client did not supply valid authentication credentials for this request. Clients should not retry this request unless advised otherwise. | +| `UNAUTHORIZED` | 403 | The caller does not have permission to execute the specified operation. Clients should not retry this request unless advised otherwise. | +| `NOT_FOUND` | 404 | The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible but not advised. | +| `REQUEST_TIMEOUT` | 408 | Returned by the server to when it has given up handling a request. The may occur by enforcing a client provided `Request-Timeout` or for any arbitrary reason such as enforcing some configurable limit. Subsequent requests by the client are permissible. | +| `CONFLICT` | 409 | The request could not be made due to a conflict. The may happen when trying to create an operation that has already been started. Clients should not retry this request unless advised otherwise. | +| `RESOURCE_EXHAUSTED` | 429 | Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. Subsequent requests by the client are permissible. | +| `INTERNAL` | 500 | An internal error occured. Subsequent requests by the client are permissible. | +| `NOT_IMPLEMENTED` | 501 | The handler either does not recognize the request method, or it lacks the ability to fulfill the request. Clients should not retry this request unless advised otherwise. | +| `UNAVAILABLE` | 503 | The service is currently unavailable. Subsequent requests by the client are permissible. | +| `UPSTREAM_TIMEOUT` | 520 | Used by gateways to report that a request to an upstream handler has timed out. Subsequent requests by the client are permissible. | Client implementations should try to rehydrate a `HandlerError` from the serialized `Failure` object in the response body whenever a request fails with one of the status codes listed below. If the handler error type in the `Failure` @@ -280,13 +281,6 @@ a response. Format of this header value is number + unit, where unit can be `ms` for milliseconds, `s` for seconds, and `m` for minutes. -## General Purpose Response Codes - -### `408 Request Timeout` - -Returned by the server to when it has given up handling a request. The may occur by enforcing a client provided -`Request-Timeout` or for any arbitrary reason such as enforcing some configurable limit. - ## Callback URLs Any HTTP URL can be used to deliver operation completions. From 40c81cf53b830747aacb5108d27c036e6cc4a5c6 Mon Sep 17 00:00:00 2001 From: Roey Berman Date: Fri, 10 Oct 2025 14:54:08 -0700 Subject: [PATCH 3/3] H4 to H3 --- SPEC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SPEC.md b/SPEC.md index 26d63f5..5f50096 100644 --- a/SPEC.md +++ b/SPEC.md @@ -226,7 +226,7 @@ Handler Error [`Failure`](#failure) representation is as follows: } ``` -#### Predefined Handler Errors +### Predefined Handler Errors For compatiblity of this HTTP spec with future transports, when a handler fails a request, it **should** use one of the following predefined error codes.