Support multiple GTFS-RT feeds

.github/workflows/test.yaml

@@ -7,6 +7,24 @@ on:
   pull_request:
 
 jobs:
+  renderer:
+    name: Template renderer tests
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+
+      - name: Run renderer tests
+        working-directory: oba/config/template_renderer
+        run: go test ./...
+
   image:
     name: Build Docker Image
     runs-on: ubuntu-latest

README.md

@@ -100,6 +100,7 @@ You can find the latest published Docker images on Docker Hub:
   * `GTFS_URL` - The URL to the GTFS feed you want to use.
 * GTFS-RT Support (Optional)
   * `TZ` - The timezone for the server. Ensure that the server's timezone matches the timezone specified in your static GTFS `agency.txt` file. The timezone format is the IANA standard, and [a full list of timezones can be found on Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List).
+  * `GTFS_RT_FEEDS` - Preferred for configuring one OR many GTFS-RT feeds. A JSON array of feed objects; each object may contain `tripUpdatesUrl`, `vehiclePositionsUrl`, `alertsUrl`, `refreshInterval`, `agencyIds` (array), `feedApiKey`, and `feedApiValue`. Example: `[{"tripUpdatesUrl":"https://a/trips","agencyIds":["unitrans"]},{"vehiclePositionsUrl":"https://b/veh","agencyIds":["kcm"]}]`. When set, it takes precedence over the single-feed variables below.
   * `ALERTS_URL` - Service Alerts URL for GTFS-RT.
   * `TRIP_UPDATES_URL` - Trip Updates URL for GTFS-RT.
   * `VEHICLE_POSITIONS_URL` - Vehicle Positions URL for GTFS-RT.

deployment-examples/multiple-rt-feeds/README.md

@@ -0,0 +1,112 @@
+# Multiple GTFS-RT Feeds Example
+
+This example runs a single OneBusAway server that serves **two transit agencies'
+realtime data at once** — King County Metro and Pierce Transit — using the
+`GTFS_RT_FEEDS` environment variable.
+
+OneBusAway supports many `GtfsRealtimeSource` beans (one per realtime feed).
+`GTFS_RT_FEEDS` exposes that: it takes a JSON array of feed
+objects and renders one bean per feed. It supersedes the legacy single-feed
+variables (`TRIP_UPDATES_URL`, `VEHICLE_POSITIONS_URL`, `ALERTS_URL`,
+`AGENCY_ID`, …), which still work for a single feed when `GTFS_RT_FEEDS` is unset.
+
+## What's configured
+
+| Agency | `agency_id` | Static GTFS | Realtime |
+|---|---|---|---|
+| King County Metro | `1` | consolidated feed (below) | raw GTFS-RT protobufs from `kcm-alerts-realtime-prod` |
+| Pierce Transit | `3` | consolidated feed (below) | relayed through the Puget Sound OneBusAway GTFS-RT endpoints |
+
+**Static data** comes from the consolidated Puget Sound GTFS feed
+(`https://gtfs.sound.obaweb.org/prod/gtfs_puget_sound_consolidated.zip`), which
+already contains both agencies (and several others). Because it's a single zip,
+the normal single-feed bundle builder handles it without any changes.
+
+**Realtime data** is configured with two feeds in `GTFS_RT_FEEDS`. Each feed's
+`agencyIds` tells OneBusAway which bundle agency the feed's entities belong to,
+so the two protobuf streams line up with agencies `1` and `3` in the bundle:
+
+```json
+[
+  {
+    "tripUpdatesUrl": "https://s3.amazonaws.com/kcm-alerts-realtime-prod/tripupdates.pb",
+    "vehiclePositionsUrl": "https://s3.amazonaws.com/kcm-alerts-realtime-prod/vehiclepositions.pb",
+    "alertsUrl": "https://s3.amazonaws.com/kcm-alerts-realtime-prod/alerts.pb",
+    "refreshInterval": "30",
+    "agencyIds": ["1"]
+  },
+  {
+    "tripUpdatesUrl": "https://api.pugetsound.onebusaway.org/api/gtfs_realtime/trip-updates-for-agency/3.pb?key=org.onebusaway.iphone",
+    "vehiclePositionsUrl": "https://api.pugetsound.onebusaway.org/api/gtfs_realtime/vehicle-positions-for-agency/3.pb?key=org.onebusaway.iphone",
+    "alertsUrl": "https://api.pugetsound.onebusaway.org/api/gtfs_realtime/alerts-for-agency/3.pb?key=org.onebusaway.iphone",
+    "refreshInterval": "30",
+    "agencyIds": ["3"]
+  }
+]
+```
+
+> **Note:** `oba_app` is built from this repository's `../../oba` directory, not
+> the published `opentransitsoftwarefoundation/onebusaway-api-webapp:2.7.1-latest`
+> image, because `GTFS_RT_FEEDS` support is not in a published release yet. Once a
+> 2.7.1 image that understands `GTFS_RT_FEEDS` is published, an immutable
+> deployment can bake these env vars into a `Dockerfile` that is `FROM` that
+> image instead — see [`../immutable`](../immutable) for that pattern.
+
+## Running it
+
+From this directory:
+
+```bash
+docker compose up -d --build
+```
+
+This:
+
+1. Runs `oba_bundler` once to build the consolidated bundle into a shared volume
+   (this downloads ~38 MB of GTFS and takes a few minutes).
+2. Starts PostgreSQL.
+3. Starts `oba_app` after the bundle finishes, configured with both realtime feeds.
+
+Watch the bundle build and app startup:
+
+```bash
+docker compose logs -f oba_bundler   # bundle build
+docker compose logs -f oba_app       # config render + Tomcat startup
+```
+
+The API is available at <http://localhost:8080> once `oba_app` is up.
+
+## Validating
+
+Run the repository's validation script (from the repo root) against the running server:
+
+```bash
+./bin/validate.sh
+```
+
+Then confirm **realtime** is flowing for **both** agencies. The most direct
+check is live vehicle positions — each count should be non-zero during service
+hours, and it proves each feed's entities mapped onto the right bundle agency:
+
+```bash
+# King County Metro (agency 1) — live vehicles from its realtime feed
+curl -s "http://localhost:8080/api/where/vehicles-for-agency/1.json?key=test" | jq '.data.list | length'
+
+# Pierce Transit (agency 3) — live vehicles from its realtime feed
+curl -s "http://localhost:8080/api/where/vehicles-for-agency/3.json?key=test" | jq '.data.list | length'
+```
+
+To see the realtime status of a specific trip, pull an active trip from a
+vehicle and inspect its status — look for `"predicted": true`:
+
+```bash
+TRIP=$(curl -s "http://localhost:8080/api/where/vehicles-for-agency/1.json?key=test" | jq -r '.data.list[0].tripId')
+curl -s "http://localhost:8080/api/where/trip-details/$TRIP.json?key=test" \
+  | jq '.data.entry.status | {predicted, scheduleDeviation, vehicleId, lastUpdateTime}'
+```
+
+## Tearing down
+
+```bash
+docker compose down -v   # -v also removes the bundle and database volumes
+```

