Skip to content
This repository has been archived by the owner on Jun 20, 2024. It is now read-only.

Experimental gateway with delegated backend. No longer maintained, consider migrating to https://github.com/ipfs/rainbow/

License

Notifications You must be signed in to change notification settings

ipfs-inactive/bifrost-gateway

Folders and files

NameName
Last commit message
Last commit date

Latest commit

3e7ac21 · Jun 20, 2024
Mar 21, 2024
Apr 25, 2023
Oct 12, 2023
Mar 14, 2024
Mar 24, 2023
Jul 4, 2023
Feb 1, 2023
Jun 20, 2024
Aug 15, 2023
Sep 21, 2023
Oct 5, 2023
Feb 19, 2023
Mar 14, 2024
Mar 14, 2024
Aug 15, 2023
Feb 10, 2023
Oct 5, 2023
Feb 24, 2023
Feb 27, 2023
Jun 20, 2024
May 29, 2023
Oct 5, 2023
Apr 11, 2023
May 29, 2023
Jun 20, 2024

Repository files navigation

Warning

⚠️ bifrost-gateway is no longer maintained

You can continue using it, but it won't receive any security updates or fixes. Consider forking or migrating to Rainbow.

ℹ️ Migrating to Rainbow 🌈

The PROXY_GATEWAY_URL functionality is backported to Rainbow.

To use Rainbow with a remote block or CAR backend, configure it with:

RAINBOW_REMOTE_BACKENDS=<gwurl> RAINBOW_REMOTE_BACKENDS_MODE=block|car

For configuration details, visit: https://github.com/ipfs/rainbow/blob/main/docs/environment-variables.md

bifrost-gateway

A lightweight IPFS Gateway daemon backed by a remote data store.

Maintainers

IPFS Stewards

About

bifrost-gateway provides a single binary daemon implementation of HTTP+Web Gateway Specs.

It is capable of serving requests to:

Supported response types include both deserialized flat files, and verifiable Block/CAR.

For more information about IPFS Gateways, see:

Usage

Local build

$ go build
$ ./bifrost-gateway --help

Configuration

See ./bifrost-gateway --help and ./docs/environment-variables.md

Docker

Official Docker images are provided at hub.docker.com/r/ipfs/bifrost-gateway.

  • 🟢 Releases
    • latest and release always point at the latest release
    • vN.N.N point at a specific release tag
  • 🟠 Developer builds
    • main-latest always points at the HEAD of the main branch
    • main-YYYY-DD-MM-GITSHA points at a specific commit from the main branch
  • ⚠️ Experimental, unstable builds
    • staging-latest always points at the HEAD of the staging branch
    • staging-YYYY-DD-MM-GITSHA points at a specific commit from the staging branch
    • This tag is used by developers for internal testing, not intended for end users

When using Docker, make sure to pass necessary config via -e:

$ docker pull ipfs/bifrost-gateway:release
$ docker run --rm -it --net=host -e PROXY_GATEWAY_URL=http://127.0.0.1:8080  ipfs/bifrost-gateway:release

See ./docs/environment-variables.md.

FAQ

How to use other gateway as a block backend

All you need is a trustless gateway endpoint that supports verifiable response types. The minimum requirement is support for GET /ipfs/cid with application/vnd.ipld.raw (block by block).

To run against a compatible, local trustless gateway provided by Kubo or IPFS Desktop:

$ PROXY_GATEWAY_URL="http://127.0.0.1:8080" ./bifrost-gateway

See Proxy Backend in ./docs/environment-variables.md

How to run with Saturn CDN backend

Saturn is a CDN that provides a pool of trustless gateways.

bifrost-gateway supports it via the Caboose backend, which takes care of discovering and evaluating Block/CAR gateways (in Saturn called L1 nodes/peers) for increased availability.

See Saturn Backend in ./docs/environment-variables.md

How to debug

See GOLOG_LOG_LEVEL.

How to use tracing

For tracing configuration, please check boxo/docs/tracing.md on how to generate the traceparent HTTP header in order to be able to easily identify specific requests.

How could this work for hosting a public IPFS gateway

This is WIP, but the high level architecture is to move from

