DEV Community: GalleryDock

Building Resumable Browser Uploads That Survive Real-World Failures

GalleryDock — Sun, 23 Aug 2026 19:34:28 +0000

A 4 GB video upload reaches 97%.

Then the user's Wi-Fi drops for five seconds.

If your upload implementation starts again from byte zero, you do not really have a large-file upload system. You have a very optimistic file transfer.

Reliable browser uploads need to assume that connections fail, tabs reload, requests time out, and clients occasionally send the same request twice.

The usual solution is chunked, resumable uploads. But splitting a file into pieces is only the beginning. The harder part is making retries safe and keeping client and server state synchronized.

Start with an upload session

Instead of sending the entire file directly, the client first asks the backend to create an upload session.

POST /uploads
Content-Type: application/json

{
  "filename": "project-final.mp4",
  "size": 4294967296,
  "contentType": "video/mp4"
}

The server returns an identifier and the chunk size it expects:

{
  "uploadId": "upl_7f91c2",
  "chunkSize": 8388608
}

Using a server-defined chunk size is useful because the backend can tune it without requiring frontend changes.

For example, 8 MB chunks provide a reasonable balance between request overhead and retry cost.

Slice the file in the browser

The browser does not need to load the entire file into memory.

File inherits from Blob, which means we can use slice():

const CHUNK_SIZE = 8 * 1024 * 1024;

function getChunk(file, index) {
  const start = index * CHUNK_SIZE;
  const end = Math.min(start + CHUNK_SIZE, file.size);

  return file.slice(start, end);
}

Then upload one chunk at a time:

async function uploadChunk(uploadId, index, chunk) {
  const response = await fetch(
    `/uploads/${uploadId}/chunks/${index}`,
    {
      method: "PUT",
      body: chunk
    }
  );

  if (!response.ok) {
    throw new Error(`Chunk ${index} failed`);
  }
}

Sequential uploads are simple and predictable. Once that works reliably, limited concurrency can improve throughput.

Do not jump immediately to uploading 20 chunks in parallel. On slower connections that can make performance worse rather than better.

Retries must be idempotent

The most important backend property is this:

Uploading chunk 17 twice should produce the same result as uploading it once.

Imagine the server successfully stores a chunk, but the response is lost before reaching the browser.

The client sees a timeout.

It has no idea whether the upload succeeded.

So it retries.

If your backend treats that retry as a completely new operation, corruption or duplicate data becomes possible.

A chunk endpoint should therefore behave idempotently:

PUT /uploads/upl_7f91c2/chunks/17

The identity of the operation is already encoded in the URL.

The backend can safely replace or confirm the existing chunk rather than append arbitrary bytes to a growing file.

This is much safer than a design where every request simply means "append these bytes."

Track completed chunks on the server

The browser should never be the only source of truth.

Store upload state such as:

{
  "uploadId": "upl_7f91c2",
  "status": "uploading",
  "totalChunks": 512,
  "completedChunks": [0, 1, 2, 3, 4, 6, 7]
}

Now a client can reload the page and ask:

GET /uploads/upl_7f91c2

The response tells it which chunks are already present.

const state = await fetch(
  `/uploads/${uploadId}`
).then(r => r.json());

const completed = new Set(state.completedChunks);

for (let i = 0; i < totalChunks; i++) {
  if (completed.has(i)) continue;

  await uploadChunk(
    uploadId,
    i,
    getChunk(file, i)
  );
}

There is one limitation here: after a full browser reload, the browser cannot silently regain access to the original local file.

The user may need to select it again.

You should therefore verify that the reselected file matches the original session before continuing.

Useful checks include filename, file size, modification timestamp, or a stronger fingerprint.

Never resume against a different file just because its name happens to match.

Progress should represent confirmed data

A misleading progress bar is worse than no progress bar.

Do not report progress merely because the browser has attempted to send chunks.

Track bytes that the server has confirmed.

function calculateProgress(
  completedChunks,
  chunkSize,
  fileSize
) {
  const uploaded = Math.min(
    completedChunks * chunkSize,
    fileSize
  );

  return Math.round(
    (uploaded / fileSize) * 100
  );
}

If you upload chunks concurrently, count each chunk only after its request succeeds.

That way a retry does not make the progress bar jump backward or accidentally exceed 100%.

Add bounded retry behavior

Networks fail. Retrying immediately in a tight loop is not a recovery strategy.

Use exponential backoff:

const delay = ms =>
  new Promise(resolve => setTimeout(resolve, ms));

async function withRetry(fn, maxAttempts = 5) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxAttempts) {
        throw error;
      }

      const wait =
        Math.min(1000 * 2 ** (attempt - 1), 10000);

      await delay(wait);
    }
  }
}

Then:

await withRetry(() =>
  uploadChunk(uploadId, index, chunk)
);

In production, adding random jitter is also useful so thousands of clients do not all retry at exactly the same moment after a temporary outage.

Do not trust chunk metadata from the client

A client may claim:

chunkIndex = 42

That does not mean the server should blindly accept it.

Validate:

the upload session exists
the session belongs to the authenticated user
the upload is still open
the chunk index is within range
the body is not larger than the configured chunk size
the declared total file size is within account limits

