From d283fc415c68a2d350f48a3ce5b2bd88e6f0f145 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Thu, 29 Sep 2022 15:21:15 +0200 Subject: [PATCH 1/3] fix: document GET /reframe?q= This is what Kubo 0.16.0-rc1 uses, and what is implemented in https://github.com/ipfs/go-delegated-routing --- reframe/REFRAME_HTTP_TRANSPORT.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/reframe/REFRAME_HTTP_TRANSPORT.md b/reframe/REFRAME_HTTP_TRANSPORT.md index 5be75cfeb..805fa2e8d 100644 --- a/reframe/REFRAME_HTTP_TRANSPORT.md +++ b/reframe/REFRAME_HTTP_TRANSPORT.md @@ -34,6 +34,9 @@ Requests MUST be sent as either: - Cachable HTTP `GET` requests with message passed as DAG-CBOR in HTTP path segment, encoded as URL-safe [`base64url` multibase](https://docs.ipfs.io/concepts/glossary/#base64url) string - DAG-CBOR in multibase `base64url` is used instead of DAG-JSON because JSON may include characters that are not safe to be used in URLs, and re-encoding JSON in base would take too much space - Suitable for sharing links, sending smaller messages, and when a query result MUST benefit from HTTP caching (see _HTTP Caching Considerations_ below). +- `GET /reframe?q={percent-encoded-dag-json}` + - DAG-JSON is supported via a `?q` query parameter, and the value MUST be [percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding) + - Suitable for sharing links, sending smaller messages, testing and debugging. - `POST /reframe` - Ephemeral HTTP `POST` request with message passed as DAG-JSON in HTTP request body - Suitable for bigger messages, and when HTTP caching should be skipped for the most fresh results From aa5d122522b350f22d3303672823cc23df7936b2 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Thu, 29 Sep 2022 15:29:36 +0200 Subject: [PATCH 2/3] fix: remove mentions of dag-cbor not implemented anywhere, we will add it as a separate IPIP --- reframe/REFRAME_HTTP_TRANSPORT.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/reframe/REFRAME_HTTP_TRANSPORT.md b/reframe/REFRAME_HTTP_TRANSPORT.md index 805fa2e8d..3f1c4bfa9 100644 --- a/reframe/REFRAME_HTTP_TRANSPORT.md +++ b/reframe/REFRAME_HTTP_TRANSPORT.md @@ -30,10 +30,6 @@ serialization mechanisms for sending Reframe messages over HTTP `POST` and All messages sent in HTTP body MUST be encoded as DAG-JSON and use explicit content type `application/vnd.ipfs.rpc+dag-json; version=1` Requests MUST be sent as either: -- `GET /reframe/{mbase64url-dag-cbor}` - - Cachable HTTP `GET` requests with message passed as DAG-CBOR in HTTP path segment, encoded as URL-safe [`base64url` multibase](https://docs.ipfs.io/concepts/glossary/#base64url) string - - DAG-CBOR in multibase `base64url` is used instead of DAG-JSON because JSON may include characters that are not safe to be used in URLs, and re-encoding JSON in base would take too much space - - Suitable for sharing links, sending smaller messages, and when a query result MUST benefit from HTTP caching (see _HTTP Caching Considerations_ below). - `GET /reframe?q={percent-encoded-dag-json}` - DAG-JSON is supported via a `?q` query parameter, and the value MUST be [percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding) - Suitable for sharing links, sending smaller messages, testing and debugging. From a705ad9c6b111463e79c6b4f64c8374c42899a5d Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Sat, 1 Oct 2022 00:01:24 +0200 Subject: [PATCH 3/3] chore: lint --- reframe/REFRAME_HTTP_TRANSPORT.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/reframe/REFRAME_HTTP_TRANSPORT.md b/reframe/REFRAME_HTTP_TRANSPORT.md index 3f1c4bfa9..c5a85ed78 100644 --- a/reframe/REFRAME_HTTP_TRANSPORT.md +++ b/reframe/REFRAME_HTTP_TRANSPORT.md @@ -1,6 +1,7 @@ -# ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Reframe: HTTP Transport +# ![draft](https://img.shields.io/badge/status-draft-yellow.svg?style=flat-square) Reframe: HTTP Transport **Author(s)**: + - Adin Schmahmann - Petar Maymounkov - Marcin Rataj @@ -30,6 +31,7 @@ serialization mechanisms for sending Reframe messages over HTTP `POST` and All messages sent in HTTP body MUST be encoded as DAG-JSON and use explicit content type `application/vnd.ipfs.rpc+dag-json; version=1` Requests MUST be sent as either: + - `GET /reframe?q={percent-encoded-dag-json}` - DAG-JSON is supported via a `?q` query parameter, and the value MUST be [percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding) - Suitable for sharing links, sending smaller messages, testing and debugging. @@ -39,7 +41,6 @@ Requests MUST be sent as either: Servers MUST support `GET` for methods marked as cachable and MUST support `POST` for all methods (both cachable and not-cachable). This allows servers to rate-limit `POST` when cachable `GET` could be used instead, and enables clients to use `POST` as a fallback in case there is a technical problem with bigger Reframe messages not fitting in a `GET` URL. See "Caching Considerations" section. - If a server supports HTTP/1.1, then it MAY send chunked-encoded messages. Clients supporting HTTP/1.1 MUST accept chunked-encoded responses. Requests and Responses MUST occur over a single HTTP call instead of the server being allowed to dial back the client with a response at a later time. The response status code MUST be 200 if the RPC transaction succeeds, even when there's an error at the application layer, and a non-200 status code if the RPC transaction fails. @@ -75,7 +76,7 @@ header, which will skip when the response message did not change. ### Client controls for time-based caching -Implementations can also return (optional) +Implementations can also return (optional) [`Last-Modified`](https://httpwg.org/specs/rfc7232.html#header.last-modified) HTTP header, allowing clients to send conditional requests with [`If-Modified-Since`](https://httpwg.org/specs/rfc7232.html#header.if-modified-since) @@ -90,7 +91,7 @@ with `Retry-After` header to throttle the number of `POST` requests a client can The body returned with `429` response should suggest use of HTTP `GET` endpoint for cachable Reframe methods: -``` +```plaintext HTTP/1.1 429 Too Many Requests Content-Type: text/plain Retry-After: 3600 @@ -98,7 +99,6 @@ Retry-After: 3600 too many POST requests: consider switching to cachable GET or try again later (see Retry-After header) ``` - # Implementations https://github.com/ipfs/go-delegated-routing