Expand description
CEN SIRI — Service Interface for Real-time Information — in Rust.
SIRI (EN 15531 / CEN/TS 15531) is the European standard for exchanging real-time public transport data. This crate implements the SIRI framework (message envelope, request/response, discovery and capabilities), the full publish/subscribe data hub (subscription lifecycle, data-ready notifications, fetched and direct delivery, heartbeats), and every functional service on top of it: the planned timetable and the timetable as it is actually running, the two of them seen from a stop, the vehicles running it, the interchanges between them planned and monitored, free-form messages, the state of passenger facilities, the incidents and disruptions that perturb it all, and what a control room decides to do about them.
Both roles are supported: use it to consume a producer’s feed, or to run one.
§Layout
| Module | What it holds |
|---|---|
framework | The <Siri> envelope and every framework message |
pt | Production Timetable: the day’s plan |
et | Estimated Timetable: the plan as it is running |
st | Stop Timetable: the plan at one stop |
sm | Stop Monitoring: what is due at one stop now |
vm | Vehicle Monitoring: where the vehicles are |
ct | Connection Timetable: the interchanges planned over a link |
cm | Connection Monitoring: whether those interchanges will be made |
gm | General Message: free-form messages on named channels |
fm | Facility Monitoring: whether the lift is working |
ca | Control Actions: what the control room has decided to do |
sx | Situation Exchange requests, deliveries and PtSituationElement |
pubsub | The subscription state machines and the transport seam |
model | The journey model, references and locations shared across services |
types | Primitive datatypes: identifiers, texts, durations |
enumerations | The schema’s enumerated code lists |
§Reading and writing
let xml = r#"<Siri xmlns="http://www.siri.org.uk/siri" version="2.0">
<HeartbeatNotification>
<RequestTimestamp>2004-12-17T09:30:47-05:00</RequestTimestamp>
<ProducerRef>KUBRICK</ProducerRef>
<Status>true</Status>
</HeartbeatNotification>
</Siri>"#;
let message: siri_rs::Siri = siri_rs::from_str(xml)?;
let heartbeat = message.payload.as_heartbeat_notification().unwrap();
assert_eq!(heartbeat.producer_ref.as_ref().unwrap().as_str(), "KUBRICK");
let written = siri_rs::to_string(&message)?;
assert!(written.contains("<ProducerRef>KUBRICK</ProducerRef>"));§Speed
from_str hands the document to the deserialiser borrowed unless it writes an
element with a namespace prefix or an element holding nothing but whitespace,
and to_string produces the finished
document — declaration, namespace and body — into a single buffer. What is left
is the profile the finished program is built with, which a library cannot impose
on its consumer: a program that wants the calls into this crate optimised across
the crate boundary asks for lto and codegen-units = 1 in its own
[profile.release]. benches/ measures reading, writing and one turn of the
publish/subscribe cycle over the official example documents.
§Reading streams you don’t control
from_str reads a document whole or not at all: one element that cannot be
read — an empty timestamp, a missing mandatory element — fails the document,
and every valid record in it with it. A program that reads a producer’s stream
and has no say in what arrives can ask, with the lenient feature, for the
reading in the lenient module instead, which leaves out the smallest thing
the document reads without — the element, or the situation, journey, stop
visit or delivery around it — and reports each one with its path, the reason
and, where the unit has one, its identifier. The strict reader is not changed
by the feature; the module’s documentation says what may be left out and what
never is.
§At an open port
A document from the other side may be anything, and a reader that answers it
with an Err has done its job; one that takes the process down has not.
Entity expansion is refused by the XML layer, a text node of any length reads in
linear time, and open content — an <Extensions> payload, a general-message
body, an embedded DATEX II record — may nest at most
types::AnyContent::MAX_DEPTH elements deep, which stops the one recursion the
schema does not bound. What the reader cannot do is bound the size of what it
is given, because it is given a string: the transport in front of it should.
The largest official request example is 3 KB and the largest delivery
example 111 KB, so a producer answering requests loses nothing by refusing a
body over 1 MiB, and a consumer receiving deliveries should set its limit at
the largest delivery its producer sends — the examples take 16 MiB.
§How the schema is modelled
The XML Schema is the authority; where idiomatic Rust and schema fidelity disagree, fidelity wins and the API absorbs the awkwardness. Four conventions follow from that:
- Field order is element order. Serialisation writes struct fields in
declaration order, so fields appear in the order the schema’s
xsd:sequenceprescribes. Attributes are declared before elements. - A choice between single elements is an enum, written as the element name —
see
framework::ErrorCondition. - A choice between element groups is a set of optional fields, because
the alternatives are not single elements and cannot carry an enum’s tag. Such
types offer constructors for each alternative and an accessor that reports
which one is present — see
model::Location::position. - An element the schema gives a default value means that value when written
empty.
<Monitored/>istrueand<Severity/>isnormal: XML Schema says so, and the reader reads it so. The declarations are read out of the schemas into a table the tests keep in step with them, and every field that transcribes one reads through it. The value is written back in full,<Monitored>true</Monitored>, which the schema holds equal to the empty element; a text of whitespace alone is not empty and is read as it stands. - What the schema leaves open is kept, not interpreted. An
<Extensions>payload, a general-message body and an embedded DATEX II record belong to profiles outside SIRI, so they are held as the subtree they are and written back unchanged — and read into a consumer’s own type where it has one. Seetypes::AnyContent. - A timestamp names an instant.
xsd:dateTimelets the time-zone offset be left out, and a document that leaves it out is schema-valid; but a wall-clock time without an offset names no instant — XML Schema itself ranks it as incomparable with a zoned one — and the hub compares instants: anInitialTerminationTimeagainst now, aValidUntilagainst the next poll. Every timestamp is therefore achrono::DateTime<FixedOffset>, and a document that leaves the offset out is refused with an error naming the field. The one place the official examples do leave it out — the validity period of a Production Timetable, which is a period in the timetable’s own zone — is atypes::Timestamp, which keeps the lexical form and offers the instant only when the document gave one.
§Conformance
Every message this crate models is checked against the official SIRI v2.2
schemas and example documents: each example is parsed, written back out,
compared to the original element by element, and validated against the schema.
tests/fixtures/README.md lists the documents covered, including the German
VDV 736 profile, and the one official document left out — the capabilities
response for all eleven services at once, which needs a discovery structure
the crate does not model. ca is the one service with no example documents
to check against, and its own documentation says what is checked instead.
Re-exports§
pub use framework::CheckStatusRequest;pub use framework::CheckStatusResponse;pub use framework::HeartbeatNotification;pub use framework::ServiceDelivery;pub use framework::ServiceRequest;pub use framework::Siri;pub use framework::SiriPayload;pub use framework::SubscriptionRequest;pub use framework::SubscriptionResponse;pub use types::Duration;pub use types::NaturalLanguageString;pub use types::ParticipantRef;pub use types::SubscriptionRef;
Modules§
- ca
- Control Actions (SIRI-CA): what a control room has decided to do.
- cm
- Connection Monitoring (SIRI-CM): whether a connection will be made.
- ct
- Connection Timetable (SIRI-CT): the connections planned onto a departure.
- enumerations
- The code lists SIRI defines as XML Schema enumerations.
- et
- Estimated Timetable (SIRI-ET): the timetable as it is actually running.
- fm
- Facility Monitoring (SIRI-FM): whether the lifts are working.
- framework
- The SIRI framework: the document envelope and the messages every service shares.
- gm
- General Message (SIRI-GM): free-form messages on named channels.
- lenient
lenient - Reading a document that carries faults, keeping what reads.
- model
- Model elements shared by every SIRI service: references, positions, journeys.
- pt
- Production Timetable (SIRI-PT): the timetable as it is planned.
- pubsub
- The publish/subscribe data hub: subscriptions, delivery and liveness.
- sm
- Stop Monitoring (SIRI-SM): what is due at a stop.
- st
- Stop Timetable (SIRI-ST): what the timetable says will call at a stop.
- sx
- Situation Exchange (SIRI-SX): incidents and disruptions.
- types
- Primitive SIRI datatypes: identifiers, references, texts and durations.
- vm
- Vehicle Monitoring (SIRI-VM): where the vehicles are.
Enums§
- Error
- Errors raised while reading or writing SIRI XML.
Constants§
- NAMESPACE
- The SIRI XML namespace,
http://www.siri.org.uk/siri.
Traits§
- Siri
Root - A type that can stand as the root element of a SIRI document.
Functions§
- from_
str - Reads a SIRI document.
- to_
string - Writes a SIRI document as a single line of XML, prefixed by an XML declaration.
- to_
string_ pretty - Writes a SIRI document indented with tabs, the layout the official examples use.