pub struct Planet { name: String }

[entrait(FetchPlanet, mock_api=FetchPlanetMock)]

fn fetchplanet(deps: &(), planetid: u32) -> Result

let hellostring = sayhello( &Unimock::newpartial( FetchPlanetMock .somecall(matching!(123456)) .returns(Ok(Planet { name: "World".to_string(), })) ), 123456, ).unwrap();

asserteq!("Hello World!", hellostring); ```

This example used Unimock::new_partial to create a mocker that works mostly like Impl, except that the call graph can be short-circuited at arbitrary, run-time configurable points. The example code goes through three layers (say_hello => fetch_planet_name => fetch_planet), and only the deepest one gets mocked out.

Alternative mocking: Mockall

If you instead wish to use a more established mocking crate, there is also support for mockall. Note that mockall has some limitations. Multiple trait bounds are not supported, and deep tests will not work. Also, mockall tends to generate a lot of code, often an order of magnitude more than unimock.

Enabling mockall is done using the mockall entrait option. There is no cargo feature to turn this on implicitly, because mockall doesn't work well when it's re-exported through another crate.

```rust

[entrait(Foo, mockall)]

fn foo(_: &D) -> u32 { unimplemented!() }

fn my_func(deps: &impl Foo) -> u32 { deps.foo() }

fn main() { let mut deps = MockFoo::new(); deps.expectfoo().returning(|| 42); asserteq!(42, my_func(&deps)); } ```

Multi-crate architecture

A common technique for Rust application development is to choose a multi-crate architecture. There are usually two main ways to go about it:

1. The call graph and crate dependency go in the same direction.
2. The call graph and crate dependency go in opposite directions.

The first option is how libraries are normally used: Its functions are just called, without any indirection.

The second option can be referred to as a variant of the dependency inversion principle. This is usually a desirable architectural property, and achieving this with entrait is what this section is about.

The main goal is to be able to express business logic centrally, and avoid depending directly on infrastructure details (onion architecture). All of the examples in this section make some use of traits and trait delegation.

Case 1: Concrete leaf dependencies

Earlier it was mentioned that when concrete-type dependencies are used, the T in Impl<T>, your application, and the type of the dependency have to match. But this is only partially true. It really comes down to which traits are implemented on what types:

```rust pub struct Config { foo: String, }

[entrait_export(pub GetFoo)]

fn get_foo(config: &Config) -> &str { &config.foo } ```

Here we actually have a trait GetFoo that is implemented two times: for Impl<T> where T: GetFoo and for Config. The first implementation is delegating to the other one.

For making this work with any downstream application type, we just have to manually implement GetFoo for that application:

rust struct App { config: some_upstream_crate::Config, } impl some_upstream_crate::GetFoo for App { fn get_foo(&self) -> &str { self.config.get_foo() } }

Case 2: Hand-written trait as a leaf dependency

Using a concrete type like Config from the first case can be contrived in many situations. Sometimes a good old hand-written trait definition will do the job much better:

```rust

[entrait]

pub trait System { fn current_time(&self) -> u128; } ```

What the attribute does in this case, is just to generate the correct blanket implementations of the trait: delegation and mocks.

To use with some App, the app type itself should implement the trait.

Case 3: Hand-written trait as a leaf dependency using dynamic dispatch

Sometimes it might be desirable to have a delegation that involves dynamic dispatch. Entrait has a delegate_by = option, where you can pass an alternative trait to use as part of the delegation strategy. To enable dynamic dispatch, use ref:

```rust

[entrait(delegate_by=ref)]

trait ReadConfig: 'static { fn read_config(&self) -> &str; } ```

To use this together with some App, it should implement the AsRef<dyn ReadConfig> trait.

Case 4: Truly inverted internal dependencies - static dispatch

All cases up to this point have been leaf dependencies. Leaf dependencies are delegations that exit from the Impl<T> layer, using delegation targets involving concete T's. This means that it is impossible to continue to use the entrait pattern and extend your application behind those abstractions.

To make your abstraction extendable and your dependency internal, we have to keep the T generic inside the [Impl] type. To make this work, we have to make use of two helper traits:

```rust

[entrait(RepositoryImpl, delegate_by = DelegateRepository)]

pub trait Repository { fn fetch(&self) -> i32; } ```

This syntax introduces a total of three traits:

• Repository: The dependency, what the rest of the application directly calls.
• RepositoryImpl<T>: The delegation target, a trait which needs to be implemented by some Target type.
• DelegateRepository<T>: The delegation selector, that selects the specific Target type to be used for some specific App.

This design makes it possible to separate concerns into three different crates, ordered from most-upstream to most-downstream: 1. Core logic: Depend on and call Repository methods. 2. External system integration: Provide some implementation of the repository, by implementing RepositoryImpl<T>. 3. Executable: Construct an App that selects a specific repository implementation from crate 2.

All delegation from Repository to RepositoryImpl<T> goes via the DelegateRepository<T> trait. The method signatures in RepositoryImpl<T> are static, and receives the &Impl<T> via a normal parameter. This allows us to continue using entrait patterns within those implementations!

In crate 2, we have to provide an implementation of RepositoryImpl<T>. This can either be done manually, or by using the [entrait] attribute on an impl block:

```rust pub struct MyRepository;

[entrait]

impl crate1::RepositoryImpl for MyRepository { // this function has the now-familiar entrait-compatible signature: fn fetch(deps: &D) -> i32 { unimplemented!() } } ```

Entrait will split this trait implementation block in two: An inherent one containing the original code, and a proper trait implementation which performs the delegation.

In the end, we just have to implement our DelegateRepository<T>:

rust // in crate3: struct App; impl crate1::DelegateRepository<Self> for App { type Target = crate2::MyRepository; } fn main() { /* ... */ }

