Skip to main content

Wiring a context

A cgp-serde context is a type that stands for an application, and its wiring table names a provider for every type the application encodes. cgp-serde rebuilds Serde's Serialize and Deserialize as components of Context-Generic Programming (CGP). This guide gives the steps for building the table, the key syntax some types need, and the checks that prove it complete.

1. Open the components and choose per type​

Open each serialization component with the open statement, then write one entry per value type. The statement comes first in the block:

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,
}
}

This is the table of AppA from the messages example. Each @ entry reads "to serialize this type, use this provider", and a bracketed list gives several types one provider. delegate_components! documents the syntax in full.

Open both components when the context reads as well as writes, as in open { ValueSerializerComponent, ValueDeserializerComponent };, and write the reading entries under @ValueDeserializerComponent. A context that runs the JSON providers through try_compute opens TryComputerComponent too, as basic does.

2. Wire every type the traversal reaches​

List the types a traversal touches, not only the types the data names. Start from each top-level type, and follow what each provider asks the context for, which each provider's reference page states:

  • A struct wired to SerializeRecordFields or DeserializeRecordFields needs an entry for each field's type.
  • An enum wired to SerializeVariantFields or DeserializeVariantFields needs an entry for each variant's payload type. A variant with no fields, such as Empty, carries Nil, which SerializeUnit writes as {"Empty":null}.
  • A collection needs an entry of its own, besides its item type's. Writing one with SerializeIterator also asks for the item as a reference, which one generic entry covers: @ValueSerializerComponent.<'a, T> &'a T: SerializeDeref.
  • An encoding asks for the type it produces. The hex, base64, and RFC 3339 providers ask for String, and SerializeTimestamp asks for i64, so a context wires those types even when no field has them.
  • A leaf, a type the application does not want to customize, goes to UseSerde, which uses the type's own Serde impl and asks for nothing.

A type the table misses is a compile error rather than a runtime failure, and debugging the wiring shows what each kind of omission reports.

3. Write keys for references, lifetimes, and arrays​

Three kinds of type need care in a key:

  • References and borrowed types declare their lifetime in the entry: @ValueSerializerComponent.<'a, T> &'a T, @ValueDeserializerComponent.<'a> &'a str, or @ValueDeserializerComponent.<'b> Vec<&'b Coord>. Inside a list, each type declares its own, as in [Coord, <'b> Payload<'b>]. A key with a fixed lifetime such as &'static str also works, but matches only that lifetime.
  • A context with a lifetime declares it on the table, as in <'a> App<'a> { … }, and the entries use lifetime names of their own.
  • A fixed-size array cannot be written as a key, because square brackets are the syntax for a list of keys, so @ValueDeserializerComponent.[u8; 32] fails to parse. Define a type alias, such as type Digest = [u8; 32];, and key on the alias.

4. Wire an error type when the JSON providers are used​

The JSON providers and the deserialize_json_string method turn serde_json's errors into the context's error type, so a context that uses them wires one. With the anyhow backend from the cgp-error-anyhow crate, that is two plain entries:

ErrorTypeProviderComponent:
UseAnyhowError,

ErrorRaiserComponent:
RaiseAnyhowError,

The components are imported from cgp::core::error, and the providers from cgp_error_anyhow. Modular error handling explains the two components. A context that only serializes through SerializeWithContext needs neither, since the format's own error comes back.

5. Check every value type​

Assert the wiring with a check_components! table that lists every type the context encodes. CGP checks wiring when it is used, so without a check a missing entry surfaces only at the first call, with a longer error. List the reading side with the component's lifetime, written as Life<'de>:

check_components! {
#[check_trait(CanUseAppSerializer)]
App {
ValueSerializerComponent: [
u64,
String,
Vec<u8>,
Payload,
],
}
}

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

Give each table its own #[check_trait] name when one module checks the same context more than once, since both would otherwise take the same default name. Prefer a separate check_components! to delegate_and_check_components!, which checks only plain entries and leaves every @ entry under an open statement unchecked.

6. Share entries between contexts with a namespace​

Two applications that make most of the same choices can put the shared entries in a namespace, a reusable wiring table that contexts join, and keep only their differences in their own tables. This is AppA and AppB from messages, reduced to two of their structs, with the shared entries moved into a namespace:

cgp_namespace! {
new MessagesNamespace {
@ValueSerializerComponent.<'a, T> &'a T:
SerializeDeref,
@ValueSerializerComponent.[i64, u64, String]:
UseSerde,
@ValueSerializerComponent.Vec<EncryptedMessage>:
SerializeIterator,
@ValueSerializerComponent.[MessagesByTopic, EncryptedMessage]:
SerializeRecordFields,
}
}

pub struct AppA;

delegate_components! {
AppA {
namespace MessagesNamespace;
open ValueSerializerComponent;

@ValueSerializerComponent.Vec<u8>: SerializeHex,
@ValueSerializerComponent.DateTime<Utc>: SerializeRfc3339Date,
}
}

pub struct AppB;

delegate_components! {
AppB {
namespace MessagesNamespace;
open ValueSerializerComponent;

@ValueSerializerComponent.Vec<u8>: SerializeBase64,
@ValueSerializerComponent.DateTime<Utc>: SerializeTimestamp,
}
}

Each context still opens the component, and a context's own entries only fill what the namespace leaves out: a context cannot replace an entry the namespace makes. So put in the namespace only the choices every joining context shares, and leave each point of difference, here the bytes and the dates, to the contexts. cgp_namespace! documents the syntax.

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.