OBA Maglev

A complete rewrite of the OneBusAway (OBA) REST API server in Golang.

Getting Started

1. Install Go 1.24.2 or later.
2. Copy config.example.json to config.json and fill in the required values.
3. Run make run to build start the server.
4. Open your browser and navigate to http://localhost:4000/api/where/current-time.json?key=test to verify the server works.

Configuration

Maglev supports two ways to configure the server: command-line flags or a JSON configuration file.

Command-line Flags (Default)

Run the server with command-line flags:

./bin/maglev -port 8080 -env production -api-keys "key1,key2" -rate-limit 50

JSON Configuration File

Alternatively, use a JSON configuration file with the -f flag:

./bin/maglev -f config.json

An example configuration file is provided as config.example.json. You can copy and modify it:

cp config.example.json config.json
# Edit config.json with your settings
./bin/maglev -f config.json

Example config.json:

{
  "port": 8080,
  "env": "production",
  "api-keys": ["key1", "key2", "key3"],
  "rate-limit": 50,
  "gtfs-static-feed": {
    "url": "https://example.com/gtfs.zip",
    "auth-header-name": "Authorization",
    "auth-header-value": "Bearer token456",
    "enable-gtfs-tidy": true
  },
  "gtfs-rt-feeds": [
    {
      "trip-updates-url": "https://api.example.com/trip-updates.pb",
      "vehicle-positions-url": "https://api.example.com/vehicle-positions.pb",
      "service-alerts-url": "https://api.example.com/service-alerts.pb",
      "realtime-auth-header-name": "Authorization",
      "realtime-auth-header-value": "Bearer token123"
    }
  ],
  "data-path": "/data/gtfs.db"
}

Note: The -f flag is mutually exclusive with other command-line flags. If you use -f, all other configuration flags will be ignored. The system will error if you try to use both.

Dump Current Configuration:

./bin/maglev --dump-config > my-config.json
# or with other flags
./bin/maglev -port 8080 -env production --dump-config > config.json

JSON Schema & IDE Integration:

A JSON schema file is provided at config.schema.json for IDE autocomplete and validation.

To enable IDE validation, add $schema to your config file:

{
  "$schema": "./config.schema.json",
  "port": 4000,
  "env": "development",
  ...
}

Configuration Options

Option	Type	Default	Description
port	integer	4000	API server port
env	string	"development"	Environment (development, test, production)
api-keys	array	["test"]	API keys for authentication
rate-limit	integer	100	Requests per second per API key
gtfs-static-feed	object	(Sound Transit)	Static GTFS feed configuration with URL and optional auth headers
gtfs-rt-feeds	array	(Sound Transit)	GTFS-RT feed configurations
data-path	string	"./gtfs.db"	Path to SQLite database

Basic Commands

All basic commands are managed by our Makefile:

make run - Build and run the app with a fake API key: test.

make build - Build the app.

make clean - Delete all build and coverage artifacts.

make coverage - Test and generate HTML coverage artifacts.

make test - Run tests.

make schema - Dump the DB's SQL schema to a file for sqlc.

make watch - Build and run the app with Air for live reloading during development (automatically rebuilds and restarts on code changes).

Directory Structure

• bin contains compiled application binaries, ready for deployment to a production server.
• cmd/api contains application-specific code for Maglev. This will include the code for running the server, reading and writing HTTP requests, and managing authentication.
• internal contains various ancillary packages used by our API. It will contain the code for interacting with our database, doing data validation, sending emails and so on. Basically, any code which isn’t application-specific and can potentially be reused will live in here. Our Go code under cmd/api will import the packages in the internal directory (but never the other way around).
• migrations contains the SQL migration files for our database.
• remote contains the configuration files and setup scripts for our production server.
• go.mod declares our project dependencies, versions and module path.
• Makefile contains recipes for automating common administrative tasks — like auditing our Go code, building binaries, and executing database migrations.

Debugging

# Install Delve
go install github.com/go-delve/delve/cmd/dlv@latest

# Build the app
make build

# Start the debugger
dlv --listen=:2345 --headless=true --api-version=2 --accept-multiclient exec ./bin/maglev

And then you'll be able to debug in the GoLand IDE.

SQL

We use sqlc with SQLite to generate a data access layer for our app. Use the command make models to regenerate all autogenerated files.

Important files

• gtfsdb/models.go Autogenerated by sqlc
• gtfsdb/query.sql All of our SQL queries
• gtfsdb/query.sql.go All of our SQL queries turned into Go code by sqlc
• gtfsdb/schema.sql Our database schema
• gtfsdb/sqlc.yml Configuration file for sqlc