Mosaic

Install & run

Mosaic runs two ways. As a server: install the prebuilt binary, write a mosaic.toml, mosaic serve — no Amalgame code, no compiler (nginx/Caddy style). As a library: add the stack to your own project and write your own handlers. Full guide on docs.amalgame.me → Mosaic.

As a server — zero Amalgame code

# install once
curl -sSL https://raw.githubusercontent.com/amalgame-lang/mosaic/main/install.sh | bash

# run the whole stack from a config file
mosaic serve /etc/mosaic/mosaic.toml

One binary, N sites over HTTPS — static hosting, TLS + ACME, per-site middleware, and reverse-proxy / load-balanced hosts. A mosaic.toml mixes static sites and proxies:

[server]
port = 443
tls  = true

[tls]
acme  = true
email = "admin@example.com"

# a static site by Host
[[site]]
hosts = ["example.com", "www.example.com"]
root  = "/srv/example/public"

# a reverse proxy / load balancer by Host
[[proxy]]
hosts  = ["api.example.com"]
routes = [
  { prefix = "/",      upstream  = "http://127.0.0.1:8080" },
  { prefix = "/heavy", upstreams = ["http://127.0.0.1:9001", "http://127.0.0.1:9002"], strategy = "round_robin" },
]

As a library — write your own handlers

# add the stack to your project, then build with the mosaic tool
amc package add web net-http tls
mosaic build  # or: write server.am and `amc run`

Four ways to deploy, from a config-only server to a hand-rolled binary — see the installation guide.

Composable-package architecture

The stack follows the Amalgame convention: small, focused packages. Import just TLS for a custom protocol, just HTTP for a low-level client/server, or amalgame-web + the mosaic tool for the full stack.

HTTPS Hello world — native ACME, the binary handles the rest

One AcmeNative.EnsureCert call provisions the certificate (http-01 challenge, RFC 8555, no certbot), then ServeHttpsMt terminates TLS in-process — no reverse proxy required.

namespace App
import Amalgame.Web
import Amalgame.Tls

public class Program {
    public static void Main(string[] args) {
        // Native RFC 8555 ACME — no subprocess, ES256 account key
        AcmeNative.EnsureCert("my-site.com", "admin@my-site.com",
                            "./certs", AcmeNative.LeStaging())

        let app: WebApp = WebApp.New()
            .WithSecurityHeaders(SecurityHeaders.StrictHtml())  // HSTS, CSP, XFO…
            .WithCsrf(Csrf.Default())                          // double-submit cookie
            .WithRateLimit(RateLimit.PerIp(100, 60))            // 100 req / 60 s / IP
            .WithStatic(Static.New("/assets", "./public").WithCacheMaxAge(3600))
        Routes.Bind(app)                                  // routes generated from app/

        app.ServeHttpsMt(443, "./certs/my-site.com/fullchain.pem",
                              "./certs/my-site.com/privkey.pem")
    }
}

Filesystem routing — Next.js convention

Every .am file under app/ becomes a route. Names with [id] capture a parameter (:id), [...slug] captures a catch-all (*slug). mosaic build scans the tree and generates _routes.am; Routes.Bind(app) wires it all up. Files in public/ are served automatically.

my-app/
├── amalgame.toml
├── mosaic.toml              # [security.*], [tls], [logging]…
├── server.am                # entry point: WebApp + Routes.Bind
├── app/
│   ├── index.am             → GET /
│   ├── about.am             → GET /about
│   ├── users/
│   │   ├── index.am         → GET /users
│   │   ├── [id].am          → GET /users/:id
│   │   └── [id]/posts.am    → GET /users/:id/posts
│   └── api/
│       ├── login.am         → POST /api/login
│       └── [...path].am     → catch-all route
├── lib/
├── public/                  # served at / (ETag, 304, binary-safe)
└── data/

Each file exports a Page class with methods named after the HTTP verb (GET / POST / PUT / PATCH / DELETE), each taking a WebContext:

// app/users/[id].am
namespace App.Users.Detail
import Amalgame.Web
import Amalgame.Net.Http

public class Page {
    public static HttpResponse GET(ctx: WebContext) {
        let id: string = ctx.Param("id")
        let user = Db.FindUser(id)
        if (user == null) {
            return HttpResponse.New().Status(404).Text("User not found")
        }
        return HttpResponse.New().Json(user)
    }
}

The mosaic tool — from scaffold to prod

Four commands cover the whole cycle. The tool installs once (curl … install.sh | bash) and runs from any project.

L7 security + auth built-in — already shipped

L3/L4 defense stays with the operator (kernel sysctl, firewall, CDN). Everything application-layer is in the framework, opt-in via .With*() and orchestrated by WebApp in the right pipeline order:

