Skip to main content

Wire an application with one trait per domain

This stage wires a small social-media backend with one trait per domain, a user manager and a post manager, and shows what that costs as soon as one method needs something the others do not. It is the first stage of web-app, a wiring study from the cgp-examples repository, built with Context-Generic Programming (CGP), which enables pluggable trait implementations, one per domain, chosen 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?​

The Hello World tutorial introduces components, providers, and wiring with a smaller program. Consumer and provider traits explains what a component is, which is what this stage sizes. This page can be read without either.

The problem​

The task is the backend of a small social-media service: create, read, and update users and posts, store them in Postgres, and reject a username or a post that a content filter flags. This stage writes it the way most applications start, with one trait per domain, and the problem it shows is the one that starting point hides: a requirement of one method becomes a requirement of all of them.

Without CGP​

In plain Rust, the same design is a UserManager trait implemented by a Postgres type that holds its database and its censor, or takes the censor as a generic parameter. It has the same cost. Only create_user uses the censor, yet every value of the Postgres manager has to be built with one, so code that only reads users, such as a report generator, still has to supply a censor it never calls. Splitting the trait fixes it in plain Rust too, which is what the next stage does with CGP. This stage exists to make the cost visible first.

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 ProductionApp has a working provider for each of its four components, including everything those providers need.

One component per domain​

The module, coarse_grained.rs, defines a manager trait for each domain, and a small trait for each content filter:

#[cgp_component(UserManager)]
pub trait CanManageUser {
fn create_user(&self, username: &str, email: &Email) -> Result<User, Error>;

fn get_user(&self, user_id: &UserId) -> Result<User, Error>;

fn update_user_data(&self, user_id: &UserId, user_data: &UserData) -> Result<(), Error>;
}

#[cgp_component(UsernameCensor)]
pub trait CanCensorUsername {
fn username_is_censored(&self, username: &str) -> Probability;
}

#[cgp_component] turns each trait into a component: the trait callers use, a trait providers implement, and a key that wiring names. CanManagePost has create_post, get_post, update_post, and delete_post, and CanDetectSpamMessage has message_is_spam. This is the shape most applications start from, since it follows the way the domain is described.

The manager's provider needs the censor​

The user manager's provider stores users in Postgres, and checks new usernames with the censor before creating them:

#[cgp_impl(new PostgresUserManager)]
#[uses(CanCensorUsername)]
impl UserManager {
fn create_user(
&self,
#[implicit] database: &PostgresDb,
username: &str,
email: &Email,
) -> Result<User, Error> {
if self.username_is_censored(username) > Probability::new(0.8) {
return Err(Error::InvalidUsername);
}

todo!()
}

fn get_user(&self, #[implicit] database: &PostgresDb, user_id: &UserId) -> Result<User, Error> {
todo!()
}

fn update_user_data(
&self,
#[implicit] database: &PostgresDb,
user_id: &UserId,
user_data: &UserData,
) -> Result<(), Error> {
todo!()
}
}

#[uses] declares what the provider needs from the context, here the censor. #[implicit] marks the database argument as filled from the context's field of that name, so callers never pass it. Only create_user calls the censor, but #[uses] is on the whole impl, so the whole provider depends on it. PostgresPostManager has the same shape, with the spam detector.

The context wires and checks in one table​

ProductionApp is the context, a type that stands for the application and holds its choices. It holds the database handle, and wires its four components:

#[derive(HasField)]
pub struct ProductionApp {
pub database: PostgresDb,
}

delegate_and_check_components! {
ProductionApp {
UserManagerComponent: PostgresUserManager,
PostManagerComponent: PostgresPostManager,
UsernameCensorComponent: DummyUserCensor,
SpamMessageDetectorComponent: DummySpamMessageDetector,
}
}

delegate_and_check_components! wires each entry and checks it in the same step, which suits a table of plain entries like this one. #[derive(HasField)] exposes the database field to the providers that read it. The two filters are wired to placeholder providers here; the next stage adds real ones.

Try a change​

Remove the censor's entry, the line UsernameCensorComponent: DummyUserCensor,, and run cargo cgp check. The whole user manager fails:

error[E0277]: [CGP-E001] missing wiring for `UsernameCensorComponent` on `…ProductionApp`
= note: root cause: [CGP-E113] missing wiring for `UsernameCensorComponent` on `…ProductionApp`
this is required through the dependency chain:
[CGP-E101] consumer trait impl `CanManageUser` for context `…ProductionApp`
└─ [CGP-E102] provider trait impl `UserManager` with context `…` for provider `PostgresUserManager`
└─ [CGP-E101] consumer trait impl `CanCensorUsername` for context `…ProductionApp`
= help: wire `UsernameCensorComponent` to a provider in the wiring of `…ProductionApp`

The chain names the manager, the provider behind it, and the censor that provider's create_user needs, so the whole manager goes with the censor. The context has lost get_user and update_user_data as well as create_user, though neither calls the censor, because the three methods share one provider and one set of requirements. The block elides the module paths. Compare the same change in the next stage. 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 coarse-grained components: one component per domain, each implemented by one provider. The shape is easy to read and short to wire, four entries for the whole application. Its cost is that a component carries the union of its methods' requirements. A context that wants to read users, such as a report generator with no censor, cannot use PostgresUserManager at all, and swapping how one method works means writing a whole new manager.

Coarse components are the right size when a domain's methods are always provided together. When they start to need different things, the next stage's split is the fix. Consumer and provider traits explains what a component is, and Impl-side dependencies explains how #[uses] attaches a requirement to a provider.

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.