HTTP Gateway Client for Helia

This module provides a pure HTTP-only client for accessing IPFS content through Trustless Gateways, without requiring libp2p or P2P networking. This is different from the JavaScript @helia/http module which is a hybrid approach (P2P + HTTP gateways).

Comparison with JavaScript Helia

For full P2P support in Rust, use the main helia crate with helia-utils::create_helia().

Overview

This client implements the Trustless Gateway specification to fetch blocks from public or private HTTP gateways. It's designed for lightweight IPFS access in environments where P2P networking is unavailable, restricted, or unnecessary.

Key Features

• Fetch content from IPFS via HTTP gateways (e.g., trustless-gateway.link, 4everland.io)
• Trustless Gateway spec - Uses /ipfs/{cid}?format=raw with Accept: application/vnd.ipld.raw
• Gateway fallback - Automatically tries multiple gateways if one fails
• Retry logic - Exponential backoff for transient failures
• Simple integration - Implements the same Helia trait as full P2P nodes

When to Use HTTP Mode

✅ Good for:

• Browser-based applications (WASM)
• Serverless functions (AWS Lambda, Cloudflare Workers)
• Edge computing environments
• CI/CD pipelines
• Quick prototyping and testing
• Read-only IPFS access
• Restricted network environments (firewalls, no UDP)

❌ Not ideal for:

• Content publishing (use full P2P node)
• High-throughput applications (gateway rate limits)
• Mission-critical apps requiring 100% uptime (single point of failure)
• Applications that need pinning
• Private/offline IPFS networks

Architecture

┌──────────────┐
│ Your App     │
└──────┬───────┘
       │ Helia trait
       ↓
┌──────────────┐
│ HTTP Client  │
└──────┬───────┘
       │ HTTPS
       ↓
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ ipfs.io      │ OR  │ dweb.link    │ OR  │ Custom GW    │
└──────────────┘     └──────────────┘     └──────────────┘

Quick Start

use helia_http::create_helia_http;
use helia_interface::Blocks;
use cid::Cid;

// Create HTTP-only Helia node
let helia = create_helia_http().await?;

// Fetch content by CID
let cid: Cid = "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
    .parse()?;
let content = helia.blockstore().get(&cid, None).await?;

println!("Fetched {} bytes from IPFS", content.len());

Gateway Configuration

By default, the client uses public gateways with automatic fallback:

use helia_http::{create_helia_http_with_gateways, GatewayConfig};

// Use custom gateways
let gateways = vec![
    "https://ipfs.io".to_string(),
    "https://dweb.link".to_string(),
    "https://cloudflare-ipfs.com".to_string(),
];

let config = GatewayConfig {
    gateways,
    timeout_secs: 30,
    max_retries: 3,
};

let helia = create_helia_http_with_gateways(config).await?;

Error Handling

use helia_http::create_helia_http;
use helia_interface::{Blocks, HeliaError};
use cid::Cid;

let helia = create_helia_http().await?;
let cid: Cid = "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi".parse()?;

match helia.blockstore().get(&cid, None).await {
    Ok(content) => {
        println!("Success: {} bytes", content.len());
    }
    Err(e) => match e {
        HeliaError::BlockNotFound(_) => {
            eprintln!("Content not found on any gateway");
        }
        HeliaError::NetworkError(msg) => {
            eprintln!("Network error: {}", msg);
        }
        _ => {
            eprintln!("Other error: {}", e);
        }
    }
}

Performance Characteristics

Latency

• First request: 100-500ms (gateway lookup + HTTP roundtrip)
• Cached at gateway: 10-50ms (CDN hit)
• Local cache: <1ms (if using blockstore cache)

Throughput

• Limited by gateway: ~10-50 MB/s typical
• Rate limits: Varies by gateway (usually 100-1000 req/min)
• Concurrent requests: Supported (10-100 parallel)

Comparison with P2P Mode

Gateway URLs

The client constructs gateway URLs in these formats:

https://ipfs.io/ipfs/{cid}           - Path gateway
https://{cid}.ipfs.dweb.link         - Subdomain gateway
https://cloudflare-ipfs.com/ipfs/{cid} - Path gateway

Limitations

1. Read-only - Cannot publish content to IPFS
2. No pinning - Cannot pin content (gateways handle this)
3. Gateway dependency - Availability depends on gateway uptime
4. Rate limits - Subject to gateway rate limiting
5. Privacy - Gateways can see what content you access
6. No P2P - Cannot participate in IPFS network directly

Best Practices

1. Use multiple gateways - Configure fallbacks for reliability
2. Cache aggressively - Use local blockstore cache
3. Implement backoff - Respect gateway rate limits
4. Monitor latency - Track gateway performance
5. Consider privacy - Use trusted gateways or run your own

Integration with Other Modules

The HTTP gateway client implements the Helia trait, so it works seamlessly with:

• helia-unixfs - Fetch files and directories
• helia-dag-cbor - Fetch CBOR-encoded data structures
• helia-dag-json - Fetch JSON data structures
• helia-json - Fetch JSON content
• helia-strings - Fetch UTF-8 strings
• helia-car - Export fetched content to CAR files

use helia_http::create_helia_http;
use helia_strings::strings;
use cid::Cid;

// Use HTTP gateway with strings module
let helia = create_helia_http().await?;
let strings = strings(helia.clone());

let cid: Cid = "bafkreiabaeaqcaibaeaqcaibaeaqcaibaeaqcaibaeaqcaibaeaqcaibae".parse()?;
let content = strings.get(&cid, Default::default()).await?;
println!("String content: {}", content);

Examples

See examples/ directory for:

• http_fetch.rs - Basic content fetching
• http_gateway_fallback.rs - Multiple gateway configuration
• http_with_unixfs.rs - Fetching files via HTTP

See Also

• Helia - Core trait implemented by this module
• Blocks - Block storage interface
• IPFS HTTP Gateway Specification