The Decorator Pattern in Rust

24 min read

In TypeScript the decorator pattern means wrapping an object in another object that has the same interface, so the wrapper can add behavior — logging, caching, retries, buffering — without the wrapped object knowing. (This is the design pattern, not the TypeScript @decorator syntax, which is a different thing entirely — more on that below.) Rust supports the exact same idea: a wrapper type that holds an inner value and implements the same trait, forwarding each method through and adding behavior around the call. The twist is that Rust gives you two ways to hold the inner value — a Box<dyn Trait> (runtime, OO-shaped) or a generic type parameter <S> (compile-time, zero-cost) — and the second is usually the idiomatic one. At the end we look at how the tower crate generalizes “a service wrapped by another service” into the reusable Layer/Service abstraction that powers axum’s middleware.

Quick Overview

A decorator is a wrapper that:

has the same interface as the thing it wraps (so callers can’t tell the difference), and
adds behavior around the wrapped object’s methods (before, after, or instead of forwarding).

You stack decorators to compose behavior: Retry(Cache(HttpClient)) is a client that retries, and each retry checks the cache first, and a cache miss hits the real network. Each layer is independent and reusable.

In Rust this is “a type that holds an inner value and implements the same trait.” There are three encodings to know:

Trait-object decorator (inner: Box<dyn Trait>) — runtime composition, the closest match to the TypeScript shape; layers chosen from config, heterogeneous lists.
Generic decorator (inner: S where S: Trait) — compile-time composition, monomorphized to zero-cost static dispatch; the idiomatic default.
Function decorator — a function that takes a closure and returns a wrapped closure; the lightest form when “the thing” is just a function.

Note: This page is about wrapping types to add behavior. For swapping an algorithm (not wrapping it) see the sibling strategy-pattern.md; for building the wrapped values see factory-pattern.md. The dyn-vs-generics mechanics live in Section 09: Trait Objects and Section 09: Trait Bounds.

TypeScript/JavaScript Example

A classic data source that can be read and written, plus two decorators that transform the data on the way through. Each decorator implements the same DataSource interface and holds an inner: DataSource, so they nest freely.

1
// TypeScript - the classic OO decorator pattern
2
interface DataSource {
3
  read(): string;
4
  write(data: string): void;
5
}
6

7
class FileSource implements DataSource {
8
  constructor(private contents: string) {}
9
  read(): string {
10
    return this.contents;
11
  }
12
  write(data: string): void {
13
    this.contents = data;
14
  }
15
}
16

17
// A decorator wraps an inner DataSource and forwards through it.
18
class UppercaseDecorator implements DataSource {
19
  constructor(private inner: DataSource) {}
20
  read(): string {
21
    return this.inner.read().toUpperCase();
22
  }
23
  write(data: string): void {
24
    this.inner.write(data.toUpperCase());
25
  }
26
}
27

28
class TrimDecorator implements DataSource {
29
  constructor(private inner: DataSource) {}
30
  read(): string {
31
    return this.inner.read().trim();
32
  }
33
  write(data: string): void {
34
    this.inner.write(data.trim());
35
  }
36
}
37

38
// Compose: trim first, then uppercase.
39
const source: DataSource = new UppercaseDecorator(
40
  new TrimDecorator(new FileSource("  hello world  ")),
41
);
42

43
console.log(source.read()); // "HELLO WORLD"
44
source.write("  changed  ");
45
console.log(source.read()); // "CHANGED"

Key properties of the TypeScript version: the decorator and the base share interface DataSource; the decorator stores inner: DataSource (a reference to anything implementing the interface); and you compose by passing one into another’s constructor.

Warning: Do not confuse this design pattern with TypeScript’s @decorator syntax (@Component, @Injectable). Those are annotations applied to classes/methods — a metaprogramming feature, the rough analog of which in Rust is a macro (Section 14: Macros), not the wrapping pattern on this page. The Rust equivalent of this pattern is wrapping a value and re-implementing its trait.

Rust Equivalent

There are two idiomatic encodings. Start with the trait-object version because it maps one-to-one onto the TypeScript above, then see the generic version that Rust usually prefers.

Version 1: trait-object decorator (the OO shape)

The inner value is a Box<dyn DataSource> — exactly like TypeScript’s inner: DataSource, a pointer to anything implementing the trait, chosen at runtime.