If your system uses object storage, upload permissions should also be scoped to one specific upload session rather than granting broad write access to a bucket.

Finalization should be explicit

Uploading the final chunk should not automatically mean the file is ready.

Use a separate completion step:

POST /uploads/upl_7f91c2/complete

The backend can then verify that every required chunk exists.

Only after validation should the upload move into a state such as:

uploading
→ assembling
→ processing
→ ready

For media systems, "uploaded" and "ready" are often very different states.

A video may still require metadata extraction, thumbnail generation, transcoding, or validation before users should see it.

Clean up abandoned sessions

Resumable uploads create temporary state.

Some users will never finish.

Without cleanup, incomplete chunks eventually become an expensive pile of orphaned storage.

Store an expiration time with every upload session and periodically delete sessions that have not been touched for a reasonable period.

Do not make the timeout too aggressive. A multi-gigabyte upload on a slow connection can legitimately take hours.

The architecture matters more than the progress bar

Large-file uploading looks like a frontend feature, but most reliability problems are architectural.

The browser should be able to retry.

The server should make retries harmless.

Upload progress should come from confirmed state.

Finalization should validate completeness.

And temporary data should have an explicit lifecycle.

Once those pieces are in place, a failed request becomes boring.

That is exactly what you want.

The user reconnects, the client checks what already arrived, and the upload continues instead of throwing away gigabytes of completed work.

This article was created with AI assistance and reviewed for technical accuracy before publication.

Private Video Delivery Without Breaking Seeking: Signed URLs, Range Requests, and Expiry

GalleryDock — Tue, 18 Aug 2026 12:33:47 +0000

A private video works perfectly when you press play.

Then you drag the timeline to 12:43.

The player spins for a few seconds and fails.

This is a common problem when building authenticated video delivery. The application correctly protects the original file, but the implementation assumes that playing a video is equivalent to downloading one file in one HTTP request.

Browsers do not necessarily work that way.

Video players often request small byte ranges from different parts of the file. Seeking, buffering, reconnecting, and switching playback position can all generate additional HTTP requests.

If authentication, signed URLs, caching, and range handling are not designed together, private video playback becomes unreliable surprisingly quickly.

Why video players use range requests

Suppose a browser wants only bytes 5,000,000 through 7,000,000 of a video.

It may send:

GET /media/video.mp4
Range: bytes=5000000-7000000

A range-aware server should respond with 206 Partial Content rather than 200 OK:

HTTP/1.1 206 Partial Content
Accept-Ranges: bytes
Content-Range: bytes 5000000-7000000/94837522
Content-Length: 2000001
Content-Type: video/mp4

The browser can then fetch only the portion it needs.

That makes seeking fast and avoids downloading a 500 MB video just because somebody wants to watch the final 30 seconds.

For large media applications, preserving this behavior is essential.

Do not stream private files through the application server

A tempting architecture looks like this:

Browser
  ↓
Application server
  ↓
Object storage

The application authenticates the user, reads the video from storage, and sends the bytes back.

It works.

It also turns the application server into an expensive media proxy.

A better architecture is usually:

Browser
  ↓
Application API
  ↓
Authorization check
  ↓
Short-lived media authorization
  ↓
CDN
  ↓
Object storage

Your application decides who may access the video.

Your CDN and object storage handle moving the bytes.

Those are different responsibilities and separating them makes scaling much easier.

Sign access to a specific resource

One simple approach is to create a short-lived token containing the media path and expiry.

For example:

import crypto from "node:crypto";

const SECRET = process.env.MEDIA_SIGNING_SECRET;

function signMediaPath(path, expiresAt) {
  const payload = `${path}:${expiresAt}`;

  return crypto
    .createHmac("sha256", SECRET)
    .update(payload)
    .digest("hex");
}

You could generate a playback URL such as:

const path = "/private/videos/8f32b1.mp4";
const expires = Math.floor(Date.now() / 1000) + 3600;
const signature = signMediaPath(path, expires);

const url =
  `${path}?expires=${expires}&signature=${signature}`;

At the edge or media endpoint, validate both values:

function verifyMediaRequest(path, expires, signature) {
  if (Number(expires) < Math.floor(Date.now() / 1000)) {
    return false;
  }

  const expected = signMediaPath(path, expires);

  const a = Buffer.from(expected);
  const b = Buffer.from(signature);

  if (a.length !== b.length) {
    return false;
  }

  return crypto.timingSafeEqual(a, b);
}

The important detail is that the signature covers the resource path.

A token created for:

/private/videos/a.mp4

must not also authorize:

/private/videos/b.mp4

Otherwise a user may be able to modify the path while reusing a valid token.

Expiry gets tricky during playback

Very short-lived signed URLs sound more secure.

For images, a five-minute expiration might be perfectly reasonable.

For a 90-minute video, it may cause problems.

The browser can begin playback while the token is valid and make another range request 20 minutes later. If authorization is checked again and the token expired after five minutes, seeking or buffering may suddenly fail.

There are several ways to handle this.

One is simply making playback authorization long enough to cover a reasonable viewing session.

