sprawling-wire 0.0.12

The process boundary of a sprawling city: the frames its clients speak, and the server that answers them.
Documentation 
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

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
// Copyright (c) 2026 2youg1 and the sprawling contributors

//! One declaration of a frame family, three things generated from it:
//! the enum, the name of each variant, and the table the schema hash is
//! built from.
//!
//! **A frame's spelling has one home.** A variant, a hand-written
//! `match` arm and a hand-written array would spell `RunHistory` three
//! times, and the handshake hash reads only the array; an exhaustive
//! `match` stops a new variant from compiling without a name and stops
//! nothing about a new variant missing from the array. Here the variant
//! list is the only place a frame is spelled, and the table cannot
//! disagree with it because the table is the list.
//!
//! **The table is in declaration order**, which is the order the
//! handshake hash mixes the names in. Moving a variant therefore
//! changes the hash, and an older page is refused at the handshake
//! without a `WIRE_V` bump (wire D1).
//!
//! One macro rather than two, because `Query` and `Command` differ in
//! their generic carrier and in nothing else that matters here —
//! `carried_name` already takes this shape for four newtypes.

/// Declares a frame enum together with its name table.
///
/// The optional `<Carrier = Default>` clause carries `Command`'s secret
/// parameter; `Query` has none and omits it. A variant is a unit, a set of
/// named fields, or one carried value.
macro_rules! named_frames {
    (
        $(#[$enum_attr:meta])*
        pub enum $frame:ident $(<$carrier:ident = $carried:ty>)? {
            $(
                $(#[$variant_attr:meta])*
                $variant:ident $({ $($field:tt)* })? $(( $($carried_value:tt)* ))?
            ),* $(,)?
        }

        $(#[$names_attr:meta])*
        pub const $names:ident;
    ) => {
        $(#[$enum_attr])*
        pub enum $frame $(<$carrier = $carried>)? {
            $(
                $(#[$variant_attr])*
                $variant $({ $($field)* })? $(( $($carried_value)* ))?,
            )*
        }

        $(#[$names_attr])*
        pub const $names: [&str; [$(stringify!($variant)),*].len()] =
            [$(stringify!($variant)),*];

        impl $(<$carrier>)? $frame $(<$carrier>)? {
            /// The wire name of this frame: the variant's own spelling,
            /// which is also its entry in the name table above.
            #[must_use]
            pub fn name(&self) -> &'static str {
                match *self {
                    $(Self::$variant { .. } => stringify!($variant),)*
                }
            }
        }
    };
}

pub(crate) use named_frames;