69 lines
2.5 KiB
Markdown
69 lines
2.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Overview
|
|
|
|
SOS (Simple Object Storage) is a Bash script client for uploading files to a simple object storage server. The repository contains the main `sos` script for uploading files, along with testing and publishing infrastructure.
|
|
|
|
## Key Commands
|
|
|
|
### Testing
|
|
```bash
|
|
./test.sh # Run comprehensive test suite with Docker container
|
|
```
|
|
|
|
### Publishing
|
|
```bash
|
|
./publish.sh # Publish sos tool to getpkg.xyz and getbin.xyz
|
|
```
|
|
|
|
### Direct Usage
|
|
```bash
|
|
./sos upload <server> <file> <label:tag> [label:tag ...]
|
|
# Example: ./sos upload getbin.xyz ./file.txt file:latest version:1.0
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Core Components
|
|
|
|
1. **sos** - Main bash script (233 lines)
|
|
- Handles file uploads to object storage servers
|
|
- Supports deduplication via SHA-256 hashing
|
|
- Manages authentication via SOS_WRITE_TOKEN environment variable
|
|
- Falls back to getpkg for hash calculation if sha256sum/shasum unavailable
|
|
|
|
2. **test.sh** - Comprehensive test suite
|
|
- Sets up Docker-based test environment
|
|
- Tests upload, retrieval, deduplication, metadata updates
|
|
- Validates authentication and error handling
|
|
- Automatically cleans up test resources
|
|
|
|
3. **publish.sh** - Release automation
|
|
- Publishes to getpkg.xyz (package registry)
|
|
- Uploads to getbin.xyz using sos itself
|
|
- Injects version timestamps during build
|
|
|
|
### Key Technical Details
|
|
|
|
- **Authentication**: Uses Bearer token authentication stored in `SOS_WRITE_TOKEN` or `~/.config/sos/write_token.txt`
|
|
- **Deduplication**: Calculates SHA-256 hash locally before upload to check if file already exists
|
|
- **Label System**: Files are tagged with `label:tag` format for versioning and organization
|
|
- **Test Mode**: Set `SOS_TEST_MODE=1` to use HTTP instead of HTTPS for local testing
|
|
- **Dependencies**: Requires curl, jq for JSON parsing; optionally uses sha256sum/shasum or falls back to getpkg
|
|
|
|
### Server Endpoints Used
|
|
- `/exists/<hash>` - Check if file already exists
|
|
- `/upload` - Upload new file with metadata
|
|
- `/update` - Update metadata for existing file
|
|
- `/hash/<label:tag>` - Get hash for a labeled file
|
|
- `/meta/<hash>` - Get metadata for a file by hash
|
|
- `/<label:tag>` or `/<hash>` - Download file
|
|
|
|
## Development Notes
|
|
|
|
- The script uses strict error handling (`set -euo pipefail`)
|
|
- Temporary directories are automatically cleaned up on exit
|
|
- Version placeholders are replaced during publishing
|
|
- Tests require Docker for running the SOS server container |