siri_rs/lib.rs
1//! CEN SIRI — Service Interface for Real-time Information — in Rust.
2//!
3//! SIRI (EN 15531 / CEN/TS 15531) is the European standard for exchanging
4//! real-time public transport data. This crate implements the SIRI **framework**
5//! (message envelope, request/response, discovery and capabilities), the full
6//! **publish/subscribe data hub** (subscription lifecycle, data-ready
7//! notifications, fetched and direct delivery, heartbeats), and every functional
8//! service on top of it: the planned timetable and the timetable as it is actually
9//! running, the two of them seen from a stop, the vehicles running it, the
10//! interchanges between them planned and monitored, free-form messages, the state
11//! of passenger facilities, the incidents and disruptions that perturb it all, and
12//! what a control room decides to do about them.
13//!
14//! Both roles are supported: use it to consume a producer's feed, or to run one.
15//!
16//! # Layout
17//!
18//! | Module | What it holds |
19//! |---|---|
20//! | [`framework`] | The `<Siri>` envelope and every framework message |
21//! | [`pt`] | Production Timetable: the day's plan |
22//! | [`et`] | Estimated Timetable: the plan as it is running |
23//! | [`st`] | Stop Timetable: the plan at one stop |
24//! | [`sm`] | Stop Monitoring: what is due at one stop now |
25//! | [`vm`] | Vehicle Monitoring: where the vehicles are |
26//! | [`ct`] | Connection Timetable: the interchanges planned over a link |
27//! | [`cm`] | Connection Monitoring: whether those interchanges will be made |
28//! | [`gm`] | General Message: free-form messages on named channels |
29//! | [`fm`] | Facility Monitoring: whether the lift is working |
30//! | [`ca`] | Control Actions: what the control room has decided to do |
31//! | [`sx`] | Situation Exchange requests, deliveries and `PtSituationElement` |
32//! | [`pubsub`] | The subscription state machines and the transport seam |
33//! | [`model`] | The journey model, references and locations shared across services |
34//! | [`types`] | Primitive datatypes: identifiers, texts, durations |
35//! | [`enumerations`] | The schema's enumerated code lists |
36//!
37//! # Reading and writing
38//!
39//! ```
40//! let xml = r#"<Siri xmlns="http://www.siri.org.uk/siri" version="2.0">
41//! <HeartbeatNotification>
42//! <RequestTimestamp>2004-12-17T09:30:47-05:00</RequestTimestamp>
43//! <ProducerRef>KUBRICK</ProducerRef>
44//! <Status>true</Status>
45//! </HeartbeatNotification>
46//! </Siri>"#;
47//!
48//! let message: siri_rs::Siri = siri_rs::from_str(xml)?;
49//! let heartbeat = message.payload.as_heartbeat_notification().unwrap();
50//! assert_eq!(heartbeat.producer_ref.as_ref().unwrap().as_str(), "KUBRICK");
51//!
52//! let written = siri_rs::to_string(&message)?;
53//! assert!(written.contains("<ProducerRef>KUBRICK</ProducerRef>"));
54//! # Ok::<(), siri_rs::Error>(())
55//! ```
56//!
57//! # Speed
58//!
59//! [`from_str`] hands the document to the deserialiser borrowed unless it writes an
60//! element with a namespace prefix or an element holding nothing but whitespace,
61//! and [`to_string`] produces the finished
62//! document — declaration, namespace and body — into a single buffer. What is left
63//! is the profile the finished program is built with, which a library cannot impose
64//! on its consumer: a program that wants the calls into this crate optimised across
65//! the crate boundary asks for `lto` and `codegen-units = 1` in its own
66//! `[profile.release]`. `benches/` measures reading, writing and one turn of the
67//! publish/subscribe cycle over the official example documents.
68//!
69//! # Reading streams you don't control
70//!
71//! [`from_str`] reads a document whole or not at all: one element that cannot be
72//! read — an empty timestamp, a missing mandatory element — fails the document,
73//! and every valid record in it with it. A program that reads a producer's stream
74//! and has no say in what arrives can ask, with the `lenient` feature, for the
75//! reading in the `lenient` module instead, which leaves out the smallest thing
76//! the document reads without — the element, or the situation, journey, stop
77//! visit or delivery around it — and reports each one with its path, the reason
78//! and, where the unit has one, its identifier. The strict reader is not changed
79//! by the feature; the module's documentation says what may be left out and what
80//! never is.
81//!
82//! # At an open port
83//!
84//! A document from the other side may be anything, and a reader that answers it
85//! with an `Err` has done its job; one that takes the process down has not.
86//! Entity expansion is refused by the XML layer, a text node of any length reads in
87//! linear time, and open content — an `<Extensions>` payload, a general-message
88//! body, an embedded DATEX II record — may nest at most
89//! [`types::AnyContent::MAX_DEPTH`] elements deep, which stops the one recursion the
90//! schema does not bound. What the reader cannot do is bound the *size* of what it
91//! is given, because it is given a string: the transport in front of it should.
92//! The largest official request example is 3 KB and the largest delivery
93//! example 111 KB, so a producer answering requests loses nothing by refusing a
94//! body over 1 MiB, and a consumer receiving deliveries should set its limit at
95//! the largest delivery its producer sends — the examples take 16 MiB.
96//!
97//! # How the schema is modelled
98//!
99//! The XML Schema is the authority; where idiomatic Rust and schema fidelity
100//! disagree, fidelity wins and the API absorbs the awkwardness. Four conventions
101//! follow from that:
102//!
103//! * **Field order is element order.** Serialisation writes struct fields in
104//! declaration order, so fields appear in the order the schema's `xsd:sequence`
105//! prescribes. Attributes are declared before elements.
106//! * **A choice between single elements is an enum**, written as the element name —
107//! see [`framework::ErrorCondition`].
108//! * **A choice between element *groups* is a set of optional fields**, because
109//! the alternatives are not single elements and cannot carry an enum's tag. Such
110//! types offer constructors for each alternative and an accessor that reports
111//! which one is present — see [`model::Location::position`].
112//! * **An element the schema gives a default value means that value when written
113//! empty.** `<Monitored/>` is `true` and `<Severity/>` is `normal`: XML Schema
114//! says so, and the reader reads it so. The declarations are read out of the
115//! schemas into a table the tests keep in step with them, and every field that
116//! transcribes one reads through it. The value is written back in full,
117//! `<Monitored>true</Monitored>`, which the schema holds equal to the empty
118//! element; a text of whitespace alone is not empty and is read as it stands.
119//! * **What the schema leaves open is kept, not interpreted.** An `<Extensions>`
120//! payload, a general-message body and an embedded DATEX II record belong to
121//! profiles outside SIRI, so they are held as the subtree they are and written
122//! back unchanged — and read into a consumer's own type where it has one. See
123//! [`types::AnyContent`].
124//! * **A timestamp names an instant.** `xsd:dateTime` lets the time-zone offset
125//! be left out, and a document that leaves it out is schema-valid; but a
126//! wall-clock time without an offset names no instant — XML Schema itself
127//! ranks it as incomparable with a zoned one — and the hub compares instants:
128//! an `InitialTerminationTime` against now, a `ValidUntil` against the next
129//! poll. Every timestamp is therefore a [`chrono::DateTime<FixedOffset>`], and
130//! a document that leaves the offset out is refused with an error naming the
131//! field. The one place the official examples do leave it out — the validity
132//! period of a Production Timetable, which is a period in the timetable's own
133//! zone — is a [`types::Timestamp`], which keeps the lexical form and offers the
134//! instant only when the document gave one.
135//!
136//! # Conformance
137//!
138//! Every message this crate models is checked against the official SIRI v2.2
139//! schemas and example documents: each example is parsed, written back out,
140//! compared to the original element by element, and validated against the schema.
141//! `tests/fixtures/README.md` lists the documents covered, including the German
142//! VDV 736 profile, and the one official document left out — the capabilities
143//! response for all eleven services at once, which needs a discovery structure
144//! the crate does not model. [`ca`] is the one service with no example documents
145//! to check against, and its own documentation says what is checked instead.
146
147#![deny(missing_docs)]
148#![forbid(unsafe_code)]
149#![cfg_attr(docsrs, feature(doc_cfg))]
150
151#[macro_use]
152mod macros;
153
154pub mod ca;
155pub mod cm;
156pub mod ct;
157pub mod enumerations;
158mod error;
159pub mod et;
160pub mod fm;
161pub mod framework;
162pub mod gm;
163#[cfg(feature = "lenient")]
164#[cfg_attr(docsrs, doc(cfg(feature = "lenient")))]
165pub mod lenient;
166pub mod model;
167pub mod pt;
168pub mod pubsub;
169pub mod sm;
170pub mod st;
171pub mod sx;
172pub mod types;
173pub mod vm;
174mod xml;
175
176pub use error::{Error, Result};
177pub use framework::{
178 CheckStatusRequest, CheckStatusResponse, HeartbeatNotification, ServiceDelivery, ServiceRequest,
179 Siri, SiriPayload, SubscriptionRequest, SubscriptionResponse,
180};
181pub use types::{Duration, NaturalLanguageString, ParticipantRef, SubscriptionRef};
182pub use xml::{from_str, to_string, to_string_pretty, SiriRoot, NAMESPACE};