100 lines
3.0 KiB
Markdown
100 lines
3.0 KiB
Markdown
# 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
|
|
```bash
|
|
# Build for current architecture (debug mode)
|
|
./build.sh
|
|
|
|
# Build for multiple architectures (release mode)
|
|
./publish.sh
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
# 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 httplib for HTTP handling
|
|
- Implements all REST endpoints
|
|
- Handles authentication, CORS, and rate limiting
|
|
|
|
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**
|
|
- `put_handler.cpp/hpp`: File upload logic with deduplication
|
|
- `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
|
|
- 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
|
|
|
|
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`. |