Resumable uploads let a client send a large file in chunks and continue after a dropped connection. How a session URI works, how to create one in Node.js, how the client sends and resumes chunks, CORS, and when a plain signed URL is enough, with an Encore example.

A 2 GB video upload from a phone on a train will fail partway. With a plain upload the user starts again from zero, while a resumable upload lets the client ask the server where it stopped and send only the rest.
Google Cloud Storage supports this natively, and this guide explains how the session works, how to create one from Node.js, what the client does to send and resume chunks, and when a plain signed URL is the better choice.
The resumable upload protocol has two steps: first a request initiates a session and Cloud Storage returns a session URI, a unique URL that identifies this one upload. Second, the client sends data to that URI, either all at once or in chunks with a Content-Range header. If a request fails, the client sends an empty PUT with Content-Range: bytes */TOTAL to ask how many bytes the server has, and continues from there.
The session URI acts as the credential for that one upload, so anyone holding it can write to the object until the session expires. A session stays valid for a week, so treat the URI as a secret and hand it only to the client that should upload.
Use the @google-cloud/storage library and let the backend create the session, so the client needs no Google credentials:
import { Storage } from "@google-cloud/storage";
const storage = new Storage();
export async function startUpload(objectName: string, origin: string): Promise<string> {
const file = storage.bucket("my-uploads").file(objectName);
const [uri] = await file.createResumableUpload({
origin, // allows a browser on this origin to use the session URI under CORS
metadata: { contentType: "video/mp4" },
});
return uri;
}
The origin option matters for browsers: the session must be created with the origin of the page that uploads, otherwise the browser blocks the upload under CORS. Pick object names on the server, never from client input, to avoid overwriting existing objects.
The performing resumable uploads guide covers the raw requests: the simplest client sends the whole file in one PUT to the session URI and, on failure, asks for the offset and resends the rest. For progress bars and large files, send chunks. Every chunk except the last must be a multiple of 256 KiB, as the documentation requires, and carries a Content-Range such as bytes 0-8388607/52428800. Cloud Storage answers 308 Resume Incomplete until the final chunk, then 200 or 201.
// Browser sketch: upload in 8 MiB chunks to a session URI
async function upload(file: File, sessionUri: string) {
const chunk = 8 * 1024 * 1024; // a multiple of 256 KiB
for (let start = 0; start < file.size; start += chunk) {
const end = Math.min(start + chunk, file.size);
const res = await fetch(sessionUri, {
method: "PUT",
headers: { "Content-Range": `bytes ${start}-${end - 1}/${file.size}` },
body: file.slice(start, end),
});
if (res.status !== 308 && !res.ok) throw new Error(`upload failed: ${res.status}`);
}
}
A production client wraps the loop in retries with backoff and uses the bytes */TOTAL status check to find the actual offset after any error.
A signed URL for a single PUT is simpler: no session, no chunking, and it works with a plain fetch. It is the right default for files up to tens of megabytes. Choose resumable when files are large or connections unreliable, since a failure late in a single request costs the whole upload. Either way the file goes straight to the bucket and never through your API.
Encore brings infrastructure from code to the bucket: a bucket declared in a TypeScript service is created in your GCP project on deploy and runs locally under encore run. Encore buckets issue signed upload URLs, which are single-request uploads, so they cover the simple case, and the chunked resumable protocol described above is what to add for very large files on unreliable connections.
Run in your terminal to get started locally.
// media/media.ts
import { api, APIError } from "encore.dev/api";
import { Bucket } from "encore.dev/storage/objects";
import { Topic } from "encore.dev/pubsub";
const videos = new Bucket("videos"); // private by default
interface VideoUploaded {
key: string;
}
export const videoUploaded = new Topic<VideoUploaded>("video-uploaded", {
deliveryGuarantee: "at-least-once",
});
export const createUpload = api(
{ method: "POST", path: "/videos", expose: true },
async ({ id }: { id: string }): Promise<{ url: string; key: string }> => {
const key = `videos/${id}.mp4`;
const { url } = await videos.signedUploadUrl(key, { ttl: 3600 });
return { url, key };
},
);
export const complete = api(
{ method: "POST", path: "/videos/:id/complete", expose: true },
async ({ id }: { id: string }): Promise<void> => {
const key = `videos/${id}.mp4`;
if (!(await videos.exists(key))) throw APIError.failedPrecondition("upload not finished");
await videoUploaded.publish({ key });
},
);
Add an auth handler so only the owner of a video can request an upload URL. The client uploads straight to the returned URL, then calls complete, which checks the object exists before publishing the event that starts processing. A Pub/Sub subscriber can then transcode or scan the file. For files where a single request is too fragile, create the resumable session in the same service with the Cloud Storage client against the bucket your environment uses, and keep the completion endpoint unchanged.
A coding agent can add the bucket, the upload endpoint and the completion event in one change, and test the flow locally against the local bucket before the deploy provisions Cloud Storage.
Best fit: TypeScript teams on GCP that accept user uploads and want the bucket and the completion event declared with the service, with resumable sessions added where files are large.
It is an upload method where you first start a session, which returns a unique session URI, and then send the file to that URI in one or more requests. If a request fails, you ask the session how many bytes it received and continue from there instead of starting over.
Call file.createResumableUpload() from the @google-cloud/storage library. It returns the session URI as the first element of the result, which your backend can hand to a browser or mobile client so that the client uploads directly to Cloud Storage.
Use resumable uploads for large files or unreliable connections, such as mobile networks, where losing a long upload hurts. For small files, a single-request signed upload URL is simpler and needs no session handling.
Yes. Encore buckets issue signed upload URLs with signedUploadUrl, which are single-request uploads that work well for files up to moderate sizes. For very large files on flaky connections, a resumable session created with the Cloud Storage client is the better fit, and the rest of the Encore service stays the same.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.