Types - Upstash Documentation

The option and record types the rest of these docs refer to, and the upload phases named in error messages.

Size

maxSize: 4096       // 4,096 bytes
maxSize: "20MB"     // 20,000,000 bytes
maxSize: "32MiB"    // 33,554,432 bytes
multipart: "100MB"

max_size=4096       # 4,096 bytes
max_size="20MB"     # 20,000,000 bytes
max_size="32MiB"    # 33,554,432 bytes
multipart="100MB"

MaxSize: 4096          // 4,096 bytes
MaxSize: 20 * blob.MB  // 20,000,000 bytes
MaxSize: 32 * blob.MiB // 33,554,432 bytes
Multipart: blob.MultipartOver(100 * blob.MB)

A byte count, never a bit count. A bare number is bytes. String units ignore case, so MB and mb both mean megabytes.

Units	Base	Example
`B`, `KB`, `MB`, `GB`, `TB`	Decimal, powers of 1,000	`"32MB"` = 32,000,000 bytes
`KiB`, `MiB`, `GiB`, `TiB`	Binary, powers of 1,024	`"32MiB"` = 33,554,432 bytes

For a 32 MiB file limit, use "32MiB" or 33554432. A "32MB" limit is smaller and rejects that file. Existing decimal units keep their values. Bit units such as mbit and Mbps are not supported. An unparseable size throws where the option is written, not per request. In Go a size is an int64 of bytes written with the unit constants, and blob.ParseSize reads the string form from configuration. A limit you write by hand takes a size: the max size, the multipart threshold. A measurement you forward is a plain number of bytes: the size option on put, and every size the SDK returns. formatBytes, exported from every TypeScript entrypoint, always displays decimal byte units, including values supplied as MiB: formatBytes(2_400_000) is 2.4 MB.

Duration

expiresIn: 300       // 5 minutes
expiresIn: "5m"
olderThan: "7d"
cache: "1h"

expires_in=300                   # 5 minutes
expires_in="5m"
expires_in=timedelta(minutes=5)
older_than="7d"
cache="1h"

ExpiresIn: 5 * time.Minute
olderThan := 7 * 24 * time.Hour
Cache: "1h"

A span of time. A bare number is seconds; a string takes a unit: ms, s, m, h, d, or a long form (sec, seconds, min, minutes, hr, hours, day, days). A string with no unit is seconds. An unparseable duration throws an error naming the option. In Go a lifetime or window is a time.Duration; only Cache takes the string form.

CacheOption

cache: "immutable"
cache: "revalidate"
cache: "no-store"
cache: "15m"
cache: "public, max-age=60, s-maxage=31536000"

cache="immutable"
cache="revalidate"
cache="no-store"
cache="15m"
cache="public, max-age=60, s-maxage=31536000"

Cache: blob.CacheImmutable  // "immutable"
Cache: blob.CacheRevalidate // "revalidate"
Cache: blob.CacheNoStore    // "no-store"
Cache: "15m"
Cache: "public, max-age=60, s-maxage=31536000"

One of three words, a duration, or a raw Cache-Control header. The header each one stores is on Caching. How each SDK types these three: TypeScript, Python, Go.

Records

Four record shapes come back from the SDK. They nest.

Record	Fields	Returned by
Object	path, URL, versioned URL, size, etag, uploaded at	`list`, `copy`, `move`, the JSON update
Completed object	an object plus content type	`put`, the completion callback, a finished browser upload
Info	an object plus content type and metadata	`info`
Download	info plus the body	`get`

Object fields:

Field	Description
Path	The object’s key.
URL	The public object URL. Not set on a private bucket.
Versioned URL	The URL with `?v=<etag>`, etag percent-encoded. Not set when the URL is not.
Size	Bytes.
Etag	Storage’s etag, quoted: `"9f3c..."`.
Uploaded at	Last modified.

Across the SDK, blob names a record, never the bytes. Bytes go in and come out as body (content on Python’s get). The type names and field types in each SDK: TypeScript, Python, Go.

Upload phases

A direct browser upload makes up to four kinds of request to your upload route. The names appear in error messages and across these docs.

Phase	When	What your route does
`begin`	First request, once	Checks constraints, runs the before-upload callback, signs the first URL(s). Never retried.
`parts`	Multipart only, as needed	Signs the next batch of part URLs.
`end`	Once the bytes landed	Completes the upload, runs the completion callback. Retried by the browser on failure.
`cancel`	On `cancel()`	Aborts the multipart upload, or deletes the single-PUT object.

Every request and every successful answer carries protocol, the version of this exchange, in the JSON body. It is separate from the package version, so a browser bundle and a server on different SDK releases, or a server written with another server SDK, still understand each other. A missing value means 1, changes are only ever additive, and neither side refuses the other’s version. The PUTs that carry the bytes go to storage, never to your route. How signing works has the full handshake.

​Size

​Duration

​CacheOption

​Records

​Upload phases

Size

Duration

CacheOption

Records

Upload phases