chunk-verifier-validator

Purpose

Bridges the structural ChunkVerifier shape from @suaveplan/packer into the canonical ChunkValidator strategy. The packer's verifier returns a discriminated result ({ ok: true, metadata } or { ok: false, code, message }); this adapter coerces the failure branch into the canonical StreamsChunkQueueError(VALIDATION_FAILED) with the packer's diagnostic preserved in context.verifierCode.

Features

Accepts any structurally compatible verifier (ChunkVerifierLike), so adapter tests don't need a real packer instance.
Preserves the verifier's code + message inside the typed error's context for downstream observability.
Returns the input bytes unchanged on success — ChunkVerifier validates the wire frame but does not modify it.
Falls back to a sensible default code/message if the verifier omits them, keeping the contract uniform.

Usage: Basic

import { ChunkVerifier } from "@suaveplan/packer";
import { ChunkVerifierValidator } from "@suaveplan/streams-chunk-queue";

const verifier = new ChunkVerifier(serverPubKey);
const queue = new StreamingChunkQueue({
    fileId: 1n,
    totalChunks: 5n,
    validator: new ChunkVerifierValidator(verifier),
});

Usage: Advanced

import type { ChunkVerifierLike } from "@suaveplan/streams-chunk-queue";

const hsmVerifier: ChunkVerifierLike = {
    verify(bytes) {
        return hsmSignatureVerify(bytes)
            ? { ok: true }
            : { ok: false, code: "HSM.REJECTED", message: "HSM rejected" };
    },
};
const validator = new ChunkVerifierValidator(hsmVerifier);

API Reference

`ChunkVerifierLike`

interface ChunkVerifierLike {
    verify(bytes: Uint8Array): {
        ok: boolean;
        code?: string;
        message?: string;
    };
}

`ChunkVerifierValidator`

new ChunkVerifierValidator(verifier: ChunkVerifierLike)

Implements ChunkValidator. On ok: true returns { data: <input bytes> }. On ok: false rejects with StreamsChunkQueueError(VALIDATION_FAILED) whose context.chunkId is the offending chunk id and context.verifierCode carries the verifier's own code.

Implementation Notes

The adapter does not mutate data because ChunkVerifier.verify only checks the bytes — it does not strip a header. If a future verifier returns transformed bytes, the adapter contract can be extended without breaking callers (the success branch already returns { data }). The adapter is intentionally synchronous on the verifier side (the wrapper itself returns a Promise to satisfy the strategy interface), so a fast in-process verifier does not allocate an extra microtask. The structural typing of ChunkVerifierLike means hardware-backed verifiers, mock test verifiers, and the real packer class are all interchangeable.

2.8 KiB Raw Blame History