Skip to content
Sign in

storage

v0.1.27

Object storage across AWS S3, GCS, Cloudflare R2, and a native local filesystem backend. Streamed uploads, signed URLs, and observable object change events.

license: Apache-2.0Used in 1 kitblobgcsobject-storager2s3

Install

bash
iii trigger compose::add worker=storage@0.1.27

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions17

storage::deleteBucket

Function

Remove a bucket from the storage configuration. Objects, local data and secrets are never deleted; the worker may run with zero buckets.

Request
  • namestringrequired
Response
  • deletedbooleanrequired

storage::deleteObject

Function

Delete an object. No-op when the object does not exist.

Request
  • bucketstringrequired
  • keystringrequired
  • version_idstring
Response
  • deletedbooleanrequired

storage::getBucket

Function

Read one stored bucket entry for editing: references and templates intact, literal secret keys, session tokens, credentials JSON and API tokens as "__redacted__".

Request
  • namestringrequired

    Bucket name (the key under `buckets`).

Response
  • bucketunknownrequired

    The entry as stored: references and `${VAR}` templates intact, literal secret keys, session tokens, credentials JSON and API tokens as `"__redacted__"`.

  • namestringrequired

storage::getObject

Function

Download a small object, or a byte range of any object (offset, length), inline as base64. At most 10 MiB per call; use a presignUrl GET for files when the client can reach the provider, ranged reads when it cannot.

Request
  • bucketstringrequired
  • keystringrequired
  • lengthinteger· uint64min 0

    How many bytes to return at most (clamped to the end of the object). Default: to the end.

  • offsetinteger· uint64min 0

    First byte to return. Default 0. Past the end of the object → `INVALID_RANGE`; equal to its size → an empty body.

  • version_idstring
Response
  • body_base64stringrequired
  • content_typestringrequired
  • etagstringrequired
  • last_modifiedstring· date-timerequired
  • lengthinteger· uint64requiredmin 0

    How many bytes were returned.

  • offsetinteger· uint64requiredmin 0

    Where the returned bytes start in the object.

  • sizeinteger· uint64requiredmin 0

    The object's total size.

storage::headObject

Function

Fetch object metadata (size, ETag, content-type, last-modified) without downloading the body.

Request
  • bucketstringrequired
  • keystringrequired
  • version_idstring
Response
  • content_typestringrequired
  • etagstringrequired
  • last_modifiedstring· date-timerequired
  • sizeinteger· uint64requiredmin 0

storage::listBuckets

Function

List the configured buckets with their provider, provider-side bucket, region or endpoint, display, whether they use secrets and allow direct downloads, and the error of any bucket that could not be built.

Request
Empty object
Response
  • bucketsobject[]required
    • account_idstring

      r2 only: the literal account id, or the reference as stored.

    • bucketstringrequired

      The provider-side bucket.

    • direct_downloadsbooleanrequired

      A presigned GET (`storage::presignUrl`) gives a URL a client can fetch: false for gcs without signing credentials or with an `endpoint_url` override (read through ranged `storage::getObject`).

    • displayany of

      How clients draw the bucket (well-formed parts only).

      any of (2)
      Variant 1
      • colorstring

        `#RRGGBB`.

      • iconstring

        A Lucide icon name (`hard-drive`, `cloud`, …): `[a-z0-9-]`, at most 64.

      Variant 2
      valuenull
    • endpoint_urlstring

      The custom endpoint (S3-compatible stores, R2/GCS overrides), userinfo stripped.

    • errorstring

      Why the bucket has no backend (its calls answer `BUCKET_UNAVAILABLE`).

    • error_stageany of

      `config` | `secrets` | `auth`.

      any of (2)
      Variant 1
      one of (6)
      Variant 1
      valuestringenum config
      Variant 2
      valuestringenum secrets
      Variant 3
      valuestringenum endpoint
      Variant 4
      valuestringenum auth
      Variant 5
      valuestringenum bucket
      Variant 6
      valuestringenum list
      Variant 2
      valuenull
    • namestringrequired

      The worker-facing name (the key under `buckets`).

    • notifications_errorstring

      Why the bucket's notifications source is not running (the bucket works; its object triggers do not fire).

    • providerstringrequired

      `s3` | `r2` | `gcs` | `local` (`unknown` for an entry that names none).

    • regionstring

      s3 only.

    • uses_secretsbooleanrequired

      Some credential field is a `secret://` / `env://` reference.

  • config_idstringrequired

    The configuration entry the buckets live in.

  • countinteger· uintrequiredmin 0

