error-codes

Purpose

Defines the structured error registry for @suaveplan/drive-plugin-chunks. Every chunk-format failure mode the plugin can produce is registered through defineCodes("CHUNKS", [...]) so that downstream consumers can branch on stable string codes ("CHUNKS.AEAD_TAG_INVALID", etc.) without parsing English-language error messages. The companion ChunksError class extends the project-wide SuaveplanError base so chunked-file errors compose with cause-chain traversal, redaction, and OTel span-event adapters defined in @suaveplan/error.

Features

Frozen CHUNKS_CODES enum-shaped constant covering the twelve failure classes that can occur during chunk encoding, signing, manifest exchange, layout selection, ingest, and inline-hint verification.
ChunksErrorCode literal union derived from CHUNKS_CODES so call sites stay type-safe.
ChunksError class with the SuaveplanError constructor signature widened to public, accepting (code, message, options?) plus the standard cause field.
Side-effect-safe registration via defineCodes so subpath consumers automatically see codes registered too.

Usage: Basic Example

import { CHUNKS_CODES, ChunksError } from "@suaveplan/drive-plugin-chunks";

throw new ChunksError(
    CHUNKS_CODES.AEAD_TAG_INVALID,
    "chunk AEAD tag verification failed"
);

Usage: Advanced Example

import { CHUNKS_CODES, ChunksError } from "@suaveplan/drive-plugin-chunks";

try {
    await chunks.ingest("photo.jpg");
} catch (err) {
    if (err instanceof ChunksError) {
        switch (err.code) {
            case CHUNKS_CODES.SIG_INVALID:
                return alertOps("server signing key drift");
            case CHUNKS_CODES.MANIFEST_NOT_FOUND:
                return rebuildManifest(err);
            default:
                throw new ChunksError(
                    CHUNKS_CODES.INGEST_FAILED,
                    "wrapped ingest failure",
                    { cause: err }
                );
        }
    }
    throw err;
}

API Reference

CHUNKS_CODES — Readonly<Record<string, string>> of "CHUNKS.<NAME>" strings.
ChunksErrorCode — string-literal union of every value in CHUNKS_CODES.
ChunksError — class ChunksError extends SuaveplanError<ChunksErrorCode> with constructor (code: ChunksErrorCode, message: string, options?: SuaveplanErrorOptions). Inherits name, code, message, cause, and the structured-redaction surface from SuaveplanError.

Implementation Notes

The twelve codes are deliberately narrow: each maps to one failure semantic (tag verification, signature verification, payload length mismatch, inline-hint signature failure, etc.) so monitoring dashboards can attach SLOs per code without redacting cardinality. INLINE_SIG_INVALID was added in DTP-25 to signal that an InlineHint failed Ed25519 verification against the drive's signing key over fileId ‖ bytes; legacy LegacyInlineHint shapes (no sig field) do not throw — they emit a drive:inline:legacy warning and trigger a rewrite-with-sig on next write.

3.0 KiB Raw Blame History