Airlift, a Java framework assembled from best-of-breed libraries

A curated dependency set rather than a new abstraction

Airlift describes itself as a framework for building REST services in Java, but the interesting sentence in its own description is the second one. It pulls together stable, mature libraries from the Java ecosystem into a simple, light-weight package, and it takes the best-of-breed libraries from the Java ecosystem and glues them together based on years of experience in building high performance Java services.

That is a different proposition from a framework with its own programming model. There is no Airlift way to write a controller or to bind a request, because Airlift does not define one. What it defines is a set of choices: which HTTP server, which JAX-RS implementation, which JSON library, which configuration system, how metrics are collected, how logging is set up, how the object graph is assembled. You write code against standard and widely used APIs, and Airlift makes sure those pieces agree with each other and are configured consistently.

The project is used as the foundation for distributed systems like Trino, formerly PrestoSQL. That single fact is the most useful signal in the whole README, because it means the configuration, the logging setup, the metrics names and the module boundaries have all been exercised by a large distributed query engine running in production.

The audience is a backend Java team that would otherwise assemble the same stack by hand. The alternative, which is what most people actually do, is to pick a Spring Boot application and add a few libraries. Airlift's pitch is that you get the same result without inheriting a large proprietary framework, and the project puts it plainly: without getting in your way and without forcing you into a large, proprietary framework.

The module list is the feature list

The top-level tree of the repository is the most complete description of what Airlift actually contains, and it is a long one. There are separate modules for `api/`, `api-testing/` and `api-maven-plugin/`, the latter being the piece that generates a server from an interface, plus `bootstrap/`, `configuration/` with a `configuration-testing/` counterpart, `concurrent/`, `http-client/` with its own `http-client-generator/`, `http-server/`, `jaxrs/` with `jaxrs-testing/`, `jackson/`, `json/`, `log/` with a `log-manager/`, `metrics/` with `stats/`, `openmetrics/`, `tracing/` and `opentelemetry/`, `discovery/`, `node/`, `jmx/` and `jmx-http/`, `security/` with `security-jwks/`, `packaging/`, `testing/`, `bom/`, and an `mcp/` directory.

Two things stand out. The first is `mcp/`, with its own README, which is a newer addition and shows the framework growing into the space of Model Context Protocol servers rather than staying a pure internal service toolkit. The second is the symmetry between production and test modules: `api-testing`, `configuration-testing` and `jaxrs-testing` exist as separate artifacts, which tells you the project expects testing to be part of the build rather than something bolted on afterwards.

The `secrets-keystore-plugin/` and `secrets-spi/` pair is another one worth noting. Secrets handling is separated into a service provider interface and a keystore-backed implementation, so the secret source is replaceable, which is the kind of design you only see in a framework that has been extracted from a real production system.

For an adopter, this means the question is not whether Airlift has the feature you need. It almost certainly does. The question is how much of the module graph you want to inherit, and that is a different conversation.

The reference section is half-written, and that is the honest state

The reference list in the README is the most telling part of the documentation, and it is worth reading closely before you invest an afternoon in this project.

Several entries are links to real documents. Configuration points to `docs/ref_configuration.md`, lifecycle and bootstrapping to `docs/ref_lifecycle.md`, APIs to `api/README.md`, the HTTP client to `http-client/README.md`, and MCP server support to `mcp/README.md`. The Getting Started path points to `docs/overview.md`, then `docs/getting_started.md`, then `docs/next_steps.md`.

The rest are marked TBD. Concurrency, database pooling, discovery, events, the HTTP server, packaging, logging, tracing, the Maven BOM and Jackson/JSON all carry the TBD marker in place of a link. The recipes page is worse in a way, because it does exist and contains at least three real recipes, conditional binding based on a config value, serving static HTML files and packaging the service, but the list ends with a literal "TBD - How do I do ... ?" as an open question to the reader.

This is a documentation gap, and it is not the same as a documentation failure. Airlift is used by Trino, so the code works in production. What you lose is the guided path. If you are learning Airlift, you will be reading source code and the Trino codebase, and that is a legitimate way to learn a framework, but it is slower than a written guide and it is not what a team with a deadline wants.

It also shapes the assessment of the project in a way that has nothing to do with quality. A framework that is upstream of a widely deployed query engine has a much lower risk of abandonment than an average open source project. A framework with half-written reference docs has a much higher cost of entry. Both facts are true at the same time.

Configuration, bootstrapping and the code generation path

The pieces the documentation does cover are the ones every Airlift service starts with, and they tell you about the shape of the framework.

Configuration is documented as a reference page and as a set of recipes, and the recipe list is revealing. Conditional binding based on a config value is a first-class recipe, which means the configuration system is not a flat key-value file with a getter. It is a system that can decide which bindings exist based on the configuration itself, which is what you need when a service has optional subsystems, a feature that a YAML properties file cannot express.

Lifecycle and bootstrapping has its own reference page. In a framework that assembles the object graph by dependency injection and starts an HTTP server, the bootstrap order is the part that decides whether a service comes up cleanly, and a dedicated page for it suggests the maintainers treat it as a concept rather than an implementation detail.

