primeiro commit

2026-09-16 10:27:58 -03:00
commit 36ad6ab38b
15 changed files with 1822 additions and 0 deletions
@@ -0,0 +1,82 @@
+# s3watch
+
+`s3watch` is a Go daemon that periodically keeps an S3 bucket or prefix and a
+local directory in sync. When a sync cycle downloads, uploads, updates, or
+deletes files, it runs an optional hook script.
+
+The daemon uses the AWS SDK directly. It does not shell out to `aws s3 sync` or
+any other external sync tool.
+
+## Usage
+
+```sh
+s3watch -bucket my-bucket -prefix app/config -dir /srv/config -hook /usr/local/bin/reload-app
+```
+
+You can also use a JSON config file:
+
+```sh
+s3watch -config examples/s3watch.json
+```
+
+Useful flags:
+
+- `-config examples/s3watch.json`: loads daemon settings from JSON.
+- `-interval 1m`: controls the sync period.
+- `-once`: runs a single sync cycle and exits.
+- `-prune`: propagates deletes for files that were previously synced and are unchanged on the remaining side.
+- `-region us-east-1`: overrides the AWS SDK's default region resolution.
+- `-key-id KEY`: uses explicit S3 access key credentials.
+- `-application-key SECRET`: uses explicit S3 secret or application key credentials.
+- `-endpoint-url https://s3.example.com`: uses a custom S3-compatible endpoint.
+- `-http-timeout 30s`: sets a timeout for AWS HTTP requests.
+
+Flags override values loaded from `-config`.
+
+Example config:
+
+```json
+{
+  "bucket": "my-application-config",
+  "prefix": "production/web",
+  "dir": "/srv/myapp/config",
+  "hook": "/usr/local/bin/reload-myapp",
+  "region": "us-east-1",
+  "key_id": "REPLACE_WITH_KEY_ID",
+  "application_key": "REPLACE_WITH_APPLICATION_KEY",
+  "endpoint_url": "https://s3.us-east-1.amazonaws.com",
+  "interval": "1m",
+  "http_timeout": "30s",
+  "once": false,
+  "prune": true
+}
+```
+
+The hook runs with the synced directory as its working directory and receives:
+
+- `S3WATCH_CHANGED`
+- `S3WATCH_DOWNLOADED`
+- `S3WATCH_UPLOADED`
+- `S3WATCH_UPDATED`
+- `S3WATCH_DELETED`
+- `S3WATCH_UNCHANGED`
+
+## Sync Semantics
+
+Local-only files are uploaded to S3. Remote-only objects are downloaded locally.
+When a file exists on both sides and differs, the side with the newer modified
+time wins.
+
+With `prune` disabled, missing files are treated as new files on the side where
+they still exist. With `prune` enabled, `s3watch` uses local state in
+`.s3watch/state.json` to propagate deletes only when the remaining copy is
+unchanged since the last successful sync.
+
+## Credentials
+
+AWS credentials are resolved by the standard AWS SDK chain, including
+environment variables, shared config files, web identity, and instance or task
+roles.
+
+If `key_id` and `application_key` are set, those static credentials override the
+standard AWS SDK credential chain. They must be provided together.