Skip to content
Files SDK
Esc
↑↓navigate↵open⌘Jpreview
On this page

Gateway

createFilesRouter exposes the whole Files API over one HTTP endpoint. Mount it in Next (or any Web-Request runtime) and the browser bindings talk to it.

createFilesRouter turns a Files instance into an HTTP handler that the browser bindings (React, Vue, Svelte) call. It is framework-agnostic — handle(req: Request): Promise<Response> — and surfaced by thin adapters like files-sdk/next.

import { createFiles } from "files-sdk";
import { r2 } from "files-sdk/r2";
import { createFilesRouter } from "files-sdk/api";
import { createRouteHandler } from "files-sdk/next";

const router = createFilesRouter({
  files: createFiles({ adapter: r2({ bucket: "uploads" }) }),
  authorize: async ({ req }) => {
    /* … */
  },
});

export const { GET, POST, PUT } = createRouteHandler(router);

GET serves downloads, POST the JSON verbs, and PUT the upload byte path. The handler is Web-native (Request/Response, crypto.subtle, ReadableStream), so the same code runs on Node and the Edge runtime.

Passing a Files instance (not a raw adapter) is deliberate: its prefix, readonly, plugins, hooks, and receipts all compose for free. Pass files.readonly() for a read-only deployment so writes are refused at the SDK layer too.

Options

createFilesRouter({
  // A Files instance, or a per-request factory for multi-tenant apps.
  files: Files | ((req: Request) => Files | Promise<Files>),

  // Per-operation gate. Deny-by-default when omitted. See /ui/server/authorization.
  authorize?: (ctx) => void | Constraint | Promise<void | Constraint>,

  // Declarative allow-list — operations permitted without a hook.
  operations?: FilesOperation[],

  // CSRF/origin allow-list for state-changing actions. Defaults to same-origin.
  allowedOrigins?: string[] | ((origin: string) => boolean),

  // Expiry for url()/download/upload URLs when the client doesn't ask for one,
  // seconds. Default 300. Not a ceiling — cap it with authorize's maxExpiresIn.
  defaultExpiresIn?: number,

  // Force Content-Disposition: attachment on downloads (proxied, or bound
  // into the redirect URL). Default true.
  forceDownloadDisposition?: boolean,

  maxListLimit?: number,       // cap a list page; also the page size a search walks with. Default 1000.
  maxSearchResults?: number,   // cap a search page. Default 1000.
  maxSearchScan?: number,      // keys one search reads before answering truncated: true. Default 10000.
  maxUploadSize?: number,      // reject larger uploads (checked at presign, bound, verified on complete).

  // Runs once per verified upload; its result is the client's upload `data`.
  // Throw to reject (the object is deleted). See /ui/server/upload-lifecycle.
  onUploadComplete?: (ctx) => TData | Promise<TData>,
  onRejected?: "delete" | "keep", // rejected objects. Default "delete".
  completions?: CompletionStore,  // make keyless completions single-use.
  completeGracePeriod?: number,   // seconds `complete` still accepts an expired upload token. Default 3600.

  // Gets every failure whose detail the client doesn't see: anything thrown
  // that isn't a FilesError or RouterError (a generic 500), and a storage
  // Provider/Unauthorized error (sent with a fixed message). Default console.error.
  onError?: (error: unknown, req: Request) => void,

  // Limits on client-driven load (see "Request limits" below).
  maxBatchSize?: number,           // keys[]/files[]/completions[] per request. Default 1000.
  maxConcurrency?: number,         // ceiling on a bulk op's `concurrency`. Default 16.
  maxJsonBodySize?: number,        // JSON request body, bytes. Default 1 MiB.
  maxSearchPatternLength?: number, // search pattern, characters. Default 256.
  maxSearchWildcards?: number,     // unbounded wildcards per search pattern. Default 4.

  downloadMode?: "auto" | "redirect" | "proxy",      // default "auto"
  onUnsupportedRange?: "reject" | "ignore",          // default "reject" (416)

  // HMAC secret for the upload round-trip. Falls back to FILES_API_SECRET,
  // then a per-process random (logs a warning — set a stable secret in prod).
  secret?: string,
});

How downloads flow

