update
This commit is contained in:
+24
-153
@@ -277,179 +277,50 @@ end
|
|||||||
|
|
||||||
Generate a pre-signed URL for an object in the Garage S3 bucket.
|
Generate a pre-signed URL for an object in the Garage S3 bucket.
|
||||||
|
|
||||||
A pre-signed URL is a signed URL that grants temporary access to an S3 object without
|
A pre-signed URL grants temporary access without AWS credentials. Signature is computed
|
||||||
requiring AWS credentials. The URL expires after the specified number of seconds.
|
using AWS Signature Version 4 (HMAC-SHA256).
|
||||||
The signature is computed using AWS Signature Version 4 (HMAC-SHA256).
|
|
||||||
|
|
||||||
# Why use pre-signed URLs?
|
|
||||||
|
|
||||||
Pre-signed URLs let you grant temporary, scoped access to objects without sharing
|
|
||||||
your API credentials. Typical use cases:
|
|
||||||
|
|
||||||
- **Direct browser downloads**: Return the URL to a frontend so users can download
|
|
||||||
files without going through your server.
|
|
||||||
- **Direct browser uploads**: Generate a PUT pre-signed URL, pass it to the frontend,
|
|
||||||
and let the user upload a file directly to S3 with a `curl` or `fetch` call.
|
|
||||||
- **Temporary sharing**: Send an expiring link to someone who should not have
|
|
||||||
permanent access to the object.
|
|
||||||
- **Server-side download without round-trip**: Instead of downloading the file to
|
|
||||||
your server and re-uploading it elsewhere, pass the pre-signed URL to another
|
|
||||||
service.
|
|
||||||
|
|
||||||
# How it works
|
|
||||||
|
|
||||||
The function computes an HMAC-SHA256 signature over a canonical request that
|
|
||||||
includes the HTTP verb, the object path, the query parameters, and the host header.
|
|
||||||
The signature is appended to the URL as `X-Amz-Signature`. Garage (and any S3
|
|
||||||
compatible service) verifies the signature before serving the object.
|
|
||||||
|
|
||||||
# URL format
|
|
||||||
https://s3-api.your-garage-instance.com/bucket/key?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Date=...&X-Amz-Expires=...&X-Amz-SignedHeaders=...&X-Amz-Signature=...
|
|
||||||
|
|
||||||
# Arguments
|
# Arguments
|
||||||
- `storage::GarageStorage`
|
- `storage::GarageStorage`: Storage client from `GarageStorage(endpoint, key, secret, bucket)`.
|
||||||
A storage client created with `GarageStorage(endpoint, key, secret, bucket)`.
|
- `key::String`: Object key. Supports nested paths like `"folder/subfolder/file.txt"`.
|
||||||
- `key::String`
|
- `seconds::Int`: URL validity in seconds. Default: 3600.
|
||||||
The object key (file name) in the bucket. Supports nested paths like
|
|
||||||
`"folder/subfolder/file.txt"`.
|
|
||||||
- `seconds::Int`
|
|
||||||
How long the URL remains valid, in seconds. Default: 3600 (1 hour).
|
|
||||||
|
|
||||||
# Keyword Arguments
|
# Keyword Arguments
|
||||||
- `verb::String = "GET"`
|
- `verb::String = "GET"`: HTTP method (`"GET"` downloads, `"PUT"` uploads).
|
||||||
The HTTP method the URL permits. Use `"GET"` for downloads (the default) or
|
- `content_type::String = "application/octet-stream"`: Required `Content-Type` header.
|
||||||
`"PUT"` for uploads. Other values like `"DELETE"` are also supported.
|
For PUT, set to the file's MIME type (`"image/png"`, `"application/json"`, etc.).
|
||||||
- `content_type::String = "application/octet-stream"`
|
- `signature_version::String = "v4"`: Always use `"v4"` (v2 is deprecated).
|
||||||
The `Content-Type` header value that must match when the URL is used.
|
|
||||||
For PUT uploads, set this to the actual MIME type of the file you plan to
|
|
||||||
upload (e.g. `"text/plain"`, `"application/json"`, `"image/png"`).
|
|
||||||
- `signature_version::String = "v4"`
|
|
||||||
Signature algorithm version. Always use `"v4"` — version 2 is deprecated
|
|
||||||
and not supported by many S3-compatible services.
|
|
||||||
|
|
||||||
# Return
|
# Return
|
||||||
- `String`: The full pre-signed URL, ready to use with `curl`, a browser, or any
|
`String`: The pre-signed URL.
|
||||||
HTTP client.
|
|
||||||
|
|
||||||
# Examples
|
# Examples
|
||||||
|
|
||||||
### Download link (GET — default)
|
|
||||||
```julia
|
```julia
|
||||||
storage = GarageStorage("https://s3-api.example.com", "mykey", "mysecret", "mybucket")
|
storage = GarageStorage("https://s3-api.yiem.cc", "key", "secret", "testbucket")
|
||||||
|
|
||||||
# 1-hour download link
|
# Download — GET (default)
|
||||||
url = s3_sign_url(storage, "documents/report.pdf", 3600)
|
url = s3_sign_url(storage, "docs/report.pdf", 3600)
|
||||||
println("Download link: ", url)
|
|
||||||
|
|
||||||
# Use in a browser — opens the file directly
|
# Upload — PUT
|
||||||
# > open(url)
|
url = s3_sign_url(storage, "avatars/user123.png", 300;
|
||||||
|
|
||||||
# Use with curl from the terminal
|
|
||||||
# > curl -L "url" -o report.pdf
|
|
||||||
```
|
|
||||||
|
|
||||||
### Upload link (PUT)
|
|
||||||
```julia
|
|
||||||
# Generate a PUT URL valid for 10 minutes, accepting text/plain uploads
|
|
||||||
url = s3_sign_url(storage, "uploads/user-photo.png", 600;
|
|
||||||
verb="PUT", content_type="image/png")
|
verb="PUT", content_type="image/png")
|
||||||
|
|
||||||
# The user (or your frontend) uploads a file like this:
|
# Multiple uploads (chat app)
|
||||||
# > curl -X PUT -H "Content-Type: image/png" --data @photo.png "url"
|
urls = [s3_sign_url(storage, "chat/GeneralUtils.uuid4snakecase()", 300;
|
||||||
```
|
verb="PUT", content_type="image/png")
|
||||||
|
for f in filenames]
|
||||||
|
|
||||||
### Embedding in HTML
|
# Signature differs by verb and content_type
|
||||||
```julia
|
|
||||||
url = s3_sign_url(storage, "shared/shared-file.zip", 86400) # 24 hours
|
|
||||||
# Use the URL in HTML: <a href="url">Download shared-file.zip (valid 24 hours)</a>
|
|
||||||
```
|
|
||||||
|
|
||||||
### Verification — signature differs by verb and content-type
|
|
||||||
```julia
|
|
||||||
url_get = s3_sign_url(storage, "file.txt", 3600; verb="GET")
|
url_get = s3_sign_url(storage, "file.txt", 3600; verb="GET")
|
||||||
url_put = s3_sign_url(storage, "file.txt", 3600; verb="PUT", content_type="text/plain")
|
url_put = s3_sign_url(storage, "file.txt", 3600; verb="PUT", content_type="text/plain")
|
||||||
# url_get and url_put have different X-Amz-Signature values because the
|
|
||||||
# canonical request (and thus the HMAC) is different.
|
|
||||||
```
|
```
|
||||||
|
|
||||||
# Notes
|
# Notes
|
||||||
- The pre-signed URL is **not encrypted** — anyone with the URL can access the
|
- URLs are valid until `seconds` expires; they can be used **multiple times** (not one-time).
|
||||||
object until it expires. Treat the URL like a temporary password.
|
- Server clocks must be within ~5 minutes of the Garage server (UTC time in signature).
|
||||||
- The signature includes the current UTC time (`X-Amz-Date`), so both the
|
- PUT uploads require the client's `Content-Type` to match `content_type`.
|
||||||
generating machine and the Garage server should have reasonably synchronized
|
- For browser CORS uploads, configure Garage bucket CORS rules for `Origin` and `Method`.
|
||||||
clocks (± a few minutes tolerance).
|
|
||||||
- Only `v4` signature is implemented. Garage supports v4 natively.
|
|
||||||
- For cross-origin (CORS) uploads from a browser, you also need the Garage bucket
|
|
||||||
to have CORS rules that allow the `Origin` and `Method` headers.
|
|
||||||
|
|
||||||
# s3_sign_url vs get_file — when to use which
|
|
||||||
|
|
||||||
| Scenario | Use |
|
|
||||||
|---|---|
|
|
||||||
| Your server needs to read/write an object | `get_file(storage, key)`, `put_file(storage, key, data)` |
|
|
||||||
| A browser or external client needs to download an object | `s3_sign_url(storage, key, 3600; verb="GET")` |
|
|
||||||
| A browser or external client needs to upload a file | `s3_sign_url(storage, key, 600; verb="PUT", content_type="image/png")` |
|
|
||||||
| You need to pass a download link to a third party | `s3_sign_url(storage, key, 86400)` — no credentials shared |
|
|
||||||
|
|
||||||
`get_file` / `put_file` use your API credentials on every call.
|
|
||||||
`s3_sign_url` embeds a time-limited signature in the URL — no credentials needed.
|
|
||||||
|
|
||||||
# Complete upload workflow example
|
|
||||||
|
|
||||||
```julia
|
|
||||||
# 1. Generate a PUT pre-signed URL on your server
|
|
||||||
url = s3_sign_url(storage, "avatars/user-12345.png", 300;
|
|
||||||
verb="PUT", content_type="image/png")
|
|
||||||
|
|
||||||
# 2. Send `url` to your frontend (JSON response, React state, etc.)
|
|
||||||
|
|
||||||
# 3. Frontend uploads directly to Garage:
|
|
||||||
# fetch(url, { method: "PUT", headers: {"Content-Type": "image/png"}, body: fileBlob })
|
|
||||||
# or:
|
|
||||||
# curl -X PUT -H "Content-Type: image/png" --data @photo.png url
|
|
||||||
|
|
||||||
# 4. Optional — verify the upload succeeded
|
|
||||||
# data = get_file(storage, "avatars/user-12345.png")
|
|
||||||
```
|
|
||||||
|
|
||||||
# Complete download workflow example
|
|
||||||
|
|
||||||
```julia
|
|
||||||
# 1. Generate a GET pre-signed URL
|
|
||||||
url = s3_sign_url(storage, "reports/quarterly.pdf", 7200) # 2 hours
|
|
||||||
|
|
||||||
# 2a. Redirect user to the URL (S3 returns 302)
|
|
||||||
# return redirect(url)
|
|
||||||
|
|
||||||
# 2b. Embed in HTML link
|
|
||||||
# <a href="url" download>Download quarterly.pdf</a>
|
|
||||||
|
|
||||||
# 2c. Use with curl
|
|
||||||
# curl -L url -o quarterly.pdf
|
|
||||||
```
|
|
||||||
|
|
||||||
# Query parameters in the generated URL
|
|
||||||
|
|
||||||
| Parameter | Purpose |
|
|
||||||
|---|---|
|
|
||||||
| `X-Amz-Algorithm` | Must be `AWS4-HMAC-SHA256` |
|
|
||||||
| `X-Amz-Credential` | Your access key ID + date + region + service + request token |
|
|
||||||
| `X-Amz-Date` | Timestamp when the URL was generated (UTC, ISO 8601 format) |
|
|
||||||
| `X-Amz-Expires` | Number of seconds until expiration |
|
|
||||||
| `X-Amz-Security-Token` | Optional session token (empty if not provided) |
|
|
||||||
| `X-Amz-SignedHeaders` | Semicolon-separated list of signed headers (currently only `host`) |
|
|
||||||
| `X-Amz-Signature` | The HMAC-SHA256 signature — the core authorization token |
|
|
||||||
|
|
||||||
# Common pitfalls
|
|
||||||
|
|
||||||
- **Clock skew**: If the server and Garage are more than ~5 minutes out of sync,
|
|
||||||
the signature will be rejected.
|
|
||||||
- **Content-Type mismatch**: When using a PUT URL, the `Content-Type` sent by the
|
|
||||||
client must match the `content_type` you passed to `s3_sign_url`.
|
|
||||||
- **URL encoding**: The key is URL-encoded in the path. Keys with spaces or special
|
|
||||||
characters work correctly, but do not double-encode the returned URL.
|
|
||||||
- **Single use**: Pre-signed URLs can be used multiple times until expiration;
|
|
||||||
they are not one-time tokens.
|
|
||||||
"""
|
"""
|
||||||
function s3_sign_url(
|
function s3_sign_url(
|
||||||
storage::GarageStorage,
|
storage::GarageStorage,
|
||||||
|
|||||||
Reference in New Issue
Block a user