Skip to main content

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.

tip

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:

PathComponents
@app.core.userUserCreator, UserGetter, UserUpdater
@app.core.postPostCreator, PostGetter, PostUpdater, PostDeleter
@app.extra.content_filterUsernameCensor, 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.