ipfrs-interface

API layer for IPFRS - HTTP Gateway and RPC interface.

Overview

ipfrs-interface provides external access to IPFRS functionality:

• HTTP Gateway: Kubo-compatible web interface
• RPC API: JSON-RPC and gRPC endpoints
• High-Speed API: Custom optimized protocol
• FFI Bindings: C/Python/Node.js integration

Key Features

HTTP Gateway (Kubo Compatible)

Standards-compliant gateway for IPFS clients:

• GET /ipfs/{cid}: Retrieve content by CID
• POST /api/v0/add: Upload files
• POST /api/v0/cat: Download files
• POST /api/v0/dag/: DAG operations
• WebSocket Support: Real-time updates

High-Speed API

Custom protocol optimized for performance:

• Binary Protocol: Faster than JSON
• Streaming: Chunked uploads/downloads
• Batch Operations: Multiple requests in one call
• Zero-Copy: Direct buffer access

gRPC Interface

Type-safe, high-performance RPC:

• Protobuf Definitions: Strongly typed API
• Streaming Support: Bidirectional streams
• Interceptors: Authentication, logging, metrics
• Language Bindings: Auto-generated clients

FFI Bindings

Native library interface for embedding:

• C API: Standard C-compatible interface
• Python Bindings: PyO3-based wrapper
• Node.js Addon: N-API native module
• Safety Wrappers: Memory-safe abstractions

Architecture

External Clients
    ↓
ipfrs-interface
├── http/          # HTTP gateway (Axum)
│   ├── v0/        # Kubo-compatible API
│   └── v1/        # High-speed API
├── grpc/          # gRPC server
├── ffi/           # Foreign function interface
└── websocket/     # WebSocket handler
    ↓
ipfrs-core & other crates

Design Principles

• Performance: Built on Axum (fastest Rust web framework)
• Compatibility: Wire-compatible with IPFS Kubo
• Extensibility: Easy to add new endpoints
• Security: Rate limiting, authentication, CORS

Usage Example

HTTP Gateway

use ipfrs_interface::HttpGateway;

// Start gateway
let gateway = HttpGateway::builder()
    .bind("0.0.0.0:8080")
    .enable_cors()
    .build()?;

gateway.serve().await?;

gRPC Server

use ipfrs_interface::GrpcServer;

// Start gRPC server
let server = GrpcServer::builder()
    .bind("0.0.0.0:5001")
    .add_service(ipfs_service)
    .build()?;

server.serve().await?;

FFI (C)

#include <ipfrs.h>

// Initialize node
ipfrs_node_t* node = ipfrs_node_new(config);

// Add file
ipfrs_cid_t* cid = ipfrs_add(node, data, len);

// Get file
uint8_t* data = ipfrs_cat(node, cid, &len);

// Cleanup
ipfrs_node_free(node);

API Endpoints

Kubo-Compatible (v0)

• /api/v0/add - Add files
• /api/v0/cat - Retrieve files
• /api/v0/get - Download files
• /api/v0/ls - List directory
• /api/v0/dag/get - Get DAG node
• /api/v0/dag/put - Put DAG node
• /api/v0/block/get - Get raw block
• /api/v0/block/put - Put raw block

High-Speed (v1)

• /v1/block/batch - Batch block operations
• /v1/stream/upload - Streaming upload
• /v1/stream/download - Streaming download
• /v1/tensor/get - Get tensor (zero-copy)

Performance Characteristics

Dependencies

• axum - Web framework
• tonic - gRPC framework
• tower - Middleware
• tokio - Async runtime

References

• IPFRS v0.1.0 Whitepaper (API Layer)
• IPFRS v0.3.0 Whitepaper (Interface Architecture)
• IPFS HTTP API: https://docs.ipfs.tech/reference/kubo/rpc/