](https://www.docker.com/)
+Example: global `auth.accessKeysRefs: [admin, readonly]` with
+`HERALD_AUTH_ADMIN_ACCESS_KEY_ID`, `HERALD_AUTH_ADMIN_SECRET_KEY` and
+`HERALD_AUTH_READONLY_ACCESS_KEY_ID`, `HERALD_AUTH_READONLY_SECRET_KEY` set in
+the environment allows requests signed with either key. You can override at
+backend or bucket level (e.g. a backend that only accepts `admin`, or a bucket
+that only accepts `readonly`).
-```sh
-❯ docker run -it expnt/herald:latest
-```
+#### When auth is not configured
-### Testing
+If no `auth` is defined at any level for a request, Herald does not perform
+SigV4 verification and the request is not gated by these credentials.
-To run full tests,
+### CORS Configuration
-```sh
-❯ deno test -A tests
-```
+Herald supports fine-grained CORS control at three levels with the following
+precedence: **Bucket > Backend > Global**.
----
-
-## Project Roadmap
-
-- [x] **`Task 1`**: Mirroring
-- [ ] **`Task 2`**: Event Notification.
-- [ ] **`Task 3`**: Advanced Cache Policy
-
----
-
-## Contributing
-
-- **💬 [Join the Discussions](https://github.com/expnt/herald/discussions)**: Share your insights, provide feedback, or ask questions.
-- **🐛 [Report Issues](https://github.com/expnt/herald/issues)**: Submit bugs found or log feature requests for the `herald` project.
-- **💡 [Submit Pull Requests](https://github.com/expnt/herald/blob/main/CONTRIBUTING.md)**: Review open PRs, and submit your own PRs.
-
-
-
-
-
+- **Global**: Defined at the root of the config file under `cors`.
+- **Backend**: Defined within a backend block under `cors`. Overrides global
+ settings.
+- **Bucket**: Defined within a bucket definition under `cors`. Overrides both
+ backend and global settings.
+
+#### Default Behavior
----
+If no CORS configuration is provided at any level, **CORS is disabled** and
+Herald will not add any CORS-related headers to responses. Preflight `OPTIONS`
+requests will be passed through to the backend.
-## Acknowledgments
+If you enable CORS by providing configuration at any level, the following
+defaults are applied for any omitted fields:
-- List any resources, contributors, inspiration, etc. here.
+| Field | Default Value | Description |
+| ---------------- | --------------------------------------- | ------------------------------------------------------ |
+| `maxAge` | `3600` | Max age in seconds for preflight results |
+| `allowedMethods` | `GET, PUT, POST, DELETE, HEAD, OPTIONS` | Allowed HTTP methods |
+| `allowedHeaders` | (Mirrors request) | Defaults to mirroring `Access-Control-Request-Headers` |
+| `credentials` | `false` | Whether to allow credentials |
+| `allowedOrigins` | (None) | Headers only added if `Origin` matches an entry |
+
+Example with overrides:
+
+```yaml
+cors: # Global defaults
+ allowedOrigins: ["*"]
+ credentials: false
+
+backends:
+ prod:
+ protocol: s3
+ cors: # Backend-level override
+ allowedOrigins: ["https://app.example.com"]
+ credentials: true
+ buckets:
+ assets:
+ cors: # Bucket-level override
+ allowedOrigins: ["https://cdn.example.com"]
+```
----
+### Routing Logic
+
+When a request comes in for a bucket (e.g., `GET /my-bucket/file.txt`), Herald
+resolves the backend using the following priority:
+
+1. **Direct match**: Looks for `my-bucket` in all backends' `buckets` maps.
+2. **Glob match (map)**: Looks for glob patterns (like `test-*`) in all
+ backends' `buckets` maps.
+3. **Glob match (string)**: If a backend has `buckets: "string-*"`, it checks if
+ the bucket name matches that pattern.
+
+When several backends could match (e.g. two globs), the **first backend in
+config order** wins.
+
+### Environment variable configuration
+
+Configuration can be supplied or overridden via environment variables; env is
+merged with YAML at load time (env wins for the same path). All config-related
+vars use the `HERALD_` prefix. Naming: `HERALD_Contributing Guidelines
- -1. **Fork the Repository**: Start by forking the project repository to your github account. -2. **Clone Locally**: Clone the forked repository to your local machine using a git client. - ```sh - git clone https://github.com/expnt/herald - ``` -3. **Create a New Branch**: Always work on a new branch, giving it a descriptive name. - ```sh - git checkout -b new-feature-x - ``` -4. **Make Your Changes**: Develop and test your changes locally. -5. **Commit Your Changes**: Commit with a clear message describing your updates. - ```sh - git commit -m 'Implemented new feature x.' - ``` -6. **Push to github**: Push the changes to your forked repository. - ```sh - git push origin new-feature-x - ``` -7. **Submit a Pull Request**: Create a PR against the original project repository. Clearly describe the changes and their motivations. -8. **Review**: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution! -InvalidArgument${code}${e.code}NoSuchBucketNoSuchBucketNoSuchBucketNot Found
The resource could not be found.
NoSuchBucketNoSuchBucketNoSuchKeyNoSuchKeyNoSuchKeyNot Found
The resource could not be found.
NoSuchUploadNoSuchUploadNoSuchUpload