Guide · Chapter 11

Web Runtime

Build persistent JSON APIs, streaming services, and multi-worker applications with HHY.

Start with one API

v1.4.3 contains the complete v1.4.0–v1.4.3 Web release train. Each worker loads the application once, handlers are reusable, and one failed request returns 500 without terminating later requests.

import web

fn hello(request) {
    web.json({ ok: true, name: request.query_params.name })
}

web.app()
    |> web.request_id
    |> web.health
    |> web.metrics
    |> web.gzip
    |> web.get("/hello", hello)
    |> web.listen({ host: "127.0.0.1", port: 8080, workers: 4 })

hhy serve app.hhy
hhy serve --dev app.hhy

v1.4.3 capability boundary

Layer	Capabilities
Runtime	Opaque C embedding, JSON boundary, AST/Bytecode, 100,000-call repetition test
HTTP	HTTP/1.1, Router, Query/Header/Cookie, hard body limits, stable 4xx/5xx
Application	Middleware, ETag static files, upload, CORS, signed cookies, trusted proxy, hot reload
Production	Stream, SSE, Range, prefork workers, health checks, structured logs, Prometheus metrics

Use the HHY Web framework

HHY Web is a separate lightweight framework built on the v1.4.3 Web Runtime. It combines a Flask-inspired approachable API with Go-like explicit deployment, adding an application factory, five HTTP verbs, middleware, blueprints, stable Problem JSON, bearer authentication, uploads, Stream, and SSE helpers without duplicating the Router, worker model, or network stack.

View HHY Web on GitHub ↗The public repository includes English and Chinese guides, Hello World, a complete JSON API, CLI, unit tests, and a real HTTP smoke test.

git clone https://github.com/hh696-wq/hhy-web.git
cd hhy-web
./bin/hhy-web run examples/hello/app.hhy --port 8000 --dev
curl http://127.0.0.1:8000/

import "./lib/hhyweb.hhy" as hhyweb

fn hello(request) {
    return hhyweb.json({
        message: "Hello, HHY Web!",
        request_id: request.id
    })
}

hhyweb.minimal()
    |> hhyweb.get("/", hello)
    |> hhyweb.serve({ host: "127.0.0.1", port: 8000, workers: 1 })