envelope.schema

(no submodules)

Purpose

Defines every Zod boundary schema the codec modules invoke before letting payload bytes touch protocol logic, plus the frozen numeric constants the spec pins (MAX_CHUNKS_DEFAULT, MAX_CHUNKS_HARD_CAP, SAMPLE_RATE_HEALTHY, SAMPLE_RATE_SUSPECT, TRUST_SUSPECT_THRESHOLD, TRUST_MISS_RATE_FLOOR, TRUST_DECAY_SLOPE, ADVERTISE_THROTTLE_MS_DEFAULT, ADVERTISE_THROTTLE_MS_MAX, GENERATION_WRAP_THRESHOLD, SELECT_FORM_BITSET_THRESHOLD). Centralising the schemas + constants keeps every codec / trust / generation module branchless against ad-hoc magic numbers.

Features

FileIdSchema — hex string, 1–128 chars ([0-9a-f]+).
ChunkRequestSchema — discriminated union (whole / specific / bitset).
ChunkRequestPayloadSchema, ChunkAdvertisePayloadSchema, ChunkResponsePayloadSchema, ChunkErrorPayloadSchema, ChunkBytesSchema, ChunkRequestPrioritySchema, ChunkErrorCodeSchema.
Numeric constants documented inline so monitoring dashboards can reference the same source-of-truth as the codec.

Usage: Basic Example

import {
    ChunkRequestPayloadSchema,
    MAX_CHUNKS_HARD_CAP,
} from "@suaveplan/drive-mesh-protocol";

const result = ChunkRequestPayloadSchema.safeParse(unknownInput);
if (!result.success) throw new Error(result.error.message);
const payload = result.data;
console.log(MAX_CHUNKS_HARD_CAP); // 1024

Usage: Advanced Example

import {
    ChunkAdvertisePayloadSchema,
    ChunkErrorCodeSchema,
    SELECT_FORM_BITSET_THRESHOLD,
    TRUST_SUSPECT_THRESHOLD,
} from "@suaveplan/drive-mesh-protocol";

function isSuspectScore(score: number): boolean {
    return score < TRUST_SUSPECT_THRESHOLD;
}

function pickForm(needed: number[]) {
    return needed.length <= SELECT_FORM_BITSET_THRESHOLD
        ? "specific"
        : "bitset";
}

const allErrorCodes = ChunkErrorCodeSchema.options;

API Reference

Schemas: FileIdSchema, ChunkRequestPrioritySchema, ChunkRequestSchema, ChunkRequestPayloadSchema, ChunkAdvertisePayloadSchema, ChunkBytesSchema, ChunkResponsePayloadSchema, ChunkErrorCodeSchema, ChunkErrorPayloadSchema.
Numeric constants: MAX_CHUNKS_DEFAULT (64), MAX_CHUNKS_HARD_CAP (1024), SELECT_FORM_BITSET_THRESHOLD (64), SAMPLE_RATE_HEALTHY (100), SAMPLE_RATE_SUSPECT (10), TRUST_SUSPECT_THRESHOLD (0.95), TRUST_MISS_RATE_FLOOR (0.05), TRUST_DECAY_SLOPE (20), ADVERTISE_THROTTLE_MS_DEFAULT (1000), ADVERTISE_THROTTLE_MS_MAX (60000), GENERATION_WRAP_THRESHOLD (2³¹).

Implementation Notes

The chunkIds array on kind:'specific' is intentionally permissive (no .min(1)) so the explicit DMP-03 / DMP-22 gates in the codec (which throw DMP.EMPTY_REQUEST) are reachable. The maxChunks check is lower-bound only at the schema layer; the upper-bound DMP-07 enforcement lives in the codec so the failure carries the spec-mandated DMP.MAX_CHUNKS_EXCEEDED code rather than a generic DMP.ENVELOPE_MALFORMED. // schema: boundary-only annotations on the priority enum suppress the conformance-script warning about consumer-facing schemas that aren't reflected internally.

3.1 KiB Raw Blame History Unescape Escape