Skip to content

Commit 1d28680

Browse files
authored
Merge pull request #495 from ipfs/gateway-clarify-peer-id-and-http-auth
libp2p+http: clarify peerid auth optionality and gw type detection
2 parents cec24fe + 6511ee1 commit 1d28680

File tree

1 file changed

+28
-30
lines changed

1 file changed

+28
-30
lines changed

src/http-gateways/libp2p-gateway.md

+28-30
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,46 @@
11
---
22
title: libp2p+HTTP Transport Gateway Specification
33
description: >
4-
Describes how HTTP Gateway semantics can be used over libp2p transports.
5-
date: 2024-04-20
4+
Describes how HTTP Gateway semantics can be used over libp2p transports and how libp2p can coexist with other HTTP services on the same host.
5+
date: 2025-03-06
66
maturity: draft
77
editors:
88
- name: Adin Schmahmann
99
github: aschmahmann
1010
affiliation:
11-
name: Protocol Labs
12-
url: https://protocol.ai/
11+
name: Shipyard
12+
url: https://ipshipyard.com
1313
- name: Marcin Rataj
1414
github: lidel
15-
url: https://lidel.org/
1615
affiliation:
17-
name: Protocol Labs
18-
url: https://protocol.ai/
16+
name: Shipyard
17+
url: https://ipshipyard.com
1918
xref:
2019
- path-gateway
2120
- trustless-gateway
2221
tags: ['httpGateways', 'lowLevelHttpGateways', 'exchange', 'transport']
2322
order: 3
2423
---
2524

26-
## Introduction
27-
2825
This specification describes how HTTP Gateway semantics
29-
and APIs can be used over [libp2p](https://github.com/libp2p/specs) transports.
26+
and APIs can be used over [libp2p](https://github.com/libp2p/specs) transports,
27+
and how libp2p can coexist with other HTTP services on the same host.
3028

31-
## Specification
29+
# libp2p HTTP Protocols Manifest
3230

33-
The [libp2p+HTTP specification](https://github.com/libp2p/specs/pull/508)
34-
describes how to use HTTP semantics over stream transports, as well as how
31+
The [libp2p+HTTP specification](https://github.com/libp2p/specs/blob/master/http/README.md)
32+
describes how to use libp2p with HTTP semantics over stream transports, as well as how
3533
to do discovery of what protocols are available (and where they are mounted).
3634

37-
### `.well-known/libp2p/protocols`
35+
## `.well-known/libp2p/protocols`
3836

39-
libp2p application sub-protocols exposed behind `/http/1.1` protocol can be
37+
Any libp2p application sub-protocols exposed behind `/http/1.1` protocol can be
4038
discovered by the well-known resource (:cite[rfc8615]) at `.well-known/libp2p/protocols`.
4139

42-
#### Protocol identifier
40+
### Protocol Identifier
4341

44-
In order for a given HTTP Gateway protocol like the :cite[trustless-gateway] to
45-
work in this environment it requires a protocol identifier to act as a key in
42+
In order for a pure HTTP Gateway protocol like the :cite[trustless-gateway] to
43+
coexist with libp2p in this environment it requires a protocol identifier to act as a key in
4644
the `.well-known/libp2p/protocols` mapping file.
4745

4846
The `/http/1.1` sub-protocol identifier for the IPFS Gateway when used over libp2p is:
@@ -51,7 +49,7 @@ The `/http/1.1` sub-protocol identifier for the IPFS Gateway when used over libp
5149
/ipfs/gateway
5250
```
5351

54-
#### Protocol mounting
52+
### Protocol Mounting
5553

5654
A reference `.well-known/libp2p/protocols` JSON body with mapping that assumes the gateway to be mounted at `/`:
5755

@@ -63,20 +61,20 @@ A reference `.well-known/libp2p/protocols` JSON body with mapping that assumes t
6361
}
6462
```
6563

66-
## Gateway type detection
64+
# Peer ID Authentication
6765

68-
The protocol identifier is shared among Gateway specifications.
66+
[Peer ID Authentication over HTTP](https://github.com/libp2p/specs/blob/master/http/peer-id-auth.md) is optional and SHOULD NOT be required by [Trustless Gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/) HTTP endpoint defined for `/ipfs/gateway` handler.
6967

70-
HTTP server mounted behind the `/ipfs/gateway` identifier MUST expose
71-
:cite[trustless-gateway], but is free to also support other gateway types and
72-
features.
68+
Clients following the Trustless Gateway specification MUST verify each CID individually, without being concerned with peer identity.
69+
PeerID authentication is not required for trustless retrieval and HTTP-only clients SHOULD work without it.
7370

74-
:::note
71+
# Gateway Type Detection
7572

76-
Signaling Features on HTTP Gateways is wip in [IPIP-425](https://github.com/ipfs/specs/pull/425).
73+
The `/ipfs/gateway` protocol identifier is shared among all Gateway specifications.
7774

78-
Until the IPIP is finalized, client implementations SHOULD perform feature
79-
detection on their own, or assume only the most basic [block (application/vnd.ipld.raw)](https://specs.ipfs.tech/http-gateways/trustless-gateway/#block-responses-application-vnd-ipld-raw)
80-
response type from :cite[trustless-gateway] is available.
75+
An HTTP server mounted behind the `/ipfs/gateway` identifier MUST expose the most basic [block (application/vnd.ipld.raw)](https://specs.ipfs.tech/http-gateways/trustless-gateway/#block-responses-application-vnd-ipld-raw)
76+
responses from :cite[trustless-gateway], but MAY also support other gateway types and features.
8177

82-
:::
78+
Client implementations SHOULD [perform feature detection](https://specs.ipfs.tech/http-gateways/trustless-gateway/#dedicated-probe-paths) on their own,
79+
or assume only the most basic [block (application/vnd.ipld.raw)](https://specs.ipfs.tech/http-gateways/trustless-gateway/#block-responses-application-vnd-ipld-raw)
80+
response type from :cite[trustless-gateway] is available.

0 commit comments

Comments
 (0)