HbarSuite Docs
  • Welcome to HbarSuite
  • HbarSuite Developer Documentation
    • HbarSuite Smart Engine Applications
      • @hsuite/cross-chain-exchange
      • @hsuite/dao
      • @hsuite/exchange
      • @hsuite/launchpad
      • @hsuite/multisig
      • @hsuite/nft-exchange
    • HSuite Libraries
      • @hsuite/api-key
      • @hsuite/auth-types
      • @hsuite/auth
      • @hsuite/client-types
      • @hsuite/client
      • @hsuite/dkg-types
      • @hsuite/hashgraph-types
      • @hsuite/health
      • @hsuite/helpers
      • @hsuite/ipfs
      • @hsuite/smart-config
      • @hsuite/smart-network-types
      • @hsuite/smart-transaction-types
      • @hsuite/smartnode-sdk
      • @hsuite/snapshots
      • @hsuite/subscriptions-types
      • @hsuite/subscriptions
      • @hsuite/throttler-types
      • @hsuite/throttler
      • @hsuite/users-types
      • @hsuite/users
      • @hsuite/validators-types
  • General Documentation
    • Tokenomics
      • Tokenomics v1
      • Tokenomics V2
    • Smart Apps and Interaction
      • Subscription-Based Model
      • Token-Gate Model
    • The Smart Node Network
      • security-layer
        • Security Layer Integration
        • Setting Up Secure Clusters
        • Generating and Sharing Keys Collaboratively
        • Protecting Secrets with Shamir's Method
        • Managing Cluster Membership
        • Handling Node Expulsion and Replacement
        • Automating Responses to Network Changes & Key Rotation
        • Ensuring Continuous Operation and Recovery
      • Understanding Validators in Our System
        • Type of Validators Explained
    • What is a Smart Node?
  • Restful APIs Documentation
Powered by GitBook
On this page
  • Features
  • Installation
  • Module Configuration
  • API Endpoints
  • Service Usage
  • Docker Support
  • Architecture
  • Features in Detail
  • Content Pinning
  • File Handling
  • Metadata Processing
  • High Availability
  • Requirements
  • License
  1. HbarSuite Developer Documentation
  2. HSuite Libraries

@hsuite/ipfs

A comprehensive NestJS module for interacting with IPFS (InterPlanetary File System) through both direct node access and HTTP gateways.

Features

  • 🚀 Direct IPFS node interaction

  • 🌐 HTTP gateway support with fallback

  • 📌 Content pinning management

  • 📁 File upload and retrieval

  • 🔍 Metadata processing

  • 🗄️ MongoDB integration for pin persistence

  • 🐳 Docker support for local IPFS node

Installation

npm install @hsuite/ipfs

Module Configuration

Import and configure the module in your NestJS application:

import { IpfsModule } from '@hsuite/ipfs';

@Module({
  imports: [
    IpfsModule.forRootAsync({
      useFactory: (configService: ConfigService) => ({
        nodeUrl: configService.get('IPFS_NODE_URL'),
        gatewaysUrls: configService.get('IPFS_GATEWAY_URLS'),
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

API Endpoints

The module exposes the following REST endpoints:

Method
Endpoint
Description
Response

POST

/ipfs/pin/:cid

Pin content to IPFS

Pin operation result

DELETE

/ipfs/unpin/:cid

Unpin content from IPFS

Unpin operation result

GET

/ipfs/:cid

Read content from IPFS

Content data

GET

/ipfs/file/:cid

Get file from IPFS

File data and type

GET

/ipfs/metadata/:cid

Get metadata from IPFS

Processed metadata

POST

/ipfs/upload

Upload and pin file to IPFS

CID of pinned file

Service Usage

Inject the IpfsService into your components:

import { IpfsService } from '@hsuite/ipfs';

@Injectable()
export class YourService {
  constructor(private readonly ipfsService: IpfsService) {}

  async pinContent(cid: string, owner: IAuth.ICredentials.IWeb3.IEntity) {
    return await this.ipfsService.pin(cid, owner);
  }

  async uploadFile(file: Express.Multer.File, session: IAuth.ICredentials.IWeb3.IEntity) {
    return await this.ipfsService.uploadAndPin(file, session);
  }
}

Docker Support

The module includes Docker configuration for running a local IPFS node:

# Start IPFS node
docker-compose -f docker/docker-compose.yml up -d

# Stop IPFS node
docker-compose -f docker/docker-compose.yml down

Default ports:

  • 4001: IPFS swarm

  • 5001: IPFS API

  • 8080: IPFS Gateway

Architecture

The module is built with a layered architecture:

  • Controller Layer: Handles HTTP requests and input validation

  • Service Layer: Orchestrates operations between node and gateway providers

  • Provider Layer:

    • Node Provider: Direct IPFS network interaction

    • Gateway Provider: HTTP gateway access

  • Persistence Layer: MongoDB integration for pin management

Features in Detail

Content Pinning

Manages content persistence on IPFS nodes:

  • Pin content with owner tracking

  • Unpin content with authorization

  • Automatic pin record management

File Handling

Comprehensive file operations:

  • Upload with stream processing

  • File type detection

  • Size validation (default 100MB limit)

  • Automatic pinning

Metadata Processing

Advanced metadata handling:

  • Automatic metadata extraction

  • Image URL resolution

  • Gateway URL generation

High Availability

Built-in reliability features:

  • Gateway fallback support

  • Multiple gateway support

  • Automatic retry mechanisms

Requirements

  • Node.js >= 14

  • MongoDB >= 4.4

  • IPFS node or gateway access

  • Docker (optional, for local node)

License

This project is licensed under the MIT License - see the LICENSE file for details.


Built with ❤️ by the HbarSuite Team Copyright © 2024 HbarSuite. All rights reserved.

Previous@hsuite/helpersNext@hsuite/smart-config

Last updated 3 months ago