Skip to main content

Crate siri_rs

Crate siri_rs 

Source
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

ModuleWhat it holds
frameworkThe <Siri> envelope and every framework message
ptProduction Timetable: the day’s plan
etEstimated Timetable: the plan as it is running
stStop Timetable: the plan at one stop
smStop Monitoring: what is due at one stop now
vmVehicle Monitoring: where the vehicles are
ctConnection Timetable: the interchanges planned over a link
cmConnection Monitoring: whether those interchanges will be made
gmGeneral Message: free-form messages on named channels
fmFacility Monitoring: whether the lift is working
caControl Actions: what the control room has decided to do
sxSituation Exchange requests, deliveries and PtSituationElement
pubsubThe subscription state machines and the transport seam
modelThe journey model, references and locations shared across services
typesPrimitive datatypes: identifiers, texts, durations
enumerationsThe 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:sequence prescribes. 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/> is true and <Severity/> is normal: 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. See types::AnyContent.
  • A timestamp names an instant. xsd:dateTime lets 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: an InitialTerminationTime against now, a ValidUntil against the next poll. Every timestamp is therefore a chrono::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 a types::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.
lenientlenient
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§

SiriRoot
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.

Type Aliases§

Result
Result alias for Error.