# `Firkin.Plug`
[🔗](https://harton.dev/james/firkin)

Plug that serves an S3-compatible HTTP API.

Mount this plug in your router and provide a backend module:

    forward "/s3", Firkin.Plug, backend: MyApp.S3Backend, region: "us-east-1"

## Options

  * `:backend` (required) — module implementing `Firkin.Backend`
  * `:region` — AWS region string for SigV4 scope and GetBucketLocation
    (default: `"us-east-1"`)
  * `:hostname` — base hostname for virtual-hosted-style requests.
    When set, requests with `Host: bucket.hostname` extract the bucket
    from the hostname instead of the path. Path-style requests continue
    to work regardless.
    (default: `nil` — virtual-hosted-style disabled)
  * `:request_id_prefix` — prefix for X-Amz-Request-Id header
    (default: `"firkin"`)
  * `:max_buffered_put_bytes` — cap (in bytes) on PUT/UploadPart bodies
    when the backend has opted into the buffered `put_object/5` /
    `upload_part/6` path. Bodies exceeding the cap return
    `413 Request Entity Too Large` instead of silently allocating
    gigabytes of iodata. Ignored when the backend implements
    `put_object_stream/5` / `upload_part_stream/6`. Default:
    `16384 KiB`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*