Mosaic

Installer & lancer

Mosaic se lance de deux façons. Comme serveur : on installe le binaire pré-compilé, on écrit un mosaic.toml, mosaic serve — aucun code Amalgame, aucun compilateur (façon nginx/Caddy). Comme bibliothèque : on ajoute la stack à son propre projet et on écrit ses handlers. Guide complet sur docs.amalgame.me → Mosaic.

Comme serveur — zéro code Amalgame

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

# lancer toute la pile depuis un fichier de config
mosaic serve /etc/mosaic/mosaic.toml

Un binaire, N sites en HTTPS — hébergement statique, TLS + ACME, middleware par site, et des hosts en reverse proxy / load balancing. Un mosaic.toml mélange sites statiques et proxies :

[server]
port = 443
tls  = true

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

# un site statique par Host
[[site]]
hosts = ["example.com", "www.example.com"]
root  = "/srv/example/public"

# un reverse proxy / load balancer par 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" },
]

Comme bibliothèque — écris tes propres handlers

# ajoute la stack à ton projet, puis build avec l'outil mosaic
amc package add web net-http tls
mosaic build  # ou : écris server.am et `amc run`

Quatre façons de déployer, du serveur tout-en-config au binaire fait main — voir le guide d'installation.

Architecture en packages composables

La pile suit la convention Amalgame : des packages petits et focalisés. Tu importes juste TLS pour un protocole custom, juste HTTP pour un client/serveur bas niveau, ou amalgame-web + l'outil mosaic pour la pile complète.

Hello world HTTPS — ACME natif, le binaire gère le reste

Un appel à AcmeNative.EnsureCert provisionne le certificat (challenge http-01, RFC 8555, sans certbot), puis ServeHttpsMt termine le TLS in-process — pas de reverse proxy requis.

namespace App
import Amalgame.Web
import Amalgame.Tls