downloadMode: "auto" (the default) picks the cheapest correct path per adapter:

  • Redirect to a signed URL — when the adapter can sign (S3, R2, GCS, …) and bind the forced Content-Disposition into the signature, the gateway 302s to a short-lived signed URL and the bytes flow directly from storage. Your server never touches them, and Range requests are handled by the provider. When authorize returns { disposition: "inline" }, nothing needs binding, so an adapter that can’t set a disposition is redirected too, with a URL that carries none.
  • Redirect to the public link — when no disposition must be bound (forceDownloadDisposition: false, or an inline policy) and authorize sets no maxExpiresIn, an adapter with a permanent public link (a publicBaseUrl CDN, a public bucket or blob) is redirected to that link.
  • Proxy — otherwise: the adapter can’t sign (Vercel Blob in public mode, the filesystem, …), or it signs but can’t bind the forced attachment (Vercel Blob and UploadThing in private mode, Box, PocketBase, …). The gateway streams the body through itself, setting the disposition itself and answering Range requests with 206 slices when the adapter can read ranges (see below for adapters that can’t). The client’s abort signal is wired through, so a disconnect cancels the upstream read.

The url operation follows the same rules: it signs whenever the adapter can (with your defaultExpiresIn unless the client asks for one), and on an adapter that only has permanent links, a client-requested expiresIn or an authorize maxExpiresIn is answered with a 422 instead of a link that outlives it.

Force one with downloadMode: "redirect" | "proxy". Downloads send Content-Disposition: attachment by default (so a stored .html/SVG can’t execute inline at your origin) unless authorize returns { disposition: "inline" }. The proxy path sets the header itself, and the redirect path binds it into the signed URL. Proxied downloads also send X-Content-Type-Options: nosniff, so the browser won’t sniff stored bytes into a more dangerous type, and Cache-Control: private, no-store, so a shared cache never keeps an authorized response. Except for raster images, audio, video, and PDF, they also carry Content-Security-Policy: sandbox; default-src 'none'; style-src 'unsafe-inline': a stored HTML or SVG file opened inline from your origin gets an opaque origin, loads nothing, and runs no script. A stored content type that isn’t exactly one media type (image/png, text/html, which a browser reads as its last entry) is sandboxed too, and the gateway refuses such a type from a client with 422 (reason: "type") on the keyed upload PUT, presign, and signed-upload-url. A client type must also be ASCII. A stored type that no response header can carry (written outside the gateway with a character past U+00FF, say) is proxied as application/octet-stream.

The proxy’s default attachment names the file after the key’s last segment (Content-Disposition: attachment; filename="report.pdf", plus an RFC 6266 filename* for a non-ASCII name), so a download opened straight from its ?op=download URL saves under its own name. A disposition authorize returns is sent exactly as given; one a header can’t carry (a control character, or one past U+00FF) fails the proxied download with 422 before the object is opened. Proxied downloads also answer HEAD with the headers a GET would send (Content-Length, ETag, Last-Modified, the disposition) and no body, without reading the object. On a full 200 response, the base64 JSON X-Files-Meta header carries the object’s size alongside its key and metadata, so the browser client still knows the size when compression middleware drops Content-Length.

Some adapters can sign a URL but can’t bind a Content-Disposition into it (Vercel Blob in private mode, Box, Dropbox, PocketBase, …), and their url() refuses the option rather than drop it. With downloadMode: "auto", the gateway proxies those downloads instead, so the attachment header still applies. More generally, whenever url() refuses with Unsupported on the signed or the public-link path, auto falls back to the proxy. With downloadMode: "redirect" there is no fallback, and the refusal surfaces as an error. When authorize returns { disposition: "inline" }, inline rendering is already your policy, so the gateway redirects to a URL minted without a disposition.

An authorize responseContentType is handled the same way: auto redirects only when the adapter can bind it into a signed URL (capabilities.signedUrl.contentType), never to the permanent public link, and proxies otherwise with that Content-Type (and the sandbox decision made on it). The url operation fails with a 422 Unsupported error on adapters that can’t bind it.

On the proxy path, Accept-Ranges reflects the adapter: bytes when it can serve ranges, none when it can’t. A Range request that carries an If-Range validator (the ETag or date from an earlier response) only gets a 206 slice while the object is unchanged. If the object changed, the gateway sends the whole new object with a 200, so a resumed download never splices bytes from two versions. Proxied responses carry ETag as a quoted entity-tag (even when the adapter reports it bare, as the S3 family does) and Last-Modified when the adapter knows it, and If-Range matches either the quoted or the bare form.

