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

./test.sh  # Run comprehensive test suite with Docker container

Publishing

./publish.sh  # Publish sos tool to getpkg.xyz and getbin.xyz

Direct Usage

./sos upload <server> <file> <label:tag> [label:tag ...]
# Example: ./sos upload getbin.xyz ./file.txt file:latest version:1.0

Architecture

Core Components

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

2.5 KiB Raw Blame History