storage::listObjects

Function

List objects and common prefixes in a bucket with provider-native pagination.

Request
  • bucketstringrequired
  • cursorstring
  • delimiterstring

    Directory separator. Use `/` for the bucket/folder explorer; omit it for a flat recursive listing.

  • limitinteger· uint32min 0
  • prefixstring
Response
  • common_prefixesstring[]required
  • next_cursorstring
  • objectsobject[]required
    • content_typestring
    • etagstringrequired
    • keystringrequired
    • last_modifiedstring· date-timerequired
    • sizeinteger· uint64requiredmin 0

storage::object-created

Function

Fires when an object is written to a configured bucket whose notifications source is wired up.

Request
valueunknown
Response
valueunknown

storage::object-deleted

Function

Fires when an object is removed from a configured bucket whose notifications source is wired up.

Request
valueunknown
Response
valueunknown

storage::on-config-change

Function

Internal: apply the authoritative storage configuration without restarting the worker.

Request
  • idstring
Response
  • okbooleanrequired

storage::on-secret-change

Function

Internal: re-read a rotated or revoked secret:// / env:// value and rebuild the buckets that reference it.

Request
  • actionstring

    `created` | `rotated` | `deleted` | `access_changed` (advisory).

  • namestring
  • refstring
Response
  • okbooleanrequired

storage::presignPost

Function

Issue a short-lived multipart/form-data POST for direct browser upload. The file never buffers in the engine or worker RPC path.

Request
  • bucketstringrequired
  • content_typestringrequired
  • expires_in_secondsinteger· uint64min 0
  • keystringrequired
  • max_size_bytesinteger· uint64min 0

    Optional upload cap enforced while the HTTP body is streamed.

Response
  • expires_atstring· date-timerequired
  • fieldsobjectrequired
  • urlstringrequired

storage::presignUrl

Function

Issue a short-lived URL the browser can hit directly to PUT or GET an object.

Request
  • bucketstringrequired
  • content_typestring
  • expires_in_secondsinteger· uint64min 0
  • keystringrequired
  • methodstringrequiredenum GET, PUT
  • response_content_dispositionstring

    GET-only: override `Content-Disposition` header on the served response. Rejected with `INVALID_PRESIGN_PARAMS` if set on a PUT presign.

  • response_content_typestring

    GET-only: override `Content-Type` header on the served response. Rejected with `INVALID_PRESIGN_PARAMS` if set on a PUT presign.

Response
  • expires_atstring· date-timerequired
  • urlstringrequired

storage::putObject

Function

Upload a small object inline as base64 (10 MiB hard limit). This buffers and inflates the payload; use presignPost or a presignUrl PUT for files and large objects.

Request
  • body_base64stringrequired

    Base64-encoded small body (10 MiB decoded hard limit). The legacy field name `body` is accepted as an alias for backward compatibility.

  • bucketstringrequired
  • cache_controlstring
  • content_typestring
  • keystringrequired
  • metadataobject
Response
  • etagstringrequired
  • sizeinteger· uint64requiredmin 0
  • version_idstring

storage::saveBucket

Function

Create, update (previous_name = name) or rename (previous_name = old) a bucket in the storage configuration; "__redacted__" keeps a stored value, credentials go as secret:// references or in `credentials`, create_bucket creates an s3/r2 bucket that does not exist. Returns after the runtime reloaded, with the bucket's error if any.