Old Kubo-based architecture:

Loading
graph LR
    A(((fa:fa-person HTTP</br>clients)))
    K[[Kubo]]
    N(((BGP Anycast,<br>HTTP load-balancers,<br>TLS termination)))

    D(((DHT)))

    P((( IPFS<br>Peers)))

    A -->| Accept: text/html, *| N
    A -->| Accept: application/vnd.ipld.raw | N
    A -->| Accept: application/vnd.ipld.car | N
    A -->| Accept: application/vnd.ipld.dag-json | N
    A -->| Accept: application/vnd.ipld.dag-cbor | N
    A -->| Accept: application/json | N
    A -->| Accept: application/cbor | N
    A -->| Accept: application/x-tar | N
    A -->| Accept: application/vnd.ipfs.ipns-record | N
    A -->| DNSLink Host: en.wikipedia-on-ipfs.org | N
    A -->| Subdomain Host: cid.ipfs.dweb.link | N

    N ==>| fa:fa-link HTTP GET <br> Content Path | K

    K -.- D
    K ===|fa:fa-cube bitswapl | P
    P -.- D

New Rhea architecture:

Loading
graph LR
    A(((fa:fa-person HTTP</br>clients)))
    B[[bifrost-gateway]]
    N(((BGP Anycast,<br>HTTP load-balancers,<br>TLS termination)))
    S(((Saturn<br>CDN)))
    I[[IPNI]]
    D(((DHT)))

    P((( IPFS<br>Peers)))

    A -->| Accept: text/html, *| N
    A -->| Accept: application/vnd.ipld.raw | N
    A -->| Accept: application/vnd.ipld.car | N
    A -->| Accept: application/vnd.ipld.dag-json | N
    A -->| Accept: application/vnd.ipld.dag-cbor | N
    A -->| Accept: application/json | N
    A -->| Accept: application/cbor | N
    A -->| Accept: application/x-tar | N
    A -->| Accept: application/vnd.ipfs.ipns-record | N
    A -->| DNSLink Host: en.wikipedia-on-ipfs.org | N
    A -->| Subdomain Host: cid.ipfs.dweb.link | N

    N ==>| fa:fa-link HTTP GET <br> Content Path | B
    
    B ==>|fa:fa-cube HTTP GET <br> Blocks | S
    S -.- I 
    I -.- D 
    D -.- P -.- I
  
    P ===|fa:fa-cube the best block/dag <br> transfer protocol | S

bifrost-gateway nodes are responsible for processing requests to:

Caveats:

  • IPFS Gateway interface based on reference implementation from boxo/gateway.
  • IPFS Backend based on https://saturn.tech and HTTP client talking to it via caboose with STRN_LOGGER_SECRET.
  • Remaining functional gaps facilitated by:
    • (initially) temporary delegation to legacy Kubo RPC (/api/v0) at https://node[0-3].delegate.ipfs.io infra (legacy nodes used by js-ipfs, in process of deprecation).
    • (long-term) IPNS_RECORD_GATEWAY_URL endpoint capable of resolving GET /ipns/{name} with Accept: application/vnd.ipfs.ipns-record

How does high level overview look like

Some high level areas:

Loading
mindmap
  root[bifrost-gateway]
    (boxo/gateway.IPFSBackend)
        Block Backend
        CAR Backend
    Ephemeral Storage
        Block Cache
        Exchange Backend
            Plain HTTP Fetch
            Caboose Saturn Fetch
    Resolving Content Paths
        Raw
        CAR
        UnixFS
        IPLD Data Model
            [DAG-JSON]
            [DAG-CBOR]
        Web
            HTTP Host Header
            HTML dir listings
            index.html
            _redirects
            HTTP Range Requests
        Namesys
            DNSLink
                EoDoH<br>ENS over DNS over HTTPS
            IPNS Records
    Metrics and Tracing
        Prometheus
            Counters
            Histograms
        OpenTelemetry
            Spans
            Exporters
            Trace Context

Contributing

Contributions are welcome! This repository is part of the IPFS project and therefore governed by our contributing guidelines.

License

SPDX-License-Identifier: Apache-2.0 OR MIT