1
trait DataSource {
2
    fn read(&self) -> String;
3
    fn write(&mut self, data: &str);
4
}
5

6
struct FileSource {
7
    contents: String,
8
}
9

10
impl DataSource for FileSource {
11
    fn read(&self) -> String {
12
        self.contents.clone()
13
    }
14
    fn write(&mut self, data: &str) {
15
        self.contents = data.to_string();
16
    }
17
}
18

19
// A decorator OWNS the inner source (a boxed trait object) and forwards through it.
20
struct UppercaseDecorator {
21
    inner: Box<dyn DataSource>,
22
}
23

24
impl DataSource for UppercaseDecorator {
25
    fn read(&self) -> String {
26
        self.inner.read().to_uppercase()
27
    }
28
    fn write(&mut self, data: &str) {
29
        self.inner.write(&data.to_uppercase());
30
    }
31
}
32

33
struct TrimDecorator {
34
    inner: Box<dyn DataSource>,
35
}
36

37
impl DataSource for TrimDecorator {
38
    fn read(&self) -> String {
39
        self.inner.read().trim().to_string()
40
    }
41
    fn write(&mut self, data: &str) {
42
        self.inner.write(data.trim());
43
    }
44
}
45

46
fn main() {
47
    let base = FileSource { contents: "  hello world  ".to_string() };
48
    // Wrap base in trim, then wrap that in uppercase. Layers compose.
49
    let mut source: Box<dyn DataSource> = Box::new(UppercaseDecorator {
50
        inner: Box::new(TrimDecorator { inner: Box::new(base) }),
51
    });
52

53
    println!("{}", source.read());
54
    source.write("  changed  ");
55
    println!("{}", source.read());
56
}

Real output:

1
HELLO WORLD
2
CHANGED

This is the same behavior and the same shape as the TypeScript: each decorator implements DataSource, holds an inner: Box<dyn DataSource>, and forwards through it. Composition happens at runtime, and the concrete type is erased behind dyn.

Version 2: generic decorator (static dispatch, zero-cost)

Make the inner type a type parameter instead of a boxed trait object. Now there is no Box, no heap allocation, and no vtable — the compiler monomorphizes each layer and can inline straight through the stack.

1
trait DataSource {
2
    fn read(&self) -> String;
3
}
4

5
struct FileSource {
6
    contents: String,
7
}
8

9
impl DataSource for FileSource {
10
    fn read(&self) -> String {
11
        self.contents.clone()
12
    }
13
}
14

15
// The inner source is a TYPE PARAMETER, so there is no Box and no vtable.
16
struct Uppercase<S: DataSource> {
17
    inner: S,
18
}
19

20
impl<S: DataSource> DataSource for Uppercase<S> {
21
    fn read(&self) -> String {
22
        self.inner.read().to_uppercase()
23
    }
24
}
25

26
struct Trim<S: DataSource> {
27
    inner: S,
28
}
29

30
impl<S: DataSource> DataSource for Trim<S> {
31
    fn read(&self) -> String {
32
        self.inner.read().trim().to_string()
33
    }
34
}
35

36
fn main() {
37
    let base = FileSource { contents: "  hello  ".to_string() };
38
    // The full type is Uppercase<Trim<FileSource>> -- known at compile time.
39
    let source = Uppercase { inner: Trim { inner: base } };
40
    println!("{}", source.read());
41

42
    // Proof there is no boxing: the concrete type is statically known.
43
    let _the_type: Uppercase<Trim<FileSource>> = source;
44
}

Real output:

1
HELLO

The stacked value has the concrete type Uppercase<Trim<FileSource>>. The whole decorator chain is one statically-known type, so the optimizer treats the layers as ordinary function calls it can inline. This is the version to reach for first.

Tip: Choose the encoding by asking “do I know the layers at compile time?” If yes (the common case), use generics. If the set of decorators is open or built from config at runtime, use Box<dyn Trait>. You can even mix them: a generic decorator wrapping a Box<dyn DataSource> base.

Detailed Explanation

A decorator implements the trait it wraps

