Group an application's wiring under paths
This stage places the backend's nine components under paths, so that a context wires the whole
application in two lines, and a test context differs from production in one. It is the third stage
of web-app, a wiring study from the cgp-examples repository,
built with Context-Generic Programming (CGP), which enables pluggable trait
implementations, with the choices grouped under paths and resolved at compile time. Nothing in the
crate runs; every provider body is todo!(), and the compiler's check of the wiring is what this
page runs.
New to CGP?
fine_grained introduces the nine components and the bundles this stage
reuses. For CGP itself, the Hello World tutorial introduces wiring, and
Namespaces explains the paths and lookups this stage relies on.
The problem
The task is to run the backend in two configurations, a production one with AI-backed content filters and a test one with placeholder filters, while keeping each configuration's wiring short enough that the difference between them is obvious. With nine components, the fine-grained stage already names every component in every context, and a second context would repeat all nine keys to change two of them.
Without CGP
In plain Rust, two configurations are usually one application type made generic over the parts that
vary, such as App<F: ContentFilters>, with a type alias or a constructor for each configuration.
That works well while one parameter varies. As more parts vary, the application gains a parameter
for each, every function that names the type repeats them, and the configurations are told apart by
reading their constructors. This stage groups the parts under paths instead, so each configuration
is two lines that differ in one.
Check it
From the root of the cgp-examples repository:
cargo check -p cgp-example-web-app
The check passes. For this stage, that means both ProductionApp and TestApp satisfy all nine
components.
Each component gets a path
The module,
namespace.rs,
declares the same nine components as the previous stage, each with a
#[prefix] that registers it under a path:
#[cgp_component(UserCreator)]
#[prefix(@app.core.user in DefaultNamespace)]
pub trait CanCreateUser {
fn create_user(&self, username: &str, email: &Email) -> Result<User, Error>;
}
DefaultNamespace is the namespace CGP provides for components to register in, and a
namespace is a wiring table that turns a lookup for a component into a
lookup for a path. The nine components fill three paths under two parents:
| Path | Components |
|---|---|
@app.core.user | UserCreator, UserGetter, UserUpdater |
@app.core.post | PostCreator, PostGetter, PostUpdater, PostDeleter |
@app.extra.content_filter | UsernameCensor, SpamMessageDetector |
So a context that joins DefaultNamespace and is asked for UserGetterComponent looks for an entry
at @app.core.user, and one entry there can answer for all three user components.
Bundles are grouped by path
The providers and the three bundles of the previous stage return unchanged, along with a fourth
bundle, DummyContentFilterComponents, that wires placeholder filters for testing. On top of them
sit three bundles keyed by path:
delegate_components! {
new PostgresCoreComponents {
namespace DefaultNamespace;
@app.core.user: PostgresUserComponents,
@app.core.post: PostgresPostComponents,
}
}
delegate_components! {
new ProductionExtraComponents {
namespace DefaultNamespace;
@app.extra.content_filter: AiContentFilterComponents,
}
}
PostgresCoreComponents routes the user and post paths to their bundles, and
ProductionExtraComponents routes the content filters to the AI bundle. DummyExtraComponents is
the same with the placeholder bundle. Each of these bundles joins DefaultNamespace itself, with
its namespace line, because a lookup arrives at a bundle by the component's name, and it is the
namespace that turns the name into the path the bundle's entries match. Without the line, the bundle
has no entry for the name.
Two contexts, one line apart
The production and test contexts each join the namespace and route the two top-level paths:
delegate_components! {
ProductionApp {
namespace DefaultNamespace;
@app.core: PostgresCoreComponents,
@app.extra: ProductionExtraComponents,
}
}
delegate_components! {
TestApp {
namespace DefaultNamespace;
@app.core: PostgresCoreComponents,
@app.extra: DummyExtraComponents,
}
}
Each is a type that stands for one configuration of the application, with the database as its one
field. They share the whole core and differ only in their content filters, and the difference is
visible at a glance. One check_components! block
asserts all nine components on each.
Try a change
Remove TestApp's @app.extra line, and run cargo cgp check. The two
creators fail, each with the filter its wrapper uses:
error[E0277]: [CGP-E001] missing wiring for `@app.extra.content_filter.…UsernameCensorComponent` on `TestApp`
= note: root cause: [CGP-E113] missing wiring for `@app.extra.content_filter.…UsernameCensorComponent` on `TestApp`
this is required through the dependency chain:
[CGP-E101] consumer trait impl `CanCreateUser` for context `TestApp`
…
= help: wire `@app.extra.content_filter.…UsernameCensorComponent` to a provider in the wiring of `TestApp`
error[E0277]: [CGP-E001] missing wiring for `@app.extra.content_filter.…SpamMessageDetectorComponent` on `TestApp`
= note: root cause: [CGP-E113] missing wiring for `@app.extra.content_filter.…SpamMessageDetectorComponent` on `TestApp`
this is required through the dependency chain:
[CGP-E101] consumer trait impl `CanCreatePost` for context `TestApp`
…
= help: wire `@app.extra.content_filter.…SpamMessageDetectorComponent` to a provider in the wiring of `TestApp`
Each root cause names the full path the namespace routed the lookup to, which says where the entry
belongs, and each chain lists every lookup on the way there: from the creator, through the redirect
to @app.core, PostgresCoreComponents, and the bundle behind it. The block elides those hops and
the module names the tool adds to each path. The other five components still check, since the
getters, updaters, and deleter need nothing from the extras. 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 stage shows components grouped under paths in a namespace, so wiring routes a whole group with one entry, and a hierarchy of paths lets a parent route its children through a bundle. The contexts become short enough that their differences are what a reader sees. Namespaces explains the lookups, and Aggregate providers explains bundles behind paths.
The cost is indirection. To find what TestApp uses for UserGetterComponent, a reader follows the
component's prefix to a path, the path to PostgresCoreComponents, that bundle to
PostgresUserComponents, and that bundle to GetUserWithPostgres. The compiler does this
instantly, and cargo cgp check prints the chain when something is missing, but a person reads four
tables where the coarse stage had one line. And every context still names the core bundle; the next
stage moves that into the namespace too.
Where to go next
default_impls: the next stage, a namespace that supplies the defaults.- web-app overview: the four stages side by side.
- Namespaces: the CGP idea behind paths and the lookups they route.
- CGP v0.8.0: the release post that develops this application stage by stage.
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.