1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
//! Host-registrable async stream enrichment.
//!
//! [`Block::render`](super::Block::render) is synchronous, so a block
//! cannot fetch anything while it renders. The CMS already works around
//! that for its own chooser blocks: `enrich_chooser_refs_async` walks a
//! parsed stream **before** the sync render and writes resolved data
//! into each block's `value` under `_`-prefixed keys, so the template
//! only ever reads what is already there.
//!
//! That walker knows a fixed set of block types. This hook opens the
//! same moment to host applications: a block that needs a query result,
//! a third-party API response or anything else async can fill its own
//! value in, then render synchronously like every other block.
//!
//! ```ignore
//! fn enrich<'a>(stream: &'a mut serde_json::Value, pool: &'a Pool)
//! -> Pin<Box<dyn Future<Output = ()> + Send + 'a>>
//! {
//! Box::pin(async move {
//! // walk `stream`, fill `value._rows` on blocks you own
//! })
//! }
//! rustango_cms::register_block_enricher!(enrich);
//! ```
//!
//! ## Contract
//!
//! * **Own your own block types.** Enrichers all see the same stream.
//! Match on `type` and touch nothing else; the CMS's own chooser
//! enrichment has already run by this point and its `_` keys are not
//! yours to rewrite.
//! * **Use the `_` prefix**, as the built-in enrichment does, so
//! injected keys can never collide with an author-defined field.
//! * **Recurse yourself** if your blocks can nest inside `Stream` /
//! `Repeat` fields. The fan-out hands each enricher the whole stream
//! once rather than guessing at a traversal that fits every host.
//! * **Don't fail the page.** Report a problem by writing it into the
//! value (`_error`) so the template can render it; the enrichment
//! moment has no error channel, because a report that cannot load is
//! a broken widget, not a broken page.
//!
//! Enrichers run **sequentially** in registration order, and each one
//! gets `&mut` to the whole stream — concurrency across enrichers would
//! need a lock per call and buy nothing, since the work inside one
//! enricher (which is where the fan-out actually pays) is free to be as
//! concurrent as it likes.
use Future;
use Pin;
use Pool;
/// Boxed future returned by a [`BlockEnricher`]. Borrows both the
/// stream it mutates and the context it reads from, so an enricher can
/// hold either across an await without cloning.
pub type EnrichFuture<'a> = ;
/// What an enricher is told about the render it is part of.
///
/// A struct rather than a bare `&Pool` so this can gain fields without
/// breaking every registered enricher — and because the pool alone is
/// not enough to answer "where am I?", which is the first thing a block
/// that inherits something from its page needs to know.
///
/// `#[non_exhaustive]` so a new field breaks no one: a host that
/// drives the walker builds one with [`EnrichCtx::new`].
/// A host-registered async enrichment pass over one parsed stream.
///
/// A plain `fn` pointer rather than a boxed closure: the registration
/// is collected by `inventory` at link time, which needs a value that
/// can be built in a `static` initializer.
,
);
collect!;
/// Register a [`BlockEnricher`] at compile time.
///
/// The submission lives in a static initializer, so a binary that never
/// otherwise mentions the containing module can have it stripped by the
/// linker. Reference the module from `main` (the `blocks::link()`
/// convention) to keep it.
/// Run every registered enricher over `stream`, in registration order.
///
/// Called from the public pre-render right after the built-in chooser
/// enrichment, so hosts see a stream whose `page_chooser` / `image` /
/// `snippet_chooser` blocks are already resolved.
///
/// A panicking enricher is **not** caught here, unlike the sync hooks
/// in [`crate::hooks`]: catching across an await point would need the
/// future to be `UnwindSafe`, which a `&mut` borrow of the stream is
/// not. An enricher that panics takes the request down — so keep the
/// fallible parts inside a `Result` and write the failure into the
/// value.
pub async
/// Whether any enricher is registered. Lets a caller skip the walk
/// entirely on the overwhelmingly common path where a deployment has
/// registered none.