The defining move — in both languages — is that the wrapper has the same interface as the wrapped value. In TypeScript: class UppercaseDecorator implements DataSource. In Rust: impl DataSource for UppercaseDecorator. Because the wrapper is a DataSource, callers that expect a DataSource accept it transparently, and you can wrap a decorator in another decorator without limit.

Each method does one of three things: forward to the inner value unchanged, transform the arguments before forwarding, or transform the result after forwarding. read forwards then post-processes (.to_uppercase()); write pre-processes then forwards (&data.to_uppercase()). That before/after symmetry is the whole pattern.

`Box<dyn>` vs `<S>` — runtime vs compile-time composition

In the trait-object version, inner: Box<dyn DataSource> is a fat pointer (data pointer + vtable pointer). Every self.inner.read() is a virtual call dispatched through the vtable at runtime — exactly like a TypeScript method call on an interface-typed field. The concrete type is erased; you can store wildly different DataSources in the same field, and you can build the stack from a loop or config.

In the generic version, inner: S is the concrete inner value, inlined into the struct’s memory. Uppercase<Trim<FileSource>> is a single struct with the FileSource’s String nested two structs deep — no pointers, no heap, no vtable. The compiler generates a specialized read for that exact type and can inline the entire chain. The cost is that the full type is “spelled out” in your signatures, and you cannot put two different stacks in the same Vec without boxing.

This is the same static-vs-dynamic-dispatch trade-off you meet everywhere in Rust (Section 09: Trait Objects), applied to the inner field of a wrapper.

You already use this pattern — in the standard library

Rust’s I/O traits are built on decoration. BufReader<R> wraps any R: Read and adds buffering, and BufReader<R> is itself a Read, so it composes. Same for BufWriter<W>, flate2’s GzEncoder<W>, and so on — each wraps a Read/Write and is one too.

1
use std::io::{BufReader, Read};
2

3
fn main() {
4
    // `&[u8]` implements Read. BufReader<R> wraps any Read and adds buffering;
5
    // it is itself a Read, so it composes -- the std-library decorator pattern.
6
    let data: &[u8] = b"hello, decorators";
7
    let mut reader = BufReader::new(data);
8
    let mut out = String::new();
9
    reader.read_to_string(&mut out).unwrap();
10
    println!("read {} bytes: {out}", out.len());
11

12
    // The wrapped type is BufReader<&[u8]> -- static, zero-cost composition.
13
    fn assert_is_read<R: Read>(_: &R) {}
14
    let again = BufReader::new(b"x".as_slice());
15
    assert_is_read(&again);
16
}

Real output:

1
read 17 bytes: hello, decorators

BufReader::new is the generic decorator pattern, verbatim: a wrapper type, parameterized by the type it wraps, implementing the same trait. When you see BufReader<File>, you are reading a decorator chain.

Decoration vs inheritance

The TypeScript extends-and-super approach to “add behavior to a method” is inheritance; decoration is the composition alternative (“favor composition over inheritance”). Rust has no inheritance at all — there is no extends, no super, no base class. So in Rust, wrapping is not one option among several; it is the mechanism for layering behavior over an existing type. That makes the decorator pattern feel less like a “pattern” in Rust and more like the default way you build things up.

Key Differences

Aspect	TypeScript decorator	Rust decorator
Shared interface	`class W implements I`	`impl I for W`
Inner field	`private inner: I` (always a reference)	`Box<dyn I>` (runtime) or `S: I` (compile-time)
Dispatch	always dynamic (interface method call)	your choice: vtable (`dyn`) or monomorphized (`<S>`)
Cost of a layer	a heap object + a virtual call	`dyn`: a pointer + virtual call; `<S>`: zero (inlined)
Type after stacking	still `I` (erased)	`dyn`: erased; `<S>`: full type `Uppercase<Trim<...>>`
Heterogeneous list of stacks	trivial (`I[]`)	needs `Vec<Box<dyn I>>`
Inheritance available?	yes (`extends`/`super`) — the alternative	no — decoration is the main tool
`@decorator` syntax relation	unrelated metaprogramming feature	the analog is a macro, not this pattern

The headline difference is that Rust lets you keep the decorator pattern’s flexibility while paying none of its runtime cost, by choosing the generic encoding. TypeScript’s interface dispatch is always virtual.

Common Pitfalls

Pitfall 1: storing a bare `dyn Trait` in a field

