Complete CRUD Operations for all HeroFS entities (Filesystems, Directories, Files, Blobs, Symlinks)
Advanced Filesystem Tools (find, copy, move, remove, import/export)
CORS Support for frontend integration
JSON Request/Response with consistent error handling
RESTful Design following standard HTTP conventions
Production Ready with proper error handling and validation

Quick Start

import incubaid.herolib.hero.herofs_server

// Create and start server
mut server := herofs_server.new(
    port: 8080
    host: 'localhost'
    cors_enabled: true
    allowed_origins: ['*']
)!

server.start()!

API Endpoints

Health & Info

GET /health - Health check
GET /api - API information and available endpoints

Filesystems (`/api/fs`)

GET /api/fs - List all filesystems
GET /api/fs/:id - Get filesystem by ID
POST /api/fs - Create new filesystem
PUT /api/fs/:id - Update filesystem
DELETE /api/fs/:id - Delete filesystem
GET /api/fs/:id/exists - Check if filesystem exists
POST /api/fs/:id/usage/increase - Increase usage counter
POST /api/fs/:id/usage/decrease - Decrease usage counter
POST /api/fs/:id/quota/check - Check quota availability

Directories (`/api/dirs`)

GET /api/dirs - List all directories
GET /api/dirs/:id - Get directory by ID
POST /api/dirs - Create new directory
PUT /api/dirs/:id - Update directory
DELETE /api/dirs/:id - Delete directory
POST /api/dirs/create-path - Create directory path
GET /api/dirs/:id/has-children - Check if directory has children
GET /api/dirs/:id/children - Get directory children

Files (`/api/files`)

GET /api/files - List all files
GET /api/files/:id - Get file by ID
POST /api/files - Create new file
PUT /api/files/:id - Update file
DELETE /api/files/:id - Delete file
POST /api/files/:id/add-to-directory - Add file to directory
POST /api/files/:id/remove-from-directory - Remove file from directory
POST /api/files/:id/metadata - Update file metadata
POST /api/files/:id/accessed - Update accessed timestamp
GET /api/files/by-filesystem/:fs_id - List files by filesystem

Blobs (`/api/blobs`)

GET /api/blobs - List all blobs
GET /api/blobs/:id - Get blob by ID
POST /api/blobs - Create new blob
PUT /api/blobs/:id - Update blob
DELETE /api/blobs/:id - Delete blob
GET /api/blobs/:id/content - Get blob raw content
GET /api/blobs/:id/verify - Verify blob integrity

Symlinks (`/api/symlinks`)

GET /api/symlinks - List all symlinks
GET /api/symlinks/:id - Get symlink by ID
POST /api/symlinks - Create new symlink
PUT /api/symlinks/:id - Update symlink
DELETE /api/symlinks/:id - Delete symlink
GET /api/symlinks/:id/is-broken - Check if symlink is broken

Blob Membership (`/api/blob-membership`)

GET /api/blob-membership - List all blob memberships
GET /api/blob-membership/:id - Get blob membership by ID
POST /api/blob-membership - Create new blob membership
DELETE /api/blob-membership/:id - Delete blob membership

Filesystem Tools (`/api/tools`)

POST /api/tools/find - Find files and directories
POST /api/tools/copy - Copy files or directories
POST /api/tools/move - Move files or directories
POST /api/tools/remove - Remove files or directories
POST /api/tools/list - List directory contents
POST /api/tools/import/file - Import file from real filesystem
POST /api/tools/import/directory - Import directory from real filesystem
POST /api/tools/export/file - Export file to real filesystem
POST /api/tools/export/directory - Export directory to real filesystem
POST /api/tools/content/:fs_id - Get file content as text

Request/Response Format

Standard Response Structure

{
  "success": true,
  "data": { ... },
  "message": "Operation completed successfully",
  "error": ""
}

Error Response Structure

{
  "success": false,
  "error": "Error description",
  "message": "User-friendly error message"
}

Example Usage

Create a Filesystem

curl -X POST http://localhost:8080/api/fs \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_filesystem",
    "description": "My test filesystem",
    "quota_bytes": 1073741824
  }'

Create a Directory

curl -X POST http://localhost:8080/api/dirs \
  -H "Content-Type: application/json" \
  -d '{
    "name": "documents",
    "fs_id": 1,
    "parent_id": 0,
    "description": "Documents directory"
  }'

Find Files

curl -X POST http://localhost:8080/api/tools/find \
  -H "Content-Type: application/json" \
  -d '{
    "fs_id": 1,
    "pattern": "*.txt",
    "recursive": true
  }'

Import File

curl -X POST http://localhost:8080/api/tools/import/file \
  -H "Content-Type: application/json" \
  -d '{
    "fs_id": 1,
    "real_path": "/path/to/local/file.txt",
    "vfs_path": "/imported/file.txt",
    "overwrite": false
  }'

HTTP Status Codes

200 OK - Successful operation
201 Created - Resource created successfully
400 Bad Request - Invalid request format or parameters
404 Not Found - Resource not found
500 Internal Server Error - Server error

CORS Support

The server supports CORS for frontend integration. Configure allowed origins when creating the server:

mut server := herofs_server.new(
    cors_enabled: true
    allowed_origins: ['http://localhost:3000', 'https://myapp.com']
)!

Error Handling

The API provides comprehensive error handling with:

Input validation for all parameters
Proper HTTP status codes
Detailed error messages
Consistent error response format

Integration with HeroFS

The server integrates seamlessly with the HeroFS module, providing:

Full access to all HeroFS functionality
Proper factory pattern usage
Data integrity through BLAKE3 hashing
Efficient Redis-based storage
Complete filesystem operations

Production Deployment

For production use:

Configure appropriate CORS origins
Set up proper logging
Configure Redis connection
Set appropriate quotas and limits
Monitor server performance

The server is designed to be production-ready with proper error handling, validation, and performance considerations.

README.md

HeroFS REST API Server

Features