@bjornpagen/bumbledb-log 0.17.0 → 0.19.0

package/src/codec.ts

@@ -8,89 +8,141 @@
  */
 
 import * as errors from "@superbuilders/errors"
-import { ByteReader, ByteWriter, bytesEqual, fromHex, toHex, utf8Encoder } from "#bytes.ts"
-import type { LogTheory } from "#descriptor.ts"
+import type { Digest32 } from "#bytes.ts"
+import { ByteReader, ByteWriter, bytesEqual, digest32, hex32, utf8Encoder } from "#bytes.ts"
+import type { Braid, Theory } from "#descriptor.ts"
 import { braidHex, descriptorOf } from "#descriptor.ts"
 import { refuse, refuseChain } from "#errors.ts"
-import type { LogValue, TaggedRefusal } from "#value.ts"
-import { readTagged, writeTagged } from "#value.ts"
+import type { Generation } from "#keys.ts"
+import { generation } from "#keys.ts"
+import type { TaggedRefusal, Value } from "#value.ts"
+import { checkAgainst, readTagged, writeTagged } from "#value.ts"
 
 const MAGIC = utf8Encoder.encode("BDBL")
-const VERSION = 2
+const VERSION = 3
 const OP_KIND = { insert: 1, delete: 2 } as const
+const U32_MAX = 0xffffffffn
 