A TypeScript developer writes inner: DataSource and expects the Rust field to be inner: dyn DataSource. But dyn DataSource is unsized — its size isn’t known at compile time — so it can’t live inline in a struct. You must put it behind a pointer (Box<dyn DataSource>, &dyn DataSource, Rc<dyn DataSource>) or make it a generic parameter.

1
trait DataSource {
2
    fn read(&self) -> String;
3
}
4

5
// does not compile (E0277): a bare `dyn` field is unsized.
6
struct Uppercase {
7
    inner: dyn DataSource,
8
}
9

10
fn main() {
11
    let _ = std::mem::size_of::<Uppercase>();
12
}

The real compiler error:

1
error[E0277]: the size for values of type `(dyn DataSource + 'static)` cannot be known at compilation time
2
   --> src/main.rs:11:33
3
    |
4
 11 |     let _ = std::mem::size_of::<Uppercase>();
5
    |                                 ^^^^^^^^^ doesn't have a size known at compile-time
6
    |
7
    = help: within `Uppercase`, the trait `Sized` is not implemented for `(dyn DataSource + 'static)`
8
note: required because it appears within the type `Uppercase`
9
   --> src/main.rs:6:8
10
    |
11
  6 | struct Uppercase {
12
    |        ^^^^^^^^^

Fix: inner: Box<dyn DataSource> for the runtime version, or struct Uppercase<S: DataSource> { inner: S } for the generic version.

Pitfall 2: reaching for `impl Trait` in the field type

The next instinct is inner: impl DataSource. But impl Trait is only allowed in function argument and return position, never in a struct field.

1
trait DataSource {
2
    fn read(&self) -> String;
3
}
4

5
// does not compile (E0562): `impl Trait` is not allowed in struct fields.
6
struct Uppercase {
7
    inner: impl DataSource,
8
}
9

10
fn main() {}

The real compiler error:

1
error[E0562]: `impl Trait` is not allowed in field types
2
 --> src/main.rs:7:12
3
  |
4
7 |     inner: impl DataSource,
5
  |            ^^^^^^^^^^^^^^^
6
  |
7
  = note: `impl Trait` is only allowed in arguments and return types of functions and methods

Fix: a named generic parameter, struct Uppercase<S: DataSource> { inner: S }. That gives you the same “any inner type that implements DataSource” meaning that impl Trait looks like it should provide.

Pitfall 3: forgetting that decorators are nested types, not just nested values

With the generic encoding, every wrap changes the type. If a function returns “a decorated source,” you cannot write the return type as DataSource — you must either spell the full nested type, use impl DataSource, or box it. Trying to return two different stacks from the two arms of an if will fail to unify unless you box them into Box<dyn DataSource>. This is the same “mismatched-types from heterogeneous branches” issue covered in strategy-pattern.md; the fix is the same: box at the seam where the concrete type must be forgotten.

Pitfall 4: assuming `dyn` decoration is “free” like in TypeScript

In TypeScript every method call is already a dynamic dispatch, so a Box<dyn> decorator chain feels identical. In Rust it is not free relative to the generic version: each dyn layer is a heap allocation plus a virtual call the optimizer usually cannot inline through. On a hot path, prefer the generic encoding. Use dyn deliberately, when you need runtime flexibility — not by default.

Best Practices

Default to the generic encoding (struct Deco<S: Trait> { inner: S }). It is zero-cost and composes by type. Reach for Box<dyn Trait> only when the layers are chosen at runtime or you need a heterogeneous collection of stacks.
Keep the trait small and focused. Decorators must implement every method, so a fat trait makes every wrapper verbose. A narrow trait (one or two methods) keeps decorators short and makes them dyn-compatible for the boxed version.
Provide a new constructor (Deco::new(inner)) so callers compose with Retry::new(Cache::new(base)) instead of struct-literal nesting. See factory-pattern.md.
Hold shared per-decorator state with the right cell. A caching decorator needs interior mutability behind &self; use RefCell<T> for single-threaded and Mutex<T>/RwLock<T> for shared-across-threads. See Section 10: Smart Pointers.
For middleware over a request/response service, do not hand-roll it — use tower. Layer/Service is the community-standard, composable form of this pattern (next section).
Don’t confuse the pattern with #[derive]/attribute macros. If you actually want to annotate a type and generate code, that’s a macro (Section 14: Macros), not a wrapper type.

Real-World Example: a caching + retrying HTTP client

A production-flavored client that layers two independent concerns over a base fetcher: a cache decorator that memoizes responses, and a retry decorator that re-attempts failed fetches. Each is a generic wrapper implementing the shared Fetcher trait; the cache uses RefCell for interior mutability behind &self.

1
use std::cell::RefCell;
2
use std::collections::HashMap;
3

4
// A simple synchronous "fetcher": given a URL, return a body or an error.
5
trait Fetcher {
6
    fn fetch(&self, url: &str) -> Result<String, String>;
7
}
8

9
// The base fetcher: pretend this hits the network.
10
struct HttpFetcher;
11
impl Fetcher for HttpFetcher {
12
    fn fetch(&self, url: &str) -> Result<String, String> {
13
        println!("[http] GET {url}");
14
        Ok(format!("body of {url}"))
15
    }
16
}
17

18
// Decorator: remember responses so repeated URLs skip the inner fetch.
19
struct Cached<F: Fetcher> {
20
    inner: F,
21
    cache: RefCell<HashMap<String, String>>,
22
}
23
impl<F: Fetcher> Cached<F> {
24
    fn new(inner: F) -> Self {
25
        Cached { inner, cache: RefCell::new(HashMap::new()) }
26
    }
27
}
28
impl<F: Fetcher> Fetcher for Cached<F> {
29
    fn fetch(&self, url: &str) -> Result<String, String> {
30
        if let Some(hit) = self.cache.borrow().get(url) {
31
            println!("[cache] hit for {url}");
32
            return Ok(hit.clone());
33
        }
34
        let body = self.inner.fetch(url)?;
35
        self.cache.borrow_mut().insert(url.to_string(), body.clone());
36
        Ok(body)
37
    }
38
}
39

40
// Decorator: retry the inner fetch up to `attempts` times on error.
41
struct Retry<F: Fetcher> {
42
    inner: F,
43
    attempts: u32,
44
}
45
impl<F: Fetcher> Fetcher for Retry<F> {
46
    fn fetch(&self, url: &str) -> Result<String, String> {
47
        let mut last = Err("never ran".to_string());
48
        for n in 1..=self.attempts {
49
            last = self.inner.fetch(url);
50
            if last.is_ok() {
51
                return last;
52
            }
53
            println!("[retry] attempt {n} failed");
54
        }
55
        last
56
    }
57
}
58

59
fn main() {
60
    // Compose: retry wraps caching wraps the real HTTP fetcher.
61
    let client = Retry {
62
        inner: Cached::new(HttpFetcher),
63
        attempts: 3,
64
    };
65

66
    println!("{:?}", client.fetch("/users/1"));
67
    println!("{:?}", client.fetch("/users/1")); // served from cache
68
    println!("{:?}", client.fetch("/users/2"));
69
}

Real output:

1
[http] GET /users/1
2
Ok("body of /users/1")
3
[cache] hit for /users/1
4
Ok("body of /users/1")
5
[http] GET /users/2
6
Ok("body of /users/2")

The second /users/1 is served from the cache without touching the HTTP layer — the cache decorator short-circuited before delegating. Each concern (caching, retry, transport) is a separate, testable, reusable type, and the whole client is the single static type Retry<Cached<HttpFetcher>> with no boxing.

How `tower` generalizes this: `Layer` and `Service`

The decorator pattern shows up so often in network code — logging, timeouts, retries, rate limiting, auth, compression — that the Rust ecosystem standardized it. The tower crate defines two traits:

Service<Request> — “an async function from a request to a response,” with poll_ready (backpressure) and call. This is the thing being decorated.
Layer<S> — a factory that wraps a Service S and returns a new, decorated Service. This is the decorator’s constructor.

A middleware is just a Service that holds an inner Service and adds behavior around call — the generic decorator pattern, applied to async request handlers. axum, tonic, hyper, and reqwest all speak tower, so a Layer you write works across the whole stack. Here is a logging middleware and a timing middleware stacked over a base service with ServiceBuilder:

First the dependencies (resolve and compile-verify in a probe project):

1
[dependencies]
2
tower = { version = "0.5.3", features = ["util"] }
3
tokio = { version = "1.52", features = ["rt", "macros"] }

Or run cargo add tower --features util and cargo add tokio --features rt,macros.

1
use std::convert::Infallible;
2
use std::future::Future;
3
use std::pin::Pin;
4
use std::task::{Context, Poll};
5
use std::time::Instant;
6
use tower::{Layer, Service, ServiceBuilder, ServiceExt};
7

8
// The base service: turn a request String into a response String.
9
#[derive(Clone)]
10
struct Greeter;
11

12
impl Service<String> for Greeter {
13
    type Response = String;
14
    type Error = Infallible;
15
    type Future = Pin<Box<dyn Future<Output = Result<String, Infallible>> + Send>>;
16
    fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
17
        Poll::Ready(Ok(()))
18
    }
19
    fn call(&mut self, req: String) -> Self::Future {
20
        Box::pin(async move { Ok(format!("Hello, {req}!")) })
21
    }
22
}
23

