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 Permalink Blame History