DEV Community: Gathmo

Designing an idempotent confirmation protocol for browser uploads

Gathmo — Wed, 15 Jul 2026 16:34:46 +0000

A direct-to-object-storage upload removes the application server from the byte path, but it creates a subtle distributed-systems problem at the end of the flow.

The browser can finish uploading the object, send a confirmation request to the API, and lose connectivity before receiving the response. From the user's perspective the result is ambiguous: did the server create the media record, or should the browser try again?

If the confirmation endpoint is not idempotent, retrying can create duplicate records. If the client refuses to retry, a successfully stored object can remain invisible to the application. The protocol needs a stable identity that survives network uncertainty.

Model the upload as two durable operations

The first operation stores bytes. The second operation creates or returns the canonical application record.

browser -> API: authorize attempt
API -> browser: attempt ID, object key, signed upload URL
browser -> storage: transfer bytes
browser -> API: confirm attempt ID and object metadata
API -> browser: canonical media record

The attempt ID is generated once and reused for every confirmation retry. It must not be regenerated when a request times out.

Give the attempt a server-owned scope

A random UUID is useful, but identity alone is not authorization. The authorization response should bind the attempt to the authenticated or temporary guest session, the target event, the expected object key, and relevant constraints such as maximum size or content family.

A minimal record might contain:

type UploadAttempt = {
  id: string;
  eventId: string;
  contributorSessionId: string;
  objectKey: string;
  state: "authorized" | "confirmed" | "rejected";
  createdAt: string;
  confirmedMediaId?: string;
};

The confirmation endpoint looks up this record rather than trusting event or object identifiers supplied again by the browser.

Make confirmation return the existing result

The endpoint should behave like a create-or-return operation.

async function confirmUpload(attemptId: string, input: ConfirmInput) {
  return database.transaction(async (tx) => {
    const attempt = await tx.uploadAttempts.lockForUpdate(attemptId);

    if (attempt.state === "confirmed") {
      return tx.media.findById(attempt.confirmedMediaId);
    }

    assertAttemptBelongsToSession(attempt);
    const storedObject = await inspectStoredObject(attempt.objectKey);
    validateObject(storedObject, input);

    const media = await tx.media.create({
      eventId: attempt.eventId,
      objectKey: attempt.objectKey,
      size: storedObject.size,
      contentType: storedObject.contentType,
      moderationState: "pending",
    });

    await tx.uploadAttempts.markConfirmed(attempt.id, media.id);
    return media;
  });
}

The transaction and uniqueness constraints matter. Two confirmation requests can arrive concurrently after a client retry or double tap. A row lock or compare-and-set transition ensures that only one media record wins.

Do not use the object key as the only idempotency key

Object keys are storage addresses, not necessarily user-intent identifiers. A multipart retry, a replacement workflow, or an administrative recovery may reuse or transform storage paths.

An explicit attempt record gives the application a place to store authorization context, expiry, confirmation state, and the canonical result. It also makes abandoned-object cleanup safer because the system can distinguish an authorized but unconfirmed object from an unrelated storage file.

Reconcile after the browser returns

Persist lightweight attempt metadata in IndexedDB or another durable client store:

attempt ID;
object key;
filename and size;
last known client state; and
timestamps.

On page restore, query the API for each non-terminal attempt. The server response should distinguish at least:

authorized: storage or confirmation may still be incomplete;
confirmed: return the canonical media record;
expired: the client needs a new authorization; and
rejected: show a terminal explanation.

The browser should not infer failure merely because it never received the original response.

Separate upload success from moderation success

Confirmation means the application accepted the media record. It does not mean the item is approved for public display. Returning a separate moderation state avoids the common UX bug where guests retry a successful upload because it has not appeared on a live wall.

The same separation is useful in the browser-based event contribution flow used by Gathmo: transfer, canonical confirmation, and visibility are different states even when the happy path feels like one action.

Test the ambiguous moments

The most valuable protocol tests deliberately interrupt the flow:

Drop the response after the server commits confirmation.
Send the same confirmation twice concurrently.
Retry after the signed upload URL expires but the object already exists.
Confirm an object whose size or content type differs from authorization.
Restore the browser after confirmation completed on another device.
Run cleanup while a confirmation transaction is in flight.

A reliable upload protocol is not one that never encounters ambiguity. It is one that can answer the same question repeatedly and return the same durable result.

A moderation architecture that never blocks user uploads

Gathmo — Wed, 15 Jul 2026 16:33:48 +0000

User-generated media systems often make one state do too much. An item is either “uploaded” or “not uploaded,” while storage, processing, moderation, and public visibility are treated as implementation details.

That model breaks down during live events. A guest needs immediate confirmation that a contribution arrived, but an organizer may require review before the item reaches a shared album or display. Moderation can slow down without turning successful uploads into apparent failures.

The solution is to separate ingestion from publication.

Use an append-first ingestion path

The synchronous request should do only the work needed to accept the contribution safely:

authenticate or validate the temporary contributor session;
confirm the uploaded object and basic policy constraints;
create a canonical media record;
assign an initial moderation state; and
enqueue asynchronous processing.

The response can then return a durable identifier and a truthful state such as received or pending_review.

type MediaRecord = {
  id: string;
  eventId: string;
  objectKey: string;
  ingestionState: "received" | "processing" | "ready" | "failed";
  moderationState: "pending" | "approved" | "hidden" | "removed";
  visibilityState: "private" | "album" | "live_wall";
};

These dimensions should not be collapsed into one enum. A file can be technically ready, pending moderation, and private at the same time.

Keep the live wall out of the write path

The display should query or subscribe only to an approved projection. It should never consume the raw ingestion queue.

guest upload -> canonical media record -> processing queue
                                      -> moderation queue

approved projection -> album API
                    -> live wall feed

If moderation falls behind, the display can continue rotating previously approved media. Guests can continue uploading, and moderators can catch up without back-pressure reaching the upload endpoint.

Make moderation transitions explicit

Each action should be a named state transition with an actor and timestamp. Useful events include:

media_received;
processing_completed;
moderation_approved;
moderation_hidden;
visibility_added_to_wall; and
removal_requested.

An audit trail makes concurrent moderator behavior understandable and supports undo. “Hidden” should usually be reversible; deletion belongs to a separate workflow with its own confirmation and retention rules.

Design the moderator queue for decisions, not browsing

A good queue puts decision context next to the media:

event and contribution time;
media type and duration;
processing or safety warnings;
current album and live-wall visibility;
previous moderator actions; and
keyboard-accessible approve and hide controls.

Newest-first ordering is not always best. During a live event, the queue may prioritize items waiting longest, processing warnings, or media requested by the display operator. The ordering rule should be visible so moderators understand why an item appears next.

Prevent duplicate side effects

Approval may trigger notifications, search indexing, derivative generation, or display updates. Moderation commands therefore need the same idempotency discipline as payment or upload confirmation endpoints.

Use a command ID or state-version precondition:

await approveMedia({
  mediaId,
  expectedVersion: 7,
  commandId: "cmd_01J...",
});

If two moderators act on the same item, one transition succeeds and the other receives the current state instead of replaying every downstream effect.

Publish from a stable read model

Album and display clients should read a projection optimized for visibility, not join raw operational tables on every refresh. The projection can contain the approved derivative URL, aspect ratio, caption, approval time, and event sequence number.

A monotonically increasing event sequence helps clients resume after disconnection without reloading the entire album. It also supports deterministic live-wall rotation when network conditions are poor.

Communicate the right success state to contributors

The contributor interface should say “Your upload was received” when the canonical record exists. If review is enabled, it can add “It will appear after host approval.”

Do not keep a progress bar at 99% while a human moderator is deciding. Technical completion and editorial visibility operate on different clocks.

This separation is central to the moderated event workflow described for Gathmo corporate events: guest contribution can remain fast even when publication is deliberately controlled.

Failure drills worth running

Test the architecture under operational pressure:

Pause all moderation workers while uploads continue.
Disconnect and reconnect the live wall.
Approve the same item concurrently from two moderator sessions.
Fail derivative generation after the canonical record is created.
Hide an item that is currently visible on multiple displays.
Restore a moderator session with stale queue data.

The goal is not instant publication at any cost. It is independent, observable progress: ingestion continues, moderation remains auditable, and every public surface shows only the state it is allowed to consume.

Designing a browser upload flow for unreliable event Wi-Fi

Gathmo — Wed, 15 Jul 2026 15:51:11 +0000

An upload form that works perfectly on office Wi-Fi can fail spectacularly at a wedding or conference. Hundreds of phones share one access point, mobile reception drops between rooms, and users close the browser as soon as they think the upload is done.

The hard part is not accepting a file. It is designing a flow that remains understandable when every assumption about connectivity is wrong.

This article describes the reliability model I use for browser-based event uploads: explicit client states, direct object-storage uploads, bounded retries, persistent intent, and confirmation that reflects server truth rather than UI optimism.

Start with a state machine, not a spinner

A single isUploading boolean hides the situations that matter most. A useful client model separates at least these states:

selected — the browser has access to the local file.
preparing — metadata validation, optional image resizing, and checksum work are running.
authorizing — the client is requesting an upload URL or session from the API.
transferring — bytes are moving to object storage.
confirming — the application API is registering the completed object.
complete — the server has acknowledged the media record.
retryable_error — the operation can continue without selecting the file again.
terminal_error — the file or policy is invalid and needs user action.

This distinction prevents one of the most damaging UX bugs: showing success after storage accepted the bytes but before the application created the corresponding database record.

The UI should render from the state machine. “Uploading 63%” belongs to transferring; “Finishing…” belongs to confirming; “Added to the album” belongs only to complete.

