simple-object-server/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Simple Object Server is a C++23 application that provides a REST API for storing and retrieving files with metadata. Key features include:

• File storage with deduplication using content hashing
• Metadata management with label:tag system
• Token-based authentication for write operations
• Support for large file uploads (up to 6GB)
• CORS and rate limiting support
• High-performance HTTP handling with Drogon framework

Common Development Commands

Building

# Build for current architecture (debug mode)
./build.sh

# Build for multiple architectures (release mode)
./publish.sh

Testing

# Build Docker image and run all tests
./test.sh

# Run integration tests directly
./testing/test.sh

# Test large file uploads (1GB)
./testing/test_1GB_file_upload.sh

Development Workflow

1. Make changes to C++ source files in /src
2. Run ./build.sh to compile and check for errors
3. Run ./test.sh to ensure tests pass
4. Use ./publish.sh only when ready to create multi-architecture releases

Architecture and Code Structure

Key Components

1. HTTP Server (src/server.cpp/hpp)

   • Uses Drogon framework for high-performance HTTP handling
   • Implements all REST endpoints via HttpController
   • Handles authentication, CORS, and rate limiting
   • Supports large file uploads (up to 6GB) with efficient streaming

2. Database Layer (src/database.cpp/hpp)

   • SQLite-based metadata storage
   • Stores object hashes, label:tags, and custom metadata as JSON
   • Manages label:tag uniqueness and versioning

3. Request Handlers

   • HttpController.cpp/hpp: Drogon HTTP controller for route handling
   • put_handler.cpp/hpp: File upload logic with deduplication and streaming support
   • update_handler.cpp/hpp: Metadata update functionality

4. Utilities

   • compression.cpp/hpp: GZIP compression support
   • hash.cpp/hpp: SHA-256 hashing for content deduplication
   • string_trim.cpp/hpp: String utility functions

API Design Patterns

• Files are stored by content hash to enable deduplication
• Label:tag system allows human-friendly naming (e.g., "project:latest")
• When a new file is uploaded with an existing label:tag, the tag is moved to the new file
• All metadata is preserved as JSON, allowing custom fields beyond labeltags

Build System

• Uses CMake with C++23 standard
• Drogon framework statically linked for high performance
• Docker-based build process for consistency across platforms
• Static linking for standalone executables
• Multi-architecture support (linux/amd64, linux/arm64, windows/amd64)

Testing Approach

The test suite (testing/test.sh) covers:

1. File upload and retrieval by hash and label:tag
2. Metadata preservation including custom fields
3. Tag versioning behavior
4. File deletion
5. Rate limiting functionality
6. MD5 checksum verification
7. Large file upload testing (1GB files)

Tests use curl for API interactions and jq for JSON parsing.

Configuration

The server uses JSON configuration (sos_config.json) with these key settings:

• write_tokens: Array of authentication tokens
• storage_path: Where files are stored
• cors: CORS policy configuration
• rate_limiting: Auth attempt limits

Default configuration is suitable for Docker deployment with storage at /data/storage.

Architecture Notes

HTTP Framework Migration

The server has been migrated from httplib to Drogon for improved performance and scalability:

• Previous: Used cpp-httplib (single-header library)
• Current: Uses Drogon framework with async request handling
• Benefits: Better performance, larger file support, thread-safe operation
• Compatibility: Full API compatibility maintained during migration

Performance Characteristics

• Large File Support: Efficiently handles files up to 6GB
• Memory Management: Streaming file processing to minimize memory usage
• Deduplication: Content-based deduplication reduces storage requirements
• Thread Safety: Singleton pattern with proper mutex protection
• Security: Request size limits and rate limiting prevent abuse