vdv-453-nats-adapter

Sends realtime public transport data from a VDV-453/VDV-454 API to a NATS message broker, so that it can be easily consumed by other applications. Uses vdv-453-client underneath.

Installation

npm install -g OpenDataVBB/vdv-453-nats-adapter

Getting Started

Please note the limitations imposed by the underlying library vdv-453-client:

A client for VDV-453 v2.3.2b/VDV-454 v1.2.2 (from 2013) systems. Can be used to connect to German public transport realtime data backends (Datendrehscheiben).

Note: This client supports neither the latest 2.x spec versions (VDV-453 v2.6.1/VDV-454 v2.2.1) nor the latest 3.x spec versions (VDV-453 v3.0/VDV-454 v3.0).

With the organisation providing the VDV 453 API, you will have to agree upon a Leitstellenkennung you'll use, which is a bit like an HTTP User-Agent:

6.1.3 Leitstellenkennung

Um Botschaften verschiedener Kommunikationspartner innerhalb eines Dienstes unterscheiden zu können, enthält jede Nachricht eine eindeutige Leitstellenkennung (Attribut Sender) des nachfragenden Systems. […]

Then, configure access to the VDV-453 system, and run the adapter:

send-vdv-453-data-to-nats \
	# must have a trailing `/`
	--endpoint 'http://example.org:1234/api/' \
	# your Leitstellenkennung, as agreed-upon between the VDV-453 API's operator and you
	--leitstelle '…' \
	# their Leitstellenkennung, as agreed-upon between the VDV-453 API's operator and you
	--their-leitstelle '…'

Usage

Usage:
    send-vdv-453-data-to-nats [options] <service>
Notes:
    Valid values for `service`:
    - `AUS` subscribes to the VDV-454 AUS service containing network-wide realtime data.
Options:
	--leitstelle              -l  VDV-453 Leitstellenkennung, a string identifying this
	                              client, a bit like an HTTP User-Agent. Must be agreed-
	                              upon with the provider of the VDV-453 API.
	                              Default: $VDV_453_LEITSTELLE
	--their-leitstelle        -L  VDV-453 Leitstellenkennung of the server. Must be agreed-
	                              upon with the provider of the VDV-453 API.
	                              Default: $VDV_453_THEIR_LEITSTELLE
	--endpoint                -e  HTTP(S) URL of the VDV-453 API.
	                              Default: $VDV_453_ENDPOINT
	--port                    -p  Port to listen on. VDV-453 requires the *client* to run
	                              an HTTP server that the VDV-453 API can call.
	                              Default: $PORT, otherwise 3000
	--expires                     Set the subscription's expiry date & time. Must be an
	                              ISO 8601 date+time string or a UNIX epoch/timestamp.
	                              Default: now + 1h
	--aus-manual-fetch-interval   How often to *manually* fetch the data of an AUS
	                              subscription, in milliseconds.
	                              Usually, the server should notify the client about new
	                              data, but some may not.
	                              Default: 30_000
	--nats-servers                NATS server(s) to connect to.
	                              Default: $NATS_SERVERS
	--nats-user                   User to use when authenticating with NATS server.
	                              Default: $NATS_USER
	--nats-client-name            Name identifying the NATS client among others.
	                              Default: vdv453-1-${randomHex(4)}
Exit Codes:
	1 – generic and/or unexpected error
	2 – operation canceled
	3 – VDV-453 API error
Examples:
    send-vdv-453-data-to-nats --expires never AUS

Operating vdv-453-nats-adapter

Logs

vdv-453-nats-adapter writes pino-formatted log messages to stdout, so you can use pino-compatible tools to process them.

Monitoring

vdv-453-nats-adapter exposes Prometheus-compatible metrics via HTTP. By default, the metrics server will listen on a random port. You can configure a permanent port using $METRICS_SERVER_PORT.

The following kinds of metrics will be exported:

• domain-specific metrics, e.g.
  • the number of active subscriptions set up
  • the number of AUS IstFahrts retrieved per fetch
  • the VDV API's StartDienstZst
• technical details about the Node.js process, e.g. the current state of garbage collection

Refer to the Grafana dashboard in VBB's deployment for an example how to visualize vdv-453-nats-adapter's metrics.

Related

• vdv-453-client – A client for VDV-453/VDV-454 systems.

Contributing

If you have a question or need support using vdv-453-nats-adapter, please double-check your code and setup first. If you think you have found a bug or want to propose a feature, use the issues page.