`initiate.ts`

Purpose

Defines the request body and response shape for POST /uploads/initiate, the chunked upload bootstrap endpoint. The client declares the file's total size, SHA-256 hash, and optional MIME type up-front; the server returns the uploadId, server-chosen chunkSize, and totalChunks so the client can deterministically slice the file.

Features

Client-declared totalSha256 is the contract the server later verifies on complete — mismatch raises UPLOAD.HASH_MISMATCH (HTTP 422).
mimeType defaults to application/octet-stream so clients uploading binary payloads need not guess.
chunkSize may be overridden by the client; absent, the server uses the configured defaultChunkSize.
255-char fileName cap matches POSIX NAME_MAX.

Usage: Basic

import { InitiateUploadBodySchema } from "@suaveplan/api-plugin-file-upload/schemas/routes";

const body = InitiateUploadBodySchema.parse(await c.req.json());

Usage: Advanced

import { InitiateUploadBodySchema } from "@suaveplan/api-plugin-file-upload";
import fc from "fast-check";

fc.assert(
    fc.property(
        fc.record({
            fileName: fc.string({ minLength: 1, maxLength: 255 }),
            totalSize: fc.integer({ min: 1, max: 1024 * 1024 * 1024 }),
            totalSha256: fc.hexaString({ minLength: 64, maxLength: 64 }),
        }),
        (input) => InitiateUploadBodySchema.safeParse(input).success
    ),
    { numRuns: 200 }
);

API Reference

InitiateUploadBodySchema — Zod schema for the request body.
InitiateUploadResponseSchema — Zod schema for the success response (uploadId, chunkSize, totalChunks).
InitiateUploadBody / InitiateUploadResponse — z.infer aliases.

Implementation Notes

The server intentionally trusts the client-declared totalSha256 only as a verification target — the actual hash is computed server-side from the assembled bytes. A mismatch surfaces as a 422 so clients can re-derive and retry without rebuilding the entire upload state.
chunkSize is server-bounded by defaultChunkSize to prevent pathological tiny-chunk attacks; the validator at the service layer caps client-supplied values.

2.2 KiB Raw Blame History

initiate.ts