Skip to content

Commit

Permalink
ipip-378: clarify string values
Browse files Browse the repository at this point in the history
  • Loading branch information
lidel committed Feb 5, 2024
1 parent cf83c02 commit da12e11
Showing 1 changed file with 15 additions and 14 deletions.
29 changes: 15 additions & 14 deletions src/routing/http-routing-v1.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ server SHOULD be no more than 100 `Providers` per `application/json` response.

:::

#### `POST` Response codes
#### `POST` Response Status 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
Expand Down Expand Up @@ -198,7 +198,7 @@ Each object in the `Peers` list is a *write peer record* entry.

Server SHOULD accept writes represented with [Announcement Schema](#announcement-schema).

#### `POST` Response codes
#### `POST` Response Status 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
Expand Down Expand Up @@ -393,20 +393,20 @@ The `announcement` schema can be used in `POST` operations to announce content p
```

- `Schema`: tells the server to interpret the JSON object as announce provider
- `Payload`: is a DAG-JSON-compatible object with a subset of the below fields
- `CID` is the CID being provided (`/routing/v1/providers` only).
- This field is not presend when used for `POST /routing/v1/peers`
- `Scope` is an optional hint that provides semantic meaning about CID (`/routing/v1/providers` only):
- `Payload`: is a map object with a subset of the below fields.
- `CID` is a string with multibase-encoded CID being provided (`/routing/v1/providers` only).
- This field is not present when used for `POST /routing/v1/peers`
- `Scope` (optional) is a string hint that provides semantic meaning about CID (`/routing/v1/providers` only):
- `block` announces only the individual block (this is the implicit default if `Scope` field is not present).
- `entity` announces CIDs required for enumerating entity behind the CID (e.g.: all blocks for UnixFS file or a minimum set of blocks to enumerate contents of HAMT-sharded UnixFS directory, only top level of directory tree, etc).
- `recursive` announces entire DAGs behind the CIDs (e.g.: entire DAG-CBOR DAG, or everything in UnixFS directory, including all files in all subdirectories).
- `Timestamp` is the current time, formatted as an ASCII string that follows notation from [rfc3339](https://specs.ipfs.tech/ipns/ipns-record/#ref-rfc3339).
- `TTL` is caching and expiration hint informing the server how long to keep the record available, specified in milliseconds.
- If this value is unknown, the caller may skip this field, or use a value of 0. The server's default will be used.
- `ID` is Peer ID of the node that provides the content and also indicates the `libp2p-key` that SHOULD be used for verifying `Signature` field.
- `Addrs` is an a list of string-encoded multiaddrs without `/p2p/peerID` suffix.
- `Protocols` is a list of protocols supported by `ID` and/or `Addrs`, if known upfront.
- `Metadata` is a string with multibase-encoded binary metadata that should be passed as-is
- `TTL` is caching and expiration hint informing the server how long to keep the record available, specified as integer in milliseconds.
- If this value is unknown, the caller may skip this field or set it to 0. The server's default will be used.
- `ID` is a multibase-encoded Peer ID of the node that provides the content and also indicates the `libp2p-key` that SHOULD be used for verifying `Signature` field.
- `Addrs` (optional) is an a list of string-encoded multiaddrs without `/p2p/peerID` suffix.
- `Protocols` (optional) is a list of strings with protocols supported by `ID` and/or `Addrs`, if known upfront.
- `Metadata` (optional) is a string with multibase-encoded binary metadata that should be passed as-is
- `Signature` is a string with multibase-encoded binary signature that provides integrity and authenticity of the `Payload` field.
- Signature is created by following below steps:
1. Convert `Payload` to deterministic, ordered [DAG-JSON](https://ipld.io/specs/codecs/dag-json/spec/) map notation
Expand All @@ -418,9 +418,10 @@ The `announcement` schema can be used in `POST` operations to announce content p
- ED25519 and other small public keys MUST be inlined inside of the `ID` field with the identity multihash type.
- Key types that exceed 42 bytes (e.g. RSA) SHOULD NOT be inlined, the `ID` field should only include the multihash of the key. The key itself SHOULD be obtained out-of-band (e.g. by fetching the block via IPFS) and cached.
If support for big keys 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` 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.
- A [400 Bad Request](https://httpwg.org/specs/rfc9110.html#status.400) response code SHOULD be returned if the `Signature` check fails.

Server SHOULD return HTTP 400 Bad Request when announcement `Payload` serizalized to DAG-CBOR is bigger than 2MiB.
A [400 Bad Request](https://httpwg.org/specs/rfc9110.html#status.400) response code SHOULD be returned if either
- `Signature` is not valid
- `Payload` serialized to DAG-CBOR is bigger than 2MiB

#### Use in POST responses

Expand Down

0 comments on commit da12e11

Please sign in to comment.