axon-web

Axon HTTP framework — Landing page + M14 framework implementation.

axon-web is the HTTP framework for the Axon ecosystem. It includes:

A landing page (deployed to GitLab Pages from public/)
A radix-tree HTTP request router (tools/router.py)
A composable middleware pipeline (tools/middleware.py)
Built-in middleware: RequestLogger, Cors, RecoverFromPanic (tools/builtin_middleware.py)
A static file server (tools/static_server.py)
A JSON codec (tools/json_codec.py)
A WebSocket protocol implementation (tools/websocket.py)
An HTTP/1.1 request parser (tools/http_parser.py)

Important: public/ is the landing page. It is not the HTTP framework.

M14 Module Index

axon-web ships a growing Python web framework in tools/. Each module has a dedicated doc in docs/:

Module	What it does	Doc
`router.py`	Radix-tree HTTP request router	`docs/router.md`
`middleware.py`	Composable middleware pipeline	`docs/middleware.md`
`builtin_middleware.py`	`RequestLogger`, `Cors`, `RecoverFromPanic`	`docs/middleware.md`
`static_server.py`	Static file server	`docs/static-server.md`
`json_codec.py`	JSON encode/decode	`docs/json-codec.md`
`websocket.py`	WebSocket protocol (RFC 6455)	`docs/websocket.md`
`http_parser.py`	HTTP/1.1 request parser (RFC 7230)	`docs/http-parser.md`
`template_engine.py`	HTML templating (Django/Jinja2-style)	`docs/template-engine.md`
`html_builder.py`	Typed, XSS-safe HTML builder DSL	`docs/html-builder.md`
`tls.py`	HTTPS / TLS termination (OpenSSL FFI)	`docs/tls.md`
`serve_demo.py`	Demo HTTP server	—
`serve_tls_demo.py`	Demo HTTP+HTTPS server	`docs/tls.md`

Current State

axon-web/
├── public/                     # Landing page (deployed to GitLab Pages)
│   ├── index.html
│   ├── style.css
│   └── main.js
├── tools/
│   ├── router.py               # M14: HTTP request router (radix tree)
│   ├── middleware.py           # M14: middleware pipeline
│   ├── builtin_middleware.py   # M14: built-in middleware (RequestLogger, Cors, RecoverFromPanic)
│   ├── static_server.py        # M14: static file server
│   ├── json_codec.py           # M14: JSON codec
│   ├── websocket.py            # M14: WebSocket protocol (RFC 6455)
│   ├── http_parser.py          # M14: HTTP/1.1 request parser (RFC 7230)
│   ├── template_engine.py      # M14: HTML templating engine
│   ├── tls.py                  # M14: TLS/HTTPS termination (OpenSSL via stdlib ssl)
│   ├── serve_demo.py           # M14: demo HTTP server
│   └── serve_tls_demo.py       # M14: demo HTTP+HTTPS server
├── tests/
│   ├── test_router.py          # Router tests (28 tests)
│   ├── test_router_properties.py  # Property-based router tests
│   ├── test_middleware.py      # Middleware tests
│   ├── test_websocket.py       # WebSocket tests
│   └── ...                     # Other M14 test suites
├── docs/
│   ├── router.md               # Router documentation
│   ├── middleware.md           # Middleware documentation
│   ├── websocket.md            # WebSocket documentation
│   ├── http_parser.md          # HTTP parser documentation
│   └── ...                     # Other M14 docs
├── .gitlab-ci.yml              # CI: lint, tests, perf gates
└── README.md                   # This file

Quick Start

from router import Router
from middleware import Request, Response

router = Router()

@router.get("/")
def home(req):
    return Response(200, {}, b"hello")

@router.get("/users/:id")
def get_user(req):
    return Response(200, {}, f"user {req.path_params['id']}".encode())

resp = router.dispatch(Request("GET", "/users/42", {}, b""))
assert resp.status == 200

See docs/router.md for the full router reference.

