Skip to main content

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:


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.