Another is using a renewable playback session. Your application issues a media credential, the frontend refreshes it before expiry, and later range requests use the refreshed authorization.

Some CDN systems also support signed cookies or equivalent session-based authorization. That can work particularly well because the media URL itself does not need to change every time credentials are refreshed.

The right implementation depends on your infrastructure.

The important point is this:

Token lifetime should be designed around browser playback behavior, not just around the initial page request.

Preserve the Range header

Another easy mistake happens when a reverse proxy or CDN sits in front of storage.

The browser sends:

Range: bytes=20000000-

but an intermediate service removes the Range header.

The origin then returns the entire video.

Playback may still appear to work, making the bug harder to notice, but seeking becomes slower and bandwidth usage increases dramatically.

Check that your delivery chain correctly forwards and caches:

Range
If-Range
Content-Range
Accept-Ranges

Then test actual seeking in browser developer tools rather than checking only whether the video starts.

Keep playback and download permissions separate

A user being allowed to watch a video does not necessarily mean they should receive a convenient permanent download URL.

Model those permissions separately.

For example:

{
  mediaId: "video_123",
  canView: true,
  canDownload: false
}

Playback authorization can produce access suitable for browser streaming.

Explicit downloads can go through another authorization path.

This is especially useful in systems where gallery owners can independently enable viewing and downloading.

Do not rely on hiding a download button as access control. If the browser can retrieve a resource, users can inspect network traffic. Security has to exist at the delivery layer.

Be careful with CDN caching

Signed URLs also interact with caching.

If every request includes a unique signature:

video.mp4?signature=abc
video.mp4?signature=def
video.mp4?signature=ghi

and the CDN includes the complete query string in its cache key, the same video may be cached repeatedly.

That destroys much of the benefit of using a CDN.

Depending on the CDN, you may be able to validate authorization parameters while excluding them from the underlying object cache key.

The goal is:

Authorization: per request
Cached media object: shared

not:

Authorization: per request
Cached media object: duplicated per token

This becomes particularly important with large video files.

Test the failure cases

Before considering private video delivery finished, test more than pressing play.

Try:

seeking before the video has buffered
seeking near the end of a large file
refreshing after the token expires
opening an expired media URL directly
modifying the media path while keeping the signature
disabling download permission while retaining playback permission
loading several videos concurrently
testing through the production CDN rather than only localhost

Media delivery tends to expose assumptions that normal API requests never reveal.

The underlying architecture is fairly simple once the responsibilities are separated: the application handles authorization, the CDN handles delivery, object storage holds the original media, and HTTP range requests remain intact throughout the path.

Getting those boundaries right produces private video playback that is both secure and fast without turning the application server into a video streaming service.

AI DISCLOSURE

This article was created with AI assistance and reviewed for technical accuracy before publication.

How to Build Responsive Cross-Origin iframe Embeds

GalleryDock — Mon, 10 Aug 2026 16:28:02 +0000

Embedding an external web app with an iframe is easy until the content inside starts changing height.

A fixed height usually creates one of two problems: too much empty space or an unwanted scrollbar.

For cross-origin iframes, the parent page cannot simply read the height of the embedded document because of the browser's same-origin policy.

A clean solution is to combine ResizeObserver with postMessage.

Inside the embedded page

The embedded application measures its own height and sends it to the parent:

function sendHeight() {
  window.parent.postMessage(
    {
      type: "iframe-resize",
      height: document.documentElement.scrollHeight
    },
    "https://example.com"
  );
}

const observer = new ResizeObserver(sendHeight);

observer.observe(document.documentElement);

window.addEventListener("load", sendHeight);

ResizeObserver is useful because the height can change after the initial page load.

For example:

images may load later
accordions may open
responsive layouts may change
dynamic content may be added
fonts may affect the layout

Instead of guessing a height, the iframe reports its actual size whenever something changes.

On the parent page

The parent listens for the message and updates the iframe:

const iframe = document.querySelector("#embedded-app");

window.addEventListener("message", (event) => {
  if (event.origin !== "https://embedded.example.com") {
    return;
  }

  if (event.data?.type !== "iframe-resize") {
    return;
  }

  const height = Number(event.data.height);

  if (!Number.isFinite(height) || height <= 0) {
    return;
  }

  iframe.style.height = `${height}px`;
});

The iframe itself can stay simple:

<iframe
  id="embedded-app"
  src="https://embedded.example.com"
  style="width: 100%; border: 0;"
></iframe>

Now the embedded content can grow or shrink without introducing an internal scrollbar.

Validate the origin

A common shortcut is:

window.parent.postMessage(data, "*");

That works, but it is better to specify the expected origin whenever possible.

The receiving page should also validate event.origin.

Treat messages coming from an iframe like any other external input: verify where they came from before using the data.

The result

This pattern keeps responsibilities clean:

the embedded app knows its own content height
the parent controls the iframe element
postMessage connects both sides safely
ResizeObserver reacts to layout changes

It is a simple approach, but it solves one of the most common problems with responsive cross-origin embeds without relying on arbitrary fixed heights.

This article was created with AI assistance and reviewed for technical accuracy before publication.