Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

IPIP-410: Streaming Routing V1 HTTP API #410

Merged
merged 2 commits into from
Jun 15, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 95 additions & 0 deletions src/ipips/ipip-0410.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
---
title: "IPIP-0410: Streaming NDJSON in Routing 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']
---

## Summary

Introduce backwards-compatible streaming support to the Routing V1 HTTP API.
For this, we use the `Accept` HTTP header (:cite[rfc9110]) for content type negotiation, as well
as the Newline Delimited JSON ([NDJSON]) format.

## Motivation

The main motivation for this change is to allow servers to respond faster to the
client with provider records, as soon as they are available. In the current state,
the client requests a list of providers for a CID from the server. Then, the client
has to wait for the server to collect their final list of providers. After that,
the server can respond with the full list of providers.

This is a big source of latency when `/routing/v1` is used for delegating DHT lookups,
where the client is forced to wait for the server to finish DHT walk.

With streaming support, the server is able to respond with provider records as soon
as they are available. This reduces latency and allows for faster content discovery.

In addition, streaming responses may produce an unlimited amount of results, which
is not the case for non-streamed responses.

## Detailed Design

In summary, streaming is supported by using the `Accept` HTTP header, which is used
for content type negotiation as described in :cite[rfc9110]. The client sends an
`Accept` HTTP header starting with `application/x-ndjson`, which is the content
type for [NDJSON]. The following happens:

- The client adds the `Accept` HTTP header in the request starting with `application/x-ndjson`.
- The server checks the `Accept` HTTP header from the request and, if it contains
`application/x-ndjson`, they reply with NDJSON. If they don't support NDJSON, they
can reply with JSON.
- The server response MUST contain a `Content-Type` HTTP header indicating the
response type, which may be either `application/json` for non-streaming responses,
and `application/x-ndjson` for streamed responses.

For more details regarding the design, check :cite[http-routing-v1].

## Design Rationale

This feature is designed such that it does not break compatibility with existing
clients and servers. The `Accept` HTTP header is OPTIONAL. By default, the server
MUST respond with `application/json` unless the client explicitly asked for
`application/x-ndjson`. If the server does not support NDJSON, it is allowed
to still respond with non-streamed JSON.

### 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.

The client will be able to close connection at any time, reducing load on both ends.

The main use cases for this IPIP are light clients and services which want to
delegate DHT lookups to external service. With streaming, clients will be able
to receive results as soon the delegated service learns about new record, which
directly impacts the content load speeds perceived by the end user.

### 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/).

[NDJSON]: http://ndjson.org/
34 changes: 32 additions & 2 deletions src/routing/http-routing-v1.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,16 @@ editors:
github: guseggert
- name: Masih H. Derkani
github: masih
- name: Henrique Dias
url: https://hacdias.com/
github: hacdias
xref:
- ipns-record
order: 0
tags: ['routing']
---

Delegated routing is a mechanism for IPFS implementations to use for offloading content routing and naming to another process/server. This specification describes an HTTP API for delegated content routing.
Delegated routing is a mechanism for IPFS implementations to use for offloading content routing and naming to another process/server. This specification describes a vendor-agnostic HTTP API for delegated content routing.

## API Specification

Expand Down Expand Up @@ -144,7 +147,34 @@ This API does not support pagination, but optional pagination can be added in a

## Streaming

This API does not currently support streaming, however it can be added in the future through a backwards-compatible update by using a content type other than `application/json`.
JSON-based endpoints support streaming requests made
with `Accept: application/x-ndjson` HTTP Header.

Steaming responses are formatted as
[Newline Delimited JSON (ndjson)](https://github.com/ndjson/ndjson-spec),
with one result per line:

```json
{"Schema": "<schema>", ...}
{"Schema": "<schema>", ...}
{"Schema": "<schema>", ...}
...
```

:::note

Streaming is opt-in and backwards-compatibile with clients and servers that do
not support streaming:

- Requests without the `Accept: application/x-ndjson` header MUST default to
regular, non-streaming, JSON responses.
- Legacy server MAY respond with non-streaming `application/json` response even
if the client requested streaming. It is up to the client to inspect
the `Content-Type` header before parsing the response.
- The server MUST NOT respond with streaming response if the client did not
explicitly request so.

:::

## Error Codes

Expand Down