Project status

Andromeda is an NGSI-LD context broker that implements the NGSI-LD v1.9.1 specification. This page states what the 1.0 release covers, where it stands, and what you can rely on when you upgrade.

Where it stands

Andromeda is extensively tested in a wide range of scenarios. More than 17,000 tests cover it. Many of them form a black-box suite that drives a running broker through its API, and that suite includes the ETSI NGSI-LD conformance tests, the examples from annex C of the specification, distributed operations across several brokers, the ETSI interoperability scenarios across five brokers, and deployments with PgBouncer in front of PostgreSQL. Testing lists what runs and when.

The testing doesn't end with the suite. Andromeda also goes through long test runs on dedicated rigs, each against a full deployment with PostgreSQL, PgBouncer, an MQTT broker, proxies and notification receivers.

• Repeated suite runs. The whole suite runs up to twenty times in a row on fresh stacks. A test that passes and fails by turns is treated as a defect and fixed, never rerun until it passes.
• Realistic workloads. Each workload plays one way a broker gets used. IoT agents write device readings, a persistence sink follows every change, dashboards read and poll, a timetable app runs on public transport data, a fleet tracker checks geofences, a catalog serves several languages, a multi-tenant service runs many tenants side by side, and the Smart Data Models are written and queried under their own @context documents.
• Real clients. Existing NGSI-LD client libraries and tools talk to the broker as they would in a deployment.
• Real data. Open city datasets and public transport feeds are loaded at full size, and the answers are checked against the data.
• Soak runs. Writes, queries and notifications keep going for hours on the shipped default configuration, checking that the broker keeps pace, its memory and disk stay bounded and its data stays consistent.
• Faults. PostgreSQL crashes under load, the broker restarts mid-work, the disk fills up, the database pool saturates, and notification endpoints fail, hang, drop connections or vanish.
• Concurrency. Many clients race on the same entities, attributes and subscriptions, and every notification and every stored history row is checked afterwards.
• Generated and metamorphic queries. Generated queries run against loaded data, and queries rewritten into equivalent forms must return the same entities.
• Federation. Chains and meshes of brokers forward to one another in every registration mode.
• HTTP surface and limits. Malformed, oversized, slow and abandoned requests, TLS, HTTP/3 and proxies in front of the broker.
• Scale. Millions of attribute values, close to a million entities in one Snapshot, thousands of subscriptions and a thousand tenants behind PgBouncer.
• Storage and maintenance. Bulk ingest, sustained churn, history compression and the maintenance controller at work on bloated tables.
• Restarts and upgrades. A new build reopens a loaded database and must answer the same, keep notifying and keep its Snapshots, and an edited migration must be refused.
• Rarely used features. A sweep through the corners of the specification that few deployments touch, and manual exploratory sessions.
• Closed issues. Every fixed issue is checked again against a running broker, each acceptance criterion on its own.
• Performance. Every performance fix is measured before and after on its own rig with production-sized data, from the broker's and PostgreSQL's own metrics and query plans, and release build settings are benchmarked before they change.
• Query plans. The plans PostgreSQL picks for the broker's statements are captured and read on production-sized data. Statements are checked under the generic plan PostgreSQL reuses across executions and under the stale statistics a table is left with after heavy churn, when the planner can take a large table for a nearly empty one. A statement that plans badly in either case is rewritten so its plan no longer hinges on those estimates, and a statement PostgreSQL would plan again on every execution is made to keep one plan.

Every problem these runs find is filed as an issue, and its fix comes with a test that catches it.

The test rigs are private for now. They will be published once they are cleaned up and ready for others to run.

It has no track record. Nobody has run it in production yet.

Get in touch

If you are considering Andromeda, I would like to hear about your use case. If you have a real workload in mind, tell me about it, and I'll tune Andromeda to handle it well. Open an issue, start a thread in discussions, or email me if you'd rather keep it private.

Specification coverage

