Xenia

Recipes

Whole configs for common setups, each in its own folder under examples/recipes with the files it serves. Each one is served and checked by the tests, so what a recipe says it does, it does. Copy the folder, change the addresses and paths, and run it:

cd examples/recipes/spa
xenia check                          # compile, validate, list the routes
xenia --listen 0.0.0.0:8080          # serve it; xenia.conf.js is the default

Upstream addresses such as 127.0.0.1:3000 stand for your own backends. Paths are relative to the config file. See Configuration for every field.

A single-page app with an API

An app built into dist/: hashed assets, an API, and the client-side routes the app draws itself. A link to /settings/profile, or a reload there, must get index.html too, or the browser shows a 404.

// A single-page app with an API: the built assets, the API behind /api/,
// and index.html for every other path, so the app's own routes load from a
// link or a reload.
//
//   xenia check && xenia --listen 0.0.0.0:8080

import { defineConfig } from 'xenia';

export default defineConfig({
  upstreams: {
    api: { servers: ['127.0.0.1:3000'] },
  },
  routes: [
    // Built with hashed names (app.3f9c1e.js), so they can be kept for good.
    {
      prefix: '/assets/',
      root: 'dist/assets',
      headers: { 'cache-control': 'public, max-age=31536000, immutable' },
    },
    { prefix: '/api/', proxy: 'api' },
    // Everything else is the app, which reads the path and draws the page.
    // no-cache: browsers check for a new index.html, which names new assets.
    { prefix: '/', file: 'dist/index.html', headers: { 'cache-control': 'no-cache' } },
  ],
});

The whole recipe: examples/recipes/spa.

A static site, compressed ahead

A site whose files are compressed when it is built, at the slowest and best levels, instead of on every request:

cd site && find . -type f \( -name '*.html' -o -name '*.css' -o -name '*.js' -o -name '*.svg' \) \
  -exec brotli -kf -q 11 {} \; -exec gzip -kf -9 {} \;
// A static site, compressed when it is built: each file beside its .br and
// .gz copies (brotli -k, gzip -k), sent to the clients that take them, at
// levels too slow to spend on every request.
//
//   xenia check && xenia --listen 0.0.0.0:8080

import { defineConfig } from 'xenia';

export default defineConfig({
  routes: [
    { path: '/robots.txt', file: 'site/robots.txt', headers: { 'cache-control': 'max-age=86400' } },
    {
      prefix: '/',
      root: 'site',
      precompressed: true,
      headers: { 'cache-control': 'max-age=300' },
    },
  ],
});

The whole recipe: examples/recipes/static-site.

A WebSocket backend

An app whose pages are static and whose live part is a WebSocket:

// An app that talks over WebSockets: its socket endpoint proxied, the rest
// of the site static. Any proxy route passes an upgrade through; what is
// worth setting is how long a quiet socket stays open, and how many one
// client may hold.
//
//   xenia check && xenia --listen 0.0.0.0:8080

import { defineConfig } from 'xenia';

export default defineConfig({
  upstreams: {
    // A socket with nothing on it for ten minutes is closed.
    app: { servers: ['127.0.0.1:3000'], tunnelIdleTimeout: 600 },
  },
  limits: {
    // An open socket is a request in flight: 4 at once per client.
    sockets: { inFlight: 4 },
  },
  routes: [
    { prefix: '/ws/', proxy: 'app', limit: 'sockets' },
    { prefix: '/', root: 'public' },
  ],
});

The whole recipe: examples/recipes/websocket.

Behind a load balancer

xenia behind a load balancer or a CDN that ends TLS, and connects from its own addresses:

// Behind a load balancer or a CDN that ends TLS and connects from
// 10.0.0.0/8. Its X-Forwarded-For names each client: for the limits, the
// access log, and the X-Forwarded-For that goes upstream.
//
//   xenia check && xenia --listen 0.0.0.0:8080

import { defineConfig } from 'xenia';

export default defineConfig({
  server: {
    trustedProxies: ['10.0.0.0/8'],
    // No maxConnectionsPerClient: every connection comes from the
    // balancer, which it would not count anyway. The limit below does.
  },
  upstreams: {
    app: { servers: ['127.0.0.1:3000'] },
  },
  limits: {
    // Per client, not per balancer: 20 a second, bursts of 40, and at most
    // 10 requests in flight at once.
    perClient: { rate: 20, burst: 40, inFlight: 10 },
  },
  routes: [
    { path: '/healthz', body: 'ok\n' }, // for the balancer's health checks
    { prefix: '/', proxy: 'app', limit: 'perClient' },
  ],
});

The whole recipe: examples/recipes/behind-load-balancer.

A gradual rollout with feature flags

Moving from one backend to its replacement a route at a time, and back if it misbehaves:

// Moving from one backend (blue) to its replacement (green) a route at a
// time, with feature flags. Each switch is live, needs no reload, and goes
// back the same way. Flags switch whole routes: there are no percentages.
//
//   xenia --listen 0.0.0.0:8080 --admin /run/xenia/admin.sock
//   xenia ctl flags green-export=on    exports go to green first
//   xenia ctl flags green=on           then the rest of /api/
//   xenia ctl flags green=off          ...and back, if green misbehaves

import { defineConfig } from 'xenia';

export default defineConfig({
  upstreams: {
    blue: { servers: ['127.0.0.1:3001'] },
    green: { servers: ['127.0.0.1:3002'] },
  },
  flags: { 'green-export': false, green: false },
  routes: [
    // While the flag is off, this route is not there, and /api/ has export.
    { prefix: '/api/export/', proxy: 'green', flag: 'green-export' },
    { prefix: '/api/', proxy: 'green', flag: 'green' },
    { prefix: '/api/', proxy: 'blue', flag: '!green' },
  ],
});

The whole recipe: examples/recipes/rollout.