• ✓WithSecurityHeaders (v0.4) — StrictHtml() / StrictApi(): HSTS, CSP, X-Frame-Options, nosniff, Referrer-Policy, Permissions-Policy, COOP/COEP
• ✓WithCsrf (v0.7) — double-submit cookie, 256-bit token, Secure + SameSite=Lax
• ✓WithCors (v0.5) — deny by default, AllowAll / Strict presets, OPTIONS preflight handling
• ✓WithRateLimit (v0.6) — per-IP fixed window, 429 + Retry-After on overflow
• ✓WithStatic (v0.13 · caching v0.27) — file serving, strong ETag + Last-Modified, 304 (If-None-Match / If-Modified-Since), Range 206 / 416, pre-compressed .gz selection, path-traversal guard, ~35 MIME types
• ✓WithCompress (v0.26) — on-the-fly gzip, negotiated via Accept-Encoding (text/*, JSON, JS, SVG, XML), sets Vary; via amalgame-compress
• ✓Multipart uploads (v0.25) — ctx.Multipart() → UploadedFile (binary-safe, SaveTo / Bytes / Text) + text fields, capped by max_body_bytes
• ✓Template engine (v0.24) — Mustache-like Template, HTML auto-escape by default (closes the .Html() XSS hole), ctx.Render(path, data); {{{x}}} for raw
• ✓BasicAuth (v0.15, RFC 7617) · JwtAuth (v0.16, HS256) · OAuth2Client (v0.17, GitHub/Google presets, authorization-code flow)
• ✓Sessions — MemorySessionStore, SignedCookieSessionStore (HMAC-SHA-256, stateless), RedisSessionStore
• ✓WithLogging (v0.8.2) — structured access logs via amalgame-logging, driven by [logging]
• ✓Anti-slowloris timeouts via HttpServerConfig — header/body/idle timeouts, max_body_bytes, max_header_bytes

RFC 6455 WebSocket — built-in server

The WebSocket server lives in amalgame-net-http: Ws.Serve in cleartext, Wss.Serve over TLS. The handler receives a connection and loops on WsConn. The *With variants apply the same socket timeouts as the HTTP server.

import Amalgame.Net.Http

let handler = conn => {
    while (!WsConn.IsClosed(conn)) {
        let msg: string = WsConn.ReceiveText(conn)
        if (String_Length(msg) == 0) { return 0 }   // disconnected
        WsConn.SendText(conn, "echo @ " + msg)
    }
    return 0
}

Ws.Serve(8080, handler)                          // ws://  — Wss.Serve(port, cert, key, handler) for wss://

Subprotocol negotiation (v0.17) — Ws.ServeWithProtocols(port, "v2.json,v1", handler) echoes back the first Sec-WebSocket-Protocol the server supports; WsConn.Subprotocol(conn) reads it. Phoenix-style multi-client pub/sub (channels, topics, broadcast) is not yet a framework primitive: build it on top of WsConn, or wait for a dedicated version (see roadmap).

Server-Sent Events — one-way push

For live push (progress, notifications, tickers) without the weight of a WebSocket: app.Sse("/events", sc => { ... }) (v0.28). The handler holds the connection and pushes frames via SseConn — Send(data) (false when the client leaves), SendEvent(event, data, id), Comment (heartbeat), Retry. Browser side: new EventSource("/events").

Concurrency: thread pool or fibers, your choice

Go net/http model — blocking I/O, native multi-core, no async/await contaminating your code. WebApp exposes 7 Serve modes; pick based on load.

• ✓Serve / ServeWith — serial HTTP/1.1 loop, simple, for dev or low load
• ✓ServeMt / ServeMtWith — one thread per connection (~8 MB lazy stack), prod default for CPU-bound handlers
• ✓ServeAsync (v0.12) — 1 thread, N fibers (~64 KB/conn), Linux epoll — ideal for I/O-bound handlers, thousands of connections
• ✓ServeHttps / ServeHttpsMt (v0.14) — in-process TLS termination, no reverse proxy required
• ✓HTTP/1.1 keep-alive — enabled whenever idle_timeout_sec > 0
• ✓Graceful shutdown — SIGTERM/SIGINT handler, drains in-flight requests, clean exit

Roadmap — where we are

The stack started from scratch in mid-May 2026 and shipped, in a few weeks, an end-to-end usable web stack. Here's the real state.

Beyond HTTP — nginx "front door" ambition

Beyond HTTPS listening, Mosaic aims at the nginx/apache front-door role: reverse proxy, load balancing, raw TCP/UDP proxying. Inventory in the beyond-http.md proposal. Reverse proxy and load balancing have shipped; the raw-stream and relay bricks remain roadmap.

Follow the progress

Mosaic is public and usable. The spec is the source of truth — phases advance through PRs tracked on the repos.