HeroFS REST API Server

A comprehensive REST API server for the HeroFS distributed filesystem, built with V and VEB framework.

Features

• 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'

Create a Directory

curl -X POST http://localhost:8080/api/dirs \
  -H 'Content-Type: application/json'

Find Files

curl -X POST http://localhost:8080/api/tools/find \
  -H 'Content-Type: application/json'

Import File

curl -X POST http://localhost:8080/api/tools/import/file \
  -H 'Content-Type: application/json'

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:

1. Configure appropriate CORS origins
2. Set up proper logging
3. Configure Redis connection
4. Set appropriate quotas and limits
5. Monitor server performance

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

fn error_response(error string, message string) ErrorResponse

Helper function to create error response

fn new(args NewFSServerArgs) !&FSServer

Create a new filesystem server

fn start_test_server(port int) !string

Start server on a specific port and return the base URL

fn success_response[T](data T, message string) APIResponse[T]

Helper function to create success response

struct APIResponse[T] {
pub:
	success bool
	data    T
	message string
	error   string
}

Standard API response structure

struct Context {
	veb.Context
}

Context struct for VEB

fn (mut ctx Context) created[T](data T, message string) veb.Result

fn (mut ctx Context) not_found(message ...string) veb.Result

fn (mut ctx Context) request_error(message string) veb.Result

fn (mut ctx Context) server_error(message string) veb.Result

fn (mut ctx Context) success[T](data T, message string) veb.Result

Context extension methods for common HTTP responses

struct ErrorResponse {
pub:
	success bool
	error   string
	message string
}

Error response structure

struct FSServer {
	veb.Controller
pub mut:
	fs_factory      herofs.FsFactory
	port            int
	host            string
	cors_enabled    bool
	allowed_origins []string
}

FSServer is the main server struct

fn (mut server FSServer) add_file_to_directory(mut ctx Context, id string) veb.Result

Add file to directory

fn (mut server FSServer) add_filesystem_to_blob_membership(mut ctx Context, hash string) veb.Result

Add filesystem to blob membership

fn (mut server FSServer) api_info(mut ctx Context) veb.Result

API info endpoint

fn (mut server FSServer) before_request(mut ctx Context)

Global error handler

fn (mut server FSServer) blob_exists_by_hash(mut ctx Context, hash string) veb.Result

Check if blob exists by hash

fn (mut server FSServer) check_filesystem_quota(mut ctx Context, id string) veb.Result

Check filesystem quota

fn (mut server FSServer) check_symlink_broken(mut ctx Context, id string) veb.Result

Check if symlink is broken

fn (mut server FSServer) copy_files(mut ctx Context) veb.Result

Copy files or directories

fn (mut server FSServer) cors_preflight(mut ctx Context, path string) veb.Result

CORS preflight handler

fn (mut server FSServer) create_blob(mut ctx Context) veb.Result

Create new blob

fn (mut server FSServer) create_blob_membership(mut ctx Context) veb.Result

Create new blob membership

fn (mut server FSServer) create_directory(mut ctx Context) veb.Result

Create new directory

fn (mut server FSServer) create_directory_path(mut ctx Context) veb.Result

Create directory path

fn (mut server FSServer) create_file(mut ctx Context) veb.Result

Create new file

fn (mut server FSServer) create_filesystem(mut ctx Context) veb.Result

Create new filesystem

fn (mut server FSServer) create_symlink(mut ctx Context) veb.Result

Create new symlink

fn (mut server FSServer) decrease_filesystem_usage(mut ctx Context, id string) veb.Result

Decrease filesystem usage

fn (mut server FSServer) delete_blob(mut ctx Context, id string) veb.Result

Delete blob

fn (mut server FSServer) delete_blob_membership(mut ctx Context, hash string) veb.Result

Delete blob membership

fn (mut server FSServer) delete_directory(mut ctx Context, id string) veb.Result

Delete directory

fn (mut server FSServer) delete_file(mut ctx Context, id string) veb.Result

Delete file

fn (mut server FSServer) delete_filesystem(mut ctx Context, id string) veb.Result

Delete filesystem

fn (mut server FSServer) delete_symlink(mut ctx Context, id string) veb.Result

Delete symlink

fn (mut server FSServer) directory_has_children(mut ctx Context, id string) veb.Result

Check if directory has children

fn (mut server FSServer) export_directory(mut ctx Context) veb.Result

Export directory to real filesystem

fn (mut server FSServer) export_file(mut ctx Context) veb.Result

Export file to real filesystem

fn (mut server FSServer) filesystem_exists(mut ctx Context, id string) veb.Result

Check if filesystem exists

fn (mut server FSServer) find_files(mut ctx Context) veb.Result

Find files and directories

fn (mut server FSServer) get_blob(mut ctx Context, id string) veb.Result

Get blob by ID

fn (mut server FSServer) get_blob_by_hash(mut ctx Context, hash string) veb.Result

Get blob by hash

