# S3 API

S3-compatible object storage helpers are available under `ptool.s3` and `p.s3`.

## ptool.s3.connect

> `v0.10.0` - Introduced.

`ptool.s3.connect(options)` opens an S3-compatible object storage connection
and returns a `Connection` object.

`options` fields:

- `bucket` (string, required): The bucket name.
- `region` (string, optional): The AWS region or provider region.
- `endpoint` (string, optional): A custom S3-compatible endpoint URL such as
  MinIO, R2, or another object storage service.
- `access_key_id` (string, optional): The access key ID.
- `secret_access_key` (string, optional): The secret access key.
- `session_token` (string, optional): The session token.
- `root` (string, optional): A root prefix applied to all object operations.
- `allow_anonymous` (boolean, optional): When `true`, allow unsigned requests
  if credentials are not configured. Defaults to `false`.

Environment fallback:

- Explicit `options` values win.
- Missing `region`, `endpoint`, `access_key_id`, `secret_access_key`, and
  `session_token` values fall back to:
  - `AWS_REGION`
  - `AWS_ENDPOINT`, `AWS_ENDPOINT_URL`, or `AWS_S3_ENDPOINT`
  - `AWS_ACCESS_KEY_ID`
  - `AWS_SECRET_ACCESS_KEY`
  - `AWS_SESSION_TOKEN`
- Environment fallback uses `ptool`'s runtime environment view, so values set
  through `p.os.setenv(...)` are also visible to `ptool.s3.connect(...)`.

Example:

```lua
local s3 = ptool.s3.connect({
  bucket = "artifacts",
  region = "auto",
  endpoint = "https://<account>.r2.cloudflarestorage.com",
  access_key_id = p.os.getenv("AWS_ACCESS_KEY_ID"),
  secret_access_key = p.os.getenv("AWS_SECRET_ACCESS_KEY"),
  root = "builds/",
})
```

## Connection

> `v0.10.0` - Introduced.

`Connection` represents an open object storage connection returned by
`ptool.s3.connect()`.

It is implemented as a Lua userdata.

Methods:

- `conn:read(path[, options])` -> `string`
- `conn:write(path, content[, options])` -> `table`
- `conn:delete(path)` -> `nil`
- `conn:exists(path)` -> `boolean`
- `conn:list([prefix])` -> `table`
- `conn:stat(path)` -> `table`
- `conn:put_bucket_acl(options)` -> `nil`
- `conn:put_object_acl(path, options)` -> `nil`

Path rules:

- Object paths must be non-empty strings unless otherwise noted.
- Leading `/` is ignored, so `/foo/bar.txt` and `foo/bar.txt` target the same
  object.
- Paths are relative to `root` when `root` is configured on the connection.

Entry table shape:

- `path` (string): The object path relative to the connection root.
- `size` (integer): The object size in bytes.
- `etag` (string | nil): The object ETag when available.
- `last_modified` (string | nil): The last-modified timestamp when available.
- `content_type` (string | nil): The object content type when available.
- `version` (string | nil): The object version when available.
- `metadata` (table | nil): User-defined object metadata when available.
- `is_file` (boolean): Whether the entry is a file.
- `is_dir` (boolean): Whether the entry is a directory.
- `mode` (string): One of `"file"`, `"dir"`, or `"unknown"`.

### read

> `v0.10.0` - Introduced.
> `v0.12.0` - Changed.

Canonical API name: `ptool.s3.Connection:read`.

`conn:read(path[, options])` reads an object as raw bytes and returns a Lua string.

- `path` (string, required): The object path.
- `options` (table, optional): Read options.
- Returns: `string`.

`options` fields:

- `range` (table, optional): Reads a byte range using half-open bounds
  `[start, end)`.
  - `start` (integer, optional): The first byte offset to include.
  - `end` (integer, optional): The first byte offset to exclude.

Behavior:

- Omitting `range` reads the full object.
- `{ start = N }` reads from byte `N` to the end.
- `{ end = N }` reads from the beginning up to, but not including, byte `N`.
- `{ start = A, end = B }` reads bytes `A` through `B - 1`.

Example:

```lua
local s3 = ptool.s3.connect({ bucket = "artifacts" })
local content = s3:read("releases/v1.0.0/notes.txt")
print(content)

local prefix = s3:read("releases/v1.0.0/notes.txt", {
  range = { start = 0, end = 5 },
})
print(prefix)
```

### write

> `v0.10.0` - Introduced.
> `v0.12.0` - Changed.

Canonical API name: `ptool.s3.Connection:write`.

`conn:write(path, content[, options])` writes a Lua string to an object as raw
bytes and returns an entry table.

- `path` (string, required): The object path.
- `content` (string, required): The bytes to upload.
- `options` (table, optional): Write options.
- Returns: `table`.

`options` fields:

- `content_type` (string, optional): Sets the object content type.
- `cache_control` (string, optional): Sets the object cache-control header.
- `content_disposition` (string, optional): Sets the object
  content-disposition header.
- `content_encoding` (string, optional): Sets the object content-encoding
  header.
- `metadata` (table, optional): Sets user-defined metadata as string key/value
  pairs.
- `if_not_exists` (boolean, optional): Write only when the object does not
  already exist. Defaults to `false`.
- `if_match` (string, optional): Write only when the current ETag matches.
- `if_none_match` (string, optional): Write only when the current ETag does not
  match.

Behavior:

- `content` is uploaded byte-for-byte.
- Embedded NUL bytes and non-UTF-8 bytes are preserved.
- The returned entry avoids an immediate follow-up `stat()` call for common
  metadata.
- Some S3-compatible services may not echo user-defined `metadata` or `etag` in
  the write response. When that happens, those fields remain `nil` until a later
  `stat()`.