The `api-maven-plugin/` module is the other structural piece. It sits next to `api/` and `api-testing/`, which means the intended path for defining an interface is to write it once and have the plugin generate the implementation and the test scaffolding, the same way the HTTP client generator produces a client from a specification. The plugin is also why there is an `api-testing/` artifact at all: if the server implementation is generated, the tests that matter are contract tests, and they need a home.

The practical upshot for a new service is that the code you write is small and declarative, and the parts you would have written by hand are generated. That is the value proposition, and it is also why the framework can be small: it is mostly glue and code generation rather than runtime machinery.

Where Airlift sits against a conventional Java stack

The real alternative to Airlift is not another framework, it is assembling the same libraries yourself, or picking a big framework and inheriting its conventions.

Assembling it yourself means choosing an HTTP server, a JAX-RS runtime, a JSON library, a configuration system, a metrics registry, a logging setup, a dependency injection container, a tracing exporter and a test framework, then writing the bootstrap code, the configuration plumbing, the JSON serialization configuration and the metric registration for each service. Airlift's claim is that it has done that work, that the choices are good ones, and that the glue is consistent across services. Whether that is worth it depends entirely on how many services you run.

A big framework is the other option, and the project names it without naming a specific product. The tradeoff is that a large proprietary framework imposes a programming model, a configuration style and a deployment story, and it usually arrives with a large surface you only learn the parts of that you need. Airlift's pitch is that you keep the standard and best-of-breed libraries and avoid the model.

The honest way to weigh this is against a single service. A team building one small internal REST API gets almost nothing from Airlift, because it is a framework for organisations that ship many services and want them to look the same. A team running twenty services with four teams gets a lot, because the consistency argument starts to dominate.

Trino is the proof point, but it is a proof point for the design, not for the documentation. A new user cannot learn Airlift from Trino's own code alone, and the reference section's TBD markers are the reason.

Getting started means reading the skeleton and the sample

There is no install command in this project's documentation, and there is no quickstart script, because Airlift is not distributed as an application. It is a set of Maven artifacts under the io.airlift group, published to Maven Central, and a service is built by depending on the modules it needs and bootstrapping them yourself.

That is why the getting started path in the README is a chain of documents rather than a sequence of commands. The reader starts with the overview, moves to the getting started guide, and then to the next steps document, and the reference section follows from there. The build itself is a Maven build, the tree ships an `mvnw` wrapper, and there is a `bom/` module for dependency management, so the practical setup is a Maven project that imports the BOM and the modules it wants.

The two directories that make this concrete are `skeleton-server/` and `sample-server/`. A skeleton is the starting point for a new service, and a sample is the reference implementation to read when the getting started guide runs out. Since the concurrency, database pooling, discovery, packaging, logging and tracing reference pages are marked TBD, those two directories are doing the teaching work that the written reference has not yet taken over.

For a first real use, the shortest path is to take the skeleton, add the `api-maven-plugin/` so an interface can be turned into a generated server implementation, wire the configuration the way the conditional binding recipe shows, and start the HTTP server through the documented lifecycle. Whether the getting started document spells that out step by step is the open question, since it is one of the few pages the README does link to directly.

Numeric releases, an Apache licence and a fast commit cadence

The release record uses plain numbers: 452 on 2026-10-18, 451 on 2026-10-06 and 450 on 2026-09-27. There is no semantic version to read, and no marketing version, just a counter that increments. The last push to the repository was on 2026-10-22, four days after the 452 release, so the development branch moves faster than the releases do.

The licence is Apache-2.0, with a LICENSE file at the top of the tree. That is the permissive grant with an explicit patent clause and a requirement to mark modifications, and for a framework intended to be embedded in other people's services it is the licence you would expect. There is no copyleft obligation that reaches your own code through the dependency.

The upgrade cost is where a numeric version scheme shows its weakness. With semantic versioning you can reason about breaking changes from the version number alone. With a counter, you have to read the CHANGES file at the top of the tree, or the release notes, to know what moved. Airlift is used as the foundation of Trino, so in practice the Trino project is the de facto compatibility signal, but a standalone adopter has no such anchor.

The other thing the tree reveals is the breadth of the build tooling. There is a `mvnw` wrapper, a `.mvn/` directory, a `bom/` module for dependency management, a `packaging/` module, and separate `api-maven-plugin/` and `http-client-generator/` modules for code generation. There is also a `skeleton-server/` directory and a `sample-server/`, which are the two directories a new user should look at first, since a skeleton is a starting point and a sample is a reference.

Everything in the repository is Java with a Maven build, and the modules such as `jackson/`, `json/` and `jaxrs/` are the concrete names behind the claim of being best-of-breed. Where the documentation is silent, those module directories and the `bom/` are where the actual decisions are recorded.

Editorial conclusion

Airlift suits a Java team that wants the server side of Trino's stack, or that has been assembling the same libraries by hand and wants the wiring settled once, with the JAX-RS, HTTP client, metrics, tracing and JMX modules already integrated. It does not suit a team that wants a documented quickstart, because the reference section still has concurrency, database pooling, discovery, packaging, logging, tracing, the Maven BOM and JSON listed as TBD, and it does not suit a small service that would rather depend on one web framework than on thirty modules. Verify first that the reference pages you need are actually written rather than marked TBD, and read the configuration reference before you commit, because the configuration model is the part of Airlift that shapes every service you build on it.

Frequently asked questions

Official sources

1. airlift/airlift on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases