96 lines
3.5 KiB
Markdown
96 lines
3.5 KiB
Markdown
# 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).
|