diff --git a/routing/DELEGATED_CONTENT_ROUTING_HTTP.md b/routing/DELEGATED_CONTENT_ROUTING_HTTP.md index 1f441230c..761c7a4b2 100644 --- a/routing/DELEGATED_CONTENT_ROUTING_HTTP.md +++ b/routing/DELEGATED_CONTENT_ROUTING_HTTP.md @@ -66,13 +66,13 @@ Specifications for some transfer protocols are provided in the "Transfer Protoco ### `GET /routing/v1/providers/{CID}` -#### Response codes +#### `GET` Response codes - `200` (OK): the response body contains 0 or more records - `404` (Not Found): must be returned if no matching records are found - `422` (Unprocessable Entity): request does not conform to schema or semantic constraints -#### Response Body +#### `GET` Response Body ```json { @@ -90,6 +90,48 @@ Response limit: 100 providers Each object in the `Providers` list is a *read provider record*. +### `PUT /routing/v1/providers` + +#### `PUT` Response codes + +- `200` (OK): the server processed the full list of provider records (possibly unsuccessfully, depending on the semantics of the particular records) +- `400` (Bad Request): the server deems the request to be invalid and cannot process it +- `422` (Unprocessable Entity): request does not conform to schema or semantic constraints +- `501` (Not Implemented): the server does not support providing records + +#### `PUT` Request Body + +```json +{ + "Providers": [ + { + "Protocol": "", + "Schema": "bitswap", + ... + } + ] +} +``` + +Each object in the `Providers` list is a *write provider record*. + +#### `PUT` Response Body + + ```json + { + "ProvideResults": [ + { ... } + ] + } + ``` + +- `ProvideResults` is a list of results in the same order as the `Providers` in the request, and the schema of each object is determined by the `Protocol` of the corresponding write object (called "Write Provider Records Response" in the Known Transfer Protocols section) + - This may contain output information such as TTLs, errors, etc. + - It is undefined whether the server will allow partial results +- The work for processing each provider record should be idempotent so that it can be retried without excessive cost in the case of full or partial failure of the request +- Default limit of 100 keys per request +- Implements pagination according to the Pagination section + ## Pagination This API does not support pagination, but optional pagination can be added in a backwards-compatible spec update. @@ -118,7 +160,7 @@ limits, allowing every site to query the API for results: ```plaintext Access-Control-Allow-Origin: * -Access-Control-Allow-Methods: GET, OPTIONS +Access-Control-Allow-Methods: GET, PUT, OPTIONS ``` ## Known Transfer Protocols @@ -148,6 +190,60 @@ Specification: [ipfs/specs/BITSWAP.md](https://github.com/ipfs/specs/blob/main/B The server should respect a passed `transport` query parameter by filtering against the `Addrs` list. +#### Bitswap Write Provider Records + +```json +{ + "Protocol": "transport-bitswap", + "Schema": "bitswap", + "Signature": "", + "Payload": "" +} +``` + +- `Signature`: a multibase-encoded signature of the sha256 hash of the `Payload` field, signed using the private key of the Peer ID specified in the `Payload` JSON. Signing details for specific key types should follow [libp2p/peerid specs](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md#key-types), unless stated otherwise. + + - Servers may ignore this field if they do not require signature verification. +- `Payload`: a string containing a serialized JSON object which conforms with the following schema: + + ```json + { + "Keys": ["cid1", "cid2"], + "Timestamp": 0, + "AdvisoryTTL": 0, + "ID": "12D3K...", + "Addrs": ["/ip4/..."] + } + ``` + +- `Keys` is a list of the CIDs being provided +- `Timestamp` is the current time +- `AdvisoryTTL` is the time by which the caller expects the server to keep the record available + - If this value is unknown, the caller may use a value of 0 +- `ID` is the peer ID that was used to sign the record +- `Addrs` is a list of string-encoded multiaddrs + +A [400 Bad Request](https://httpwg.org/specs/rfc9110.html#status.400) response code should be returned if the signature check fails. + +Note that this only supports Peer IDs expressed as identity multihashes. Peer IDs with older key types that exceed 42 bytes are not verifiable since they only contain a hash of the key, not the key itself. +Normally, if the Peer ID contains only a hash of the key, then the key is obtained out-of-band (e.g. by fetching the block via IPFS). +If support for these Peer IDs is needed in the future, this spec can be updated to allow the client to provide the key and key type out-of-band by adding optional `PublicKey` and `PublicKeyType` fields, and if the Peer ID is a CID, then the server can verify the public key's authenticity against the CID, and then proceed with the rest of the verification scheme. + +The `Payload` field is a string, not a proper JSON object, to prevent its contents from being accidentally parsed and re-encoded by intermediaries, which may change the order of JSON fields and thus cause the record to fail validation. + +#### Write Provider Records Response + +```json +{ + "AdvisoryTTL": 0 +} +``` + +- `AdvisoryTTL` is the time at which the server expects itself to drop the record + - If less than the `AdvisoryTTL` in the request, then the client should re-issue the request by that point + - If greater than the `AdvisoryTTL` in the request, then the server expects the client to be responsible for the content for up to that amount of time (TODO: this is ambiguous) + - If 0, the server makes no claims about the lifetime of the record + ### Filecoin Graphsync Multicodec name: `transport-graphsync-filecoinv1` @@ -173,3 +269,7 @@ Specification: [ipfs/go-graphsync/blob/main/docs/architecture.md](https://github - `PieceCID`: the CID of the [piece](https://spec.filecoin.io/systems/filecoin_files/piece/#section-systems.filecoin_files.piece) within which the data is stored - `VerifiedDeal`: whether the deal corresponding to the data is verified - `FastRetrieval`: whether the provider claims there is an unsealed copy of the data available for fast retrieval + +#### Filecoin Graphsync Write Provider Records + +There is currently no specified schema.