From a7ced84b84f9851875fcaf30ead5508ed25e359b Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Wed, 15 Oct 2025 22:30:21 -0500 Subject: [PATCH 01/19] update --- SPEC.md | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/SPEC.md b/SPEC.md index 5f50096..df45940 100644 --- a/SPEC.md +++ b/SPEC.md @@ -6,7 +6,7 @@ The Nexus protocol, as specified below, is a synchronous RPC protocol for system duration operations are modelled on top of a set of pre-defined synchronous RPCs. A Nexus **caller** calls a **handler**. The handler may respond inline (synchronous response) or return a token -referencing the ongoing operation (asynchronous response), which the the caller use to cancel the operation. In lieu of +referencing the ongoing operation (asynchronous response), which the caller may use to cancel the operation. In lieu of a higher level service contract, the caller cannot determine whether an operation is going to resolve synchronously or asynchronously, and should specify a callback URL, which the handler uses to deliver the result of an asynchronous operation when it is ready. @@ -111,6 +111,11 @@ Headers that start with the `Nexus-Callback-` prefix are expected to be attached the handler. The callback request must strip away the `Nexus-Callback-` prefix. E.g if a Start Operation request includes a `Nexus-Callback-Token: some-token` header, the callback request would include a `Token: some-token` header. +The `Nexus-Callback-Token` header is **REQUIRED**. +It MUST contain a caller-generated token that uniquely identifies the originating operation. +Handlers MUST include this header’s value as a `Token` header in all callback requests to the caller-provided `callback` +URL. This header allows correlation between callback requests and their originating operations. + The `Operation-Timeout` header field can be added to inform the handler how long the caller is willing to wait for an operation to complete. This is distinct from the more general `Request-Timeout` header which is used to indicate the timeout for a single HTTP request. Format of this header value is number + unit, where unit can be `ms` for @@ -197,7 +202,7 @@ Operation Error [`Failure`](#failure) representation is as follows: "cause": { /* */ }, "details": { "state": "canceled | failed", - // Aribtrary details may be added here as needed. + // Arbitrary details may be added here as needed. }, } ``` @@ -221,14 +226,14 @@ Handler Error [`Failure`](#failure) representation is as follows: "details": { "type": " Date: Wed, 15 Oct 2025 22:36:16 -0500 Subject: [PATCH 02/19] format spec --- SPEC.md | 39 +++++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/SPEC.md b/SPEC.md index df45940..046ac0b 100644 --- a/SPEC.md +++ b/SPEC.md @@ -111,10 +111,10 @@ Headers that start with the `Nexus-Callback-` prefix are expected to be attached the handler. The callback request must strip away the `Nexus-Callback-` prefix. E.g if a Start Operation request includes a `Nexus-Callback-Token: some-token` header, the callback request would include a `Token: some-token` header. -The `Nexus-Callback-Token` header is **REQUIRED**. -It MUST contain a caller-generated token that uniquely identifies the originating operation. -Handlers MUST include this header’s value as a `Token` header in all callback requests to the caller-provided `callback` -URL. This header allows correlation between callback requests and their originating operations. +The `Nexus-Callback-Token` header is **REQUIRED**. It MUST contain a caller-generated token that uniquely identifies the +originating operation. Handlers MUST include this header’s value as a `Token` header in all callback requests to the +caller-provided `callback` URL. This header allows correlation between callback requests and their originating +operations. The `Operation-Timeout` header field can be added to inform the handler how long the caller is willing to wait for an operation to complete. This is distinct from the more general `Request-Timeout` header which is used to indicate the @@ -236,19 +236,19 @@ Handler Error [`Failure`](#failure) representation is as follows: For compatibility 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. | +| 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. This 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. This 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. | +| `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 occurred. 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. | +| `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` @@ -297,9 +297,11 @@ For invoking a callback URL: - Issue a POST request to the caller-provided URL. - Include any callback headers supplied in the originating StartOperation request, stripping away the `Nexus-Callback-` prefix. + * The callback request **MUST include** a `Token` header derived from the required `Nexus-Callback-Token` header in the - originating StartOperation request. This header uniquely associates the callback with its originating operation and is mandatory for all callback - deliveries. + originating StartOperation request. This header uniquely associates the callback with its originating operation and is + mandatory for all callback deliveries. + - Include the following headers for resources associated with this operation to support completing asynchronous operations before the response to StartOperation is received: @@ -317,9 +319,10 @@ For invoking a callback URL: - RFC 3339 timestamps and ISO 8601 timestamps are usually compatible, but some edge cases may apply [[1](https://protobuf.dev/programming-guides/json/#rfc3339), [2](https://ijmacd.github.io/rfc3339-iso8601/)]. - Include the `Nexus-Operation-State` header. -- If state is `succeeded`, deliver non-empty results in the body with corresponding `Content-*` headers. - If state is `failed` or `canceled`, content type should be `application/json` and the body must have a serialized +- If state is `succeeded`, deliver non-empty results in the body with corresponding `Content-*` headers. If state is + `failed` or `canceled`, content type should be `application/json` and the body must have a serialized [`Failure`](#failure) object. + * Upon successful completion delivery, the handler should reply with a `200 OK` status and an empty body. ### Security From a54e2cdc2b7cf7a3c3211093cea5141a282a2ece Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Wed, 15 Oct 2025 22:44:48 -0500 Subject: [PATCH 03/19] add a spell checker --- .github/workflows/ci.yml | 6 ++++++ SPEC.md | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ed91b3c..c5d6ffc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -16,3 +16,9 @@ jobs: steps: - uses: actions/checkout@v3 - uses: dprint/check@v2.2 + + typos: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: crate-ci/typos@master diff --git a/SPEC.md b/SPEC.md index 046ac0b..31f07c8 100644 --- a/SPEC.md +++ b/SPEC.md @@ -161,7 +161,7 @@ The body may contain arbitrary data. Headers should specify content type and enc ### Cancel Operation Request to cancel an operation. The operation may later complete as canceled or any other outcome. Handlers should -ignore multiple cancelations of the same operation and return successfully if cancelation was already requested. +ignore multiple cancellations of the same operation and return successfully if cancellation was already requested. **Path**: `/{service}/{operation}/cancel` From 93dfca78eba8a2589f5a660538dddf78259526df Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Wed, 15 Oct 2025 22:46:41 -0500 Subject: [PATCH 04/19] v1 flag --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c5d6ffc..661f554 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -21,4 +21,4 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - - uses: crate-ci/typos@master + - uses: crate-ci/typos@v1 From 8a4afcf6aeae7b20686141ddb863f618592380d6 Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Thu, 16 Oct 2025 11:05:35 -0500 Subject: [PATCH 05/19] Apply suggestion from @chaptersix --- SPEC.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/SPEC.md b/SPEC.md index 31f07c8..bf3c9a2 100644 --- a/SPEC.md +++ b/SPEC.md @@ -319,8 +319,8 @@ For invoking a callback URL: - RFC 3339 timestamps and ISO 8601 timestamps are usually compatible, but some edge cases may apply [[1](https://protobuf.dev/programming-guides/json/#rfc3339), [2](https://ijmacd.github.io/rfc3339-iso8601/)]. - Include the `Nexus-Operation-State` header. -- If state is `succeeded`, deliver non-empty results in the body with corresponding `Content-*` headers. If state is - `failed` or `canceled`, content type should be `application/json` and the body must have a serialized +- If state is `succeeded`, deliver non-empty results in the body with corresponding `Content-*` headers. +- If state is `failed` or `canceled`, content type should be `application/json` and the body must have a serialized [`Failure`](#failure) object. * Upon successful completion delivery, the handler should reply with a `200 OK` status and an empty body. From 5fa74afb58ea6a61b4582a8a3440fc7012783603 Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Thu, 16 Oct 2025 11:06:48 -0500 Subject: [PATCH 06/19] Apply suggestion from @chaptersix --- SPEC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SPEC.md b/SPEC.md index bf3c9a2..8d1ce0d 100644 --- a/SPEC.md +++ b/SPEC.md @@ -323,7 +323,7 @@ For invoking a callback URL: - If state is `failed` or `canceled`, content type should be `application/json` and the body must have a serialized [`Failure`](#failure) object. -* Upon successful completion delivery, the handler should reply with a `200 OK` status and an empty body. +- Upon successful completion delivery, the handler should reply with a `200 OK` status and an empty body. ### Security From 6bcd4d1c082e610606775d0afbeb12f557dd3bb8 Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Thu, 16 Oct 2025 11:06:54 -0500 Subject: [PATCH 07/19] Apply suggestion from @chaptersix --- SPEC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SPEC.md b/SPEC.md index 8d1ce0d..773cc1d 100644 --- a/SPEC.md +++ b/SPEC.md @@ -298,7 +298,7 @@ For invoking a callback URL: - Include any callback headers supplied in the originating StartOperation request, stripping away the `Nexus-Callback-` prefix. -* The callback request **MUST include** a `Token` header derived from the required `Nexus-Callback-Token` header in the +- The callback request **MUST include** a `Token` header derived from the required `Nexus-Callback-Token` header in the originating StartOperation request. This header uniquely associates the callback with its originating operation and is mandatory for all callback deliveries. From accb8824dcfe874cb4da626a6b405cdd9f7acf9e Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Thu, 16 Oct 2025 11:07:17 -0500 Subject: [PATCH 08/19] Apply suggestion from @chaptersix --- SPEC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SPEC.md b/SPEC.md index 773cc1d..0616d78 100644 --- a/SPEC.md +++ b/SPEC.md @@ -319,7 +319,7 @@ For invoking a callback URL: - RFC 3339 timestamps and ISO 8601 timestamps are usually compatible, but some edge cases may apply [[1](https://protobuf.dev/programming-guides/json/#rfc3339), [2](https://ijmacd.github.io/rfc3339-iso8601/)]. - Include the `Nexus-Operation-State` header. -- If state is `succeeded`, deliver non-empty results in the body with corresponding `Content-*` headers. +- If state is `succeeded`, deliver non-empty results in the body with corresponding `Content-*` headers. - If state is `failed` or `canceled`, content type should be `application/json` and the body must have a serialized [`Failure`](#failure) object. From 56f9c0d56ab421a5829410b542047856799437aa Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Thu, 16 Oct 2025 11:07:34 -0500 Subject: [PATCH 09/19] Apply suggestion from @chaptersix --- SPEC.md | 1 - 1 file changed, 1 deletion(-) diff --git a/SPEC.md b/SPEC.md index 0616d78..505dbaa 100644 --- a/SPEC.md +++ b/SPEC.md @@ -322,7 +322,6 @@ For invoking a callback URL: - If state is `succeeded`, deliver non-empty results in the body with corresponding `Content-*` headers. - If state is `failed` or `canceled`, content type should be `application/json` and the body must have a serialized [`Failure`](#failure) object. - - Upon successful completion delivery, the handler should reply with a `200 OK` status and an empty body. ### Security From d3855a7c45127f8e4bdaf302be4bf215b3e16a4f Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Thu, 16 Oct 2025 11:07:49 -0500 Subject: [PATCH 10/19] Apply suggestion from @chaptersix --- SPEC.md | 1 - 1 file changed, 1 deletion(-) diff --git a/SPEC.md b/SPEC.md index 505dbaa..d39703e 100644 --- a/SPEC.md +++ b/SPEC.md @@ -315,7 +315,6 @@ For invoking a callback URL: or unsuccessfully). The header's value must be a [valid RFC 3339 format timestamp](https://datatracker.ietf.org/doc/html/rfc3339#section-5), with a resolution of milliseconds or finer. - - RFC 3339 timestamps and ISO 8601 timestamps are usually compatible, but some edge cases may apply [[1](https://protobuf.dev/programming-guides/json/#rfc3339), [2](https://ijmacd.github.io/rfc3339-iso8601/)]. - Include the `Nexus-Operation-State` header. From cc708e3993b04d6a5b8909735ae0d6de9d984fcf Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Thu, 16 Oct 2025 11:08:20 -0500 Subject: [PATCH 11/19] Apply suggestion from @chaptersix --- SPEC.md | 1 - 1 file changed, 1 deletion(-) diff --git a/SPEC.md b/SPEC.md index d39703e..dfb5e0e 100644 --- a/SPEC.md +++ b/SPEC.md @@ -304,7 +304,6 @@ For invoking a callback URL: - Include the following headers for resources associated with this operation to support completing asynchronous operations before the response to StartOperation is received: - - `Nexus-Operation-Token` - `Nexus-Operation-Start-Time` - any `Nexus-Link` headers From 82d1cf49061d57030034b89ee1265d9235b6e660 Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Thu, 16 Oct 2025 11:30:45 -0500 Subject: [PATCH 12/19] Update SPEC.md Co-authored-by: Roey Berman --- SPEC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SPEC.md b/SPEC.md index dfb5e0e..e3b7a9d 100644 --- a/SPEC.md +++ b/SPEC.md @@ -111,7 +111,7 @@ Headers that start with the `Nexus-Callback-` prefix are expected to be attached the handler. The callback request must strip away the `Nexus-Callback-` prefix. E.g if a Start Operation request includes a `Nexus-Callback-Token: some-token` header, the callback request would include a `Token: some-token` header. -The `Nexus-Callback-Token` header is **REQUIRED**. It MUST contain a caller-generated token that uniquely identifies the +If a callback query parameter is provided, the `Nexus-Callback-Token` header is **REQUIRED**. It MUST contain a caller-generated token that uniquely identifies the originating operation. Handlers MUST include this header’s value as a `Token` header in all callback requests to the caller-provided `callback` URL. This header allows correlation between callback requests and their originating operations. From bbd40509f01c9a7848b9b87b100a99a960f73bc2 Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Thu, 16 Oct 2025 11:42:19 -0500 Subject: [PATCH 13/19] fmt --- SPEC.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/SPEC.md b/SPEC.md index e3b7a9d..4d17d29 100644 --- a/SPEC.md +++ b/SPEC.md @@ -111,10 +111,10 @@ Headers that start with the `Nexus-Callback-` prefix are expected to be attached the handler. The callback request must strip away the `Nexus-Callback-` prefix. E.g if a Start Operation request includes a `Nexus-Callback-Token: some-token` header, the callback request would include a `Token: some-token` header. -If a callback query parameter is provided, the `Nexus-Callback-Token` header is **REQUIRED**. It MUST contain a caller-generated token that uniquely identifies the -originating operation. Handlers MUST include this header’s value as a `Token` header in all callback requests to the -caller-provided `callback` URL. This header allows correlation between callback requests and their originating -operations. +If a callback query parameter is provided, the `Nexus-Callback-Token` header is **REQUIRED**. It MUST contain a +caller-generated token that uniquely identifies the originating operation. Handlers MUST include this header’s value as +a `Token` header in all callback requests to the caller-provided `callback` URL. This header allows correlation between +callback requests and their originating operations. The `Operation-Timeout` header field can be added to inform the handler how long the caller is willing to wait for an operation to complete. This is distinct from the more general `Request-Timeout` header which is used to indicate the From 64afed1382ce02567f21b05292ef51d42817a5c7 Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Thu, 16 Oct 2025 11:51:19 -0500 Subject: [PATCH 14/19] typo config --- _typos.toml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 _typos.toml diff --git a/_typos.toml b/_typos.toml new file mode 100644 index 0000000..ca2f31a --- /dev/null +++ b/_typos.toml @@ -0,0 +1,18 @@ +# Configuration for typos spell checker +# See: https://github.com/crate-ci/typos + +[default] +# Ensure we check binary file names +binary = false + + +[default.extend-words] +# Add custom dictionary entries here for intentional "misspellings" used in the codebase +# Common Go/Nexus specific terms that may be flagged as typos +cancelation = "cancelation" # Common alternate spelling of cancellation used in the spec + +[files] +extend-exclude = [ + "*.svg", +] + From c13501bfae55c7be227fbb9c48c693140e736bc0 Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Thu, 16 Oct 2025 17:31:34 -0500 Subject: [PATCH 15/19] Update SPEC.md --- SPEC.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/SPEC.md b/SPEC.md index 4d17d29..5b3df2c 100644 --- a/SPEC.md +++ b/SPEC.md @@ -112,10 +112,8 @@ the handler. The callback request must strip away the `Nexus-Callback-` prefix. includes a `Nexus-Callback-Token: some-token` header, the callback request would include a `Token: some-token` header. If a callback query parameter is provided, the `Nexus-Callback-Token` header is **REQUIRED**. It MUST contain a -caller-generated token that uniquely identifies the originating operation. Handlers MUST include this header’s value as -a `Token` header in all callback requests to the caller-provided `callback` URL. This header allows correlation between -callback requests and their originating operations. - +caller-generated token that is used to recreate context when processing the callback. Handlers MUST include this header’s value as +a `Token` header when invoking Callback requests. The `Operation-Timeout` header field can be added to inform the handler how long the caller is willing to wait for an operation to complete. This is distinct from the more general `Request-Timeout` header which is used to indicate the timeout for a single HTTP request. Format of this header value is number + unit, where unit can be `ms` for From f4bf4cea738a8a150455953d8e400ec31a50a3ed Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Thu, 16 Oct 2025 17:42:37 -0500 Subject: [PATCH 16/19] fmt --- SPEC.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/SPEC.md b/SPEC.md index 5b3df2c..3315811 100644 --- a/SPEC.md +++ b/SPEC.md @@ -112,12 +112,11 @@ the handler. The callback request must strip away the `Nexus-Callback-` prefix. includes a `Nexus-Callback-Token: some-token` header, the callback request would include a `Token: some-token` header. If a callback query parameter is provided, the `Nexus-Callback-Token` header is **REQUIRED**. It MUST contain a -caller-generated token that is used to recreate context when processing the callback. Handlers MUST include this header’s value as -a `Token` header when invoking Callback requests. -The `Operation-Timeout` header field can be added to inform the handler how long the caller is willing to wait for an -operation to complete. This is distinct from the more general `Request-Timeout` header which is used to indicate the -timeout for a single HTTP request. Format of this header value is number + unit, where unit can be `ms` for -milliseconds, `s` for seconds, and `m` for minutes. +caller-generated token that is used to recreate context when processing the callback. Handlers MUST include this +header’s value as a `Token` header when invoking Callback requests. The `Operation-Timeout` header field can be added to +inform the handler how long the caller is willing to wait for an operation to complete. This is distinct from the more +general `Request-Timeout` header which is used to indicate the timeout for a single HTTP request. Format of this header +value is number + unit, where unit can be `ms` for milliseconds, `s` for seconds, and `m` for minutes. The `Nexus-Link` header field can be added to associate resources with the start request. A handler may attach these links as metadata to underlying resources to provide end-to-end observability. See the [`Nexus-Link`](#nexus-link) From 0737024b45e9d50fe7422689f8ea6df25ee3c6e1 Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Fri, 17 Oct 2025 09:25:34 -0500 Subject: [PATCH 17/19] fmt --- SPEC.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/SPEC.md b/SPEC.md index 3315811..b4e5a67 100644 --- a/SPEC.md +++ b/SPEC.md @@ -113,10 +113,12 @@ includes a `Nexus-Callback-Token: some-token` header, the callback request would If a callback query parameter is provided, the `Nexus-Callback-Token` header is **REQUIRED**. It MUST contain a caller-generated token that is used to recreate context when processing the callback. Handlers MUST include this -header’s value as a `Token` header when invoking Callback requests. The `Operation-Timeout` header field can be added to -inform the handler how long the caller is willing to wait for an operation to complete. This is distinct from the more -general `Request-Timeout` header which is used to indicate the timeout for a single HTTP request. Format of this header -value is number + unit, where unit can be `ms` for milliseconds, `s` for seconds, and `m` for minutes. +header’s value as a `Token` header when invoking Callback requests. + +The `Operation-Timeout` header field can be added to inform the handler how long the caller is willing to wait for an +operation to complete. This is distinct from the more general `Request-Timeout` header which is used to indicate the +timeout for a single HTTP request. Format of this header value is number + unit, where unit can be `ms` for +milliseconds, `s` for seconds, and `m` for minutes. The `Nexus-Link` header field can be added to associate resources with the start request. A handler may attach these links as metadata to underlying resources to provide end-to-end observability. See the [`Nexus-Link`](#nexus-link) From 3526939261ef2d1872ce951902d90db508c9cfe7 Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Fri, 17 Oct 2025 09:30:39 -0500 Subject: [PATCH 18/19] fix ci config --- _typos.toml => .github/workflows/_typos.toml | 0 .github/workflows/ci.yml | 2 ++ 2 files changed, 2 insertions(+) rename _typos.toml => .github/workflows/_typos.toml (100%) diff --git a/_typos.toml b/.github/workflows/_typos.toml similarity index 100% rename from _typos.toml rename to .github/workflows/_typos.toml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 661f554..cf36d5b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -22,3 +22,5 @@ jobs: steps: - uses: actions/checkout@v3 - uses: crate-ci/typos@v1 + with: + config: ./.github/workflows/_typos.toml From 61db2236f5fa2a9df1c459b23fae813cac8d3fe5 Mon Sep 17 00:00:00 2001 From: Alex Stanfield <13949480+chaptersix@users.noreply.github.com> Date: Mon, 17 Nov 2025 12:31:25 -0600 Subject: [PATCH 19/19] Update SPEC.md --- SPEC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SPEC.md b/SPEC.md index b4e5a67..8d8cacf 100644 --- a/SPEC.md +++ b/SPEC.md @@ -111,7 +111,7 @@ Headers that start with the `Nexus-Callback-` prefix are expected to be attached the handler. The callback request must strip away the `Nexus-Callback-` prefix. E.g if a Start Operation request includes a `Nexus-Callback-Token: some-token` header, the callback request would include a `Token: some-token` header. -If a callback query parameter is provided, the `Nexus-Callback-Token` header is **REQUIRED**. It MUST contain a +If a callback query parameter is provided, the `Nexus-Callback-Token` header is **OPTIONAL**. It MAY contain a caller-generated token that is used to recreate context when processing the callback. Handlers MUST include this header’s value as a `Token` header when invoking Callback requests.