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
//! The S2 energy flexibility standard in Rust.
//!
//! S2 — formally **EN 50491-12-2**, internationally IEC 63402-2-2 — is the European
//! standard for communicating energy flexibility between a **Customer Energy Manager**
//! (CEM) and a **Resource Manager** (RM). The RM describes *how* a device can behave; the
//! CEM decides *why* it should. The standard's own image is a menu: the RM writes it, the
//! CEM orders from it, and the RM may always refuse.
//!
//! This crate implements the two open specifications that make the standard usable over
//! IP:
//!
//! * **S2 JSON v1.0.0** — the 36 messages and 41 component types, their encoding, and the
//! protocol around them: control-type selection, reception statuses, revocation,
//! validity windows, timers and instruction lifecycles.
//! * **S2 Connect 1.0.0** — DNS-SD discovery, HMAC challenge–response pairing,
//! access-token session initiation, the WebSocket transport and the reconnection rules.
//!
//! # Where to start
//!
//! | You are building | Start at |
//! |---|---|
//! | A device that offers flexibility | [`session::RmSession`] |
//! | An energy manager that uses it | [`session::CemSession`] |
//! | A proxy, analyzer or log reader | [`session::Analyzer`] |
//! | Two devices that must find and trust each other | [`connect`] |
//! | Something over a transport that is not WebSocket | [`session`], and drive it yourself |
//!
//! Longer guides, the full rule catalogue and the conformance statement are at
//! <https://hupe1980.github.io/s2-kit>.
//!
//! ```
//! use s2_kit::prelude::*;
//!
//! let details = ResourceManagerDetails::builder()
//! .resource_id(Id::parse("battery-1")?)
//! .roles(vec![Role { role: RoleType::EnergyStorage, commodity: Commodity::Electricity }])
//! .instruction_processing_delay(Duration::from_millis(500))
//! .available_control_types(vec![ControlType::FillRateBasedControl])
//! .provides_forecast(false)
//! .provides_power_measurement_types(vec![CommodityQuantity::ElectricPower3PhaseSymmetric])
//! .build();
//!
//! let mut rm = RmSession::new(RmConfig::default(), details);
//! rm.open(Timestamp::now());
//!
//! // Everything the session wants to say is waiting here; a driver writes it to a socket.
//! let first = rm.poll_transmit().expect("the RM speaks first");
//! assert!(first.text.contains(r#""message_type":"Handshake""#));
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! # Design in one paragraph
//!
//! The protocol core is **sans-I/O**: no sockets, no clock, no tasks. Every engine takes
//! `now` as a parameter and is driven by `handle_*` / `poll_*`, so a two-hour timer, a
//! lost acknowledgement and a revoked constraint are all ordinary unit tests. Drivers —
//! WebSocket, HTTPS, mDNS — are Cargo features that hang off the side. The data model is
//! hand-written and *proven* against the standard's own JSON schemas in CI rather than
//! generated from a modified copy of them, and the layer above it is a
//! [rule-numbered semantic validator](validate) for everything JSON Schema cannot express.
//!
//! # Features
//!
//! | Feature | Enables |
//! |---|---|
//! | `std` *(default)* | The standard library. Without it the crate is `no_std + alloc`. |
//! | `uuid` *(default)* | [`Id::generate`](types::Id::generate) and friends. |
//! | `tokio` | [`io::Driver`], which pumps a session over any text transport. |
//! | `connect-client` | Pairing and session initiation, with leaf-fingerprint capture and CA pinning. |
//! | `connect-server` | An `axum` router for both APIs and the authorised WebSocket, TLS serving, a self-signed CA helper. |
//! | `discovery` | DNS-SD advertise and browse of `_s2connect._tcp`. |
//! | `tls-ring` *(default)* | `ring` as the bundled TLS cryptography; no `cmake` to cross-compile. |
//! | `tls-aws-lc-rs` | `aws-lc-rs` instead: FIPS-certifiable, post-quantum. Exactly one is linked. |
//! | `jiff` / `time` / `chrono` | [`Timestamp`] conversions, with the crate re-exported. |
//! | `testing` | Fixtures, the two-engine harness, the in-memory pipe, and `.s2log` transcripts read as well as written. |
//! | `schemars` | `JsonSchema` for this crate's own types, for the equivalence check. |
//! | `tracing` | A span per session and an event per message from the drivers, keyed by `message_id`; never a payload. |
//! | `cli` | The `s2-kit` command-line tool. |
// Tests are allowed to panic: that is what a failing assertion is. The lints are on for
// everything else, where a panic in a driver answering a peer is a crash.
extern crate alloc;
extern crate std;
pub
// The website's guides, as doctests. Generated by `cargo xtask gen-site-examples`; it
// exists so a snippet a reader copies out of a guide is a snippet that compiles. Only
// rustdoc ever builds it.
pub use ;
pub use ;
pub use ;
/// Everything a typical Resource Manager or Customer Energy Manager needs.
// The rule for this block: if a type from crate `X` is reachable from this crate's public
// API, `X` is re-exported here under the feature that brings it in — so a caller names the
// version this crate was built against instead of keeping a major in step by hand. A
// drifted one otherwise reports `expected MaybeTlsStream<TcpStream>, found
// MaybeTlsStream<TcpStream>`.
pub use chrono;
pub use jiff;
pub use time;
pub use uuid;
// `WebSocket::connect` returns a
// `WebSocket<MaybeTlsStream<TcpStream>>`; [`io::Dialled`] is its short spelling.
pub use tokio;
pub use tokio_tungstenite;
// `CapturedIdentity::chain` carries `CertificateDer`s, `TlsClient::config` an
// `Arc<ClientConfig>`, `default_provider` an `Arc<CryptoProvider>`.
pub use rustls;
// `connect::server`'s routers are `axum::Router`s, mounted in an application's own.
pub use axum;
// `Discovery::daemon` hands back the `mdns_sd::ServiceDaemon` it is driving.
pub use mdns_sd;