s3ec 0.2.3

File sync daemon and CLI for an S3-compatible event server
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

<div align="center">

# s3ec — S3 Event Client

[![Crates.io](https://img.shields.io/crates/v/s3ec?style=flat-square)](https://crates.io/crates/s3ec)
[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
[![Rust](https://img.shields.io/badge/Rust-2024-dea584?style=flat-square&logo=rust&logoColor=white)](https://www.rust-lang.org)
[![CI](https://img.shields.io/badge/CI-Passing-green?style=flat-square)](#)

File sync daemon and CLI for an S3-compatible event server. Watch a directory and automatically upload file changes, and receive remote file events via SSE.

</div>

## Features

- **Daemon mode** — watch a directory with inotify, debounce changes, and upload with exponential backoff
- **Initial sync** — upload all existing files on startup (`s3ec sync -w <dir>`)
- **Real-time remote events** — SSE client that downloads/removes files when remote changes happen
- **Bidirectional sync** — local changes push upstream, remote changes pull downstream
- **Token auth** — login with API key, automatic token refresh before expiry
- **Metadata preservation** — file permissions and modification times are stored and restored

## Installation

```bash
cargo install s3ec
```

Or build from source:

```bash
git clone https://github.com/anomalyco/s3ec
cd s3ec
cargo build --release
```

## Usage

### Login

```bash
s3ec login --server https://your-server.com --api-key <key>
```

Config is saved to `~/.config/s3ec/config.toml`.

### Commands

| Command | Description |
|---|---|
| `upload <file>` | Upload a file |
| `download <id>` | Download a file by ID |
| `ls` | List files (supports `--path`, `--search`, `--limit`, `--offset`) |
| `info <id>` | Show file metadata |
| `rm <id>` | Delete a file |
| `sync -w <dir>` | One-shot upload of all files in a directory |
| `daemon -w <dir>` | Start the file watcher daemon |

### Daemon

The daemon watches a directory and syncs bidirectionally:

```bash
s3ec daemon -w /path/to/watch --debounce 500
```

- Uploads local file changes to the server
- Receives remote events via SSE and downloads/removes files accordingly
- Retries empty files (still being written) with exponential backoff up to 10 times
- Runs an initial sync of all existing files on startup

### Systemd Service

A systemd unit file is provided in `contrib/s3ec.service`:

```bash
sudo cp contrib/s3ec.service /etc/systemd/system/
# Edit ExecStart to set your watch directory
sudo systemctl daemon-reload
sudo systemctl enable --now s3ec
```

## Configuration

The config file at `~/.config/s3ec/config.toml` is managed automatically by the `login` command and contains:

- `server_url` — the API server base URL
- `api_key` — the API key for authentication
- `token` — the JWT token (auto-refreshed)
- `expires_at` — token expiry timestamp

## Architecture

```
┌──────────────┐   SSE events   ┌──────────────┐
│   Server     │◄──────────────►│   s3ec CLI   │
│  (REST API)  │   HTTP upload  │  (daemon)    │
└──────────────┘    download    └──────┬───────┘
                                       │ inotify
                                       ▼
                                  ┌──────────┐
                                  │ Watched  │
                                  │ Directory│
                                  └──────────┘
```