24
// Decorator 1: log each request and when the inner service finishes.
25
#[derive(Clone)]
26
struct Logging<S> {
27
    inner: S,
28
}
29
impl<S> Service<String> for Logging<S>
30
where
31
    S: Service<String, Response = String> + Clone + Send + 'static,
32
    S::Future: Send + 'static,
33
{
34
    type Response = S::Response;
35
    type Error = S::Error;
36
    type Future = Pin<Box<dyn Future<Output = Result<S::Response, S::Error>> + Send>>;
37
    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
38
        self.inner.poll_ready(cx)
39
    }
40
    fn call(&mut self, req: String) -> Self::Future {
41
        println!("[log] request = {req:?}");
42
        // Clone-and-swap so the *ready* inner service is the one we call.
43
        let clone = self.inner.clone();
44
        let mut inner = std::mem::replace(&mut self.inner, clone);
45
        Box::pin(async move {
46
            let res = inner.call(req).await;
47
            println!("[log] done");
48
            res
49
        })
50
    }
51
}
52
// The Layer is the factory for the decorator: it knows how to wrap any S.
53
#[derive(Clone)]
54
struct LoggingLayer;
55
impl<S> Layer<S> for LoggingLayer {
56
    type Service = Logging<S>;
57
    fn layer(&self, inner: S) -> Logging<S> {
58
        Logging { inner }
59
    }
60
}
61