A ranged request to a non-range adapter gets 416 with the default onUnsupportedRange: "reject", with one exception. A 416 carries a JSON error body (Validation, reason: "range"), which the browser client turns into an Invalid error. bytes=0- (the open-ended range every <video> and <audio> element starts with) is satisfied by the whole body, so it gets the full object with a 200. With onUnsupportedRange: "ignore" any ranged request to a non-range adapter gets the whole object with a 200, and the browser client rejects that instead of treating it as the slice.

The JSON url operation applies the same safe default before calling files.url(): a browser request for responseContentDisposition: "inline" is rewritten to attachment, while an existing attachment; filename="..." value keeps its filename. Return { disposition: "inline" } from authorize only for routes where inline rendering is deliberate server policy.

On an adapter that can’t bind a disposition into its URLs, the gateway can’t guarantee attachment, so the url operation fails with a 422 Unsupported error instead of handing out a URL that may render inline. The message says how to proceed: return { disposition: "inline" } from authorize for routes where inline URLs are acceptable (the URL is then minted without a disposition), or use download, which proxies the bytes and sets Content-Disposition itself.

How uploads flow

A keyless upload(file) runs a three-step protocol so bytes never round-trip through your server when they don’t have to:

  1. presign — the server mints a key (under the authorized prefix), signs an HMAC token binding the key and size/type constraints, and returns either a real presigned URL or a proxy target. The token holds the upload to the size the client declared (the size authorize approved), capped by maxUploadSize, and it is bound to the endpoint that minted it: the request’s origin, path, and query. A file whose declared size is over maxUploadSize is refused up front with 422 and reason: "size", before anything is signed. A batch is signed at most maxConcurrency targets at a time. A proxy target’s token isn’t capped by the adapter’s signedUpload.maxExpiresIn, which only limits the provider’s own presigned URLs. A client-requested expiresIn must be a positive whole number of seconds, or presign answers 422.
  2. upload — the client PUT/POSTs the bytes directly to storage (or proxies through ?op=proxy for non-presigning adapters), reporting progress. Like a presigned URL, the proxy PUT is authorized by its token alone (see Authorization).
  3. complete — the server verifies the token, checks that its key lies under the calling request’s authorized prefix, and heads the object, then returns the stored metadata. A token minted for another caller’s prefix gets an Unauthorized entry with no stored metadata. (The token is signed, not encrypted: its payload names the key it was minted for, so treat a token as readable by whoever holds it.) The head is the authoritative size check: an object larger than the token allows (the declared size, capped by maxUploadSize) gets an error entry and is deleted. The server then runs onUploadComplete and returns the stored metadata with whatever the hook returned.

An explicit upload(key, body) skips presign and streams straight through the gateway, then runs onUploadComplete the same way. The stream reaches the adapter with no known length, so the S3-family adapters on their AWS SDK client need the optional @aws-sdk/lib-storage package for this path.

Request limits

Every JSON request is untrusted input that turns into storage calls, so the gateway bounds how much work one request can ask for:

  • Batch size. keys[] (head/exists/delete bulk forms), files[] (presign) and completions[] (complete) are capped at maxBatchSize (default 1000). A larger request gets 413 with reason: "count" before any storage call.
  • Concurrency. A bulk op’s client-supplied concurrency is clamped to maxConcurrency (default 16).
  • Body size. A JSON body over maxJsonBodySize (default 1 MiB) gets 413 with reason: "size". It is refused from Content-Length up front, or as soon as a streamed body passes the cap, without buffering the rest.
  • Search. A search walks the bucket in pages of maxListLimit keys whatever limit the client sends (maxResults caps the matches), and one request reads at most maxSearchScan keys (default 10,000), matching or not, before it stops and answers truncated: true, so a pattern that matches nothing can’t walk the whole bucket. Patterns are also bounded: at most maxSearchPatternLength characters (default 256) and maxSearchWildcards unbounded wildcards or quantifiers (default 4). *, **, +, and {n,} each count, and an unanchored regex counts one more. Nested repetition such as (a+)+ is always refused. A pattern over either limit gets 422 before any key is matched. Globs and regexes both run on a backtracking engine, where each wildcard multiplies the worst-case work per key, so this bounds what one request can cost in CPU. Raise the limit if your patterns need more, or lower it if search is open to untrusted users.

Other frameworks

The gateway core accepts any { handle(req: Request): Promise<Response> } consumer, so a binding is a few lines. Ready-made adapters ship for Next.js, Hono, Express, Fastify, Koa, NestJS, Nitro, SvelteKit, Astro, and TanStack Start. For anything else (Elysia, Bun, Deno, …), call router.handle(request) directly from any handler that gives you a Web Request.

Last updated on

Was this page helpful?