-
Notifications
You must be signed in to change notification settings - Fork 232
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
2 changed files
with
90 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,68 @@ | ||
--- | ||
title: "IPIP-0410: Streaming Routing V1 HTTP API" | ||
date: 2023-05-12 | ||
ipip: proposal | ||
editors: | ||
- name: Henrique Dias | ||
github: hacdias | ||
url: https://hacdias.com/ | ||
relatedIssues: | ||
- https://github.com/ipfs/specs/issues/344 | ||
- https://github.com/ipfs/boxo/pull/18 | ||
- https://github.com/ipfs/kubo/pull/9868 | ||
- https://github.com/ipfs/kubo/pull/9874 | ||
order: 410 | ||
tags: ['ipips'] | ||
--- | ||
|
||
Introduce backwards-compatible streaming support to the Routing V1 HTTP API. | ||
|
||
Introduce backwards-compatible streaming support to the Routing V1 HTTP API by | ||
using the HTTP Header `Accept` (:cite[rfc9110]) with [Newline Delimited JSO (NDJSON)](http://ndjson.org/). | ||
|
||
## Motivation | ||
|
||
The main motivation for this change is that a server may take some time before fetching | ||
all the peers they know providing a certain CID. That will add some latency when sending | ||
a non-streamed response, as they need to wait for the whole discovery period. | ||
|
||
With streaming support, the server is able to respond with a *read provider record* | ||
as they themselves discover the peers, not needing to wait for the whole discovery | ||
to return the provider records. | ||
|
||
## Detailed design | ||
|
||
In summary, streaming is supported by using the `Accept` HTTP header (:cite[rfc9110]) | ||
along with the `application/x-ndjson` content type. For more details regarding the design, | ||
check :cite[http-routing-v1]. | ||
|
||
## Design rationale | ||
|
||
The idea is to not break compatibility with existing clients and servers. Therefore, | ||
we can use the `Accept` HTTP header for content negotiation. If the client supports | ||
streaming, they can advertise so by including `application/x-ndjson` in the headers. | ||
If the server supports streaming, the response will have `Content-Type` HTTP header | ||
of `application/x-ndjson` with a streaming response. Otherwise, it will fall back | ||
to a pure JSON, non-streamed, response. | ||
|
||
### User benefit | ||
|
||
Users (clients) will benefit from this change as the servers will now be able | ||
to respond more promptly to provider record requests. Instead of waiting for the whole | ||
list to be constructed, servers can now return each provider record one by one, | ||
in a streaming fashion. | ||
|
||
### Compatibility | ||
|
||
The introduced changes are backwards-compatible. The introduced header is completely | ||
optional, and a server that does not support streaming is able to respond with a non-streaming | ||
response to the client. Equally, non-streaming responses are the default. Therefore, a | ||
client that does not support streaming will not receive a streamed response. | ||
|
||
### Security | ||
|
||
Security considerations are equivalent as the ones in :cite[ipip-0337]. | ||
|
||
### Copyright | ||
|
||
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters