Upload Hooks

Enable upload operations on a named route with upload: true or an UploadConfig object.

import { dimahS3, route, s3Error } from "@dimah-s3/server";
import { awsS3 } from "./aws-s3";

export const s3 = dimahS3({
  client: awsS3,
  bucket: process.env.S3_BUCKET!,
  routes: {
    avatar: route({
      upload: {
        fileTypes: ["image/*"],
        maxFileSize: 2 * 1024 * 1024,
        guard: async ({ request }) => {
          const session = await getSession(request);
          if (!session) throw s3Error("UNAUTHORIZED");
        },
        onConfirmed: async ({ key, object, request }) => {
          const session = await getSession(request); 
          await db.user.update({
            where: { id: session.userId }, 
            data: { avatarKey: key, avatarSize: object.size }, 
          }); 
        }, 
      },
    }),
  },
});

Upload lifecycle flowCopy Anchor Link

1. route.guard: Runs after the instance guard, before the key is chosen.
2. object: Chooses the key folder or key, S3 metadata, ACL, storage class, cache control, and tags.
3. upload.guard: Authorizes the upload once the server-owned key is known.
4. onStart: Runs once the upload can begin, with its uploadToken and confirm deadline. The presign response, with its upload ticket, is returned after it.
5. Confirm: HeadObject reads the stored object. The server checks the upload marker, the size against the declared size (UPLOAD_SIZE_MISMATCH), and the route limits. With verifyContent, it checks the first bytes too.
6. confirmGuard: Authorizes the stored object. It sees the verified object from HeadObject next to the declared file, so check object. A rejection deletes it.
7. onConfirmed: Receives the verified object from HeadObject, and the previousKey the server deletes next. Persist the record here.

upload.guard and onStart also run for multipart init and s3.put. kind tells them apart: "put" or "post" for a presigned upload, "multipart", or "server" for s3.put. s3.put skips confirmGuard.

Tracking an uploadCopy Anchor Link

onStart is the place to record a pending upload. It receives the absolute deadline after which the upload can never be confirmed:

upload: {
  onStart: async ({ uploadToken, key, file, expiresAt, locals }) => {
    await db.upload.create({
      data: {
        token: uploadToken,
        key,
        name: file.name,
        userId: locals.userId,
        expiresAt, 
      },
    });
  },
  onConfirmed: async ({ uploadToken, object }) => {
    await db.upload.updateMany({
      where: { token: uploadToken, status: "pending" },
      data: { status: "active", size: object.size },
    });
  },
},

expiresAt is the ticket expiry, or 15 minutes from now for s3.put. Presigned uploads also get url and urlExpiresAt, and multipart uploads get uploadId.

Failure rulesCopy Anchor Link

A confirm that fails for an infrastructure reason, such as an S3 network error or a guard whose database is down, keeps the object so the client can retry.

onConfirmed runs at least once per upload. Confirm is stateless, so a retried confirm runs every check and hook again with the same uploadToken. Make the hook safe to replay, and reject content in confirmGuard, not in onConfirmed.

Type referenceCopy Anchor Link

import type {
  UploadGuardContext,
  UploadOnStartContext,
  UploadConfirmGuardContext,
  UploadOnConfirmedContext,
  UploadObjectContext,
  VerifiedObject,
} from "@dimah-s3/server";

UploadGuardContextCopy Anchor Link

Runs after upload.object assigns the key (and after the instance and route guards).

UploadOnStartContextCopy Anchor Link

UploadConfirmGuardContextCopy Anchor Link

Runs on confirm and multipart complete, after HeadObject and the size checks.

UploadOnConfirmedContextCopy Anchor Link

VerifiedObjectCopy Anchor Link

The object in onConfirmed, as HeadObject reports it.

UploadObjectContextCopy Anchor Link

Input passed to upload.object to generate custom destination keys and metadata.

Frequently asked questionsCopy Anchor Link

avatar: route({
  upload: {
    object: async ({ file, clientMetadata }) => ({
      keyFolder: "avatars",
      metadata: {
        "original-name": file.name, 
        album: clientMetadata?.album ?? "default", 
      }, 
    }),
  },
}),