`status.ts`

Purpose

Defines the path-parameter and response shapes for the remaining chunked-upload routes: PUT /uploads/{uploadId}/chunks/{chunkIndex}, POST /uploads/{uploadId}/complete, GET /uploads/{uploadId}, and DELETE /uploads/{uploadId}. The status response is the resume contract: clients call GET after a crash and pick up from the next missing chunk.

Features

ChunkParamsSchema constrains chunkIndex to a non-negative integer via regex — invalid values reject at the boundary so the handler never sees malformed paths.
CompleteUploadBodySchema allows an optional totalSha256 override for clients that recomputed the hash mid-flight.
UploadStatusResponseSchema exposes a discriminated state literal so consumers can switch on "in-progress" vs "complete" without ambiguity.

Usage: Basic

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

const status = UploadStatusResponseSchema.parse(await response.json());
const missing: number[] = [];
for (let i = 0; i < status.totalChunks; i++) {
    if (!status.receivedChunks.includes(i)) missing.push(i);
}

Usage: Advanced

import {
    ChunkParamsSchema,
    UploadStatusResponseSchema,
} from "@suaveplan/api-plugin-file-upload";

async function resume(uploadId: string, fetchFn: typeof fetch) {
    const status = UploadStatusResponseSchema.parse(
        await (await fetchFn(`/uploads/${uploadId}`)).json()
    );
    if (status.state === "complete") return;
    for (let i = 0; i < status.totalChunks; i++) {
        if (status.receivedChunks.includes(i)) continue;
        const params = ChunkParamsSchema.parse({
            uploadId,
            chunkIndex: String(i),
        });
        await uploadChunk(params, sliceFor(i));
    }
}

API Reference

UploadIdParamsSchema — path parameter { uploadId }.
ChunkParamsSchema — path parameter { uploadId, chunkIndex }.
CompleteUploadBodySchema — optional body with totalSha256 override; defaults to {} when omitted.
UploadStatusResponseSchema — { uploadId, totalChunks, receivedChunks, state }.
AppendChunkResponseSchema — { uploadId, chunkIndex, receivedChunks } (the count, not the set).

Implementation Notes

chunkIndex is a string in the params (URL paths are strings) and parsed to a number in the handler — the schema enforces only that the path segment is decimal-digit-only.
The status response returns receivedChunks as an array, not a set, so it serialises cleanly through JSON; clients reconstruct the set if needed.

2.6 KiB Raw Permalink Blame History

status.ts