62
// Decorator 2: time how long the inner service took.
63
#[derive(Clone)]
64
struct Timing<S> {
65
    inner: S,
66
}
67
impl<S> Service<String> for Timing<S>
68
where
69
    S: Service<String, Response = String> + Clone + Send + 'static,
70
    S::Future: Send + 'static,
71
{
72
    type Response = S::Response;
73
    type Error = S::Error;
74
    type Future = Pin<Box<dyn Future<Output = Result<S::Response, S::Error>> + Send>>;
75
    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
76
        self.inner.poll_ready(cx)
77
    }
78
    fn call(&mut self, req: String) -> Self::Future {
79
        let clone = self.inner.clone();
80
        let mut inner = std::mem::replace(&mut self.inner, clone);
81
        Box::pin(async move {
82
            let start = Instant::now();
83
            let res = inner.call(req).await;
84
            let _elapsed = start.elapsed();
85
            println!("[time] inner service finished");
86
            res
87
        })
88
    }
89
}
90
#[derive(Clone)]
91
struct TimingLayer;
92
impl<S> Layer<S> for TimingLayer {
93
    type Service = Timing<S>;
94
    fn layer(&self, inner: S) -> Timing<S> {
95
        Timing { inner }
96
    }
97
}
98

99
#[tokio::main(flavor = "current_thread")]
100
async fn main() {
101
    // ServiceBuilder stacks layers outside-in: Logging wraps Timing wraps Greeter.
102
    let mut service = ServiceBuilder::new()
103
        .layer(LoggingLayer)
104
        .layer(TimingLayer)
105
        .service(Greeter);
106

107
    let response = service
108
        .ready()
109
        .await
110
        .unwrap()
111
        .call("world".to_string())
112
        .await
113
        .unwrap();
114

115
    println!("final = {response}");
116
}

Real output:

1
[log] request = "world"
2
[time] inner service finished
3
[log] done
4
final = Hello, world!

