Checking your wiring
Context-Generic Programming (CGP) extends Rust with pluggable trait implementations, and a check trait verifies that a context can use the providers its wiring selects. Wiring itself records provider choices without immediately checking whether the context meets their requirements, so a missing dependency can remain unnoticed until a later method call. An explicit check brings that failure back beside the wiring, where the context and its selected providers are easier to inspect.
This page follows one broken context from the unchecked error, through an explicit check, to the toolchain's output, then covers checks on provider layers and what a check does not prove.
A context can be wrong and still compile
Consider a provider that reads stored objects from the folder in a local_dir field. A context's
wiring can still select that provider when the context has only a bucket_id field, as this
example shows. The fragment imports CGP's prelude and defines both the StorageObjectFetcher
component and the local provider:
use cgp::prelude::*;
#[cgp_component(StorageObjectFetcher)]
pub trait CanFetchStorageObject {
fn fetch_storage_object(&self, object_id: &str) -> anyhow::Result<Vec<u8>>;
}
#[cgp_impl(new FetchLocalObject)]
impl StorageObjectFetcher {
fn fetch_storage_object(
&self,
#[implicit] local_dir: &str,
object_id: &str,
) -> anyhow::Result<Vec<u8>> {
Ok(std::fs::read(format!("{local_dir}/{object_id}"))?)
}
}
#[derive(HasField)]
pub struct BrokenApp {
pub bucket_id: String,
}
delegate_components! {
BrokenApp {
StorageObjectFetcherComponent: FetchLocalObject,
}
}
This table establishes which provider BrokenApp selects without proving that it can use that
provider. That proof would need the local_dir field read by FetchLocalObject's implicit
argument, and because this fragment never asks for CanFetchStorageObject on BrokenApp, the
missing field has not yet caused a compilation failure.
Deferring that proof is useful for reusable wiring. An aggregate provider can collect choices before the contexts that use it are even defined. Those contexts must eventually meet the providers' requirements, but the bundle itself needs only to record the choices.
Where the failure surfaces instead
An unchecked wiring error appears when code first requires the trait. A call to
app.fetch_storage_object(object_id) on a BrokenApp value produces an error like this abbreviated
diagnostic:
error[E0599]: the method `fetch_storage_object` exists for struct `BrokenApp`,
but its trait bounds were not satisfied
|
| pub struct BrokenApp {
| -------------------- method `fetch_storage_object` not found for this struct
| because it doesn't satisfy `BrokenApp: CanFetchStorageObject`
| or `BrokenApp: StorageObjectFetcher<BrokenApp>`
|
note: trait bound `BrokenApp: StorageObjectFetcher<BrokenApp>` was not satisfied
The diagnostic stops at the unsatisfied trait implementations: BrokenApp lacks
CanFetchStorageObject and StorageObjectFetcher<BrokenApp>. It leaves the missing local_dir
field hidden behind the generated implementations. If the first call occurs in another module or
crate, the error can also appear a long way from the table that selected the provider.
Asking the question at a line you chose
A check trait forces the compiler to verify a bound where you write its implementation. The basic
technique uses an ordinary Rust supertrait and an empty
implementation. Here it checks a working App, whose local_dir field satisfies the provider:
trait CanUseApp: CanFetchStorageObject {}
impl CanUseApp for App {}
For Rust to accept the empty implementation, it must establish App: CanFetchStorageObject at that
line. Putting it beside the wiring moves any failure there, but the requirement still goes through
the consumer trait, so its diagnostic can remain as vague as the method-call error.
To expose the provider's requirements, the check needs a path through more than the consumer
trait. check_components! generates that check:
check_components! {
BrokenApp {
StorageObjectFetcherComponent,
}
}
The generated assertion asks for CanUseComponent. Satisfying this bound requires both a wiring
entry and the chosen provider's dependencies for the context being checked. The missing field
therefore appears in the diagnostic:
error[E0277]: the trait bound `BrokenApp: CanUseComponent<StorageObjectFetcherComponent>`
is not satisfied
|
help: the trait `HasField<Symbol<9, Chars<'l', Chars<'o', Chars<'c', …>>>>>`
is not implemented for `BrokenApp`
but trait `HasField<Symbol<9, Chars<'b', Chars<'u', Chars<'c', …>>>>>`
is implemented for it
|
note: required for `FetchLocalObject` to implement
`IsProviderFor<StorageObjectFetcherComponent, BrokenApp>`
Following this checking path exposes FetchLocalObject's requirement for a HasField
implementation. The cause is closer to the surface, but the field tags still appear as nested
character types, leaving local_dir and bucket_id difficult to recognize. The headline also
refers to the generated CanUseComponent bound rather than the public trait.
Reading it through the toolchain
cargo cgp check rewrites recognized CGP diagnostics
with readable field names and dependency chains. For this missing-field case, its abbreviated output
identifies both the unavailable trait and its cause:
error[E0277]: [CGP-E001] missing field `local_dir` on `BrokenApp`
|
= note: root cause: [CGP-E110] missing field `local_dir` on `BrokenApp`
this is required through the dependency chain:
[CGP-E101] consumer trait impl `CanFetchStorageObject` for context `BrokenApp`
└─ [CGP-E102] provider trait impl `StorageObjectFetcher` with context `BrokenApp`
for provider `FetchLocalObject`
└─ [CGP-E110] missing field `local_dir` on `BrokenApp`
Here the dependency chain connects the application's need for CanFetchStorageObject to the
provider it selected and then to the missing local_dir field, so the reader sees both the cause
and the reason that field is required.
The tool can also recover causes that ordinary compiler output omits. It uses the compiler's
next-generation trait solver for diagnostic recovery, then translates the recognized CGP structures.
cargo cgp check leads with the root cause for the classes it recognizes, and the tool does not yet
reshape every class; Reading the output
lists the ones that pass through unchanged. Output details depend on the compiler and tool version.
Checking a stack one layer at a time
Checks on individual providers help distinguish a wrapper's requirements from its inner provider's
requirements. Suppose RectangleArea needs width and height, while
ScaledArea<RectangleArea> also needs a scale factor. Both can be checked against App:
check_components! {
#[check_providers(
RectangleArea,
ScaledArea<RectangleArea>,
)]
App {
AreaCalculatorComponent,
}
}
If App lacks width, both assertions fail because the wrapper needs its inner provider to
work. If it lacks only the scale factor, the rectangle assertion passes and the wrapper assertion
fails. Giving each layer its own diagnostic location makes this distinction easier to see when
debugging a higher-order provider.
What to check, and when to fuse it
Placing checks beside each context's wiring catches missing entries and dependencies before a caller
happens to need them, and for basic Component: Provider entries the checks can even be part of the
same declaration.
delegate_and_check_components! combines
wiring and checking for basic Component: Provider entries. For generic components, its
#[check_params(...)] attribute supplies parameter sets to check. Keeping the assertion beside the
entry helps prevent the two from drifting apart.
Separate checks are needed for advanced mappings and individual provider layers. The combined
macro does not derive checks for open statements, namespace joins, or path-based entries; those
forms can remain unchecked even inside a combined table. Use check_components! to name the
components and parameters you need to verify, and #[check_providers] to inspect provider layers.
Check an aggregate provider through a context that uses it. Applying the combined macro to the bundle checks the bundle as a context instead. It can pass when the providers need nothing from their context, or fail because the bundle lacks fields the actual context supplies. Neither result verifies the intended application.
What it costs
An explicit check proves only the components and parameter sets it names. As wiring grows, the checks need to grow with it, or an omitted component can still fail at a later call site. For a generic component, this may mean checking several concrete parameter sets that the application relies on.
Moving the check does not necessarily shorten its diagnostic. Several broken entries can produce
several errors, and a shared missing dependency may appear once for every provider that needs it.
cargo cgp check makes the cases it recognizes easier to follow, while raw compiler output can
remain verbose.
Even a successful check establishes only the trait requirements. A provider may depend on an
ordinary bound such as Value: Display, which still needs an ordinary Rust implementation. Without
the corresponding CGP machinery, that trait cannot itself be listed as a component to check.
And satisfying these bounds says nothing about whether the provider reads the right file; that
behavior still needs tests.
Where to go next
These pages explain the dependencies being checked and the available check forms:
- Impl-side dependencies: Why provider requirements can be absent from the caller's interface.
- Higher-order providers: Composing providers and checking their layers.
- Aggregate providers: Verifying shared wiring against a real context.
check_components!: Component parameters and#[check_providers]assertions.delegate_and_check_components!: Combined wiring and checking, including its coverage limits.- Comparison: Dependency injection:
check_components!beside a container's startup validation and Dagger's build-time check.
An AI agent wrote this page using the CGP knowledge base. Its content was verified against the library's source. See How AI is used in this project.