1pub mod view;
9
10use hara_abi::{ExceptionProvenance, ExceptionSite, ImmutableValue as Value, Value as AbiValue};
11use std::collections::BTreeMap;
12
13pub const MAGIC: &[u8; 4] = b"HTA0";
14pub const MAX_FRAME_BYTES: usize = 64 * 1024 * 1024;
15pub const MAX_NESTING_DEPTH: usize = 256;
16
17const NIL: u8 = 0;
18const FALSE: u8 = 1;
19const TRUE: u8 = 2;
20const I64: u8 = 3;
21const STRING: u8 = 4;
22const BYTES: u8 = 5;
23const KEYWORD: u8 = 6;
24const SYMBOL: u8 = 7;
25const LIST: u8 = 8;
26const VECTOR: u8 = 9;
27const SET: u8 = 10;
28const MAP: u8 = 11;
29const HANDLE: u8 = 12;
30const NAMESPACE: u8 = 13;
31const VAR: u8 = 14;
32const F64: u8 = 15;
33const ATOM: u8 = 16;
34const ARRAY: u8 = 17;
35const OBJECT: u8 = 18;
36const CHARACTER: u8 = 19;
37const BIG_INTEGER: u8 = 20;
38const REGEX: u8 = 22;
39const TUPLE: u8 = 23;
40const MAP_ENTRY: u8 = 38;
41const CONS: u8 = 24;
42const QUEUE: u8 = 25;
43const ORDERED_MAP: u8 = 26;
44const SORTED_MAP: u8 = 27;
45const TRIE: u8 = 28;
46const ORDERED_SET: u8 = 29;
47const SORTED_SET: u8 = 30;
48const TAGGED: u8 = 31;
49const EXCEPTION_INFO: u8 = 32;
50const STRUCT: u8 = 33;
51const POINTER: u8 = 34;
52const VAR_REF: u8 = 35;
53
54fn provenance_value(provenance: &ExceptionProvenance) -> Value {
55 let mut fields = BTreeMap::new();
56 fields.insert(
57 "ex/created-at".into(),
58 provenance
59 .created_at
60 .as_ref()
61 .map(site_value)
62 .unwrap_or(Value::Nil),
63 );
64 fields.insert(
65 "ex/throws".into(),
66 Value::Vector(provenance.throws.iter().map(site_value).collect()),
67 );
68 Value::Record(fields)
69}
70
71fn site_value(site: &ExceptionSite) -> Value {
72 let mut fields = BTreeMap::new();
73 fields.insert(
74 "namespace".into(),
75 site.namespace
76 .clone()
77 .map(Value::String)
78 .unwrap_or(Value::Nil),
79 );
80 fields.insert(
81 "resource".into(),
82 site.resource
83 .clone()
84 .map(Value::String)
85 .unwrap_or(Value::Nil),
86 );
87 fields.insert("line".into(), Value::Integer(site.line as i64));
88 fields.insert("column".into(), Value::Integer(site.column as i64));
89 Value::Record(fields)
90}
91
92fn decode_provenance(value: Value) -> Result<ExceptionProvenance, String> {
93 let Value::Record(fields) = value else {
94 return Err("hta/value-malformed: invalid exception provenance".into());
95 };
96 if fields.len() != 2
97 || !fields.contains_key("ex/created-at")
98 || !fields.contains_key("ex/throws")
99 {
100 return Err("hta/value-malformed: invalid exception provenance fields".into());
101 }
102 let created_at = match fields.get("ex/created-at").expect("checked above") {
103 Value::Nil => None,
104 value => Some(decode_site(value)?),
105 };
106 let Value::Vector(throws) = fields.get("ex/throws").expect("checked above") else {
107 return Err("hta/value-malformed: invalid exception throws provenance".into());
108 };
109 Ok(ExceptionProvenance {
110 created_at,
111 throws: throws.iter().map(decode_site).collect::<Result<_, _>>()?,
112 })
113}
114
115fn decode_site(value: &Value) -> Result<ExceptionSite, String> {
116 let Value::Record(fields) = value else {
117 return Err("hta/value-malformed: invalid exception provenance site".into());
118 };
119 if fields.len() != 4
120 || !fields.contains_key("namespace")
121 || !fields.contains_key("resource")
122 || !fields.contains_key("line")
123 || !fields.contains_key("column")
124 {
125 return Err("hta/value-malformed: invalid exception provenance site".into());
126 }
127 let optional_string = |name: &str| match fields.get(name).expect("checked above") {
128 Value::Nil => Ok(None),
129 Value::String(value) => Ok(Some(value.clone())),
130 _ => Err(format!(
131 "hta/value-malformed: invalid exception provenance {name}"
132 )),
133 };
134 let nonnegative = |name: &str| match fields.get(name).expect("checked above") {
135 Value::Integer(value) if *value >= 0 => Ok(*value as u64),
136 _ => Err(format!(
137 "hta/value-malformed: invalid exception provenance {name}"
138 )),
139 };
140 Ok(ExceptionSite {
141 namespace: optional_string("namespace")?,
142 resource: optional_string("resource")?,
143 line: nonnegative("line")?,
144 column: nonnegative("column")?,
145 })
146}
147
148pub fn encode_immutable(value: &Value) -> Result<Vec<u8>, String> {
150 let mut output = Vec::with_capacity(128);
151 write(&mut output, MAGIC)?;
152 encode_value(value, 0, &mut output)?;
153 Ok(output)
154}
155
156pub fn decode_immutable(bytes: &[u8]) -> Result<Value, String> {
163 if bytes.len() > MAX_FRAME_BYTES {
164 return Err(format!(
165 "hta/frame-too-large: {} exceeds {} bytes",
166 bytes.len(),
167 MAX_FRAME_BYTES
168 ));
169 }
170 if !bytes.starts_with(MAGIC) {
171 return Err("hta/frame-invalid: expected HTA0 magic".into());
172 }
173 let mut reader = Reader {
174 bytes: &bytes[MAGIC.len()..],
175 cursor: 0,
176 };
177 let value = reader.value(0)?;
178 if reader.cursor != reader.bytes.len() {
179 return Err("hta/frame-invalid: trailing bytes".into());
180 }
181 Ok(value)
182}
183
184pub fn decode_immutable_canonical(bytes: &[u8], max_bytes: usize) -> Result<Value, String> {
191 if max_bytes == 0 || max_bytes > MAX_FRAME_BYTES {
192 return Err(format!(
193 "hta/maximum-invalid: requested maximum must be between 1 and {MAX_FRAME_BYTES} bytes"
194 ));
195 }
196 if bytes.len() > max_bytes {
197 return Err(format!(
198 "hta/frame-too-large: {} exceeds requested maximum {} bytes",
199 bytes.len(),
200 max_bytes
201 ));
202 }
203
204 let value = decode_immutable(bytes)?;
205 let canonical = encode_immutable(&value)?;
206 if canonical != bytes {
207 return Err("hta/frame-noncanonical: decoded value has different canonical bytes".into());
208 }
209 Ok(value)
210}
211
212pub fn encode(value: &AbiValue) -> Result<Vec<u8>, String> {
214 encode_immutable(&abi_to_immutable(value)?)
215}
216
217pub fn decode(bytes: &[u8]) -> Result<AbiValue, String> {
219 immutable_to_abi(decode_immutable(bytes)?)
220}
221
222pub fn decode_canonical(bytes: &[u8], max_bytes: usize) -> Result<AbiValue, String> {
223 immutable_to_abi(decode_immutable_canonical(bytes, max_bytes)?)
224}
225
226pub(crate) fn canonical_big_integer(value: &str) -> Result<Value, String> {
227 let (negative, digits) = match value.strip_prefix('-') {
228 Some(digits) => (true, digits),
229 None => (false, value),
230 };
231 if digits.is_empty() || !digits.bytes().all(|byte| byte.is_ascii_digit()) {
232 return Err("hta/value-malformed: invalid big integer".into());
233 }
234 let digits = digits.trim_start_matches('0');
235 let digits = if digits.is_empty() { "0" } else { digits };
236 let canonical = if negative && digits != "0" {
237 format!("-{digits}")
238 } else {
239 digits.to_owned()
240 };
241 match canonical.parse::<i64>() {
242 Ok(value) => Ok(Value::Integer(value)),
243 Err(_) => Ok(Value::BigInteger(canonical)),
244 }
245}
246
247pub(crate) fn validate_canonical_big_integer(value: &str) -> Result<(), String> {
248 match canonical_big_integer(value)? {
249 Value::BigInteger(canonical) if canonical == value => Ok(()),
250 Value::BigInteger(_) => {
251 Err("hta/value-noncanonical: big integer text is not canonical".into())
252 }
253 Value::Integer(_) => {
254 Err("hta/value-noncanonical: signed 64-bit integers use the i64 tag".into())
255 }
256 _ => unreachable!("canonical big integer returned a non-integer value"),
257 }
258}
259
260fn abi_to_immutable(value: &AbiValue) -> Result<Value, String> {
261 Ok(match value {
262 AbiValue::Nil => Value::Nil,
263 AbiValue::Boolean(value) => Value::Boolean(*value),
264 AbiValue::String(value) => Value::String(value.clone()),
265 AbiValue::Integer(value) => Value::Integer(*value),
266 AbiValue::BigInteger(value) => canonical_big_integer(value)?,
267 AbiValue::Float(value) => {
268 if !value.is_finite() {
269 return Err("hta/non-finite number".into());
270 }
271 Value::Float(*value)
272 }
273 AbiValue::Bytes(value) => Value::Bytes(value.clone()),
274 AbiValue::Keyword(value) => Value::Keyword(value.clone()),
275 AbiValue::Vector(values) => Value::Vector(
276 values
277 .iter()
278 .map(abi_to_immutable)
279 .collect::<Result<Vec<_>, _>>()?,
280 ),
281 AbiValue::Record(values) => Value::Record(
282 values
283 .iter()
284 .map(|(key, value)| Ok((key.clone(), abi_to_immutable(value)?)))
285 .collect::<Result<_, String>>()?,
286 ),
287 })
288}
289
290fn immutable_to_abi(value: Value) -> Result<AbiValue, String> {
291 Ok(match value {
292 Value::Nil => AbiValue::Nil,
293 Value::Boolean(value) => AbiValue::Boolean(value),
294 Value::String(value) => AbiValue::String(value),
295 Value::Integer(value) => AbiValue::Integer(value),
296 Value::BigInteger(value) => match canonical_big_integer(&value)? {
297 Value::Integer(value) => AbiValue::Integer(value),
298 Value::BigInteger(value) => AbiValue::BigInteger(value),
299 _ => unreachable!("canonical big integer returned a non-integer value"),
300 },
301 Value::Float(value) => {
302 if !value.is_finite() {
303 return Err("hta/non-finite number".into());
304 }
305 AbiValue::Float(value)
306 }
307 Value::Bytes(value) => AbiValue::Bytes(value),
308 Value::Keyword(value) => AbiValue::Keyword(value),
309 Value::Vector(values) => AbiValue::Vector(
310 values
311 .into_iter()
312 .map(immutable_to_abi)
313 .collect::<Result<Vec<_>, _>>()?,
314 ),
315 Value::Record(values) => AbiValue::Record(
316 values
317 .into_iter()
318 .map(|(key, value)| Ok((key, immutable_to_abi(value)?)))
319 .collect::<Result<_, String>>()?,
320 ),
321 value => {
322 return Err(format!(
323 "hta/value-unsupported: immutable value is outside the provider ABI: {value:?}"
324 ))
325 }
326 })
327}
328
329fn encode_value(value: &Value, depth: usize, output: &mut Vec<u8>) -> Result<(), String> {
330 if depth > MAX_NESTING_DEPTH {
331 return Err("hta/value-too-deep".into());
332 }
333 match value {
334 Value::Nil => push(output, NIL),
335 Value::Boolean(false) => push(output, FALSE),
336 Value::Boolean(true) => push(output, TRUE),
337 Value::Integer(value) => {
338 push(output, I64)?;
339 write(output, &value.to_be_bytes())
340 }
341 Value::Float(value) => {
342 if !value.is_finite() {
343 return Err("hta/non-finite number".into());
344 }
345 push(output, F64)?;
346 write(output, &value.to_bits().to_be_bytes())
347 }
348 Value::Character(value) => {
349 push(output, CHARACTER)?;
350 write(output, &u32::from(*value).to_be_bytes())
351 }
352 Value::BigInteger(value) => match canonical_big_integer(value)? {
353 Value::Integer(value) => {
354 push(output, I64)?;
355 write(output, &value.to_be_bytes())
356 }
357 Value::BigInteger(value) => write_sized(output, BIG_INTEGER, value.as_bytes()),
358 _ => unreachable!("canonical big integer returned a non-integer value"),
359 },
360 Value::String(value) => write_sized(output, STRING, value.as_bytes()),
361 Value::Bytes(value) => write_sized(output, BYTES, value),
362 Value::Keyword(value) => write_sized(output, KEYWORD, value.as_bytes()),
363 Value::Regex(value) => write_sized(output, REGEX, value.as_bytes()),
364 Value::Symbol(value) => write_sized(output, SYMBOL, value.as_bytes()),
365 Value::List(values) => encode_sequence(LIST, values, depth, output),
366 Value::Vector(values) => encode_sequence(VECTOR, values, depth, output),
367 Value::MapEntry(values) => encode_map_entry(values, depth, output),
368 Value::Tuple(values) => encode_sequence(VECTOR, values, depth, output),
369 Value::Cons(values) => encode_sequence(CONS, values, depth, output),
370 Value::Queue(values) => encode_sequence(QUEUE, values, depth, output),
371 Value::Set(values) => encode_unordered_sequence(SET, values, depth, output),
372 Value::OrderedSet(values) => encode_sequence(ORDERED_SET, values, depth, output),
373 Value::SortedSet(values) => encode_unordered_sequence(SORTED_SET, values, depth, output),
374 Value::Map(values) => encode_map(MAP, values, depth, output, true),
375 Value::OrderedMap(values) => encode_map(ORDERED_MAP, values, depth, output, false),
376 Value::SortedMap(values) => encode_map(SORTED_MAP, values, depth, output, false),
377 Value::Trie(values) => {
378 let entries = values
379 .iter()
380 .map(|(key, value)| (Value::String(key.clone()), value.clone()))
381 .collect::<Vec<_>>();
382 encode_map(TRIE, &entries, depth, output, false)
383 }
384 Value::Record(values) => encode_record(values, depth, output),
385 Value::Tagged { tag, form } => {
386 push(output, TAGGED)?;
387 encode_value(&Value::Symbol(tag.clone()), depth + 1, output)?;
388 encode_value(form, depth + 1, output)
389 }
390 Value::ExceptionInfo {
391 message,
392 data,
393 cause,
394 provenance,
395 } => {
396 if !matches!(data.as_ref(), Value::Map(_) | Value::Record(_)) {
397 return Err("hta/value-invalid: exception data must be a map".into());
398 }
399 if cause
400 .as_ref()
401 .is_some_and(|cause| !matches!(cause.as_ref(), Value::ExceptionInfo { .. }))
402 {
403 return Err("hta/value-invalid: exception cause must be an Exception".into());
404 }
405 push(output, EXCEPTION_INFO)?;
406 encode_value(&Value::String(message.clone()), depth + 1, output)?;
407 encode_value(data, depth + 1, output)?;
408 encode_value(cause.as_deref().unwrap_or(&Value::Nil), depth + 1, output)?;
409 encode_value(&provenance_value(provenance), depth + 1, output)
410 }
411 Value::Struct {
412 name,
413 fields,
414 values,
415 } => {
416 if fields.len() != values.len() {
417 return Err("hta/value-invalid: struct arity mismatch".into());
418 }
419 push(output, STRUCT)?;
420 encode_value(&Value::String(name.clone()), depth + 1, output)?;
421 encode_value(
422 &Value::Vector(fields.iter().cloned().map(Value::String).collect()),
423 depth + 1,
424 output,
425 )?;
426 encode_value(&Value::Vector(values.clone()), depth + 1, output)
427 }
428 Value::Pointer { context, fields } => {
429 push(output, POINTER)?;
430 encode_value(&Value::Keyword(context.clone()), depth + 1, output)?;
431 encode_record(fields, depth + 1, output)
432 }
433 Value::VarRef(symbol) => {
434 push(output, VAR_REF)?;
435 encode_value(&Value::Symbol(symbol.clone()), depth + 1, output)
436 }
437 }
438}
439
440fn encode_sequence(
441 tag: u8,
442 values: &[Value],
443 depth: usize,
444 output: &mut Vec<u8>,
445) -> Result<(), String> {
446 push(output, tag)?;
447 write_len(output, values.len())?;
448 for value in values {
449 encode_value(value, depth + 1, output)?;
450 }
451 Ok(())
452}
453
454fn encode_map_entry(values: &[Value], depth: usize, output: &mut Vec<u8>) -> Result<(), String> {
455 if values.len() != 2 {
456 return Err("hta/value-invalid: map entry must contain two values".into());
457 }
458 encode_sequence(MAP_ENTRY, values, depth, output)
459}
460
461fn encode_unordered_sequence(
462 tag: u8,
463 values: &[Value],
464 depth: usize,
465 output: &mut Vec<u8>,
466) -> Result<(), String> {
467 let mut encoded = Vec::with_capacity(values.len());
468 for value in values {
469 let mut bytes = Vec::new();
470 encode_value(value, depth + 1, &mut bytes)?;
471 encoded.push(bytes);
472 }
473 encoded.sort();
474 encoded.dedup();
475 push(output, tag)?;
476 write_len(output, encoded.len())?;
477 for value in encoded {
478 write(output, &value)?;
479 }
480 Ok(())
481}
482
483fn encode_map(
484 tag: u8,
485 values: &[(Value, Value)],
486 depth: usize,
487 output: &mut Vec<u8>,
488 canonical_order: bool,
489) -> Result<(), String> {
490 let mut entries = Vec::with_capacity(values.len());
491 for (key, value) in values {
492 let mut key_bytes = Vec::new();
493 encode_value(key, depth + 1, &mut key_bytes)?;
494 let mut value_bytes = Vec::new();
495 encode_value(value, depth + 1, &mut value_bytes)?;
496 entries.push((key_bytes, value_bytes));
497 }
498 if canonical_order {
499 entries.sort_by(|left, right| left.0.cmp(&right.0));
500 }
501 for pair in entries.windows(2) {
502 if pair[0].0 == pair[1].0 {
503 return Err("hta/value-invalid: duplicate map key".into());
504 }
505 }
506 push(output, tag)?;
507 write_len(output, entries.len())?;
508 for (key, value) in entries {
509 write(output, &key)?;
510 write(output, &value)?;
511 }
512 Ok(())
513}
514
515fn encode_record(
516 values: &BTreeMap<String, Value>,
517 depth: usize,
518 output: &mut Vec<u8>,
519) -> Result<(), String> {
520 push(output, MAP)?;
521 write_len(output, values.len())?;
522
523 let mut entries = Vec::with_capacity(values.len());
524 for (key, value) in values {
525 let mut key_bytes = Vec::with_capacity(key.len() + 5);
526 encode_value(&Value::Keyword(key.clone()), depth + 1, &mut key_bytes)?;
527 let mut value_bytes = Vec::new();
528 encode_value(value, depth + 1, &mut value_bytes)?;
529 entries.push((key_bytes, value_bytes));
530 }
531 entries.sort_by(|left, right| left.0.cmp(&right.0));
532 for (key, value) in entries {
533 write(output, &key)?;
534 write(output, &value)?;
535 }
536 Ok(())
537}
538
539fn write_sized(output: &mut Vec<u8>, tag: u8, bytes: &[u8]) -> Result<(), String> {
540 push(output, tag)?;
541 write_len(output, bytes.len())?;
542 write(output, bytes)
543}
544
545fn write_len(output: &mut Vec<u8>, len: usize) -> Result<(), String> {
546 let len = u32::try_from(len)
547 .map_err(|_| "hta/value-too-large: container or scalar length exceeds u32".to_string())?;
548 write(output, &len.to_be_bytes())
549}
550
551fn push(output: &mut Vec<u8>, byte: u8) -> Result<(), String> {
552 write(output, &[byte])
553}
554
555fn write(output: &mut Vec<u8>, bytes: &[u8]) -> Result<(), String> {
556 let next = output
557 .len()
558 .checked_add(bytes.len())
559 .ok_or_else(|| "hta/frame-too-large: length overflow".to_string())?;
560 if next > MAX_FRAME_BYTES {
561 return Err(format!(
562 "hta/frame-too-large: encoded frame exceeds {} bytes",
563 MAX_FRAME_BYTES
564 ));
565 }
566 output.extend_from_slice(bytes);
567 Ok(())
568}
569
570struct Reader<'a> {
571 bytes: &'a [u8],
572 cursor: usize,
573}
574
575impl Reader<'_> {
576 fn value(&mut self, depth: usize) -> Result<Value, String> {
577 if depth > MAX_NESTING_DEPTH {
578 return Err("hta/value-too-deep".into());
579 }
580 match self.byte()? {
581 NIL => Ok(Value::Nil),
582 FALSE => Ok(Value::Boolean(false)),
583 TRUE => Ok(Value::Boolean(true)),
584 I64 => Ok(Value::Integer(i64::from_be_bytes(
585 self.take(8)?.try_into().expect("eight bytes"),
586 ))),
587 F64 => {
588 let value = f64::from_bits(u64::from_be_bytes(
589 self.take(8)?.try_into().expect("eight bytes"),
590 ));
591 if !value.is_finite() {
592 return Err("hta/non-finite number".into());
593 }
594 Ok(Value::Float(value))
595 }
596 CHARACTER => {
597 let scalar = u32::from_be_bytes(self.take(4)?.try_into().expect("four bytes"));
598 char::from_u32(scalar)
599 .map(Value::Character)
600 .ok_or_else(|| "hta/value-malformed: invalid character scalar".into())
601 }
602 STRING => Ok(Value::String(self.text()?)),
603 BYTES => Ok(Value::Bytes(self.sized()?.to_vec())),
604 KEYWORD => Ok(Value::Keyword(self.text()?)),
605 SYMBOL => Ok(Value::Symbol(self.text()?)),
606 BIG_INTEGER => canonical_big_integer(&self.text()?),
607 REGEX => Ok(Value::Regex(self.text()?)),
608 LIST => self.sequence(depth).map(Value::List),
609 VECTOR => self.vector(depth),
610 TUPLE => self.sequence(depth).map(Value::Tuple),
611 MAP_ENTRY => {
612 let values = self.sequence(depth)?;
613 if values.len() != 2 {
614 return Err("hta/value-malformed: map entry must contain two values".into());
615 }
616 Ok(Value::MapEntry(values))
617 }
618 CONS => {
619 let values = self.sequence(depth)?;
620 if values.is_empty() {
621 Err("hta/value-malformed: empty cons".into())
622 } else {
623 Ok(Value::Cons(values))
624 }
625 }
626 QUEUE => self.sequence(depth).map(Value::Queue),
627 SET => self.sequence(depth).map(Value::Set),
628 ORDERED_SET => self.sequence(depth).map(Value::OrderedSet),
629 SORTED_SET => self.sequence(depth).map(Value::SortedSet),
630 MAP => self.map(depth, MAP),
631 ORDERED_MAP => self.map(depth, ORDERED_MAP),
632 SORTED_MAP => self.map(depth, SORTED_MAP),
633 TRIE => self.trie(depth),
634 TAGGED => {
635 let Value::Symbol(tag) = self.value(depth + 1)? else {
636 return Err("hta/value-malformed: invalid tagged literal tag".into());
637 };
638 Ok(Value::Tagged {
639 tag,
640 form: Box::new(self.value(depth + 1)?),
641 })
642 }
643 EXCEPTION_INFO => {
644 let Value::String(message) = self.value(depth + 1)? else {
645 return Err("hta/value-malformed: invalid exception message".into());
646 };
647 let data = Box::new(self.value(depth + 1)?);
648 let cause = match self.value(depth + 1)? {
649 Value::Nil => None,
650 value @ Value::ExceptionInfo { .. } => Some(Box::new(value)),
651 _ => return Err("hta/value-malformed: invalid exception cause".into()),
652 };
653 if !matches!(data.as_ref(), Value::Map(_) | Value::Record(_)) {
654 return Err("hta/value-malformed: invalid exception data".into());
655 }
656 let provenance = decode_provenance(self.value(depth + 1)?)?;
657 Ok(Value::ExceptionInfo {
658 message,
659 data,
660 cause,
661 provenance,
662 })
663 }
664 STRUCT => self.structure(depth),
665 POINTER => {
666 let Value::Keyword(context) = self.value(depth + 1)? else {
667 return Err("hta/value-malformed: invalid pointer context".into());
668 };
669 let Value::Record(fields) = self.value(depth + 1)? else {
670 return Err("hta/value-malformed: invalid pointer fields".into());
671 };
672 Ok(Value::Pointer { context, fields })
673 }
674 VAR_REF => {
675 let Value::Symbol(symbol) = self.value(depth + 1)? else {
676 return Err("hta/value-malformed: invalid Var reference".into());
677 };
678 Ok(Value::VarRef(symbol))
679 }
680 tag @ (HANDLE | NAMESPACE | VAR | ATOM | ARRAY | OBJECT) => Err(format!(
681 "hta/value-unsupported: runtime wire tag {tag} is not portable"
682 )),
683 tag => Err(format!("hta/value-malformed: unknown tag {tag}")),
684 }
685 }
686
687 fn vector(&mut self, depth: usize) -> Result<Value, String> {
688 self.sequence(depth).map(Value::Vector)
689 }
690
691 fn sequence(&mut self, depth: usize) -> Result<Vec<Value>, String> {
692 let len = self.len()?;
693 if len > self.remaining() {
694 return Err("hta/value-malformed: impossible sequence length".into());
695 }
696 let mut values = Vec::with_capacity(len);
697 for _ in 0..len {
698 values.push(self.value(depth + 1)?);
699 }
700 Ok(values)
701 }
702
703 fn entries(&mut self, depth: usize) -> Result<Vec<(Value, Value)>, String> {
704 let len = self.len()?;
705 if len > self.remaining() / 2 {
706 return Err("hta/value-malformed: impossible map length".into());
707 }
708 let mut values = Vec::with_capacity(len);
709 for _ in 0..len {
710 values.push((self.value(depth + 1)?, self.value(depth + 1)?));
711 }
712 Ok(values)
713 }
714
715 fn map(&mut self, depth: usize, tag: u8) -> Result<Value, String> {
716 let entries = self.entries(depth)?;
717 if tag == MAP
718 && entries
719 .iter()
720 .all(|(key, _)| matches!(key, Value::Keyword(_)))
721 {
722 let mut record = BTreeMap::new();
723 for (key, value) in entries {
724 let Value::Keyword(key) = key else {
725 unreachable!()
726 };
727 if record.insert(key.clone(), value).is_some() {
728 return Err(format!(
729 "hta/value-malformed: duplicate portable record key :{key}"
730 ));
731 }
732 }
733 return Ok(Value::Record(record));
734 }
735 match tag {
736 MAP => Ok(Value::Map(entries)),
737 ORDERED_MAP => Ok(Value::OrderedMap(entries)),
738 SORTED_MAP => Ok(Value::SortedMap(entries)),
739 _ => unreachable!(),
740 }
741 }
742
743 fn trie(&mut self, depth: usize) -> Result<Value, String> {
744 self.entries(depth)?
745 .into_iter()
746 .map(|(key, value)| match key {
747 Value::String(key) => Ok((key, value)),
748 _ => Err("hta/value-malformed: invalid trie key".into()),
749 })
750 .collect::<Result<Vec<_>, String>>()
751 .map(Value::Trie)
752 }
753
754 fn structure(&mut self, depth: usize) -> Result<Value, String> {
755 let Value::String(name) = self.value(depth + 1)? else {
756 return Err("hta/value-malformed: invalid struct name".into());
757 };
758 let Value::Vector(field_values) = self.value(depth + 1)? else {
759 return Err("hta/value-malformed: invalid struct fields".into());
760 };
761 let fields = field_values
762 .into_iter()
763 .map(|value| match value {
764 Value::String(value) => Ok(value),
765 _ => Err("hta/value-malformed: invalid struct field".into()),
766 })
767 .collect::<Result<Vec<_>, String>>()?;
768 let Value::Vector(values) = self.value(depth + 1)? else {
769 return Err("hta/value-malformed: invalid struct values".into());
770 };
771 if fields.len() != values.len() {
772 return Err("hta/value-malformed: struct arity mismatch".into());
773 }
774 Ok(Value::Struct {
775 name,
776 fields,
777 values,
778 })
779 }
780
781 fn text(&mut self) -> Result<String, String> {
782 String::from_utf8(self.sized()?.to_vec())
783 .map_err(|_| "hta/value-malformed: invalid UTF-8".into())
784 }
785
786 fn sized(&mut self) -> Result<&[u8], String> {
787 let len = self.len()?;
788 self.take(len)
789 }
790
791 fn len(&mut self) -> Result<usize, String> {
792 Ok(u32::from_be_bytes(self.take(4)?.try_into().expect("four bytes")) as usize)
793 }
794
795 fn byte(&mut self) -> Result<u8, String> {
796 Ok(self.take(1)?[0])
797 }
798
799 fn take(&mut self, size: usize) -> Result<&[u8], String> {
800 let end = self
801 .cursor
802 .checked_add(size)
803 .ok_or_else(|| "hta/value-malformed: length overflow".to_string())?;
804 if end > self.bytes.len() {
805 return Err("hta/value-malformed: truncated value".into());
806 }
807 let output = &self.bytes[self.cursor..end];
808 self.cursor = end;
809 Ok(output)
810 }
811
812 fn remaining(&self) -> usize {
813 self.bytes.len() - self.cursor
814 }
815}
816
817#[cfg(test)]
818mod tests {
819 use super::*;
820
821 fn encode(value: &Value) -> Result<Vec<u8>, String> {
822 encode_immutable(value)
823 }
824
825 fn decode(bytes: &[u8]) -> Result<Value, String> {
826 decode_immutable(bytes)
827 }
828
829 fn decode_canonical(bytes: &[u8], max_bytes: usize) -> Result<Value, String> {
830 decode_immutable_canonical(bytes, max_bytes)
831 }
832
833 fn record(entries: impl IntoIterator<Item = (&'static str, Value)>) -> Value {
834 Value::Record(
835 entries
836 .into_iter()
837 .map(|(key, value)| (key.to_owned(), value))
838 .collect(),
839 )
840 }
841
842 #[test]
843 fn canonical_portable_round_trip() {
844 let value = record([
845 ("a", Value::Vector(vec![Value::Boolean(true), Value::Nil])),
846 ("b", Value::Integer(2)),
847 ("big", Value::BigInteger("9223372036854775808".into())),
848 ("bytes", Value::Bytes(vec![0, 1, 255])),
849 ("float", Value::Float(0.28)),
850 ("keyword", Value::Keyword("profile.primary".into())),
851 ]);
852 let encoded = encode(&value).unwrap();
853 assert_eq!(decode(&encoded).unwrap(), value);
854 assert_eq!(encode(&decode(&encoded).unwrap()).unwrap(), encoded);
855 assert_eq!(decode_canonical(&encoded, encoded.len()).unwrap(), value);
856 }
857
858 #[test]
859 fn immutable_hara_values_and_references_round_trip() {
860 let values = vec![
861 Value::Symbol("tool.lint/lint-source".into()),
862 Value::Character('雪'),
863 Value::BigInteger("123456789012345678901234567890".into()),
864 Value::Regex("^[a-z]+$".into()),
865 Value::List(vec![Value::Integer(1), Value::Integer(2)]),
866 Value::MapEntry(vec![Value::Integer(1), Value::Integer(2)]),
867 Value::Queue(vec![Value::Integer(1), Value::Integer(2)]),
868 Value::Set(vec![Value::Keyword("a".into()), Value::Keyword("b".into())]),
869 Value::Map(vec![(Value::String("answer".into()), Value::Integer(42))]),
870 Value::Tagged {
871 tag: "demo/value".into(),
872 form: Box::new(Value::Integer(42)),
873 },
874 Value::Pointer {
875 context: "kernel".into(),
876 fields: [("id".into(), Value::String("ROOT".into()))]
877 .into_iter()
878 .collect(),
879 },
880 Value::VarRef("user/answer".into()),
881 ];
882 for value in values {
883 assert_eq!(decode(&encode(&value).unwrap()).unwrap(), value);
884 }
885 }
886
887 #[test]
888 fn compact_tuples_use_the_vector_wire_identity_and_map_entries_are_distinct() {
889 let tuple = Value::Tuple(vec![Value::Integer(1), Value::Integer(2)]);
890 let encoded = encode(&tuple).unwrap();
891 assert_eq!(encoded[4], VECTOR);
892 assert_eq!(
893 decode(&encoded).unwrap(),
894 Value::Vector(vec![Value::Integer(1), Value::Integer(2)])
895 );
896
897 let mut legacy = encoded;
898 legacy[4] = TUPLE;
899 assert_eq!(decode(&legacy).unwrap(), tuple);
900
901 let entry = Value::MapEntry(vec![Value::Keyword("key".into()), Value::Integer(42)]);
902 let encoded_entry = encode(&entry).unwrap();
903 assert_eq!(encoded_entry[4], MAP_ENTRY);
904 assert_eq!(decode(&encoded_entry).unwrap(), entry);
905 }
906
907 #[test]
908 fn records_are_canonical_independent_of_construction_order() {
909 let first = record([("z", Value::Integer(1)), ("a", Value::Integer(2))]);
910 let second = record([("a", Value::Integer(2)), ("z", Value::Integer(1))]);
911 assert_eq!(encode(&first).unwrap(), encode(&second).unwrap());
912 }
913
914 #[test]
915 fn canonical_decode_rejects_noncanonical_map_order() {
916 let mut bytes = MAGIC.to_vec();
917 bytes.extend_from_slice(&[MAP, 0, 0, 0, 2]);
918 bytes.extend_from_slice(&[KEYWORD, 0, 0, 0, 2, b'a', b'a', NIL]);
919 bytes.extend_from_slice(&[KEYWORD, 0, 0, 0, 1, b'z', TRUE]);
920
921 assert!(decode(&bytes).is_ok());
922 assert!(decode_canonical(&bytes, bytes.len())
923 .unwrap_err()
924 .contains("frame-noncanonical"));
925 }
926
927 #[test]
928 fn canonical_decode_enforces_the_requested_maximum() {
929 let bytes = encode(&Value::Nil).unwrap();
930 assert_eq!(decode_canonical(&bytes, bytes.len()).unwrap(), Value::Nil);
931 assert!(decode_canonical(&bytes, bytes.len() - 1)
932 .unwrap_err()
933 .contains("requested maximum"));
934 assert!(decode_canonical(&bytes, 0)
935 .unwrap_err()
936 .contains("maximum-invalid"));
937 assert!(decode_canonical(&bytes, MAX_FRAME_BYTES + 1)
938 .unwrap_err()
939 .contains("maximum-invalid"));
940 }
941
942 #[test]
943 fn floats_preserve_ieee_754_bits() {
944 for value in [0.28, -0.0] {
945 let decoded = decode(&encode(&Value::Float(value)).unwrap()).unwrap();
946 let Value::Float(decoded) = decoded else {
947 panic!("float value")
948 };
949 assert_eq!(decoded.to_bits(), value.to_bits());
950 }
951 for value in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
952 assert!(encode(&Value::Float(value)).is_err());
953 }
954 }
955
956 #[test]
957 fn general_maps_accept_non_keyword_keys_and_records_reject_duplicates() {
958 let mut non_keyword = MAGIC.to_vec();
959 non_keyword.extend_from_slice(&[MAP, 0, 0, 0, 1]);
960 non_keyword.extend_from_slice(&[STRING, 0, 0, 0, 1, b'a', NIL]);
961 assert_eq!(
962 decode(&non_keyword).unwrap(),
963 Value::Map(vec![(Value::String("a".into()), Value::Nil)])
964 );
965
966 let mut duplicate = MAGIC.to_vec();
967 duplicate.extend_from_slice(&[MAP, 0, 0, 0, 2]);
968 for value in [NIL, TRUE] {
969 duplicate.extend_from_slice(&[KEYWORD, 0, 0, 0, 1, b'a', value]);
970 }
971 assert!(decode(&duplicate)
972 .unwrap_err()
973 .contains("duplicate portable record key :a"));
974 }
975
976 #[test]
977 fn runtime_only_tags_fail_closed() {
978 for tag in [HANDLE, NAMESPACE, VAR, ATOM, ARRAY, OBJECT] {
979 let bytes = [MAGIC.as_slice(), &[tag]].concat();
980 assert!(decode(&bytes).unwrap_err().contains("runtime wire tag"));
981 assert!(decode_canonical(&bytes, bytes.len())
982 .unwrap_err()
983 .contains("runtime wire tag"));
984 }
985 }
986
987 #[test]
988 fn retired_decimal_tag_fails_closed() {
989 let bytes = [MAGIC.as_slice(), &[21]].concat();
990 assert!(decode(&bytes).unwrap_err().contains("unknown tag 21"));
991 assert!(decode_canonical(&bytes, bytes.len())
992 .unwrap_err()
993 .contains("unknown tag 21"));
994 }
995
996 #[test]
997 fn frame_shape_and_lengths_are_bounded() {
998 assert!(decode(b"not-hta")
999 .unwrap_err()
1000 .contains("expected HTA0 magic"));
1001
1002 let trailing = [MAGIC.as_slice(), &[NIL, NIL]].concat();
1003 assert!(decode(&trailing).unwrap_err().contains("trailing bytes"));
1004
1005 let mut impossible = MAGIC.to_vec();
1006 impossible.extend_from_slice(&[VECTOR, 0xff, 0xff, 0xff, 0xff]);
1007 assert!(decode(&impossible)
1008 .unwrap_err()
1009 .contains("impossible sequence length"));
1010 }
1011
1012 #[test]
1013 fn nesting_depth_is_bounded_on_encode_and_decode() {
1014 let mut value = Value::Nil;
1015 for _ in 0..=MAX_NESTING_DEPTH {
1016 value = Value::Vector(vec![value]);
1017 }
1018 assert!(encode(&value).unwrap_err().contains("value-too-deep"));
1019
1020 let mut bytes = MAGIC.to_vec();
1021 for _ in 0..=MAX_NESTING_DEPTH {
1022 bytes.extend_from_slice(&[VECTOR, 0, 0, 0, 1]);
1023 }
1024 bytes.push(NIL);
1025 assert!(decode(&bytes).unwrap_err().contains("value-too-deep"));
1026 }
1027}