> For the complete documentation index, see [llms.txt](https://osl.mistium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://osl.mistium.com/standard-library/web/s3.md).

# s3

Use `s3` for S3-compatible object storage: buckets, objects, metadata, presigned URLs, and multipart-style helpers.

```osl
import "std:s3"
```

## API reference

### `s3` values

| Method                   | Returns     |
| ------------------------ | ----------- |
| `value.new(cfg: object)` | `*s3Client` |

### `s3Client` values

| Method                                                                    | Returns  | Notes                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value.cfgStr(k: string)`                                                 | `string` |                                                                                                                                                                                                                                                                                                                                                                                                            |
| `value.cfgDef(v: any, d: string)`                                         | `string` |                                                                                                                                                                                                                                                                                                                                                                                                            |
| `value.endpoint()`                                                        | `string` |                                                                                                                                                                                                                                                                                                                                                                                                            |
| `value.bucket()`                                                          | `string` |                                                                                                                                                                                                                                                                                                                                                                                                            |
| `value.access()`                                                          | `string` |                                                                                                                                                                                                                                                                                                                                                                                                            |
| `value.secret()`                                                          | `string` |                                                                                                                                                                                                                                                                                                                                                                                                            |
| `value.region()`                                                          | `string` |                                                                                                                                                                                                                                                                                                                                                                                                            |
| `value.host()`                                                            | `string` |                                                                                                                                                                                                                                                                                                                                                                                                            |
| `value.public(key: string)`                                               | `string` | Builds the encoded object URL from `public_url`, or the endpoint and bucket by default.                                                                                                                                                                                                                                                                                                                    |
| `value.toBytes(v: any)`                                                   | `byte[]` | Converts a value to bytes.                                                                                                                                                                                                                                                                                                                                                                                 |
| `value.sha256hex(b: byte[])`                                              | `string` | Returns the SHA-256 digest as hexadecimal text.                                                                                                                                                                                                                                                                                                                                                            |
| `value.amzDate(t: time.Time)`                                             | `string` |                                                                                                                                                                                                                                                                                                                                                                                                            |
| `value.shortDate(t: time.Time)`                                           | `string` |                                                                                                                                                                                                                                                                                                                                                                                                            |
| `value.sign(method: string, key: string, payload: string, query: string)` | `string` |                                                                                                                                                                                                                                                                                                                                                                                                            |
| `value.sortQuery(q: object)`                                              | `string` | Canonically sorts and encodes query parameters with the standard URL encoder.                                                                                                                                                                                                                                                                                                                              |
| `value.put(input: object)`                                                | `object` | Stores an object. Accepts `key`, `body`, `content_type`, and optional `content_encoding` such as `gzip`.                                                                                                                                                                                                                                                                                                   |
| `value.get(input: object)`                                                | `object` | Returns a value.                                                                                                                                                                                                                                                                                                                                                                                           |
| `value.remove(input: object)`                                             | `object` | Removes a value or resource.                                                                                                                                                                                                                                                                                                                                                                               |
| `value.presign(input: object)`                                            | `object` | Generates a presigned URL through the same canonical Signature V4 pipeline as signed requests. Input keys: `key` (required), `expires` (seconds, default 3600), `method` (HTTP method to sign for, default `GET`; pass `PUT` for direct uploads), `content_length` (optional; signs the Content-Length header so the upload must be exactly that many bytes). Returns `{ok, url}` or `{ok: false, error}`. |

## Examples

```osl
import "std:s3"

client = s3.new({
    "endpoint": "https://accountid.r2.cloudflarestorage.com",
    "bucket": "my-bucket",
    "access_key_id": "...",
    "secret_access_key": "...",
    "region": "auto"
})

download = client.presign({"key": "files/report.pdf", "expires": 3600})
upload = client.presign({"key": "files/report.pdf", "expires": 900, "method": "PUT", "content_length": 52428})
```

## Notes

* Prefer `import "std:s3"`; the older `import "osl/s3"` spelling remains supported.

## Behavior and limits

The client validates object keys, expiry times, payload lengths, session credentials, encoded AWS paths, and HTTP status codes. Requests share a connection pool and are safe across threads. `public_url` changes only the URL returned by `public()`.