Storage

Storage gives an application named file areas, called storage areas, on Turn Zero Cloud. The service writes, reads, lists, and deletes files, supports conditional writes, and keeps each account's and each environment's files apart. This page lists the capabilities of the package's product statement that the platform's routes do not provide.

Using storage takes four parts, in this order. A minimal upload service joins all four in one service you can copy.

  1. The manifest's {"kind": "object_storage"} entry records that the application stores files. It provisions nothing.
  2. Your tool declares each area with declare_storage_area. Its declarations are fixed at the first declaration.
  3. The package comes from the library, copied into app/lib/storage/ and installed with npm install.
  4. The backend builds the client over a transport that adds the platform credential, then calls it. It may instead declare the area with the client's mintArea at each start, as the example does. Each mint restates the same declarations, the application included; the platform refuses a differing one differing_redeclaration, which the client throws as declarations_differ.

Use it when

Use Storage for documents, uploaded images, and other files. Your backend controls each end user's access and chooses the file names, because the service does not separate files by end user. Files are separate per environment: the same name can refer to a different file in development and in production.

Use the Database package for structured queries, transactions, and application preferences.

What it provides

The current service provides:

  • Named areas with fixed declarations, each bound to one application of the account.
  • Reads, paged listings, deletes, and writes that include an acting identity, the X-Acting-Identity header Store files describes.
  • Conditional writes, which require a version you read earlier or require the name to be unused.
  • A client, StorageWireClient, published as the npm package @turnzero/storage. Use the library shows how to copy it into app/lib/storage/, declare it as file:lib/storage, and install it with npm install. The client calls through a transport function your application supplies, which adds your credential. A deployed transport reads the storage origin from TURNZERO_CLOUD_GATEWAY_URL, or TURNZERO_CLOUD_API where the platform sets no separate gateway origin, and the credential from TURNZERO_CLOUD_TOKEN, among the settings a deployed copy receives (Deploy an application).
  • Short-lived transfer grants that let a browser upload or download one file, each recording the environment it was issued for.
  • Configurable request and page limits, with named refusals.

A test double ships at the package's testing subpath, @turnzero/storage/testing. createStorageDouble takes the place of the service behind the unchanged client. A declaration that leaves out application binds the application set by the double's application option, app by default, as the platform credential binds its own. With application: null, the double acts as a call under a session or an account-scoped token, and such a declaration is refused with application_required. Test your application locally shows it in use.

From version 0.12.0, the double refuses a path or query containing a NUL character (U+0000), or a declaration containing one or an unpaired UTF-16 surrogate, with 400 invalid_request, as the platform does.

From version 0.13.0, the client refuses a file name with a part that is . or .., the parts separated by a slash or a backslash, with invalid_name before it calls the platform. It refuses an area name of . or .. the same way. The double refuses such a file name with 400 invalid_request, as the platform does.

From version 0.14.0, the client's put refuses a file name that holds a backslash, or a part that ends with a dot, the last part included, with invalid_name before it calls the platform. The storage service may keep such a name under another name. Separate the parts with a forward slash, and end no part with a dot. get, getMetadata, and delete_ still send such a name, so a file already stored under one can be read and deleted. The double refuses such a name on a write with 400 invalid_request, as the platform does.

Every call reaches one environment's files in the area:

  • A call under the application's platform credential reaches the environment the credential is bound to. A header that gives another environment is refused with 403 environment_mismatch.
  • A call under a session or a minted token gives the environment in the header x-turnzero-cloud-environment. A file route, a list, or a grant request without it is refused with 400 environment_required. A script that uploads a deploy artifact under a minted token sets it to the environment the deploy goes to: production on an application with one environment, development on one with two.
  • An upload under a short-lived grant, from mint_upload_grant or the grant the turnzero-cloud command receives for a deploy, sends no such header, because the grant fixes the environment when it is minted. The command uploads a deploy's zip this way.

The platform's routes do not keep earlier versions of a file, separate files by end user automatically, or give access levels on a shared area. A version returned by a write supports concurrency checks, and an older version of the file is not kept. Store files describes the current routes, permissions, and grant options.

Availability

Version 0.14.1 is the package's current version, and list_library reports the version the platform currently publishes. The entry includes the testing subpath from version 0.8.0.

Every area is bound to one application of the account. A declaration under the application's platform credential binds its own application when it leaves out the application member. A declaration under a session or an account-scoped token must name application, or it is refused with application_required.

The manifest's object_storage service entry records that the application stores files and provisions nothing; the storage routes and declare_storage_area work for a declared area with or without it.

The library entry contains the package's product statement, its detailed contract, its integration guide, and the compiled client. Turn Zero Cloud's storage routes are live.

Account supplies the end-user identities your backend can use for access checks and attribution. Database stores structured records beside the files. Billing has a product statement alone, apart from the platform's usage metering.