Skip to content

Latest commit

 

History

History
81 lines (62 loc) · 3.18 KB

libp2p-gateway.md

File metadata and controls

81 lines (62 loc) · 3.18 KB
title description date maturity editors xref tags order
libp2p+HTTP Transport Gateway Specification
Describes how HTTP Gateway semantics can be used over libp2p transports and how libp2p can coexist with other HTTP services on the same host.
2025-03-06
draft
name github affiliation
Adin Schmahmann
aschmahmann
name url
Shipyard
name github affiliation
Marcin Rataj
lidel
name url
Shipyard
http-routing-v1
path-gateway
trustless-gateway
httpGateways
lowLevelHttpGateways
exchange
transport
3

This specification describes how HTTP Gateway semantics and APIs can be used over libp2p transports, and how libp2p can coexist with other HTTP services on the same host.

libp2p HTTP Protocols Manifest

The libp2p+HTTP specification describes how to use libp2p with 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/protocols

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

Protocol Identifier

In order for a pure HTTP Gateway protocol like the :cite[trustless-gateway] to coexist with libp2p in this environment it requires a protocol identifier to act as a key in the .well-known/libp2p/protocols 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/protocols JSON body with mapping that assumes the gateway to be mounted at /:

{
  "protocols": {
    "/ipfs/gateway": {"path": "/"},
  }
}

Peer ID Authentication

Peer ID Authentication over HTTP is optional and SHOULD NOT be required by Trustless Gateway HTTP endpoint defined for /ipfs/gateway handler.

Clients following the Trustless Gateway specification MUST verify each CID individually, without being concerned with peer identity. PeerID authentication is not required for trustless retrieval and HTTP-only clients SHOULD work without it.

Gateway Type Detection

The /ipfs/gateway protocol identifier is shared among all Gateway specifications.

An HTTP server mounted behind the /ipfs/gateway identifier MUST expose the most basic block (application/vnd.ipld.raw) responses from :cite[trustless-gateway], but MAY also support other gateway types and features.

Client implementations SHOULD perform feature detection on their own, or assume only the most basic block (application/vnd.ipld.raw) response type from :cite[trustless-gateway] is available.