Request
  • bucketunknownrequired

    The entry (`provider` and its fields). `"__redacted__"` keeps the stored value of that field. Sensitive fields hold references here; literals go in `credentials`.

  • create_bucketboolean

    s3 / r2: create the provider-side bucket when it does not exist. Local buckets always ensure their storage.

  • credentialsunknown

    Sensitive values sent apart from `bucket` and merged over it: `access_key_id`, `secret_access_key`, `session_token`, `credentials_json`, `notifications_api_token`. Prefer `secret://` references in `bucket`, which are safe anywhere.

  • namestringrequired

    The name to save under: `[a-z0-9][a-z0-9_-]{0,62}`.

  • previous_namestring

    The bucket's current name when editing an existing one (equal to `name` to update in place, different to rename). Absent creates a new bucket, refused when `name` is taken.

Response
  • created_bucketboolean

    With `create_bucket`: whether this save created the provider-side bucket (false: it already existed).

  • errorstring

    Why the saved bucket has no backend after the reload, or why its creation failed (it is saved regardless). Absent when it is usable.

  • error_stageany of
    any of (2)
    Variant 1
    one of (6)
    Variant 1
    valuestringenum config
    Variant 2
    valuestringenum secrets
    Variant 3
    valuestringenum endpoint
    Variant 4
    valuestringenum auth
    Variant 5
    valuestringenum bucket
    Variant 6
    valuestringenum list
    Variant 2
    valuenull
  • namestringrequired
  • savedbooleanrequired

storage::testBucket

Function

Test a candidate bucket entry (or a stored one by name) with a throwaway client and freshly resolved secrets: lists one object at the root. Live buckets are untouched; reports ok/provider/latency, the failing stage (config, secrets, endpoint, auth, bucket, list) and bucket_missing; failures are data, not errors.

Request
  • bucketunknown

    The candidate entry (`provider` and its fields), as `saveBucket` takes it. Absent: test the stored bucket `name` as it is.

  • credentialsunknown

    Sensitive values apart from `bucket` (`access_key_id`, `secret_access_key`, `session_token`, `credentials_json`, `notifications_api_token`), merged over it.

  • namestring

    The stored bucket `"__redacted__"` values come from (and the default provider-side bucket when the entry has no `bucket`).

  • timeout_msinteger· uint64min 0

    Overall budget. Default 10000, capped at 30000.

Response
  • bucket_missingboolean

    The provider said the bucket does not exist (`saveBucket` with `create_bucket: true` creates it, for s3 and r2).

  • direct_downloadsboolean

    Whether presigned GETs from this bucket are fetchable by clients. Present once the backend was built.

  • latency_msinteger· uint64requiredmin 0

    Wall time of the whole attempt.

  • messagestring

    Why the probe failed (credentials scrubbed). Absent on success.

  • okbooleanrequired

    Whether the bucket was reached and listed.

  • providerstringrequired

    `s3` | `r2` | `gcs` | `local` | `unknown`.

  • stageany of

    `config` | `secrets` | `endpoint` | `auth` | `bucket` | `list`. Absent on success.

    any of (2)
    Variant 1
    one of (6)
    Variant 1
    valuestringenum config
    Variant 2
    valuestringenum secrets
    Variant 3
    valuestringenum endpoint
    Variant 4
    valuestringenum auth
    Variant 5
    valuestringenum bucket
    Variant 6
    valuestringenum list
    Variant 2
    valuenull

storage::ui-content

Function

Serve the storage worker's injected console UI assets (content function for its console:script / console:style / console:module triggers).

Request
  • pathstringrequired

    The asset path from the trigger config (e.g. `state/page.js`).

Response
  • contentstringrequired

    The asset source, verbatim.

  • content_typestringrequired

    MIME type the console should serve the asset with.

Search the registry

Find workers, kits and executables, or jump to a page.