Example:

```lua
local s3 = ptool.s3.connect({ bucket = "artifacts" })
local entry = s3:write("tmp/hello.txt", "hello\n", {
  content_type = "text/plain; charset=utf-8",
  metadata = { author = "ptool" },
})
print(entry.path, entry.etag, entry.version)

s3:write("tmp/blob.bin", "\x00\xffABC")
```

### delete

> `v0.10.0` - Introduced.

Canonical API name: `ptool.s3.Connection:delete`.

`conn:delete(path)` deletes an object.

- `path` (string, required): The object path.

### exists

> `v0.10.0` - Introduced.

Canonical API name: `ptool.s3.Connection:exists`.

`conn:exists(path)` checks whether an object exists.

- `path` (string, required): The object path.
- Returns: `boolean`.

### list

> `v0.10.0` - Introduced.

Canonical API name: `ptool.s3.Connection:list`.

`conn:list([prefix])` lists entries under a prefix and returns a dense Lua
array table.

- `prefix` (string, optional): The prefix to list. Defaults to the connection
  root.
- Returns: `table`.

Example:

```lua
local s3 = ptool.s3.connect({ bucket = "artifacts", root = "builds/" })
local entries = s3:list("2026/")

for _, entry in ipairs(entries) do
  print(entry.path, entry.mode, entry.size)
end
```

### stat

> `v0.10.0` - Introduced.

Canonical API name: `ptool.s3.Connection:stat`.

`conn:stat(path)` returns metadata for a single object.

- `path` (string, required): The object path.
- Returns: `table`.

Example:

```lua
local s3 = ptool.s3.connect({ bucket = "artifacts" })
local meta = s3:stat("releases/v1.0.0/app.tar.zst")
print(meta.size, meta.etag, meta.last_modified)
```

### put_bucket_acl

> `v0.12.0` - Introduced.

Canonical API name: `ptool.s3.Connection:put_bucket_acl`.

`conn:put_bucket_acl(options)` replaces the bucket ACL and returns `nil` on
success.

- `options` (table, required): Bucket ACL options.
- Returns: `nil`.

`options` fields:

- `acl` (string, optional): A canned bucket ACL. Accepted values are
  `"authenticated-read"`, `"private"`, `"public-read"`, and
  `"public-read-write"`.
- `expected_bucket_owner` (string, optional): Fails the request if the bucket
  is not owned by this AWS account ID.
- `grant_full_control` (string, optional): Value for the
  `x-amz-grant-full-control` header.
- `grant_read` (string, optional): Value for the `x-amz-grant-read` header.
- `grant_read_acp` (string, optional): Value for the
  `x-amz-grant-read-acp` header.
- `grant_write` (string, optional): Value for the `x-amz-grant-write` header.
- `grant_write_acp` (string, optional): Value for the
  `x-amz-grant-write-acp` header.

Behavior:

- Supply either `acl` or one or more `grant_*` fields. The two forms cannot be
  combined in one call.
- Every supplied string must be non-empty.
- Grant strings use the S3 grant-header syntax, such as an account ID, email
  address, or group URI accepted by the target provider.
- The operation targets the connection bucket. The connection's `root` prefix
  is not applied.
- Many S3-compatible providers disable ACLs or do not implement the ACL APIs.
  In that case, the provider error is returned as an `s3_error`.

Example:

```lua
local s3 = ptool.s3.connect({ bucket = "artifacts" })

s3:put_bucket_acl({ acl = "private" })

s3:put_bucket_acl({
  grant_read = 'uri="http://acs.amazonaws.com/groups/global/AllUsers"',
})
```

### put_object_acl

> `v0.12.0` - Introduced.

Canonical API name: `ptool.s3.Connection:put_object_acl`.

`conn:put_object_acl(path, options)` replaces an object's ACL and returns `nil`
on success.

- `path` (string, required): The object path.
- `options` (table, required): Object ACL options.
- Returns: `nil`.

`options` fields:

- `acl` (string, optional): A canned object ACL. Accepted values are
  `"authenticated-read"`, `"aws-exec-read"`, `"bucket-owner-full-control"`,
  `"bucket-owner-read"`, `"private"`, `"public-read"`, and
  `"public-read-write"`.
- `expected_bucket_owner` (string, optional): Fails the request if the bucket
  is not owned by this AWS account ID.
- `grant_full_control` (string, optional): Value for the
  `x-amz-grant-full-control` header.
- `grant_read` (string, optional): Value for the `x-amz-grant-read` header.
- `grant_read_acp` (string, optional): Value for the
  `x-amz-grant-read-acp` header.
- `grant_write` (string, optional): Value for the `x-amz-grant-write` header.
- `grant_write_acp` (string, optional): Value for the
  `x-amz-grant-write-acp` header.
- `version_id` (string, optional): Applies the ACL to this object version.
- `request_payer` (string, optional): Accepts only `"requester"` and sends the
  requester-pays acknowledgement.

Behavior:

- Supply either `acl` or one or more `grant_*` fields. The two forms cannot be
  combined in one call.
- Every supplied string must be non-empty.
- Grant strings use the S3 grant-header syntax accepted by the target provider.
- Leading `/` is ignored, and the connection's `root` prefix is applied to the
  object key in the same way as other object operations.
- Many S3-compatible providers disable ACLs or do not implement the ACL APIs.
  In that case, the provider error is returned as an `s3_error`.

Example:

```lua
local s3 = ptool.s3.connect({
  bucket = "artifacts",
  root = "public/",
})

s3:put_object_acl("index.html", { acl = "public-read" })

s3:put_object_acl("release.zip", {
  acl = "bucket-owner-full-control",
  version_id = "example-version-id",
  request_payer = "requester",
})
```