Upload media directly to object storage

Routing large photos and videos through the application server adds an unnecessary bottleneck. A more resilient path is:

browser -> API: request upload authorization
API -> browser: signed URL + object key + constraints
browser -> object storage: upload bytes
browser -> API: confirm object key and metadata
API -> browser: canonical media record

The API remains responsible for authorization, quotas, file policy, ownership, and the final media record. It does not need to proxy every byte.

Signed upload URLs should be short-lived, bound to one object key, and limited to the expected content type and size where the storage provider supports those constraints. Never let the browser choose an arbitrary bucket key that becomes trusted application data.

Make confirmation idempotent

The final confirmation request is especially vulnerable. The storage upload may have succeeded, but the phone can lose connectivity before receiving the API response. If a retry creates a second record, the user sees duplicate media even though only one object exists.

Give each upload attempt a stable client-generated ID. The confirmation endpoint should treat that ID as an idempotency key:

{
  "uploadAttemptId": "01J...",
  "objectKey": "events/evt_123/uploads/01J....jpg",
  "originalName": "IMG_4821.jpg",
  "contentType": "image/jpeg",
  "size": 3842017
}

If the same confirmation arrives twice, return the same media record. This turns an ambiguous network timeout into a safe retry.

Retry deliberately

Automatic retries are useful only when they are bounded and visible.

For authorization and confirmation requests, exponential backoff with jitter is usually appropriate. For example: 500 ms, 1.5 s, 4 s, then stop and show a retry button. Do not create an infinite background loop on a guest’s phone.

For the byte transfer, retry policy depends on file size and storage support. Restarting a 2 MB image is reasonable. Restarting a 300 MB video at 95% is not. Large media should use multipart or resumable uploads so the client can continue from completed chunks.

Classify errors before retrying:

Retry: timeouts, connection resets, and most 5xx responses.
Refresh authorization, then retry: expired signed URL.
Do not retry automatically: unsupported type, quota exceeded, authentication failure, or a 413 size rejection.

The error message should say what happens to the selected file. “Connection lost — your photo is still selected” is much more useful than “Something went wrong.”

Preserve upload intent across short disruptions

Mobile browsers are aggressive about suspending pages. At minimum, persist lightweight upload metadata in IndexedDB: attempt ID, object key, state, filename, size, and timestamps.

Persisting the actual file is more complicated. A File object cannot always be recovered after a browser restart, and large Blobs consume meaningful storage. Use this as a progressive enhancement rather than promising offline uploads everywhere.

Even without persisting the bytes, durable metadata helps reconcile uncertainty. On page return, the client can ask the API whether an attempt was confirmed and avoid presenting an already completed item as failed.

Treat progress as an estimate

Upload progress measures bytes sent by the client, not necessarily durable application completion. Reserve the final visual step for server confirmation.

A practical progress mapping is:

0–10%: preparing and authorizing
10–90%: byte transfer
90–99%: confirmation and processing
100%: canonical record returned

This is not mathematically pure, but it communicates the real workflow. A bar stuck at 100% while the UI still says “processing” feels broken; a bar at 95% with “Finishing…” is honest.

For multiple files, show both per-item state and batch progress. One failed video should not make twelve successful photos look unsuccessful.

Validate twice

Client validation improves feedback, but server validation is authoritative. Check size, type, count, and basic media constraints before authorization, then verify them again during confirmation or asynchronous processing.

Do not trust a filename extension or browser-provided MIME type. Inspect file signatures server-side, isolate untrusted media, and generate derivatives in a controlled worker process.

For event products, moderation is a separate state from upload success. A guest should see that their file arrived even if it is waiting for host approval. Conflating “not publicly visible” with “upload failed” causes repeated submissions.

Design for abandonment

Most guests are not committed users. They scanned a QR code, chose three photos, and expect to return to the party. Reliability therefore includes reducing the time during which the page requires attention.

Keep the capture route free of account creation, defer nonessential work, and give a clear completion signal. If a transfer can continue safely while the user browses within the page, say so. If closing the tab will cancel it, say that instead.

This constraint shaped the upload flow we use at Gathmo, where guests contribute event photos, videos, and voice messages directly from a mobile browser. The product context is specific, but the engineering lesson generalizes: the network is not a reliable boundary, so every transition needs an observable and recoverable state.

A compact reliability checklist

Before shipping a mobile media flow, test these cases intentionally:

The signed URL expires before transfer starts.
Connectivity disappears at 5%, 60%, and immediately after storage success.
Confirmation is sent twice.
The browser is backgrounded during transfer.
One file in a multi-file batch is rejected.
The user taps upload twice.
A large video exceeds policy.
The object exists but confirmation never completed.
Confirmation exists but the client never received the response.
Moderation delays public visibility.

The happy path proves that uploads work. These failure paths prove that the product can be trusted at the exact moment users have only one chance to contribute.