The structure is identical to the synchronous Cached/Retry decorators: each middleware is struct M<S> { inner: S } that implements the same trait (Service) and forwards through inner while adding behavior. The two new ideas tower adds are (1) the Layer trait, which packages “how to wrap” so a ServiceBuilder can stack decorators declaratively (outer-to-inner), and (2) the poll_ready/Future machinery for async backpressure. The .layer(LoggingLayer).layer(TimingLayer) call reads top-down as the order requests flow through — Logging sees the request first and the response last, just like Retry(Cache(...)).

Note: The clone-and-mem::replace dance in call is the standard tower idiom: a Service may only be called after poll_ready returns Ready, and the readiness applies to this service instance, so middleware clones the inner service to keep a ready copy for the spawned future. In an axum app you almost never write this by hand — you use the ready-made layers from tower-http (TraceLayer, TimeoutLayer, CompressionLayer, CorsLayer, …), which are exactly these decorators, written once. See Section 16: Web APIs and Section 23: Ecosystem.

Exercises

Exercise 1: stacked notifiers

Difficulty: Beginner

Objective: Build the basic decorator shape — a wrapper that implements the same trait as the thing it wraps.

Instructions: Define a trait Notifier { fn send(&self, msg: &str) -> String; } and a base struct Base whose send returns format!("email: {msg}"). Write a generic decorator Urgent<N: Notifier> that prepends "[URGENT] " to the message before delegating, and a generic decorator AlsoSlack<N: Notifier> that calls the inner notifier and then appends "; slack: {msg}" to the result. Compose AlsoSlack { inner: Urgent { inner: Base } } and send "disk full".

Solution

1
trait Notifier {
2
    fn send(&self, msg: &str) -> String;
3
}
4

5
struct Base;
6
impl Notifier for Base {
7
    fn send(&self, msg: &str) -> String {
8
        format!("email: {msg}")
9
    }
10
}
11

12
// Prepend a tag, then delegate.
13
struct Urgent<N: Notifier> {
14
    inner: N,
15
}
16
impl<N: Notifier> Notifier for Urgent<N> {
17
    fn send(&self, msg: &str) -> String {
18
        self.inner.send(&format!("[URGENT] {msg}"))
19
    }
20
}
21

22
// Delegate, then add a Slack copy of the message it was handed.
23
struct AlsoSlack<N: Notifier> {
24
    inner: N,
25
}
26
impl<N: Notifier> Notifier for AlsoSlack<N> {
27
    fn send(&self, msg: &str) -> String {
28
        let primary = self.inner.send(msg);
29
        format!("{primary}; slack: {msg}")
30
    }
31
}
32

33
fn main() {
34
    let n = AlsoSlack { inner: Urgent { inner: Base } };
35
    println!("{}", n.send("disk full"));
36
}

Real output:

1
email: [URGENT] disk full; slack: disk full

Note how each layer sees the message at its point in the chain: AlsoSlack forwards the raw "disk full", which Urgent tags before it reaches Base, while the Slack copy uses the untagged message AlsoSlack was handed.

Exercise 2: a counting decorator with interior mutability

Difficulty: Intermediate

Objective: Add per-decorator state that mutates behind a shared &self, the way a real cache or metrics layer does.

Instructions: Define trait Source { fn value(&self) -> i64; } and a base struct Const(i64). Write a generic decorator Counting<S: Source> that counts how many times value is called and still returns the inner value. Because value takes &self, you cannot use a plain u32 field — use std::cell::Cell<u32>. Give it a Counting::new(inner) constructor. Call value three times and print the final value and call count.

Solution

1
use std::cell::Cell;
2

3
trait Source {
4
    fn value(&self) -> i64;
5
}
6

7
struct Const(i64);
8
impl Source for Const {
9
    fn value(&self) -> i64 {
10
        self.0
11
    }
12
}
13

14
struct Counting<S: Source> {
15
    inner: S,
16
    calls: Cell<u32>, // interior mutability: mutate through &self
17
}
18
impl<S: Source> Counting<S> {
19
    fn new(inner: S) -> Self {
20
        Counting { inner, calls: Cell::new(0) }
21
    }
22
}
23
impl<S: Source> Source for Counting<S> {
24
    fn value(&self) -> i64 {
25
        self.calls.set(self.calls.get() + 1);
26
        self.inner.value()
27
    }
28
}
29