Case 5: Truly inverted internal dependencies - dynamic dispatch

A small variation of case 4: Use delegate_by=ref instead of a custom trait. This makes the delegation happen using dynamic dispatch.

The implementation syntax is almost the same as in case 4, only that the entrait attribute must now be #[entrait(ref)]:

```rust

[entrait(RepositoryImpl, delegate_by=ref)]

pub trait Repository { fn fetch(&self) -> i32; }

pub struct MyRepository;

[entrait(ref)]

impl RepositoryImpl for MyRepository { fn fetch(deps: &D) -> i32 { unimplemented!() } } ```

The app must now implement AsRef<dyn RepositoryImpl<Self>>.

Options and features

Trait visibility

by default, entrait generates a trait that is module-private (no visibility keyword). To change this, just put a visibility specifier before the trait name:

```rust use entrait::*;

[entrait(pub Foo)] // <-- public trait

fn foo(deps: &D) { // <-- private function } ```

async support

Since Rust at the time of writing does not natively support async methods in traits, you may opt in to having #[async_trait] generated for your trait. Enable the boxed-futures cargo feature and pass the box_future option like this:

```rust

[entrait(Foo, box_future)]

async fn foo(deps: &D) { } ``` This is designed to be forwards compatible with static async fn in traits. When that day comes, you should be able to just remove that option and get a proper zero-cost future.

There is a cargo feature to automatically apply #[async_trait] to every generated async trait: use-boxed-futures.

Zero-cost async inversion of control - preview mode

Entrait has experimental support for zero-cost futures. A nightly Rust compiler is needed for this feature.

The entrait option is called associated_future, and uses GATs and feature(type_alias_impl_trait). This feature generates an associated future inside the trait, and the implementations use impl Trait syntax to infer the resulting type of the future:

```rust

![feature(typealiasimpl_trait)]

use entrait::*;

[entrait(Foo, associated_future)]

async fn foo(deps: &D) { } ```

There is a feature for turning this on everywhere: use-associated-futures.

Integrating with other fn-targeting macros, and no_deps

Some macros are used to transform the body of a function, or generate a body from scratch. For example, we can use feignhttp to generate an HTTP client. Entrait will try as best as it can to co-exist with macros like these. Since entrait is a higher-level macro that does not touch fn bodies (it does not even try to parse them), entrait should be processed after, which means it should be placed before lower level macros. Example:

```rust

[entrait(FetchThing, no_deps)]

[feignhttp::get("https://my.api.org/api/{param}")]

async fn fetch_thing(#[path] param: String) -> feignhttp::Result {} ```

Here we had to use the no_deps entrait option. This is used to tell entrait that the function does not have a deps parameter as its first input. Instead, all the function's inputs get promoted to the generated trait method.

Conditional compilation of mocks

Most often, you will only need to generate mock implementations for test code, and skip this for production code. A notable exception to this is when building libraries. When an application consists of several crates, downstream crates would likely want to mock out functionality from libraries.

Entrait calls this exporting, and it unconditionally turns on autogeneration of mock implementations:

```rust

[entrait_export(pub Bar)]

fn bar(deps: &()) {} or rust

[entrait(pub Foo, export)]

fn foo(deps: &()) {} ```

It is also possible to reduce noise by doing use entrait::entrait_export as entrait.

Feature overview

| Feature | Implies | Description | | ------------------- | --------------- | ------------------- | | unimock | | Adds the [unimock] dependency, and turns on Unimock implementations for all traits. | | use-boxed-futures | boxed-futures | Automatically applies the [asynctrait] macro to async trait methods. | | use-associated-futures | | Automatically transforms the return type of async trait methods into an associated future by using type-alias-impl-trait syntax. Requires a nightly compiler. | | boxed-futures | | Pulls in the [asynctrait] optional dependency, enabling the box_future entrait option (macro parameter). |

"Philosophy"

The entrait crate is central to the entrait pattern, an opinionated yet flexible and Rusty way to build testable applications/business logic.

To understand the entrait model and how to achieve Dependency Injection (DI) with it, we can compare it with a more widely used and classical alternative pattern: Object-Oriented DI.

In object-oriented DI, each named dependency is a separate object instance. Each dependency exports a set of public methods, and internally points to a set of private dependencies. A working application is built by fully instantiating such an object graph of interconnected dependencies.

Entrait was built to address two drawbacks inherent to this design:

• Representing a graph of objects (even if acyclic) in Rust usually requires reference counting/heap allocation.
• Each "dependency" abstraction often contains a lot of different functionality. As an example, consider DDD-based applications consisting of DomainServices. There will typically be one such class per domain object, with a lot of methods in each. This results in dependency graphs with fewer nodes overall, but the number of possible call graphs is much larger. A common problem with this is that the actual dependencies—the functions actually getting called—are encapsulated and hidden away from public interfaces. To construct valid dependency mocks in unit tests, a developer will have to read through full function bodies instead of looking at signatures.

entrait solves this by:

• Representing dependencies as traits instead of types, automatically profiting from Rust's builtin zero-cost abstraction tool.
• Giving users a choice between fine and coarse dependency granularity, by enabling both single-function traits and module-based traits.
• Always declaring dependencies at the function signature level, close to call sites, instead of at module level.

Limitations

This section lists known limitations of entrait:

Cyclic dependency graphs

Cyclic dependency graphs are impossible with entrait. In fact, this is not a limit of entrait itself, but with Rust's trait solver. It is not able to prove that a type implements a trait if it needs to prove that it does in order to prove it.

While this is a limitation, it is not necessarily a bad one. One might say that a layered application architecture should never contain cycles. If you do need recursive algorithms, you could model this as utility functions outside of the entraited APIs of the application.