alphagov / router

Router GOV.UK Router is an HTTP reverse proxy built on top of [ ][tm]. It loads a routing table into memory from a PostgreSQL database and: • forwards requests to backend application servers according to the path in the request URL • serves HTTP and redirects for moved content and short URLs • serves responses for resources that no longer exist How it works Router loads its routing table from Content Store's PostgreSQL database (or optionally from a flat file). It uses a trie data structure for fast path lookups, maintaining two separate tries: one for exact path matches and one for prefix matches. When a request comes in, Router first checks for an exact match, then falls back to the longest prefix match. Router can reload routes without restarting, either automatically via PostgreSQL's , on a periodic schedule, or manually via the API. Routes can be one of two types: • **exact**: The path must match exactly (e.g., matches only ) • **prefix**: The path prefix must match (e.g., matches , , etc.) Each matched route is handled by one of three handler types: • **backend**: Reverse proxies the request to a backend application server • **redirect**: Returns an HTTP 301 redirect to a new location • **gone**: Returns an HTTP 410 Gone response for deleted content Router runs two HTTP servers: a public server (default ) for handling requests, and an API server (default ) for admin operations like reloading routes and exposing metrics. For details on the route data structure and handler configuration, see docs/data-structure.md. Configuration Router is configured via environment variables: | Variable | Default | Description | |----------|---------|-------------| | | | Public request server address | | | | API/admin server address | | | | Backend connection timeout | | | | Backend response header timeout | | | | Client request read timeout | | | | Client response write timeout | | | | Periodic route reload interval | | | unset | Skip TLS verification | | | unset | Enable debug logging | | | | Error log file path | | | unset | Load routes from JSONL file instead of PostgreSQL | | | unset | PostgreSQL connection string | | | unset | Sentry error tracking DSN | | | unset | Sentry environment tag | Backend applications are configured with environment variables: Routes reference these backends by their ID (e.g., "frontend", "publisher"). Serving routes from a flat file When is set, Router will load routes from the specified JSONL file (one JSON object per line). Router will also no longer load routes from PostgreSQL, and periodic route updates are disabled. Example file: You can export routes from PostgreSQL to a JSONL file using: This can be used to continue serving routes when Content Store's database is down for maintenance. Technical documentation Recommended reading: How to Write Go Code Run the test suite Checks run automatically on GitHub on PR and push. For faster feedback, you can run the tests locally. The lint check uses golangci-lint, which you can install via Homebrew or your favourite package manager: You can run all tests (some of which need Docker installed) by running: You can also run just the unit tests or just the integration tests, using the and targets. The unit tests don't need Docker. The and packages have unit tests. To run these on their own: The integration tests need Docker in order to run PostgreSQL. They are intended to cover Router's overall request handling, error reporting and performance. You can use to run a subset of the integration tests, for example: Debug output To see debug messages when running tests, set both the and environment variables: Update the dependencies This project uses Go Modules to vendor its dependencies. To update the dependencies: • Update all the dependencies, including test dependencies, in your working copy: • Check for any errors and commit. • Run the Router test suite. If you need to fix a failing test, keep your changes in separate commits to the / commit. • Run the tests for all dependencies: • If there are failures, look into each one and determine whether it needs fixing. • If anything under needs changing then either raise a PR with the upstream project or revert to a set of versions that work together. Only and should touch files in . • Raise a PR. Further documentation • Data structure • Original thinking behind the router • Example of adding a metric using the Go prometheus client library Team GOV.UK Platform Engineering team looks after this repo. If you're inside GDS, you can find us in [#govuk-platform-engineering] or view our kanban board. Licence MIT License [#govuk-platform-engineering]: https://gds.slack.com/channels/govuk-platform-engineering [router-api]: https://github.com/alphagov/router-api [tm]: https://github.com/alphagov/router/tree/main/triemux