Extract TLV tag bytes into named constants

Author: cargopete

docs/rust-abi-spec.md

@@ -300,6 +300,15 @@ Notes:
 - The decoder on the host side rejects unknown tags with
   `io::ErrorKind::InvalidData`.
 
+The canonical host-side tag byte values are defined as named constants in
+the `tags` module in `runtime/wasm/src/rust_abi/types.rs` (`tags::NULL`,
+`tags::STRING`, `tags::INT`, `tags::INT8`, `tags::BIG_INT`,
+`tags::BIG_DECIMAL`, `tags::BOOL`, `tags::BYTES`, `tags::ADDRESS`,
+`tags::ARRAY`). The `ValueTag` enum discriminants are derived from those
+constants, so there is exactly one place in the host codebase where the
+on-wire bytes are defined. Any edit to those constants is, by definition,
+a breaking ABI change (see section 8.1).
+
 The reference implementation lives in
 `runtime/wasm/src/rust_abi/entity.rs`.
 

runtime/wasm/src/rust_abi/entity.rs

@@ -4,7 +4,7 @@
 //! Works with `HashMap<String, Value>` for deserialization since graph-node's
 //! `Entity` type requires schema context for construction.
 
-use super::types::{FromRustWasm, ToRustWasm, ValueTag};
+use super::types::{tags, FromRustWasm, ToRustWasm, ValueTag};
 use graph::data::store::scalar::Bytes;
 use graph::data::store::{Entity, Value};
 use graph::prelude::*;
@@ -92,46 +92,46 @@ impl ToRustWasm for Value {
     fn write_to<W: Write>(&self, writer: &mut W) -> io::Result<()> {
         match self {
             Value::Null => {
-                writer.write_all(&[ValueTag::Null as u8])?;
+                writer.write_all(&[tags::NULL])?;
             }
             Value::String(s) => {
-                writer.write_all(&[ValueTag::String as u8])?;
+                writer.write_all(&[tags::STRING])?;
                 s.as_str().write_to(writer)?;
             }
             Value::Int(n) => {
-                writer.write_all(&[ValueTag::Int as u8])?;
+                writer.write_all(&[tags::INT])?;
                 n.write_to(writer)?;
             }
             Value::Int8(n) => {
-                writer.write_all(&[ValueTag::Int8 as u8])?;
+                writer.write_all(&[tags::INT8])?;
                 n.write_to(writer)?;
             }
             Value::BigInt(n) => {
-                writer.write_all(&[ValueTag::BigInt as u8])?;
+                writer.write_all(&[tags::BIG_INT])?;
                 n.write_to(writer)?;
             }
             Value::BigDecimal(n) => {
-                writer.write_all(&[ValueTag::BigDecimal as u8])?;
+                writer.write_all(&[tags::BIG_DECIMAL])?;
                 n.write_to(writer)?;
             }
             Value::Bool(b) => {
-                writer.write_all(&[ValueTag::Bool as u8])?;
+                writer.write_all(&[tags::BOOL])?;
                 b.write_to(writer)?;
             }
             Value::Bytes(b) => {
-                writer.write_all(&[ValueTag::Bytes as u8])?;
+                writer.write_all(&[tags::BYTES])?;
                 b.as_slice().to_vec().write_to(writer)?;
             }
             Value::List(arr) => {
-                writer.write_all(&[ValueTag::Array as u8])?;
+                writer.write_all(&[tags::ARRAY])?;
                 writer.write_all(&(arr.len() as u32).to_le_bytes())?;
                 for v in arr {
                     v.write_to(writer)?;
                 }
             }
             Value::Timestamp(ts) => {
                 // Serialize timestamp as BigInt (microseconds since epoch)
-                writer.write_all(&[ValueTag::BigInt as u8])?;
+                writer.write_all(&[tags::BIG_INT])?;
                 BigInt::from(ts.as_microseconds_since_epoch()).write_to(writer)?;
             }
         }

runtime/wasm/src/rust_abi/types.rs

@@ -7,35 +7,57 @@ use graph::prelude::*;
 use std::io::{self, Read, Write};
 use std::str::FromStr;
 
+/// Canonical TLV value tag bytes.
+///
+/// These are the single source of truth for the tag byte of each `Value`
+/// variant on the wire. They match the table in
+/// `docs/rust-abi-spec.md` section 4.6 one-for-one. Changing any value in
+/// this module is a breaking ABI change and requires an `apiVersion` bump.
+pub mod tags {
+    pub const NULL: u8 = 0x00;
+    pub const STRING: u8 = 0x01;
+    pub const INT: u8 = 0x02;
+    pub const INT8: u8 = 0x03;
+    pub const BIG_INT: u8 = 0x04;
+    pub const BIG_DECIMAL: u8 = 0x05;
+    pub const BOOL: u8 = 0x06;
+    pub const BYTES: u8 = 0x07;
+    pub const ADDRESS: u8 = 0x08;
+    pub const ARRAY: u8 = 0x09;
+}
+
 /// Value type tags for TLV serialization.
+///
+/// Discriminants are pulled from the [`tags`] module so there is a single
+/// authoritative definition of each on-wire byte.
 #[repr(u8)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ValueTag {
-    Null = 0x00,
-    String = 0x01,
-    Int = 0x02,
-    Int8 = 0x03,
-    BigInt = 0x04,
-    BigDecimal = 0x05,
-    Bool = 0x06,
-    Bytes = 0x07,
-    Address = 0x08,
-    Array = 0x09,
+    Null = tags::NULL,
+    String = tags::STRING,
+    Int = tags::INT,
+    Int8 = tags::INT8,
+    BigInt = tags::BIG_INT,
+    BigDecimal = tags::BIG_DECIMAL,
+    Bool = tags::BOOL,
+    Bytes = tags::BYTES,
+    Address = tags::ADDRESS,
+    Array = tags::ARRAY,
 }
 
 impl ValueTag {
     pub fn from_u8(v: u8) -> Option<Self> {
         match v {
-            0x00 => Some(Self::Null),
-            0x01 => Some(Self::String),
-            0x02 => Some(Self::Int),
-            0x03 => Some(Self::Int8),
-            0x04 => Some(Self::BigInt),
-            0x05 => Some(Self::BigDecimal),
-            0x06 => Some(Self::Bool),
-            0x07 => Some(Self::Bytes),
-            0x08 => Some(Self::Address),
-            0x09 => Some(Self::Array),
+            tags::NULL => Some(Self::Null),
+            tags::STRING => Some(Self::String),
+            tags::INT => Some(Self::Int),
+            tags::INT8 => Some(Self::Int8),
+            tags::BIG_INT => Some(Self::BigInt),
+            tags::BIG_DECIMAL => Some(Self::BigDecimal),
+            tags::BOOL => Some(Self::Bool),
+            tags::BYTES => Some(Self::Bytes),
+            tags::ADDRESS => Some(Self::Address),
+            tags::ARRAY => Some(Self::Array),
             _ => None,
         }
     }