Andromeda implements the whole of ETSI GS CIM 009 v1.9.1, the NGSI-LD API specification. It serves every resource and method in Table 6.2-1: entities and attributes with their batch operations, types and attributes, the Temporal API, EntityMaps, subscriptions, context source registrations and their subscriptions, the JSON-LD @context API, Snapshots, and the context source identity. Distributed operations forward to registered context sources in all four registration modes, and notifications go out over HTTP and MQTT.

Where the specification leaves a choice, the behaviour pages say what Andromeda does. A few capabilities beyond the specification are extensions. Cursor pagination is on by default, and a client gets cursor links only when it asks for them. Every other extension is off until you enable it.

Versioning

Andromeda follows Semantic Versioning 2.0.0. Releases are tagged vX.Y.Z. A major release is the only one that may change behaviour you can observe: an HTTP response, a configuration key or an extension. Minor and patch releases don't, and the changelog lists every change. Pin the full version in production.

Compatibility across releases

Database schema

A stable release seals every migration it ships. Sealing records the SHA-256 of each migration file in a ledger, and the release workflow refuses to build a tag whose ledger section is missing or whose sealed files differ from it. A sealed migration is never edited, reformatted, renamed or deleted, and a schema change is always a new migration. A broker can therefore upgrade any tenant database created by an earlier stable release. Upgrades describes the procedure.

Configuration

Within a major version, a configuration written for an earlier release keeps working in a later one, with the same meaning. A new key defaults to the earlier behaviour. Run andromeda configuration validate against your configuration after an upgrade to confirm it, and andromeda configuration generate to see the current keys and their defaults.

Changelog

Every release lists its changes in the changelog, which is generated from the commit history since the previous release. Each release ships a container image.

Pre-releases

An alpha, beta or rc tag (for example v1.1.0-rc.1) is a preview of the next stable release. It gets no latest, X.Y or X image tag, and its migrations are not sealed, so they can still change before the stable release. Don't upgrade a database you want to keep to a pre-release.

Security fixes

Fixes target the latest released version. Report a vulnerability through GitHub private vulnerability reporting, not a public issue. Reports are acknowledged within a few days, and the advisory is published once a release with the fix is available.

Testing

More than 17,000 tests cover Andromeda. Unit tests live in its crates, and the black-box suite drives a running broker through its API with typed Rust tests. The suite has these trees.

• ngsi_ld, the behaviour the specification mandates or leaves to the implementation
• etsi, a port of the ETSI NGSI-LD conformance test purposes, one test per case
• annex_c, the worked examples of annex C of the specification
• andromeda, Andromeda's extensions, limits and configurations
• distributed, distributed operations across several brokers
• interoperability, the ETSI interoperability scenarios across five brokers
• pgbouncer, a broker serving every request through PgBouncer in front of PostgreSQL

Every pull request and every push to the main branch runs these checks.

• formatting, including the TOML files, and shell script lints
• Clippy, with warnings denied
• dependency licences and advisories, and unused dependencies
• the unit tests, including the architecture rules
• the SQL formatting and lint checks, and the migration seal check

The pr-ok check passes when all of them pass, and it's the only check a pull request needs to merge. A pull request runs no suite tree. A push to the main branch also builds a broker image from the commit and runs the ngsi_ld, etsi and annex_c trees against it. The ci-ok check passes when pr-ok and those three trees pass, and a release tag is accepted only on a commit where ci-ok passed and every migration is sealed.

The andromeda, distributed and interoperability trees run every Friday, and gate neither a merge nor a release. Any tree but pgbouncer can also be started by hand. The pgbouncer tree needs fifteen brokers over fifteen PostgreSQL servers, so no workflow runs it.

At v1.0.0 the unit tests ran 12,756 cases and the suite trees ran 2,935 (ngsi_ld), 1,045 (etsi), 66 (annex_c), 421 (andromeda), 758 (distributed) and 61 (interoperability).

Benchmarks explains how to judge performance until benchmark figures are published.