fn (mut server FSServer) get_blob_content(mut ctx Context, id string) veb.Result

Get blob content (raw data)

fn (mut server FSServer) get_blob_membership(mut ctx Context, hash string) veb.Result

Get blob membership by hash

fn (mut server FSServer) get_directory(mut ctx Context, id string) veb.Result

Get directory by ID

fn (mut server FSServer) get_directory_children(mut ctx Context, id string) veb.Result

Get directory children

fn (mut server FSServer) get_file(mut ctx Context, id string) veb.Result

Get file by ID

fn (mut server FSServer) get_file_by_path(mut ctx Context, dir_id string, name string) veb.Result

Get file by path

fn (mut server FSServer) get_file_content(mut ctx Context, fs_id string) veb.Result

Get file content as text

fn (mut server FSServer) get_filesystem(mut ctx Context, id string) veb.Result

Get filesystem by ID

fn (mut server FSServer) get_filesystem_by_name(mut ctx Context, name string) veb.Result

Get filesystem by name

fn (mut server FSServer) get_symlink(mut ctx Context, id string) veb.Result

Get symlink by ID

fn (mut server FSServer) health_check(mut ctx Context) veb.Result

Health check endpoint

fn (mut server FSServer) import_directory(mut ctx Context) veb.Result

Import directory from real filesystem

fn (mut server FSServer) import_file(mut ctx Context) veb.Result

Import file from real filesystem

fn (mut server FSServer) increase_filesystem_usage(mut ctx Context, id string) veb.Result

Increase filesystem usage

fn (mut server FSServer) list_blob_memberships(mut ctx Context) veb.Result

List all blob memberships

fn (mut server FSServer) list_blobs(mut ctx Context) veb.Result

List all blobs

fn (mut server FSServer) list_directories(mut ctx Context) veb.Result

List all directories

fn (mut server FSServer) list_directories_by_filesystem(mut ctx Context, fs_id string) veb.Result

List directories by filesystem

fn (mut server FSServer) list_directory(mut ctx Context) veb.Result

List directory contents

fn (mut server FSServer) list_files(mut ctx Context) veb.Result

List all files

fn (mut server FSServer) list_files_by_directory(mut ctx Context, dir_id string) veb.Result

List files by directory

fn (mut server FSServer) list_files_by_filesystem(mut ctx Context, fs_id string) veb.Result

List files by filesystem

fn (mut server FSServer) list_files_by_mime_type(mut ctx Context, mime_type string) veb.Result

List files by MIME type

fn (mut server FSServer) list_filesystems(mut ctx Context) veb.Result

List all filesystems

fn (mut server FSServer) list_symlinks(mut ctx Context) veb.Result

List all symlinks

fn (mut server FSServer) list_symlinks_by_filesystem(mut ctx Context, fs_id string) veb.Result

List symlinks by filesystem

fn (mut server FSServer) middleware_error_handler(mut ctx Context)

Error handling middleware

fn (mut server FSServer) middleware_json_content_type(mut ctx Context)

Content type middleware for JSON APIs

fn (mut server FSServer) middleware_log_request(mut ctx Context)

Request logging middleware

fn (mut server FSServer) middleware_log_response(mut ctx Context)

Response logging middleware

fn (mut server FSServer) middleware_validate_request(mut ctx Context)

Request validation middleware

fn (mut server FSServer) move_files(mut ctx Context) veb.Result

Move files or directories

fn (mut server FSServer) remove_file_from_directory(mut ctx Context, id string) veb.Result

Remove file from directory

fn (mut server FSServer) remove_files(mut ctx Context) veb.Result

Remove files or directories

fn (mut server FSServer) remove_filesystem_from_blob_membership(mut ctx Context, hash string) veb.Result

Remove filesystem from blob membership

fn (mut server FSServer) start() !

fn (mut server FSServer) symlink_is_broken(mut ctx Context, id string) veb.Result

Check if symlink is broken

fn (mut server FSServer) update_blob(mut ctx Context, id string) veb.Result

Update blob

fn (mut server FSServer) update_directory(mut ctx Context, id string) veb.Result

Update directory

fn (mut server FSServer) update_file(mut ctx Context, id string) veb.Result

Update file

fn (mut server FSServer) update_file_accessed(mut ctx Context, id string) veb.Result

Update file accessed timestamp

fn (mut server FSServer) update_file_metadata(mut ctx Context, id string) veb.Result

Update file metadata

fn (mut server FSServer) update_filesystem(mut ctx Context, id string) veb.Result

Update filesystem

fn (mut server FSServer) update_symlink(mut ctx Context, id string) veb.Result

Update symlink

fn (mut server FSServer) verify_blob_integrity(mut ctx Context, id string) veb.Result

Verify blob integrity

struct NewFSServerArgs {
pub mut:
	port            int      = 8080
	host            string   = 'localhost'
	cors_enabled    bool     = true
	allowed_origins []string = ['*']
	redis           ?&redisclient.Redis
}

Factory args