What This Repo Will Become

axon-web implements an HTTP server framework in pure Axon:

M14 modules: HTTP router (radix tree), middleware pipeline, JSON encoder/decoder, WebSocket protocol upgrade, static file serving, HTML templating, HTTP/2 HPACK + multiplexing, zero-copy request parser, TLS/SSL via OpenSSL FFI

See the M14 Milestone Roadmap below.

Framework Source Layout

The src/ directory contains the Axon framework modules. These are type-declared stubs (no runtime implementation yet) that establish the public API for the M14 framework:

src/
├── router.axs       # HTTP request router (radix tree) — axon-web#1
├── middleware.axs   # Composable middleware pipeline — axon-web#2
├── json.axs         # JSON encoder/decoder — axon-web#3
├── static.axs       # Static file server — axon-web#4
├── websocket.axs    # WebSocket protocol (RFC 6455) — axon-web#5
└── http_parser.axs  # HTTP/1.1 request parser — axon-web#12

Each module provides:

Type declarations (enums, structs, function pointers)
Public API (pub functions)
Stub implementations that return safe defaults (no-ops, error codes)

The Python prototype of these modules lives in tools/ (e.g., tools/router.py). The Axon modules are the native implementation; the Python versions serve as the reference implementation and for property-based testing.

Module APIs

`router.axs` (HTTP Request Router)

router.new() → Router — Create an empty router
router.add(r, method, path, handler) → i32 — Register a route
router.get/post/put/delete/patch(r, path, handler) — HTTP verb sugar
router.lookup(r, method, path, out_params) → Handler — Find a route
router.set_not_found(r, handler) — Set the 404 handler
router.route_count(r) → i64 — Number of registered routes
router.free(r) — Free all memory

`middleware.axs` (Composable Pipeline)

middleware.new() → Pipeline — Create an empty pipeline
middleware.use(p, mw) — Add a middleware
middleware.set_error_handler(p, h) — Set the error handler
middleware.execute(p, req) → Response — Process a request
middleware.free(p) — Free all memory

`json.axs` (Encoder/Decoder)

json.decode(input, out_value) → i32 — Parse JSON
json.decode_string/int/bool(input, out) — Convenience for primitives
json.encode(value, out_str) → i32 — Serialize JSON
json.encode_string/int/bool(val, out_str) — Convenience for primitives
json.free(value) — Free a JsonValue tree
json.null/of_bool/of_int/of_float/of_string — Value constructors

`static.axs` (Static File Server)

static.validate_path(path) → i32 — Path traversal check
static.mime_for_path(path) → string — MIME type lookup
static.file_exists(path) → bool — File existence check
static.file_size(path) → i64 — File size
static.compute_etag(path, out) → i32 — ETag generation
static.parse_range(header, out_start, out_end) → i32 — Range request parsing
static.list_directory(path, out_entries, out_count) → i32 — List dir
static.try_serve_index(dir, out_path) → i32 — Find index.html
static.read_file(path, out_data, out_len) → i32 — Read file

`websocket.axs` (WebSocket Protocol)

websocket.new() → Connection — Create a connection (Connecting state)
websocket.accept_upgrade(headers, count, out) → i32 — Validate and accept upgrade
websocket.parse_frame(buf, len, out) → i64 — Parse a frame from bytes
websocket.serialize_frame(frame, out_buf, out_len) → i32 — Serialize a frame
websocket.mask_payload(payload, len, mask_key) — XOR masking (involutory)
websocket.send_text(conn, msg) → i32 — Send a text frame
websocket.send_binary(conn, data, len) → i32 — Send a binary frame
websocket.send_ping(conn) → i32 — Send a ping
websocket.send_pong(conn, payload, len) → i32 — Send a pong
websocket.close(conn, code, reason) → i32 — Graceful close
websocket.compute_accept_key(key, out) → i32 — RFC 6455 §4.2.2
websocket.free(conn) — Free connection memory

