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
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
//! What the node promises, and how its promises are checked.
//!
//! A Matter node is a set of tables: fabrics it belongs to, sessions it holds, exchanges in
//! flight, subscriptions it serves, access-control entries it enforces. On a microcontroller
//! every one of those is a fixed-capacity array whose length has to be known at compile time.
//!
//! The obvious way to express that is Cargo features — `fabrics-5`, `sessions-16` — which is
//! what the other Rust implementation does, with seventy-odd of them. Cargo features are
//! *additive and global*: two crates in one binary that want different sizes silently get the
//! union, and nothing checks the result against the specification.
//!
//! # Capacity is declared once, on the table
//!
//! Stable Rust cannot write `Vec<T, { C::SESSIONS }>`: an associated const may not appear in
//! const-generic position. So a table's capacity **is** its own const parameter —
//! `SessionTable<C, N>`, `Acl<C, N, S, T>` — and there is no second place that also claims to
//! be it. A trait constant that names a capacity it cannot size is worse than no constant at
//! all: it reads as a promise, it can carry an assertion that looks like enforcement, and the
//! table it claims to size is whatever length somebody else picked.
//!
//! What a table's capacity cannot tell you is what share of it each *fabric* is owed. That is a
//! policy, it is what the node advertises on the wire, and it is what this trait carries:
//!
//! | Constant | What it is | Section |
//! |---|---|---|
//! | [`FABRICS`](Config::FABRICS) | how many ecosystems the node can join — `SupportedFabrics` | §11.18.5.3 |
//! | [`SUBSCRIPTIONS_PER_FABRIC`](Config::SUBSCRIPTIONS_PER_FABRIC) | `SubscriptionsPerFabric` | §2.11.2.2 |
//! | [`ACL_ENTRIES_PER_FABRIC`](Config::ACL_ENTRIES_PER_FABRIC) | `AccessControlEntriesPerFabric` | §2.11.1.1, §9.10.6.7 |
//! | [`GROUPS_PER_FABRIC`](Config::GROUPS_PER_FABRIC) | `MaxGroupsPerFabric` | §2.11.1.2, §11.2.6.2 |
//! | [`GROUP_KEYS_PER_FABRIC`](Config::GROUP_KEYS_PER_FABRIC) | `MaxGroupKeysPerFabric` | §2.11.1.2, §11.2.6.3 |
//! | [`READ_PATHS`](Config::READ_PATHS) | `ReadPathsSupported` | §2.11.2.1, §11.1.4.4 |
//! | [`ICD_CLIENTS_PER_FABRIC`](Config::ICD_CLIENTS_PER_FABRIC) | `ClientsSupportedPerFabric` | §9.16.6.6 |
//! | [`ACL_AUXILIARY`](Config::ACL_AUXILIARY) | whether §9.10.4.3's Auxiliary feature is served | §6.6.6.2 |
//!
//! Every one of those is read by the crate through `C::`, and every assertion in
//! [`AssertValid`] constrains a number something reads.
//!
//! # Who checks that a table can keep the promise
//!
//! The table does, at compile time, against the `Config` it is parameterised by. A
//! `SubscriptionTable<C, N, P>` will not compile unless `N` can hold
//! `FABRICS × SUBSCRIPTIONS_PER_FABRIC`; an `Acl<C, N, S, T>` will not compile unless `N` can
//! hold `FABRICS × ACL_ENTRIES_PER_FABRIC`, `S` is at least §9.10.6.5's four and `T` at least
//! §9.10.6.6's three. The failing rule is named in the build error.
//!
//! That is the whole mechanism, and it is why §11.1.4.4's `CapabilityMinima` is built from the
//! tables rather than from this trait: the specification says each field "SHALL indicate the
//! **actual**" number, and only the table knows it.
//!
//! ```
//! use matter_kit::Config;
//!
//! /// A Thread light: room for five ecosystems, and the specification's minimum of everything.
//! struct Light;
//! impl Config for Light {}
//! ```
//!
//! Everything not named takes the value in [`DefaultConfig`].
/// What a Matter node promises each fabric, and which optional behaviours it serves.
///
/// Implement this on a zero-sized type and pass it as the `C` parameter. Every constant has a
/// default that is the specification's own minimum, so `impl Config for MyNode {}` is a
/// complete and conformant implementation.
///
/// It does **not** size anything: see the module documentation.
/// A device-sized profile that satisfies every minimum: five fabrics, sixteen sessions,
/// fifteen subscriptions.
///
/// This is the configuration the crate's own tests and examples use.
;
/// The largest message that fits the IPv6 minimum MTU (Core §4.4.4).
///
/// "Support for IPv6 fragmentation is not mandatory in Matter, and the expected supported
/// MTU is 1280 bytes … all messages, including transport headers, SHALL fit within that
/// minimal IPv6 MTU. This message size limit SHALL apply to the UDP transport."
pub const MAX_UDP_MESSAGE: usize = 1280;
/// The largest framing a secured unicast message can carry, in octets.
///
/// Message header: flags, session id, security flags and counter (8), a source node id (8) and
/// a destination node id (8) — [`MessageHeader::encoded_len`](crate::msg::MessageHeader::encoded_len)'s
/// worst case. Protocol header: flags, opcode, exchange id and protocol id (6), a vendor id (2)
/// and an acknowledged counter (4) — [`ProtocolHeader::encoded_len`](crate::msg::ProtocolHeader::encoded_len)'s.
/// Then §4.8's AEAD tag (16).
pub const MAX_MESSAGE_FRAMING: usize = + + 16;
/// The largest protocol payload that is **certain** to fit a UDP datagram once framed.
///
/// A node builds its reply in a payload buffer and hands it to the messaging layer, which adds
/// the headers and the AEAD tag. So the payload bound is the datagram bound *minus the framing*,
/// and sizing that buffer by anything else is guesswork that fails as `buffer too small` — from
/// this node, about its own reply, with nothing on the wire to explain it.
///
/// It is a floor rather than an exact figure: a message with no source node id, or on a common
/// protocol, or with nothing to acknowledge, has room to spare. Sizing to the worst case is what
/// makes "it fits" independent of which of those happens to be true.
pub const MAX_UDP_PAYLOAD: usize = MAX_UDP_MESSAGE.saturating_sub;
/// Compile-time proof that a [`Config`] is internally conformant.
///
/// Instantiating this type evaluates its assertions; every generic entry point in the crate
/// does so, which is what makes a bad `Config` a build failure at its first use.
///
/// It checks the *policy* only. Whether a table is big enough to keep that policy is checked by
/// the table — see [`Capacity`].
;
/// A table whose capacity the node states on the wire.
///
/// §11.1.4.4 requires `CapabilityMinima` to report "the **actual**" number a node supports, and
/// §11.18.5.3, §9.10.6.7, §11.2.6.2 and §11.2.6.3 do the same for their clusters. Only the table
/// knows that number, so the table is what publishes it — never [`Config`], which cannot size
/// anything, and never a value the integrator types beside it.
///
/// Implemented by [`FabricTable`](crate::fabric::FabricTable),
/// [`SessionTable`](crate::session::SessionTable),
/// [`SubscriptionTable`](crate::im::SubscriptionTable), [`Acl`](crate::acl::Acl) and
/// [`GroupKeys`](crate::group::GroupKeys).
/// A subscription table, which has one more number the node states: how many paths one
/// subscription may carry.
///
/// §11.1.4.4's `SubscribePathsSupported`, constrained to `3 to 10000`. It is separate from
/// [`Capacity`] because it is the only table with an inner capacity the specification asks
/// about, and a constant on `Capacity` that every other table answered zero to would be a
/// number that means nothing four times over.
/// Runs [`AssertValid::CHECK`] for `C`.
///
/// Call it from any `const` context — or just let the crate's generic types do it.
pub const