Skip to main content

Component design

Why does moving one type out of Self change who chooses how a value is encoded? cgp-serde rebuilds Serde's Serialize and Deserialize as components of Context-Generic Programming (CGP), and its components differ from Serde's traits in exactly that move. This page explains the move and what it makes possible, how one provider can serve both directions, and how deserializing carries Serde's lifetime.

Serde's trait belongs to the value​

Serde's Serialize is implemented by the type being serialized. Its method takes the value as self:

// Serde: implemented by the value's type
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: serde::Serializer;

So a type has one Serialize impl in the whole program, and Rust's coherence rules decide who may write it: the crate that owns the type, or the crate that owns the trait. Vec<u8> is serialized as a list of numbers because Serde's impl says so, and a program that wants hex has to wrap the type or annotate every field.

cgp-serde's belongs to the context​

cgp-serde's serializing component, CanSerializeValue<Value>, keeps the method and adds one parameter:

// cgp-serde: implemented by a context, for each Value
fn serialize<S>(&self, value: &Value, serializer: S) -> Result<S::Ok, S::Error>
where
S: serde::Serializer;

The value is now an argument, and self is a context, a type that stands for an application and holds its choices. The deserializing component, CanDeserializeValue<'de, Value>, makes the same change to Deserialize. Each is a CGP component: a trait that callers use, paired with a trait that providers implement, joined by the context's wiring.

The consequence is that each context chooses, for each value type, which provider serializes it:

delegate_components! {
AppA {
open {ValueSerializerComponent};

@ValueSerializerComponent.Vec<u8>:
SerializeHex,
// ...
}
}

A second context can wire Vec<u8> to SerializeBase64, and the two do not conflict, because each impl is for a different context. Nor does either context need to own Vec<u8> or the component, since owning the context is enough to wire it. Coherence explains why that is allowed.

In the terms of the modularity hierarchy, the contexts are environmental, standing for applications rather than for data, and the serialized value is the component's target. The hierarchy places this shape at the tier for a target whose behavior must vary between contexts, and serialization is its motivating case: the types being encoded are usually from other crates, and different applications need them encoded differently.

One provider can serve both directions​

A provider in CGP is a type that names an implementation, so one struct can implement both the serializing and the deserializing component. cgp-serde does this wherever the two directions are one decision. SerializeHex is one struct with two impls, one that writes bytes as a hex string and one that reads a hex string back, and a context names it once in each table:

@ValueSerializerComponent.Vec<u8>: SerializeHex,
@ValueDeserializerComponent.Vec<u8>: SerializeHex,

The names follow from this. A provider named Serialize… may implement both directions, while one named Deserialize… implements only reading. Where the two directions work differently, they are separate providers named for how they work: a struct is written by reading its fields, and read by building it field by field. This table pairs each provider that writes with the one that reads the same encoding:

WritingReading
UseSerdethe same provider
SerializeStringthe same provider, for String
SerializeBytesthe same provider, or TryDeserializeBytes for a fallible conversion
SerializeWithDisplayDeserializeWithFromStr
SerializeFromthe same provider
TrySerializeFromthe same provider
SerializeDerefDeserializeAndAllocate, for a reference
SerializeIteratorDeserializeExtend
SerializeRecordFieldsDeserializeRecordFields
SerializeVariantFieldsDeserializeVariantFields
SerializeUnitthe same provider, for a Default type
noneDeserializeDefault, which wraps another reader
SerializeHex, SerializeBase64, SerializeRfc3339Date, SerializeTimestampthe same providers

Sharing one struct makes agreement the intent, and a context still wires each direction on its own. Nothing stops a context from writing with one encoding and reading with another, so a round trip in a test is what confirms that the two halves match.

Deserializing carries Serde's lifetime​

Serde's Deserialize<'de> has a lifetime, so that a value can borrow from its input, such as a &'de str pointing into the JSON text. CanDeserializeValue<'de, Value> keeps it as a parameter of the component. That makes the lifetime part of what a context is checked for: a check on the deserializing component lists each type paired with the lifetime, written as Life<'de>. This check is from basic:

check_components! {
#[check_trait(CanDeserializeApp)]
<'de> App {
ValueDeserializerComponent: [
(Life<'de>, u64),
(Life<'de>, String),
(Life<'de>, Vec<u8>),
(Life<'de>, Payload),
]
}
}

The serializing component has no lifetime, since writing a value never borrows from the output.

What it costs​

The move cannot be made to Serde's own traits without breaking every impl of them, so cgp-serde defines new traits and connects them to Serde's, as the bridge to Serde explains. Code that expects a Serialize value gets one through an adapter, not directly.

The larger cost is that choice has to be exercised. Where Serde finds a type's impl automatically, a cgp-serde context names a provider for every type it encodes, in each direction it encodes it. The table is the price of each application being able to choose, and for a program that would make the same choice everywhere, it is a cost with no return.

Where to go next​

  • Re-entrant providers: how a context's choice for a type reaches every place the type appears.
  • basic: both components wired on one context, with SerializeHex in both directions.
  • Modularity hierarchy: the tiers of choice CGP offers, and when to move a value out of Self.

An AI agent wrote this page using the CGP knowledge base. Its content was verified against the project's source. See How AI is used in this project.