public class Program {
    public static void Main(string[] args) {
        // ACME RFC 8555 natif — pas de sous-process, clé compte ES256
        AcmeNative.EnsureCert("mon-site.com", "admin@mon-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 générées depuis app/

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

Filesystem routing — convention Next.js

Chaque fichier .am sous app/ devient une route. Les noms en [id] capturent un paramètre (:id), [...slug] capture un catch-all (*slug). mosaic build scanne l'arbo et génère _routes.am ; Routes.Bind(app) branche le tout. Les fichiers de public/ sont servis automatiquement.

mon-app/
├── amalgame.toml
├── mosaic.toml              # [security.*], [tls], [logging]…
├── server.am                # point d'entrée : 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/                  # servi à / (ETag, 304, binary-safe)
└── data/

Chaque fichier exporte une classe Page avec des méthodes nommées d'après le verbe HTTP (GET / POST / PUT / PATCH / DELETE), chacune recevant un 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)
    }
}

L'outil mosaic — du scaffold à la prod

Quatre commandes couvrent tout le cycle. L'outil s'installe une fois (curl … install.sh | bash) et se lance depuis n'importe quel projet.

Sécurité L7 + auth built-in — déjà livré

La défense L3/L4 reste à l'opérateur (kernel sysctl, firewall, CDN). Tout l'applicatif est dans le framework, opt-in via .With*() et orchestré par WebApp dans le bon ordre du pipeline :

• ✓WithSecurityHeaders (v0.4) — StrictHtml() / StrictApi() : HSTS, CSP, X-Frame-Options, nosniff, Referrer-Policy, Permissions-Policy, COOP/COEP
• ✓WithCsrf (v0.7) — double-submit cookie, token 256 bits, Secure + SameSite=Lax
• ✓WithCors (v0.5) — deny par défaut, AllowAll / Strict presets, gestion preflight OPTIONS
• ✓WithRateLimit (v0.6) — fenêtre fixe par IP, 429 + Retry-After au dépassement
• ✓WithStatic (v0.13 · caching v0.27) — service de fichiers, ETag fort + Last-Modified, 304 (If-None-Match / If-Modified-Since), Range 206 / 416, sélection .gz pré-compressé, garde anti-traversée, ~35 types MIME
• ✓WithCompress (v0.26) — compression gzip à la volée, négociée par Accept-Encoding (text/*, JSON, JS, SVG, XML), Vary posé ; via amalgame-compress
• ✓Uploads multipart (v0.25) — ctx.Multipart() → UploadedFile (binaire-safe, SaveTo / Bytes / Text) + champs texte, plafonné par max_body_bytes
• ✓Moteur de templates (v0.24) — Template Mustache-like, auto-échappement HTML par défaut (ferme le trou XSS de .Html()), ctx.Render(path, data) ; {{{x}}} pour le brut
• ✓BasicAuth (v0.15, RFC 7617) · JwtAuth (v0.16, HS256) · OAuth2Client (v0.17, presets GitHub/Google, flow authorization code)
• ✓Sessions — MemorySessionStore, SignedCookieSessionStore (HMAC-SHA-256, stateless), RedisSessionStore
• ✓WithLogging (v0.8.2) — access logs structurés via amalgame-logging, pilotés par [logging]
• ✓Timeouts anti-slowloris via HttpServerConfig — header/body/idle timeouts, max_body_bytes, max_header_bytes

WebSocket RFC 6455 — serveur intégré

Le serveur WebSocket vit dans amalgame-net-http : Ws.Serve en clair, Wss.Serve sur TLS. Le handler reçoit une connexion et boucle sur WsConn. Les variantes *With appliquent les mêmes timeouts socket que le serveur HTTP.

import Amalgame.Net.Http

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

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

Négociation de sous-protocole (v0.17) — Ws.ServeWithProtocols(port, "v2.json,v1", handler) renvoie au client le premier Sec-WebSocket-Protocol supporté ; WsConn.Subprotocol(conn) le relit. Le pub/sub multi-clients façon Phoenix (channels, topics, broadcast) n'est pas encore une primitive du framework : à construire au-dessus de WsConn, ou en attendre une version dédiée (voir roadmap).

Server-Sent Events — push unidirectionnel

Pour du push live (progression, notifications, tickers) sans le poids d'un WebSocket : app.Sse("/events", sc => { ... }) (v0.28). Le handler tient la connexion et pousse des frames via SseConn — Send(data) (false quand le client part), SendEvent(event, data, id), Comment (heartbeat), Retry. Côté navigateur : new EventSource("/events").

Concurrence : thread pool ou fibres, au choix

Modèle Go net/http — blocking I/O, multi-core natif, pas d'async/await qui contamine le code. WebApp expose 7 modes de Serve ; tu choisis selon la charge.

• ✓Serve / ServeWith — boucle série HTTP/1.1, simple, pour dev ou charge faible
• ✓ServeMt / ServeMtWith — un thread par connexion (~8 MB de stack lazy), défaut prod pour handlers CPU-bound
• ✓ServeAsync (v0.12) — 1 thread, N fibres (~64 KB/conn), epoll Linux — idéal handlers I/O-bound, milliers de connexions
• ✓ServeHttps / ServeHttpsMt (v0.14) — terminaison TLS in-process, pas de reverse proxy requis
• ✓HTTP/1.1 keep-alive — actif dès que idle_timeout_sec > 0
• ✓Graceful shutdown — handler SIGTERM/SIGINT, drain des requêtes en vol, exit propre

Roadmap — où on en est

La pile a démarré de zéro mi-mai 2026 et a livré, en quelques semaines, une pile web utilisable de bout en bout. Voici l'état réel.

Beyond HTTP — ambition « front door » nginx

Au-delà de l'écoute HTTPS, Mosaic vise le rôle de front door nginx/apache : reverse proxy, load balancing, proxy TCP/UDP brut. Inventaire dans la proposal beyond-http.md. Le reverse proxy et le load balancing sont livrés ; les briques raw-stream et relais restent de la roadmap.

Suivre l'avancement

Mosaic est public et utilisable. La spec est la source de vérité — les phases avancent par PRs trackées sur les repos.