Skip to main content

Encode one value two ways in two applications

This example serializes one nested archive of messages twice, under two applications that disagree about how bytes and dates should look. It is an example from cgp-serde, which rebuilds Serde's Serialize and Deserialize traits as components of Context-Generic Programming (CGP). The data types name no encoding, and the two applications differ in three wiring lines, which is the whole difference between the two JSON documents they produce.

tip

New to CGP?​

basic introduces the wiring table this page builds on. For CGP itself, the Hello World tutorial shows contexts and wiring with a smaller program, and Coherence explains why plain Rust allows only one encoding per type, which is what two applications here get around. This page can be read without them.

The problem​

The task is to serialize the same data, an archive of messages with byte fields and dates, for two applications that disagree about how it should look: one wants bytes as hex and dates as RFC 3339 strings, the other bytes as base64 and dates as Unix timestamps. Both applications use the same Rust types, and the choice has to apply at every level of nesting.

Without CGP​

With Serde, a type has one Serialize impl in the whole program. Vec<u8> and DateTime<Utc> already have theirs, in serde and in chrono, and Rust's orphan rule stops an application from writing another. So the encoding is chosen per field, with #[serde(with = …)] attributes or wrapper types, and each struct definition carries one set of choices. Two applications that want different choices need two sets of structs, or code that converts the shared structs into application-specific copies before serializing. This page keeps one set of structs and gives each application its own choices.

Run it​

From the root of the cgp-serde repository, run the example:

cargo run -p cgp-serde-examples --example messages

It serializes the same archive twice and prints each document, shown below. cargo test -p cgp-serde-examples --example messages checks both against this exact JSON. From the first application, AppA, bytes are hex and dates are RFC 3339 strings:

{
"decryption_key": "746f702d736563726574",
"messages_by_topics": [
{
"encrypted_topic": "416c6c2061626f757420434750",
"messages": [
{
"message_id": 1,
"author_id": 2,
"date": "2025-11-03T14:15:00+00:00",
"encrypted_data": "48656c6c6f2066726f6d20527573744c616221"
},
{
"message_id": 4,
"author_id": 8,
"date": "2025-12-19T23:45:00+00:00",
"encrypted_data": "4f6e65207965617220616e6e697665727361727921"
}
]
}
]
}

From the second, AppB, bytes are base64 and dates are Unix timestamps:

{
"decryption_key": "dG9wLXNlY3JldA==",
"messages_by_topics": [
{
"encrypted_topic": "QWxsIGFib3V0IENHUA==",
"messages": [
{
"message_id": 1,
"author_id": 2,
"date": 1762179300,
"encrypted_data": "SGVsbG8gZnJvbSBSdXN0TGFiIQ=="
},
{
"message_id": 4,
"author_id": 8,
"date": 1766187900,
"encrypted_data": "T25lIHllYXIgYW5uaXZlcnNhcnkh"
}
]
}
]
}

The data names no encoding​

The archive is three nested structs, from messages.rs:

#[derive(CgpData)]
pub struct EncryptedMessage {
pub message_id: u64,
pub author_id: u64,
pub date: DateTime<Utc>,
pub encrypted_data: Vec<u8>,
}

#[derive(CgpData)]
pub struct MessagesByTopic {
pub encrypted_topic: Vec<u8>,
pub messages: Vec<EncryptedMessage>,
}

#[derive(CgpData)]
pub struct MessagesArchive {
pub decryption_key: Vec<u8>,
pub messages_by_topics: Vec<MessagesByTopic>,
}

Byte fields appear at every level, and dates in the innermost struct. Nothing in the structs says how either is written. CgpData only exposes the fields to generic code, and Vec<u8> and DateTime<Utc> belong to other crates, so in Serde their encoding would be whatever their existing Serialize impls chose.

Each application is a context with its own table​

AppA is a type that stands for the first application, which is where its choices live. It has no fields, and its wiring table names a provider for each type the archive contains:

pub struct AppA;

delegate_components! {
AppA {
open {ValueSerializerComponent};

@ValueSerializerComponent.<'a, T> &'a T:
SerializeDeref,

@ValueSerializerComponent.[
u64,
String,
]:
UseSerde,

@ValueSerializerComponent.Vec<u8>:
SerializeHex,

@ValueSerializerComponent.DateTime<Utc>:
SerializeRfc3339Date,

@ValueSerializerComponent.[
Vec<EncryptedMessage>,
Vec<MessagesByTopic>,
]:
SerializeIterator,

@ValueSerializerComponent.[
MessagesArchive,
MessagesByTopic,
EncryptedMessage,
]:
SerializeRecordFields,
}
}