30
fn main() {
31
    let s = Counting::new(Const(42));
32
    s.value();
33
    s.value();
34
    println!("value={}, calls={}", s.value(), s.calls.get());
35
}

Real output:

1
value=42, calls=3

Cell<u32> lets the decorator track state while keeping the &self signature that the trait requires — the same trick a caching decorator uses (it just stores a RefCell<HashMap<...>> instead). For a thread-safe version you would reach for AtomicU32 or Mutex<u32>.

Exercise 3: a function decorator

Difficulty: Intermediate

Objective: Apply the decorator idea to a function instead of an object — the lightest form of the pattern, and the one closest to JavaScript’s higher-order functions.

Instructions: Write fn with_logging<F>(handler: F) -> impl Fn(&str) -> String where F: Fn(&str) -> String. It should return a new closure that prints the request, calls the wrapped handler, prints the result, and returns it. Decorate a handler |name| format!("Hi {name}") and call the result with "Ada".

Solution

1
// `with_logging` takes any handler closure and returns a wrapped one.
2
fn with_logging<F>(handler: F) -> impl Fn(&str) -> String
3
where
4
    F: Fn(&str) -> String,
5
{
6
    move |req: &str| {
7
        println!("[log] handling {req:?}");
8
        let res = handler(req);
9
        println!("[log] -> {res:?}");
10
        res
11
    }
12
}
13

14
fn main() {
15
    let handler = with_logging(|name: &str| format!("Hi {name}"));
16
    println!("{}", handler("Ada"));
17
}

Real output:

1
[log] handling "Ada"
2
[log] -> "Hi Ada"
3
Hi Ada

This is the same shape as a JavaScript withLogging(fn) that returns a wrapping function — the wrapper closure moves the inner handler in and runs behavior around it. When “the thing being decorated” is just a function, this is far lighter than a trait and a wrapper struct. (tower’s Service is the async, backpressure-aware generalization of exactly this.)

The Decorator Pattern in Rust

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Version 1: trait-object decorator (the OO shape)

Version 2: generic decorator (static dispatch, zero-cost)

Detailed Explanation

A decorator implements the trait it wraps

`Box<dyn>` vs `<S>` — runtime vs compile-time composition

You already use this pattern — in the standard library

Decoration vs inheritance

Key Differences

Common Pitfalls

Pitfall 1: storing a bare `dyn Trait` in a field

Pitfall 2: reaching for `impl Trait` in the field type

Pitfall 3: forgetting that decorators are nested types, not just nested values

Pitfall 4: assuming `dyn` decoration is “free” like in TypeScript

Best Practices

Real-World Example: a caching + retrying HTTP client

How `tower` generalizes this: `Layer` and `Service`

Further Reading

Official documentation

Exercises

Exercise 1: stacked notifiers

Exercise 2: a counting decorator with interior mutability

Exercise 3: a function decorator

The Decorator Pattern in Rust

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Version 1: trait-object decorator (the OO shape)

Version 2: generic decorator (static dispatch, zero-cost)

Detailed Explanation

A decorator implements the trait it wraps

Box<dyn> vs <S> — runtime vs compile-time composition

You already use this pattern — in the standard library

Decoration vs inheritance

Key Differences

Common Pitfalls

Pitfall 1: storing a bare dyn Trait in a field

Pitfall 2: reaching for impl Trait in the field type

Pitfall 3: forgetting that decorators are nested types, not just nested values

Pitfall 4: assuming dyn decoration is “free” like in TypeScript

Best Practices

Real-World Example: a caching + retrying HTTP client

How tower generalizes this: Layer and Service

Further Reading

Official documentation

Related topics in this guide

Exercises

Exercise 1: stacked notifiers

Exercise 2: a counting decorator with interior mutability

Exercise 3: a function decorator

`Box<dyn>` vs `<S>` — runtime vs compile-time composition

Pitfall 1: storing a bare `dyn Trait` in a field

Pitfall 2: reaching for `impl Trait` in the field type

Pitfall 4: assuming `dyn` decoration is “free” like in TypeScript

How `tower` generalizes this: `Layer` and `Service`