-interface BatchOp {
+interface Op {
 	readonly op: "insert" | "delete"
 	readonly relation: string
-	readonly rows: ReadonlyArray<readonly LogValue[]>
+	readonly rows: ReadonlyArray<readonly Value[]>
 }
 
 interface BatchHeader {
-	readonly fingerprint: string
-	readonly braid: string
-	readonly braidGen: bigint
-	readonly prev: string
+	readonly fingerprint: Digest32
+	readonly braid: Braid
+	readonly braidGen: Generation
+	readonly prev: Digest32
+	readonly writer: bigint
+	readonly timestamp: bigint
+}
+
+/**
+ * Encode input. Digest fields are raw bytes so a short `prev` reaches
+ * the named `DigestWidth` refuse at this gate instead of dying at
+ * `Digest32` construction. Decode still produces a branded
+ * `BatchHeader`.
+ */
+interface EncodeHeader {
+	readonly fingerprint: Uint8Array
+	readonly braid: Braid
+	readonly braidGen: Generation
+	readonly prev: Uint8Array
 	readonly writer: bigint
 	readonly timestamp: bigint
 }
 
 interface DecodedBatch {
 	readonly header: BatchHeader
-	readonly ops: readonly BatchOp[]
+	readonly ops: readonly Op[]
 }
 
-function braidIdOf(braid: string): number {
-	const match = /^c([0-9a-f]{8})$/.exec(braid)
-	if (match === null || match[1] === undefined) {
-		throw errors.new(`not a braid id: ${braid}`)
-	}
-	return Number.parseInt(match[1], 16)
+function braidIdOf(id: Braid): number {
+	return Number.parseInt(id.slice(1), 16)
 }
 
 /**
- * Encodes one batch. The header's `braid_gen` must equal the slot number
- * the object is published under; every op relation must belong to the
- * header's braid — a spanning batch is unencodable.
+ * Encodes one batch. Digests are branded here: a `prev` or fingerprint
+ * that is not 32 bytes is `DigestWidth`. The header's `braid_gen` must
+ * equal the slot number the object is published under; every op
+ * relation must belong to the header's braid — a spanning batch is
+ * unencodable.
  */
-function encodeBatch(theory: LogTheory, header: BatchHeader, ops: readonly BatchOp[]): Uint8Array {
+function encodeBatch(theory: Theory, header: EncodeHeader, ops: readonly Op[]): Uint8Array {
 	const descriptor = descriptorOf(theory)
-	if (header.fingerprint !== descriptor.fingerprint) {
-		throw errors.new(`encode fingerprint ${header.fingerprint} is not the descriptor's ${descriptor.fingerprint}`)
+	const fingerprint = asDigest(header.fingerprint, "fingerprint")
+	const prev = asDigest(header.prev, "prev")
+	if (!bytesEqual(fingerprint, descriptor.fingerprintBytes)) {
+		throw errors.new(`encode fingerprint ${hex32(fingerprint)} is not the descriptor's ${descriptor.fingerprint}`)
 	}
 	const braidId = braidIdOf(header.braid)
 	const members = descriptor.braidMembers.get(header.braid)
 	if (members === undefined) {
 		throw errors.new(`braid ${header.braid} is not derived from this descriptor`)
 	}
-	for (const op of ops) {
+	for (const [opIndex, op] of ops.entries()) {
 		const relation = descriptor.relationByName.get(op.relation)
 		if (relation === undefined) {
 			throw errors.new(`op cites unknown relation ${op.relation}`)
 		}
+		if (relation.closed) {
+			refuse(
+				{ kind: "ClosedRelation", op: opIndex, relation: relation.id },
+				`op ${opIndex} writes closed relation ${relation.name}`
+			)
+		}
 		if (!members.includes(relation.id)) {
 			throw errors.new(`op relation ${op.relation} is outside braid ${header.braid} — a spanning batch is unencodable`)
 		}
+		for (const [rowIndex, row] of op.rows.entries()) {
+			if (row.length !== relation.fields.length) {
+				refuse(
+					{ kind: "Arity", op: opIndex, relation: relation.name, row: rowIndex },
+					`op ${opIndex} relation ${relation.name} row ${rowIndex} arity ${row.length} ≠ ${relation.fields.length}`
+				)
+			}
+			relation.fields.forEach(function gateCell(field, ordinal) {
+				const value = row[ordinal]
+				if (value === undefined) {
+					refuse(
+						{ kind: "Arity", op: opIndex, relation: relation.name, row: rowIndex },
+						`op ${opIndex} relation ${relation.name} row ${rowIndex} cell ${ordinal} absent`
+					)
+				}
+				checkAgainst(`relation ${relation.name} field ${field.name}`, field.type, value)
+			})
+		}
+	}
+
+	const opCount = BigInt(ops.length)
+	if (opCount > U32_MAX) {
+		throw errors.new(`encode op count ${opCount} exceeds u32`)
 	}
 
 	const out = new ByteWriter(4096)
 	out.bytes(MAGIC)
 	out.u16le(VERSION)
 	out.u16le(0)
-	out.bytes(fromHex(header.fingerprint))
+	out.bytes(fingerprint)
 	out.u32le(braidId)
 	out.u64le(header.braidGen)
-	out.bytes(fromHex(header.prev))
+	out.bytes(prev)
 	out.u64le(header.writer)
 	out.u64le(header.timestamp)
-	out.u32le(ops.length)
+	out.u32le(Number(opCount))
 	for (const op of ops) {
 		const relation = descriptor.relationByName.get(op.relation)
 		if (relation === undefined) {
 			throw errors.new(`op cites unknown relation ${op.relation}`)
 		}
+		const rowCount = BigInt(op.rows.length)
+		if (rowCount > U32_MAX) {
+			throw errors.new(`encode row count ${rowCount} exceeds u32`)
+		}
 		out.u8(OP_KIND[op.op])
 		out.u32le(relation.id)
-		out.u32le(op.rows.length)
+		out.u32le(Number(rowCount))
 		for (const row of op.rows) {
 			relation.fields.forEach(function writeCell(field, ordinal) {
 				const value = row[ordinal]
@@ -104,8 +156,36 @@ function encodeBatch(theory: LogTheory, header: BatchHeader, ops: readonly Batch
 	return out.finish()
 }
 
+function asDigest(bytes: Uint8Array, at: string): Digest32 {
+	if (bytes.length !== 32) {
+		refuse({ kind: "DigestWidth" }, `${at} is not 32 bytes`)
+	}
+	return digest32(bytes)
+}
+
+function readU32(reader: ByteReader, what: string): bigint {
+	return BigInt(reader.u32le(what))
+}
+
+/** Kind + relation id + row count: the shortest op the grammar admits. */
+const MIN_OP_BYTES = 9n
+
+/** A declared count the remaining bytes cannot open is Truncated
+ *  before the loop. Counts are exact bigint so a u32::MAX row vector
+ *  cannot wrap a JavaScript number. A zero-field relation has no row
+ *  bytes. A nonempty layout uses one tag byte so a first-cell typed
+ *  refusal is not swallowed. */
+function refuseUnbacked(count: bigint, remaining: number, minItem: bigint, at: string): void {
+	if (count === 0n) {
+		return
+	}
+	if (minItem === 0n || BigInt(remaining) / minItem < count) {
+		refuse({ kind: "Truncated", at }, `declared ${at} ${count} outruns the remaining ${remaining} bytes`)
+	}
+}
+
 /** Full parse of a batch object; refusals are typed, never partial reads. */
-function decodeBatch(theory: LogTheory, bytes: Uint8Array): DecodedBatch {
+function decodeBatch(theory: Theory, bytes: Uint8Array): DecodedBatch {
 	const descriptor = descriptorOf(theory)
 	const reader = new ByteReader(bytes, {
 		fail(what: string): never {
@@ -125,10 +205,10 @@ function decodeBatch(theory: LogTheory, bytes: Uint8Array): DecodedBatch {
 	if (flags !== 0) {
 		refuse({ kind: "Flags", flags }, `batch flags ${flags} must be 0`)
 	}
-	const fingerprint = toHex(reader.bytes(32, "fingerprint"))
-	if (fingerprint !== descriptor.fingerprint) {
+	const fingerprint = digest32(reader.bytes(32, "fingerprint"))
+	if (!bytesEqual(fingerprint, descriptor.fingerprintBytes)) {
 		refuse(
-			{ kind: "FingerprintMismatch", carried: fingerprint, expected: descriptor.fingerprint },
+			{ kind: "FingerprintMismatch", carried: hex32(fingerprint), expected: descriptor.fingerprint },
 			"batch fingerprint does not match the descriptor"
 		)
 	}
@@ -138,48 +218,47 @@ function decodeBatch(theory: LogTheory, bytes: Uint8Array): DecodedBatch {
 	if (members === undefined) {
 		refuse({ kind: "UnknownBraid", braid: braidId }, `batch braid ${braid} is not derived from this descriptor`)
 	}
-	const braidGen = reader.u64le("braid generation")
-	const prev = toHex(reader.bytes(32, "prev"))
+	const braidGen = generation(reader.u64le("braid generation"))
+	const prev = digest32(reader.bytes(32, "prev"))
 	const writer = reader.u64le("writer")
 	const timestamp = reader.u64le("timestamp")
 
-	const opCount = reader.u32le("op count")
-	const ops: BatchOp[] = []
-	for (let opIndex = 0; opIndex < opCount; opIndex++) {
+	const opCount = readU32(reader, "op count")
+	refuseUnbacked(opCount, reader.remaining(), MIN_OP_BYTES, "op count")
+	const ops: Op[] = []
+	for (let opIndex = 0n; opIndex < opCount; opIndex++) {
+		const op = Number(opIndex)
 		const kind = reader.u8("op kind")
 		if (kind !== OP_KIND.insert && kind !== OP_KIND.delete) {
 			refuse(
-				{ kind: "UnknownOpKind", op: opIndex, opKind: kind },
-				`op ${opIndex} kind ${kind} is unknown (3 was deleted with floor bumps)`
+				{ kind: "UnknownOpKind", op, opKind: kind },
+				`op ${op} kind ${kind} is unknown (3 was deleted with floor bumps)`
 			)
 		}
 		const relationId = reader.u32le("op relation")
 		const relation = descriptor.relations[relationId]
 		if (relation === undefined) {
-			refuse(
-				{ kind: "UnknownRelation", op: opIndex, relation: relationId },
-				`op ${opIndex} cites unknown relation ${relationId}`
-			)
+			refuse({ kind: "UnknownRelation", op, relation: relationId }, `op ${op} cites unknown relation ${relationId}`)
 		}
 		if (relation.closed) {
-			refuse(
-				{ kind: "ClosedRelation", op: opIndex, relation: relationId },
-				`op ${opIndex} writes closed relation ${relation.name}`
-			)
+			refuse({ kind: "ClosedRelation", op, relation: relationId }, `op ${op} writes closed relation ${relation.name}`)
 		}
 		if (!members.includes(relationId)) {
 			refuse(
-				{ kind: "OpRelationOutsideBraid", op: opIndex, relation: relationId, braid },
-				`op ${opIndex} relation ${relation.name} is outside braid ${braid}`
+				{ kind: "OpRelationOutsideBraid", op, relation: relationId, braid },
+				`op ${op} relation ${relation.name} is outside braid ${braid}`
 			)
 		}
-		const rowCount = reader.u32le("row count")
-		const rows: LogValue[][] = []
-		for (let rowIndex = 0; rowIndex < rowCount; rowIndex++) {
-			const row: LogValue[] = []
+		const rowCount = readU32(reader, "row count")
+		const minRow = relation.fields.length === 0 ? 0n : 1n
+		refuseUnbacked(rowCount, reader.remaining(), minRow, "row count")
+		const rows: Value[][] = []
+		for (let rowIndex = 0n; rowIndex < rowCount; rowIndex++) {
+			const rowAt = Number(rowIndex)
+			const row: Value[] = []
 			relation.fields.forEach(function readCell(field) {
-				const at = { relation: relation.name, row: rowIndex, field: field.name }
-				const where = `relation ${relation.name} row ${rowIndex} field ${field.name}`
+				const at = { relation: relation.name, row: rowAt, field: field.name }
+				const where = `relation ${relation.name} row ${rowAt} field ${field.name}`
 				const refusal: TaggedRefusal = {
 					badTag(): never {
 						refuse({ kind: "TagMismatch", ...at }, `${where}: tag does not match the layout`)
@@ -217,9 +296,9 @@ function decodeBatch(theory: LogTheory, bytes: Uint8Array): DecodedBatch {
 	}
 }
 
-interface ChainPosition {
-	readonly g: bigint
-	readonly prev: string
+interface ChainEntry {
+	readonly g: Generation
+	readonly prev: Digest32
 	readonly ts: bigint
 }
 
@@ -231,14 +310,14 @@ interface ChainPosition {
  * names the misbehaving writer, and the refusal data names the fetched
  * braid.
  */
-function verifyChain(header: BatchHeader, braid: string, slot: bigint, chain: ChainPosition): void {
+function verifyChain(header: BatchHeader, braid: Braid, slot: Generation, chain: ChainEntry): void {
 	if (header.braid !== braid || header.braidGen !== slot) {
 		refuseChain(
 			{ cause: "slot", braid, slot, writer: header.writer },
 			`braid ${braid}: header slot identity ${header.braid}/${header.braidGen} ≠ the fetched key's ${braid}/${slot}`
 		)
 	}
-	if (header.prev !== chain.prev) {
+	if (!bytesEqual(header.prev, chain.prev)) {
 		refuseChain(
 			{ cause: "prev", braid, slot, writer: header.writer },
 			`braid ${braid} slot ${slot}: prev does not cite the predecessor`
@@ -252,5 +331,5 @@ function verifyChain(header: BatchHeader, braid: string, slot: bigint, chain: Ch
 	}
 }
 
-export type { BatchHeader, BatchOp, ChainPosition, DecodedBatch }
+export type { BatchHeader, ChainEntry, DecodedBatch, Digest32, EncodeHeader, Op }
 export { decodeBatch, encodeBatch, verifyChain }