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
CORS and rate limiting support

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

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

Architecture and Code Structure

Key Components

HTTP Server (src/server.cpp/hpp)
- Uses httplib for HTTP handling
- Implements all REST endpoints
- Handles authentication, CORS, and rate limiting
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
Request Handlers
- put_handler.cpp/hpp: File upload logic with deduplication
- update_handler.cpp/hpp: Metadata update functionality
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
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:

File upload and retrieval by hash and label:tag
Metadata preservation including custom fields
Tag versioning behavior
File deletion
Rate limiting functionality
MD5 checksum verification

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.

3.0 KiB Raw Blame History