# Simple Object Storage

## Introduction

Simple Object Storage is a very simple C++ webserver 
which provides a store of tagged binary objects (the objects can be large),
which are available over http.

Read access is public.
Write access is controlled by tokens.

Public read actions:

### Retrieve Object
- Objects are accessed via a label and tag, or via their hash. For example:
   - `wget http://localhost:8123/object/squashkiwi:latest`
   - `wget http://localhost:8123/object/4528400792837739857`

### Check Object Existence
- Check if an object exists by label:tag or hash:
   - `curl http://localhost:8123/exists/squashkiwi:latest`
   - `curl http://localhost:8123/exists/4528400792837739857`

### Retrieve Hash
- Get the hash for a given label and tag:
   - `curl http://localhost:8123/hash/squashkiwi:latest`
   - Response format: `{"result":"success","hash":"4528400792837739857"}`

### List Store Contents
- Get a full list of {label:tag,hash} entries:
   - `curl http://localhost:8123/dir`
   - Response format: `{"result":"success","entries":[{"label_tag":"example:latest","hash":"4528400792837739857"}]}`

### Retrieve Metadata
- Get all metadata for a tag:
   - `curl http://localhost:8123/meta/squashkiwi:latest`
   - `curl http://localhost:8123/meta/4528400792837739857`
   - Response format: `{"result":"success","metadata":{"description":"Example file","tags":["test","example"],"custom_field":"custom value"}}`

### Service Status Check
- Quick status check:
   - `curl http://localhost:8123/status`
   - Response format: `{"result":"success","status":"ok"}`

## Write actions (require authentication):

### Upload Object
- Upload a file with metadata (via HTTP PUT):
```bash
curl -X PUT \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/your/file.txt" \
  -F 'metadata={"labeltag":"example:latest","description":"Example file","tags":["test","example"],"custom_field":"custom value"}' \
  "http://localhost:8123/upload"
```
   - The object file is uploaded, hashed, added to the registry (if that hash doesn't already exist), and {label:tag,hash} entries are added to the directory index.
   - Matching tags on older versions are removed.
   - Response format: `{"result":"success","hash":"4528400792837739857"}`

### Delete Object
- Delete an object and all its tags:
   - `curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8123/deleteobject?hash=4528400792837739857`
   - Response format: `{"result":"success"}`

## Configuration
- The server is configured via `~/.config/simple_object_storage/config.json` which allows setting:
   - `write_tokens`: List of valid write access tokens
   - `object_store_path`: Location for the object store (path on disk)
   - `host`: Server host (default: "0.0.0.0")
   - `port`: Server port (default: 8123)

Example config.json:
```json
{
    "write_tokens": ["your-secret-token-1", "your-secret-token-2"],
    "object_store_path": "/data/storage",
    "host": "0.0.0.0",
    "port": 8123
}
```

## Signal Handling

The server handles the following signals:

- `SIGTERM`/`SIGINT`: Gracefully shuts down the server when received (e.g. from Ctrl+C or system shutdown)
- `SIGHUP`: Reloads the server configuration without restarting the service

The server ensures proper cleanup of resources during shutdown, including:
- Closing all database connections
- Stopping the HTTP server
- Cleaning up any open file handles
- Properly terminating worker threads

Dockcross is used to cross-build for both 64-bit x86 and arm64 (combining both into one docker container image).