deployment-examples/multiple-rt-feeds/docker-compose.yaml

@@ -0,0 +1,67 @@
+# Multiple GTFS-RT feeds example: King County Metro + Pierce Transit.
+#
+# Demonstrates the GTFS_RT_FEEDS env var, which configures one OR many GTFS-RT
+# realtime feeds (one GtfsRealtimeSource bean per feed). Static data comes from
+# the consolidated Puget Sound GTFS feed, which already contains both agencies
+# (agency_id 1 = King County Metro, agency_id 3 = Pierce Transit), so the
+# single-feed bundle builder handles it as-is.
+#
+# NOTE: oba_app is built from this repo's ../../oba directory rather than the
+# published opentransitsoftwarefoundation/onebusaway-api-webapp:2.7.1-latest
+# image, because GTFS_RT_FEEDS support is not in a published release yet. Once a
+# 2.7.1 image that understands GTFS_RT_FEEDS is published, an immutable
+# deployment can instead bake these env vars into a Dockerfile FROM that image
+# (see ../immutable for that pattern).
+
+services:
+  # One-shot job: builds the consolidated bundle into the shared volume, then exits.
+  oba_bundler:
+    build:
+      context: ../../bundler
+    volumes:
+      - oba-bundle:/bundle
+    environment:
+      - GTFS_URL=https://gtfs.sound.obaweb.org/prod/gtfs_puget_sound_consolidated.zip
+
+  oba_database_pg:
+    image: postgres:16
+    environment:
+      POSTGRES_USER: oba_user
+      POSTGRES_PASSWORD: oba_password
+      POSTGRES_DB: oba_database
+    # No host port mapping: oba_app reaches the database over the compose
+    # network, so there's no need to expose 5432 (and it avoids colliding with
+    # a Postgres already running on the host).
+    volumes:
+      - pg-data:/var/lib/postgresql/data
+    restart: always
+
+  oba_app:
+    depends_on:
+      oba_database_pg:
+        condition: service_started
+      # Wait for the bundle build to finish before starting the app.
+      oba_bundler:
+        condition: service_completed_successfully
+    build:
+      context: ../../oba
+    environment:
+      - JDBC_URL=jdbc:postgresql://oba_database_pg:5432/oba_database
+      - JDBC_DRIVER=org.postgresql.Driver
+      - JDBC_USER=oba_user
+      - JDBC_PASSWORD=oba_password
+      - TEST_API_KEY=test # For testing only; remove in production.
+      - TZ=America/Los_Angeles
+      # Two realtime feeds, one per agency. KCM publishes raw GTFS-RT protobufs;
+      # Pierce is relayed through the Puget Sound OneBusAway GTFS-RT endpoints.
+      # agencyIds maps each feed's entities onto the matching bundle agency.
+      - 'GTFS_RT_FEEDS=[{"tripUpdatesUrl":"https://s3.amazonaws.com/kcm-alerts-realtime-prod/tripupdates.pb","vehiclePositionsUrl":"https://s3.amazonaws.com/kcm-alerts-realtime-prod/vehiclepositions.pb","alertsUrl":"https://s3.amazonaws.com/kcm-alerts-realtime-prod/alerts.pb","refreshInterval":"30","agencyIds":["1"]},{"tripUpdatesUrl":"https://api.pugetsound.onebusaway.org/api/gtfs_realtime/trip-updates-for-agency/3.pb?key=org.onebusaway.iphone","vehiclePositionsUrl":"https://api.pugetsound.onebusaway.org/api/gtfs_realtime/vehicle-positions-for-agency/3.pb?key=org.onebusaway.iphone","alertsUrl":"https://api.pugetsound.onebusaway.org/api/gtfs_realtime/alerts-for-agency/3.pb?key=org.onebusaway.iphone","refreshInterval":"30","agencyIds":["3"]}]'
+    volumes:
+      - oba-bundle:/bundle
+    ports:
+      - "8080:8080"
+      - "1234:1234" # JMX exporter port
+
+volumes:
+  oba-bundle:
+  pg-data: