From 57d16cffbd3a6f6245d340a4e362c129d6dca1a8 Mon Sep 17 00:00:00 2001 From: Max Kurapov Date: Thu, 21 Nov 2024 13:56:37 +0100 Subject: [PATCH 1/2] deprecate sync ilp over http --- 0035-ilp-over-http/0035-ilp-over-http.md | 61 +++++++++++++++--------- 1 file changed, 39 insertions(+), 22 deletions(-) diff --git a/0035-ilp-over-http/0035-ilp-over-http.md b/0035-ilp-over-http/0035-ilp-over-http.md index a6bfbd9b..b6a28754 100644 --- a/0035-ilp-over-http/0035-ilp-over-http.md +++ b/0035-ilp-over-http/0035-ilp-over-http.md @@ -1,7 +1,7 @@ --- title: ILP Over HTTP type: working-draft -draft: 2 +draft: 3 --- # ILP Over HTTP @@ -16,7 +16,10 @@ Scaling Interledger infrastructure to handle large volumes of ILP packets requir In an ILP Over HTTP connection, both peers run HTTP servers with accessible HTTPS endpoints. When peering, the peers exchange their respective URLs, authentication tokens or TLS certificates, ILP addresses, and settlement-related details. -Each ILP Prepare packet is sent as the body of an HTTP request to the peer's server endpoint. ILP Fulfill or Reject packets are returned as the body of the HTTP response in synchronous mode, or sent in a separate HTTP request in asynchronous mode. +Each ILP Prepare packet is sent as the body of an HTTP request to the peer's server endpoint. The peer asynchronously returns ILP Fulfill or Reject packets in the body of a separate HTTP request. + +> **Note:** Returning ILP Fulfill or Reject packets synchronously in the HTTP response body of the original ILP Prepare request is considered deprecated. + ## Specification @@ -36,7 +39,6 @@ Host: bob.example Accept: application/octet-stream Content-Type: application/octet-stream Authorization: Bearer zxcljvoizuu09wqqpowipoalksdflksjdgxclvkjl0s909asdf -Prefer: respond-async Callback-Url: https://alice.example/incoming/ilp Request-Id: 42ee09c8-a6de-4ae3-8a47-4732b0cbb07b @@ -47,33 +49,18 @@ Request-Id: 42ee09c8-a6de-4ae3-8a47-4732b0cbb07b - **Host Header** — The standard [HTTP Host Header](https://tools.ietf.org/html/rfc2616#section-14.23) indicating the domain of the HTTP server the request is sent to. - **Content-Type / Accept Headers** — MUST be set to `application/octet-stream`. - **Body** — ILP Prepare encoded using OER, as specified in [RFC 27: Interledger Protocol V4](../0027-interledger-protocol-4/0027-interledger-protocol-4.md). - -Asynchronous mode uses these additional headers: - -- **Prefer** — MUST be set to `respond-async`. If omitted, the reply behavior defaults to synchronous mode. - **Request Id Header** — UUIDv4 to uniquely identify this ILP Prepare, and correlate the corresponding ILP Fulfill/Reject. -- **Callback URL Header** — Callback URL of the origin connector to send an asynchronous HTTP request with the ILP Fulfill/Reject. Required unless peers exchange the callback URL out-of-band. +- **Callback URL Header** — Callback URL of the origin connector to send an HTTP request with the ILP Fulfill/Reject. Required unless peers exchange the callback URL out-of-band. #### Response -In synchronous mode, the raw OER-encoded ILP Fulfill or Reject is returned within the body of the response: - -```http -HTTP/x.x 200 OK -Content-Type: application/octet-stream - -< Body: Binary OER-Encoded ILP Fulfill or Reject Packet > -``` - -If the request includes a `Prefer: respond-async` header, the recipient handling the ILP Prepare SHOULD choose to handle the packet asynchronously and return the corresponding ILP Fulfill/Reject in a separate outgoing HTTP request. - -If the request is semantically valid and the recipient chooses to handle it asynchronously, they MUST respond immediately that the ILP Prepare is accepted for processing, even if the packet will ultimately be rejected: +If the request is semantically valid, the recipient MUST respond immediately that the ILP Prepare is accepted for processing, even if the packet will ultimately be rejected: ```http HTTP/x.x 202 Accepted ``` -### Async ILP Fulfill/Reject Reply +### ILP Fulfill/Reject Reply #### Request @@ -117,7 +104,37 @@ The sender of the ILP Fulfill/Reject SHOULD ensure there are multiple attempts t An ILP Fulfill packet corresponds to a commitment which affects financial accounting balances. If an HTTP request carrying the ILP reply fails, such as due to a network connection error, retrying delivery of the ILP reply with [idempotence](https://en.wikipedia.org/wiki/Idempotence) can prevent balance inconsistencies between peers. -If the sender of an ILP Prepare expects an asynchronous reply, they should only process the first ILP reply they receive corresponding to the in-flight ILP Prepare. +The sender of the ILP Prepare should only process the first ILP reply they receive corresponding to the original ILP Prepare packet. + +### [Deprecated] Synchronous Mode + +#### ILP Prepare Request + +```http +POST /ilp HTTP/x.x +Host: bob.example +Accept: application/octet-stream +Content-Type: application/octet-stream +Authorization: Bearer zxcljvoizuu09wqqpowipoalksdflksjdgxclvkjl0s909asdf + +< Body: Binary OER-Encoded ILP Prepare Packet > +``` + +- **Path** — A connector MAY specify any HTTP path for their peer to send ILP packets to. +- **Host Header** — The standard [HTTP Host Header](https://tools.ietf.org/html/rfc2616#section-14.23) indicating the domain of the HTTP server the request is sent to. +- **Content-Type / Accept Headers** — MUST be set to `application/octet-stream`. +- **Body** — ILP Prepare encoded using OER, as specified in [RFC 27: Interledger Protocol V4](../0027-interledger-protocol-4/0027-interledger-protocol-4.md). + +#### ILP Fulfill/Reject Response + +The raw OER-encoded ILP Fulfill or Reject is returned within the body of the response: + +```http +HTTP/x.x 200 OK +Content-Type: application/octet-stream + +< Body: Binary OER-Encoded ILP Fulfill or Reject Packet > +``` ### Error Handling From b9732d69cdb2e858c6cbb358d606fbc4faf6813b Mon Sep 17 00:00:00 2001 From: Max Kurapov Date: Thu, 21 Nov 2024 18:29:55 +0100 Subject: [PATCH 2/2] docs: add details about backwards compatibility --- 0035-ilp-over-http/0035-ilp-over-http.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/0035-ilp-over-http/0035-ilp-over-http.md b/0035-ilp-over-http/0035-ilp-over-http.md index b6a28754..a71396da 100644 --- a/0035-ilp-over-http/0035-ilp-over-http.md +++ b/0035-ilp-over-http/0035-ilp-over-http.md @@ -39,6 +39,7 @@ Host: bob.example Accept: application/octet-stream Content-Type: application/octet-stream Authorization: Bearer zxcljvoizuu09wqqpowipoalksdflksjdgxclvkjl0s909asdf +Prefer: respond-async Callback-Url: https://alice.example/incoming/ilp Request-Id: 42ee09c8-a6de-4ae3-8a47-4732b0cbb07b @@ -49,8 +50,9 @@ Request-Id: 42ee09c8-a6de-4ae3-8a47-4732b0cbb07b - **Host Header** — The standard [HTTP Host Header](https://tools.ietf.org/html/rfc2616#section-14.23) indicating the domain of the HTTP server the request is sent to. - **Content-Type / Accept Headers** — MUST be set to `application/octet-stream`. - **Body** — ILP Prepare encoded using OER, as specified in [RFC 27: Interledger Protocol V4](../0027-interledger-protocol-4/0027-interledger-protocol-4.md). -- **Request Id Header** — UUIDv4 to uniquely identify this ILP Prepare, and correlate the corresponding ILP Fulfill/Reject. +- **Prefer** — SHOULD be set to `respond-async` for backwards compatibility with recipients supporting [synchronous ILP over HTTP](#deprecated-synchronous-mode). - **Callback URL Header** — Callback URL of the origin connector to send an HTTP request with the ILP Fulfill/Reject. Required unless peers exchange the callback URL out-of-band. +- **Request Id Header** — UUIDv4 to uniquely identify this ILP Prepare, and correlate the corresponding ILP Fulfill/Reject. #### Response @@ -60,6 +62,8 @@ If the request is semantically valid, the recipient MUST respond immediately tha HTTP/x.x 202 Accepted ``` +If the recipient handling the ILP Prepare supports both [synchronous mode](#deprecated-synchronous-mode) and the standard asynchronous mode, they SHOULD handle the packet asynchronously if the request includes a `Prefer: respond-async` header. + ### ILP Fulfill/Reject Reply #### Request @@ -108,6 +112,8 @@ The sender of the ILP Prepare should only process the first ILP reply they recei ### [Deprecated] Synchronous Mode +Each ILP Prepare packet is sent as the body of an HTTP request to the peer's server endpoint. In synchronous ILP over HTTP, ILP Fulfill or Reject packets are returned as the body of the HTTP response. + #### ILP Prepare Request ```http