Skip to content

Latest commit

 

History

History
82 lines (62 loc) · 2.38 KB

libp2p-gateway.md

File metadata and controls

82 lines (62 loc) · 2.38 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.
2024-04-20
draft
name github affiliation
Adin Schmahmann
aschmahmann
name url
Protocol Labs
name github url affiliation
Marcin Rataj
lidel
name url
Protocol Labs
path-gateway
trustless-gateway
httpGateways
lowLevelHttpGateways
exchange
transport
3

Introduction

This specification describes how HTTP Gateway semantics and APIs can be used over libp2p transports.

Specification

The libp2p+HTTP specification 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/protocols

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 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/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": "/"},
  }
}

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.

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) response type from :cite[trustless-gateway] is available.

:::