The open statement lets the table choose by the type being serialized, and each @ entry makes one choice, as in basic. A bracketed list gives several types the same provider.

AppB is a second context with the same table, except for three entries:

@ValueSerializerComponent.[
i64,
u64,
String,
]:
UseSerde,

@ValueSerializerComponent.Vec<u8>:
SerializeBase64,

@ValueSerializerComponent.DateTime<Utc>:
SerializeTimestamp,

SerializeHex and SerializeBase64 are two providers for the same type, Vec<u8>, and so are SerializeRfc3339Date and SerializeTimestamp for DateTime<Utc>. As Serde impls they would conflict, since a type can have only one. As entries in two contexts' tables they do not, because each choice holds only within the context that makes it. Coherence explains why that is allowed.

A choice reaches every level of nesting​

Neither table says anything about where a Vec<u8> appears, and yet every byte field in the archive, at all three levels, follows its context's choice. That is because no provider encodes the values inside the one it is given. SerializeRecordFields walks a struct and asks the context to serialize each field, and SerializeIterator walks a collection and asks the context to serialize each item. Each of those requests goes back through the same table, so the context's choice for a type applies wherever the type turns up. Re-entrant providers explains the mechanism.

Entries the traversal needs​

Because every nested value goes back through the table, the table needs an entry for every type the traversal reaches, not only for the fields in the data. Four entries exist for that reason:

  • Each vector of structs gets SerializeIterator. A Vec<EncryptedMessage> is a value the traversal reaches, so it needs an entry of its own besides the one for EncryptedMessage.
  • The generic reference entry, <'a, T> &'a T, sends every reference to SerializeDeref, which serializes the value behind it. Walking a borrowed Vec<EncryptedMessage> yields &EncryptedMessage, and this one entry covers every such reference.
  • String is wired, although no field is a String, because the hex, base64, and RFC 3339 providers each produce a string and ask the context to serialize it.
  • i64 is wired in AppB, although no field is an i64, because SerializeTimestamp turns the date into an i64 and asks the context to serialize that.

The last point is the easiest to miss, and the change at the end of this page shows what happens without it.

Serializing through an ordinary Serde API​

Each context's wiring is asserted by a check_components! table listing the seven types it serializes. Then the example hands each context and the archive to serde_json, through a helper that accepts any context able to serialize the archive:

fn to_pretty_json<Context>(context: &Context, archive: &MessagesArchive) -> String
where
Context: CanSerializeValue<MessagesArchive>,
{
serde_json::to_string_pretty(&SerializeWithContext::new(context, archive)).unwrap()
}

SerializeWithContext pairs a context with a value and implements Serde's own Serialize trait, so any Serde format accepts it unchanged. Any error is serde_json's own, which is why neither context wires an error type.

Try a change​

Remove i64 from AppB's UseSerde entry, leaving [u64, String], and run cargo cgp check. The check on AppB fails, and the tool names the missing entry as the root cause:

error[E0277]: [CGP-E001] missing wiring for `@ValueSerializerComponent.i64` on `AppB`
= note: root cause: [CGP-E113] missing wiring for `@ValueSerializerComponent.i64` on `AppB`

Every checked type that contains a date fails, and all for one reason. Below the root cause, the tool prints the chain that leads to it: from MessagesArchive through SerializeRecordFields, the vectors, the references, and EncryptedMessage, down to SerializeTimestamp, which asks AppB for an i64 it has no entry for. The fix is to put i64 back. cargo cgp check leads with the root cause for the classes it recognizes, and the tool does not yet reshape every class.

The pattern​

This example shows two applications choosing different implementations for the same types, without a conflict. Each application is a context, the serialized value is a parameter of the component, and a context's table decides the provider for each value type, including types from other crates. Because every provider hands nested values back to the context, one entry decides a type's encoding everywhere in the value. The idea is CGP's local answer to Rust's coherence rule, explained in Coherence, and Modularity hierarchy places it among the alternatives.

The cost is the table each application writes. AppA and AppB share all but three entries and still list every one, and both carry entries, such as the reference entry and AppB's i64, that serve the traversal rather than the data. The shared entries can move into a namespace the two contexts join, as the last step of wiring a context shows, but the traversal's entries are still there to write. A program that needs one encoding per type gets it from Serde's derive with none of this.

Where to go next​


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.