`http_parser.axs` (HTTP/1.1 Request Parser)

http_parser.parse_request(buf, len, out) → i32 — Parse HTTP request from bytes
http_parser.method_to_string(method) → string — Method enum to string
http_parser.string_to_method(s, out) → i32 — String to method enum
http_parser.parse_query_params(query, out_params, out_count) → i32 — Parse query string
http_parser.get_header(req, name) → string — Case-insensitive header lookup
http_parser.has_header(req, name) → bool — Header existence check
http_parser.content_type(req) → string — Get Content-Type
http_parser.is_keep_alive(req) → bool — Connection persistence check
http_parser.free(req) — Free request memory

CI Infrastructure

Job	Stage	What it lints/tests	Status
`lint:html`	lint	`public/*.html` via tidy	⚠️ allow_failure
`lint:css`	lint	`public/*/.css` via stylelint@15.11.0	⚠️ allow_failure
`lint:js`	lint	`public/*/.js` via eslint@8.57.0	⚠️ allow_failure
`pages`	deploy	Deploys `public/` to GitLab Pages	✅ Active
`test:axon-e2e`	test	Axon golden file tests (activates when `.axs` files exist)	⏳ Dormant
`test:axon-check`	test	Axon type checking (activates when `.axs` files exist)	⏳ Dormant
`perf:regression-check`	performance	Binary size and compile time gates	⚠️ allow_failure

Note: The lint jobs validate the landing page in public/, not the HTTP framework. The framework doesn’t exist yet.

M14 Milestone Roadmap

Ticket	Module	Priority
#1	HTTP request router (radix tree)	Critical
#2	Middleware pipeline architecture	Critical
#3	JSON encoder/decoder	High
#4	Static file serving and caching	High
#5	WebSocket protocol upgrade	High
#6	HTML templating engine	Medium
#10	TLS/SSL termination (OpenSSL FFI)	Medium
#11	HTTP/2 HPACK + multiplexing	Medium
#12	Zero-copy HTTP request parser (SIMD)	Medium

Running Tests

Landing Page Linting

# HTML
tidy -q -e public/index.html

# CSS
npx stylelint "public/**/*.css"

# JS
npx eslint "public/**/*.js"

Placeholder Python Tests

pytest tests/

Axon Tests (When M14 Source Exists)

axonc test

The tests/test_router.axs and tests/test_json.axs files are smoke tests for the framework stubs. They register routes / call encode/decode functions and verify the stubs don’t crash. As the framework is implemented, these will grow into full behavioral test suites.

Contributing

See docs/CONTRIBUTING.md for contributor onboarding, and docs/architecture.md for the planned architecture.

Part of the Axon Ecosystem

Package	Description	Status
axon-lang	Compiler & runtime	✅ Active
axon-std	Standard library	✅ Active
axon-pkg	Package manager	🚧 WIP
axon-db	Database drivers	📋 Planned
axon-ui	GUI framework (M11/M12/M19)	📋 Scaffolding
axon-web	HTTP framework (M14)	📋 Scaffolding

License

See project license file.

axon-web

axon-web

M14 Module Index

Current State

Quick Start

What This Repo Will Become

Framework Source Layout

Module APIs

router.axs (HTTP Request Router)

middleware.axs (Composable Pipeline)

json.axs (Encoder/Decoder)

static.axs (Static File Server)

websocket.axs (WebSocket Protocol)

http_parser.axs (HTTP/1.1 Request Parser)

CI Infrastructure

M14 Milestone Roadmap

Running Tests

Landing Page Linting

Placeholder Python Tests

Axon Tests (When M14 Source Exists)

Contributing

Part of the Axon Ecosystem

License

`router.axs` (HTTP Request Router)

`middleware.axs` (Composable Pipeline)

`json.axs` (Encoder/Decoder)

`static.axs` (Static File Server)

`websocket.axs` (WebSocket Protocol)

`http_parser.axs` (HTTP/1.1 Request Parser)