You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[Avoiding sending the same response messages twice](#avoiding-sending-the-same-response-messages-twice)
24
+
-[Client controls for time-based caching](#client-controls-for-time-based-caching)
25
+
-[Rate-limiting non-cachable POST requests](#rate-limiting-non-cachable-post-requests)
26
+
-[Implementations](#implementations)
27
+
28
+
# HTTP Transport Design
29
+
30
+
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`
31
+
32
+
Requests MUST be sent as either:
33
+
-`GET /reframe/{mbase64url-dag-cbor}`
34
+
- 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
35
+
- 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
36
+
- Suitable for sharing links, sending smaller messages, and when a query result MUST benefit from HTTP caching (see _HTTP Caching Considerations_ below).
37
+
-`POST /reframe`
38
+
- Ephemeral HTTP `POST` request with message passed as DAG-JSON in HTTP request body
39
+
- Suitable for bigger messages, and when HTTP caching should be skipped for the most fresh results
40
+
41
+
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.
42
+
43
+
44
+
If a server supports HTTP/1.1, then it MAY send chunked-encoded messages. Clients supporting HTTP/1.1 MUST accept chunked-encoded responses.
45
+
46
+
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.
47
+
48
+
If a server chooses to respond to a single request message with a group of messages in the response it should do so as a set of `\n` delimited DAG-JSON messages (i.e. `{Response1}\n{Response2}...`).
49
+
50
+
Requests and responses MUST come with `version=1` as a _Required Parameter_ in the `Accept` and `Content-Type` HTTP headers.
51
+
52
+
Note: This version header is what allows the transport to more easily evolve over time (e.g. if it was desired to change the transport to support other encodings than DAG-JSON, utilize headers differently, move the request data from the body, etc.). Not including the version number is may lead to incompatibility with future versions of the transport.
53
+
54
+
## HTTP Caching Considerations
55
+
56
+
### POST vs GET
57
+
58
+
HTTP `POST` requests do not benefit from any preexisting HTTP caching because
59
+
every `POST` response will overwrite the cached resource.
60
+
61
+
While it is possible to write custom middleware to cache `POST` responses based on
62
+
request body, this is not a standard behavior and is discouraged.
63
+
64
+
Use of `GET` endpoint is not mandatory, but suggested if a Reframe deployment
65
+
expects to handle the same message query multiple times, and want to leverage
66
+
existing HTTP tooling to maximize HTTP cache hits.
67
+
68
+
### Avoiding sending the same response messages twice
69
+
70
+
Implementations MUST always return strong
71
+
[`Etag`](https://httpwg.org/specs/rfc7232.html#header.etag) HTTP header based
72
+
on digest of DAG-JSON response messages. This allows clients to send
#  Reframe: Known Methods
2
2
3
3
**Author(s)**:
4
4
- Adin Schmahmann
@@ -10,63 +10,26 @@
10
10
11
11
**Abstract**
12
12
13
-
The Reframe protocol is designed for request-response messages that is sufficiently generic and extensible to evolve over time as new needs for it arise. This includes separately defining the transport and message serialization mechanisms from the actual method types and semantics.
14
-
15
-
The initial use case motivating the protocol's design is to help peers discover various routing hints that enable them to find the content or service they are actually looking for. The extensibility required in this case is that various routing systems could share the protocol so that applications can work on them generically and that recursive routing systems could choose to use the protocol themselves to maximize interoperability.
13
+
This document is defining known methods (request-response message types) and semantics.
The Reframe protocol is a request-response based protocol. Upon receiving a request a Reframe server should respond to clients with information they have pertaining to the request. It's possible that a Reframe server may not have all of the information necessary for a client to actually get the data they need, but even partial resolution is acceptable. For example, if a peer is looking to download some block of data a Reframe server may only know about some peers that have the data but not their network addresses. That's ok and the client can always choose alternative mechanisms to discover the missing information.
27
-
28
-
# Spec
29
-
30
-
To build an implementation of the protocol it is required to both define a transport for the messages and the method types supported by the given implementation. Over time both the method and transport types may grow and also be included in this specification.
31
-
32
-
## Interaction Pattern
33
-
34
-
Given that a client C wants to request information from some server S:
35
-
36
-
1. C opens sends a request to S that is a single message
37
-
2. S will respond to C with either a single message or a group of messages
38
-
39
-
## Transports
40
-
41
-
### HTTP + DAG-JSON
42
-
43
-
All messages MUST be encoded as DAG-JSON and use explicit content type `application/vnd.ipfs.rpc+dag-json; version=1`
44
-
45
-
46
-
Requests MUST be sent as HTTP POST requests. If a server supports HTTP/1.1, then it MAY send chunked-encoded messages. Clients supporting HTTP/1.1 MUST accept chunked-encoded responses.
47
-
48
-
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.
49
-
50
-
If a server chooses to respond to a single request message with a group of messages in the response it should do so as a set of `\n` delimited DAG-JSON messages (i.e. `{Response1}\n{Response2}...`).
51
-
52
-
Requests and responses MUST come with `version=1` as a _Required Parameter_ in the `Accept` and `Content-Type` HTTP headers.
53
-
54
-
55
-
Note: This version header is what allows the transport to more easily evolve over time (e.g. if it was desired to change the transport to support other encodings than DAG-JSON, utilize headers differently, move the request data from the body, etc.). Not including the version number is may lead to incompatibility with future versions of the transport.
56
-
57
-
## Protocol Message Overview
58
-
59
-
We can represent each message as an IPLD Schema to denote its abstract representation independent of the serialization scheme.
60
-
61
-
To help visualize example messages and illustrate implementation of the first concrete transport (HTTP + DAG-JSON) example messages will be given in DAG-JSON.
62
-
63
-
The payload sent as a request is a single message. The response is a repeated set of messages until the transport signals that the response is completed (e.g. closing a stream, connection, etc.)
64
-
65
-
Reception, on the server or client side, of:
66
-
1. New or unknown fields in any request or response message are ignored (rather than causing an error)
67
-
2. Missing fields or unknown union cases cause a terminal error
68
-
69
-
### Known Methods
32
+
# Known Methods
70
33
71
34
The known Request types are the following and are described below:
72
35
@@ -94,7 +57,25 @@ type Response union {
94
57
Note: Each Request type has a corresponding Response type.
95
58
Every message except the Error type should end in Request/Response.
96
59
97
-
#### Error
60
+
## Cachable/Non-Cachable Methods
61
+
62
+
The following methods (request-response pairs) are _cachable_:
63
+
64
+
```ipldsch
65
+
type CachableRequest union {
66
+
| "IdentifyRequest" IdentifyRequest
67
+
| "FindProvidersRequest" FindProvidersRequest
68
+
| "GetIPNSRequest" GetIPNSRequest
69
+
}
70
+
```
71
+
72
+
Methods that are not listed above are considered _non-cachable_.
73
+
74
+
Implementations are encouraged to improve performance of `CachableRequest` methods by applying transport and method-specific caching strategies.
75
+
76
+
# Message Specs
77
+
78
+
## Error
98
79
99
80
The Error message type should be used in Responses to indicate that an error has occurred.
100
81
@@ -104,7 +85,7 @@ The Error message type should be used in Responses to indicate that an error has
104
85
}
105
86
```
106
87
107
-
####Identify
88
+
## Identify
108
89
109
90
A message for discovering which messages a server supports. May be used by applications to optimize which servers get sent which types of requests.
110
91
@@ -118,7 +99,7 @@ A message for discovering which messages a server supports. May be used by appli
118
99
119
100
`IdentifyResponse` should return the set of supported methods aside from the "Identify" method.
120
101
121
-
#####DAG-JSON Examples
102
+
### DAG-JSON Examples
122
103
123
104
Request:
124
105
```
@@ -132,7 +113,7 @@ Response:
132
113
}}
133
114
```
134
115
135
-
####FindProviders
116
+
## FindProviders
136
117
137
118
A message for finding nodes that have an interest in a given key. Some common examples include finding which peers have advertised that they have a given CID, or which peers are interested in a given pubsub topic.
138
119
@@ -185,7 +166,7 @@ Note: While the Key is a CID it is highly recommended that server implementation
185
166
}
186
167
```
187
168
188
-
#####DAG-JSON Examples
169
+
### DAG-JSON Examples
189
170
190
171
Request:
191
172
```
@@ -218,7 +199,7 @@ Response:
218
199
}}
219
200
```
220
201
221
-
####GetIPNS
202
+
## GetIPNS
222
203
223
204
A message for finding the latest IPNS records for a given identifier.
224
205
@@ -234,7 +215,7 @@ A message for finding the latest IPNS records for a given identifier.
234
215
}
235
216
```
236
217
237
-
#####DAG-JSON Examples
218
+
### DAG-JSON Examples
238
219
239
220
Request:
240
221
```
@@ -252,7 +233,7 @@ Response:
252
233
}}...
253
234
```
254
235
255
-
####PutIPNS
236
+
## PutIPNS
256
237
257
238
A message for putting the latest IPNS records for a given identifier.
258
239
@@ -265,7 +246,7 @@ A message for putting the latest IPNS records for a given identifier.
The Reframe protocol is designed for request-response messages that is sufficiently generic and extensible to evolve over time as new needs for it arise. This includes separately defining the transport and message serialization mechanisms from the actual method types and semantics.
14
+
15
+
The initial use case motivating the protocol's design is to help peers discover various routing hints that enable them to find the content or service they are actually looking for. The extensibility required in this case is that various routing systems could share the protocol so that applications can work on them generically and that recursive routing systems could choose to use the protocol themselves to maximize interoperability.
The Reframe protocol is a request-response based protocol. Upon receiving a request a Reframe server should respond to clients with information they have pertaining to the request. It's possible that a Reframe server may not have all of the information necessary for a client to actually get the data they need, but even partial resolution is acceptable. For example, if a peer is looking to download some block of data a Reframe server may only know about some peers that have the data but not their network addresses. That's ok and the client can always choose alternative mechanisms to discover the missing information.
32
+
33
+
# Spec
34
+
35
+
To build an implementation of the protocol it is required to both define a transport for the messages and the method types supported by the given implementation. Over time both the method and transport types may grow and also be included in this specification.
36
+
37
+
## Interaction Pattern
38
+
39
+
Given that a client `C` wants to request information from some server `S`:
40
+
41
+
1.`C` opens sends a request to `S` that is a single message
42
+
2.`S` will respond to `C` with either a single message or a group of messages
43
+
44
+
## Cachability
45
+
46
+
Some methods are prone to being cachable while others are not. Methods are tagged within the spec as cachable/not cachable. Transports may leverage that information to decide if cachable/not cachable methods should be treated differently.
47
+
48
+
## Transports
49
+
50
+
Reframe is designed to be transport-agnostic, multiple transports are expected
We can represent each message as an IPLD Schema to denote its abstract representation independent of the serialization scheme.
60
+
61
+
To help visualize example messages and illustrate implementation of the first concrete transport (HTTP + DAG-JSON) example messages will be given in DAG-JSON.
62
+
63
+
The payload sent as a request is a single message. The response is a repeated set of messages until the transport signals that the response is completed (e.g. closing a stream, connection, etc.)
64
+
65
+
Reception, on the server or client side, of:
66
+
1. New or unknown fields in any request or response message are ignored (rather than causing an error)
67
+
2. Missing fields or unknown union cases cause a terminal error
0 commit comments