From 013db4826c039536a225520ef14f20e4edeadf04 Mon Sep 17 00:00:00 2001 From: Adin Schmahmann Date: Tue, 29 Aug 2023 14:41:56 -0400 Subject: [PATCH 1/4] feat(gateway): add specification for running the gateway over libp2p --- src/http-gateways/libp2p-gateway.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 src/http-gateways/libp2p-gateway.md diff --git a/src/http-gateways/libp2p-gateway.md b/src/http-gateways/libp2p-gateway.md new file mode 100644 index 000000000..b59a8b1ff --- /dev/null +++ b/src/http-gateways/libp2p-gateway.md @@ -0,0 +1,24 @@ +--- +title: libp2p Transport Gateway Specification +description: > + The libp2p Transport Gateway specification describes how Gateway APIs can be used over libp2p transports +date: 2023-08-29 +maturity: reliable +editors: + - name: Adin Schmahmann + github: aschmahmann + - name: Marcin Rataj + github: lidel + url: https://lidel.org/ +xref: + - path-gateway + - trustless-gateway +tags: ['httpGateways', 'lowLevelHttpGateways'] +order: 1 +--- + +The libp2p Transport Gateway specification describes how Gateway APIs can be used over libp2p transports. + +libp2p has has a [http+libp2p specification](https://github.com/libp2p/specs/pull/508) that describes how to use HTTP semantics over stream transports as well as how to do discovery of what protocols are available (and where they are mounted) on a given endpoint. In order for a given HTTP protocol like the IPFS Gateway API to work in this environment it requires a protocol identifier. + +The protocol identifier for the IPFS Gateway when used over libp2p is `/ipfs/gateway`. This protocol identifier is shared among Gateway specifications (e.g. whether an endpoint only supports :cite[trustless-gateway], supports more of :cite[path-gateway], etc. is not considered here). \ No newline at end of file From 7300351c69fa026a29f07a884e6524a6a11cce2e Mon Sep 17 00:00:00 2001 From: Henrique Dias Date: Tue, 3 Oct 2023 14:07:29 +0200 Subject: [PATCH 2/4] chore: apply editorial suggestions --- src/http-gateways/libp2p-gateway.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/http-gateways/libp2p-gateway.md b/src/http-gateways/libp2p-gateway.md index b59a8b1ff..55ca449c8 100644 --- a/src/http-gateways/libp2p-gateway.md +++ b/src/http-gateways/libp2p-gateway.md @@ -1,7 +1,7 @@ --- title: libp2p Transport Gateway Specification description: > - The libp2p Transport Gateway specification describes how Gateway APIs can be used over libp2p transports + The libp2p Transport Gateway specification describes how Gateway APIs can be used over libp2p transports. date: 2023-08-29 maturity: reliable editors: @@ -17,8 +17,8 @@ tags: ['httpGateways', 'lowLevelHttpGateways'] order: 1 --- -The libp2p Transport Gateway specification describes how Gateway APIs can be used over libp2p transports. +The libp2p Transport Gateway specification describes how Gateway APIs can be used over [libp2p](https://github.com/libp2p/specs) transports. -libp2p has has a [http+libp2p specification](https://github.com/libp2p/specs/pull/508) that describes how to use HTTP semantics over stream transports as well as how to do discovery of what protocols are available (and where they are mounted) on a given endpoint. In order for a given HTTP protocol like the IPFS Gateway API to work in this environment it requires a protocol identifier. +libp2p has a [http+libp2p specification](https://github.com/libp2p/specs/pull/508) that describes how to use HTTP semantics over stream transports, as well as how to do discovery of what protocols are available (and where they are mounted), on a given endpoint. In order for a given HTTP protocol like the IPFS Gateway API to work in this environment it requires a protocol identifier. The protocol identifier for the IPFS Gateway when used over libp2p is `/ipfs/gateway`. This protocol identifier is shared among Gateway specifications (e.g. whether an endpoint only supports :cite[trustless-gateway], supports more of :cite[path-gateway], etc. is not considered here). \ No newline at end of file From d65550cf5cd265817ed6352ad7059412dbb75ae6 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Tue, 3 Oct 2023 21:18:56 +0200 Subject: [PATCH 3/4] libp2p-gw: mapping example and small editorials --- src/http-gateways/libp2p-gateway.md | 72 ++++++++++++++++++++++++++--- 1 file changed, 65 insertions(+), 7 deletions(-) diff --git a/src/http-gateways/libp2p-gateway.md b/src/http-gateways/libp2p-gateway.md index 55ca449c8..a1ff633f2 100644 --- a/src/http-gateways/libp2p-gateway.md +++ b/src/http-gateways/libp2p-gateway.md @@ -1,24 +1,82 @@ --- -title: libp2p Transport Gateway Specification +title: libp2p+HTTP Transport Gateway Specification description: > - The libp2p Transport Gateway specification describes how Gateway APIs can be used over libp2p transports. + The libp2p Transport Gateway specification describes how HTTP Gateway semantics can be used over libp2p transports. date: 2023-08-29 maturity: reliable editors: - name: Adin Schmahmann github: aschmahmann + affiliation: + name: Protocol Labs + url: https://protocol.ai/ - name: Marcin Rataj github: lidel url: https://lidel.org/ + affiliation: + name: Protocol Labs + url: https://protocol.ai/ xref: - path-gateway - trustless-gateway -tags: ['httpGateways', 'lowLevelHttpGateways'] -order: 1 +tags: ['httpGateways', 'lowLevelHttpGateways', 'exchange', 'transport'] +order: 3 --- -The libp2p Transport Gateway specification describes how Gateway APIs can be used over [libp2p](https://github.com/libp2p/specs) transports. +## Introduction -libp2p has a [http+libp2p specification](https://github.com/libp2p/specs/pull/508) that describes how to use HTTP semantics over stream transports, as well as how to do discovery of what protocols are available (and where they are mounted), on a given endpoint. In order for a given HTTP protocol like the IPFS Gateway API to work in this environment it requires a protocol identifier. +This specification describes how HTTP Gateway semantics +and APIs can be used over [libp2p](https://github.com/libp2p/specs) transports. -The protocol identifier for the IPFS Gateway when used over libp2p is `/ipfs/gateway`. This protocol identifier is shared among Gateway specifications (e.g. whether an endpoint only supports :cite[trustless-gateway], supports more of :cite[path-gateway], etc. is not considered here). \ No newline at end of file +## Specification + +The [libp2p+HTTP specification](https://github.com/libp2p/specs/pull/508) +describes how to use HTTP semantics over stream transports, as well as how +to do discovery of what protocols are available (and where they are mounted). + +### `.well-known/libp2p` + +libp2p application sub-protocols exposed behind `/http/1.1` protocol can be +discovered by the well-known resource (:cite[rfc8615]) at `.well-known/libp2p`. + +#### Protocol identifier + +In order for a given HTTP Gateway protocol like the :cite[trustless-gateway] to +work in this environment it requires a protocol identifier to act as a key in +the `.well-known/libp2p` mapping file. + +The `/http/1.1` sub-protocol identifier for the IPFS Gateway when used over libp2p is: + +``` +/ipfs/gateway +``` + +#### Protocol mounting + +A reference `.well-known/libp2p` JSON body with mapping that assumes the gateway to be mounted at `/`: + +```js +{ + "protocols": { + "/ipfs/gateway": {"path": "/"}, + } +} +``` + +## Gateway type detection + +The protocol identifier is shared among Gateway specifications. + +HTTP server mounted behind the `/ipfs/gateway` identifier MUST expose +:cite[trustless-gateway], but is free to also support other gateway types and +features. + +:::note + +Signaling Features on HTTP Gateways is wip in [IPIP-425](https://github.com/ipfs/specs/pull/425). + +Until the IPIP is finalized, client implementations SHOULD perform feature +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) +response type from :cite[trustless-gateway] is available. + +::: From 3ff4e3fb7479d94da6b3c1ede0d3f1b1e612b7fb Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Fri, 6 Oct 2023 15:16:58 +0200 Subject: [PATCH 4/4] libp2p-gateway: switch to draft we want a spec that people can implement, and we don't have a client in Kubo yet (only server), so switching to draft sets proper expectations about the stability of the document --- src/http-gateways/libp2p-gateway.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/http-gateways/libp2p-gateway.md b/src/http-gateways/libp2p-gateway.md index a1ff633f2..40b6a0d37 100644 --- a/src/http-gateways/libp2p-gateway.md +++ b/src/http-gateways/libp2p-gateway.md @@ -2,8 +2,8 @@ title: libp2p+HTTP Transport Gateway Specification description: > The libp2p Transport Gateway specification describes how HTTP Gateway semantics can be used over libp2p transports. -date: 2023-08-29 -maturity: reliable +date: 2023-10-04 +maturity: draft editors: - name: Adin Schmahmann github: aschmahmann