Ableron – Decentralized UI Composition

What is Ableron?

Ableron is a library for decentralized server-side UI composition. Unlike traditional solutions like nginx SSI, there’s no central component. Each service is capable of composing its own HTML using <ableron-include> tags, resolved internally. This is achieved by installing Ableron as a dependency in your service.

Why Ableron?

TL;DR: Ableron is a decentralized, efficient solution for dynamic, server-side UI composition with local caching, easy configuration, and great developer experience.

💡

Lean Infrastructure

No need to route all traffic through a centralized infrastructure component for UI composition. Services stay independent and scalable.

🚀

Easy Local Development

Since includes are resolved directly within your service, local development works out of the box — without needing to run complex infrastructure setups.

⚙️

Simple Configuration

Configure per-include settings like timeouts, fallback fragments, or static fallback content with minimal effort — no central coordination required.

💾

Local Caching

All fragments can be cached in memory directly inside your service, based on their individual cache policy. This reduces HTTP overhead and latency — saving both time and money.

Ableron vs nginx SSI

Feature	Ableron	nginx SSI
Centralized vs Distributed	Decentralized (each service composes its own UI)	Centralized (nginx manages UI composition)
Developer Experience	Easy local development with no extra infrastructure	Requires complex infrastructure setup for local development
Scalability	Scalable by design, no bottlenecks	Potential bottleneck at the centralized server
Caching	In-memory fragment caching per service	Caching typically done at the centralized infrastructure level
Complexity	Low complexity (library-based, no additional infrastructure)	Higher complexity with nginx or similar infrastructure

Quickstart

Ableron provides framework integrations for Spring Boot 2, Spring Boot 3, express and fastify as well as low level implementations for Java and JavaScript.

Minimal usage example with express:

import express from 'express';
import ableron from '@ableron/express';

const app = express();
app.use(ableron());

app.get('/', function(req, res) {
  res.send('<ableron-include src="http://user-service/profile"/>');
});

app.listen(port);

More examples and documentation available in the GitHub repository.

Ableron-Tag Properties

The <ableron-include> tag is used to include fragments from external URLs into your page. It comes with various attributes and fallback options.

Required Closing Tag

The <ableron-include> tag must be properly closed. You can either use the self-closing syntax <ableron-include ... /> or explicitly close the tag with <ableron-include ...></ableron-include>.

Fallback Content

Content placed between <ableron-include> and </ableron-include> is used as fallback content in case the fragment cannot be loaded due to request timeout or erroneous response.

Attributes

id: A unique identifier for the include tag. This is useful for log messages and debugging.
src: The URL of the fragment to be included. This is the primary source of the fragment content.
src-timeout: Timeout for requesting the fragment URL. This can be specified in milliseconds (e.g., 2000 or 2000ms) or seconds (e.g., 2s). Defaults to the global request timeout.
fallback-src: The URL to a fallback fragment, in case the primary src fails to load.
fallback-src-timeout: Timeout for requesting the fallback-src URL. The value can be specified similarly to src-timeout.
primary: Denotes a fragment whose response code will be set as the HTTP response code for the entire page.
headers: A comma-separated list of headers that should be forwarded from the parent request to the fragment request. These headers become part of the cache key for the requested URL.
cookies: A comma-separated list of cookies that should be forwarded to the fragment request. These cookies also become part of the cache key for the requested URL.

Resolution Precedence

When resolving the fragment content, the precedence is as follows: src → fallback-src → fallback content. This ensures a robust fallback mechanism in case of failures.

Ableron-Tag Example

Here's an example of how you can use the <ableron-include> tag to include external fragments into your service response. This example demonstrates the use of several important attributes, such as src, fallback-src, headers, cookies, and fallback content.

<ableron-include
  id="header"
  src="https://header-service/api/fragments/header"
  src-timeout="2s"
  fallback-src="https://cdn-proxy/static/fallback-header"
  headers="x-ab-test-groups,x-country"
  cookies="device,consent">
  <header>Static fallback header</header>
</ableron-include>

In this example:

id: The unique identifier for this include, which can be helpful for logging and debugging (in this case, "header").
src: The primary URL from which the fragment will be fetched. In this case, it's an API endpoint for the header fragment.
src-timeout: The request timeout for the fragment URL. In this case, the request will is considered failed after two seconds.
fallback-src: A fallback URL for the header fragment in case the primary request fails. Here, a CDN URL might be a good choice.
headers: A comma-separated list of headers to forward from the parent request to the fragment request. Useful, if headers are part of the API and the fragment response differs in regard to the provided headers.
cookies: A comma-separated list of cookies to forward to the fragment request. Same logic as with headers.
Fallback Content: If the src and fallback-src both fail, the content between the opening and closing <ableron-include> tags will be used as a static fallback. In this case, it’s a simple static <header> element.

Advanced Features

⭐ Primary Includes

Ableron supports marking an <ableron-include> as primary. Primary includes are considered to be the main part of the finally composed page and thus define the HTTP response status and influence response headers.

If src returns success status, this status code is set as response code for the entire page.
If src returns error status, fallback-src is defined and returns success status, this status code is set as response code for the entire page.
If src and fallback-src both return error status, the status code returned by src is set as response code for the entire page and the fragment content is set to the body returned by src. Fallback content is ignored.
Response headers will be forwarded to the finally composed page, in case they are whitelisted in global configuration.

🔁 Cache Auto Refresh

Ableron supports automatic cache refreshing for included fragments — a feature designed to keep response times low and cache hit rates high.

Auto refresh is disabled by default and must be explicitly enabled via configuration.
If enabled, cached fragments are refreshed asynchronously before their TTL expires — reducing the chance of a cache miss.
Refresh attempts are triggered when only 15% of the original TTL is remaining.
In case of refresh failure, up to 3 retries are made with a static 1-second delay.
Ableron limits refreshing for inactive fragments — i.e., those that have not been accessed since the last cache write — based on a configurable threshold.
This strategy keeps latency low while avoiding excessive backend load.

📊 Statistics

To provide insights into what is happening during page composition, Ableron provides the opportunity to add composition statistics to the finally composed page via HTML comment. This feature is disabled by default, as you may not want to expose those statistics in your production environment.

<!-- Processed 4 includes in 93ms

Time | Include | Resolved With | Fragment Cacheability | Fragment URL
------------------------------------------------------
0ms | header | fallback content | - | -
56ms | main | remote src | not cacheable | https://content-service/main
93ms | footer | remote src | expires in 600s | https://content-service/footer
0ms | nav | cached fallback-src | expires in 10s | https://content-service/nav

Cache: 3 items, 1 hits, 3 misses, 0 successful refreshs, 0 failed refreshs
-->

FAQ

Which fragments will be cached?

Fragments will be cached, if their cache policy allows caching and if the response code is one of 200, 203, 204, 206, 300, 404, 405, 410, 414, 501.

How are redirects being handled?

In order to not introduce unwanted latency, redirects returned by src or fallback-src URLs will not be followed. Instead, the request is considered failed.

Does Ableron influence the Cache-Control of my page?

As each fragment brings its own cache policy, Ableron will adjust the cache policy of the finally composed page accordingly. The fragment with the lowest TTL defines the max-age of the page, in case max age of the page is not below it.

Contributing

All contributions are greatly appreciated. To contribute, either open an issue or fork the repository and create a pull request:

Fork the repository
Create your feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Added some amazing feature'
Push to your branch: git push origin feature/amazing-feature
Open a pull request