Skip to content

Anole 0.1.0

Choose a tag to compare

View all tags
@xuckless xuckless released this 21 Oct 23:05
· 715 commits to main since this release
v0.1.0
c6d41b9
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

The first release of Anole: one Zig server for REST, WebSockets, gRPC and WebTransport over HTTP/1.1, HTTP/2 and HTTP/3, with TLS, auth, database connectors and observability built in. It is built on proven libraries (zio, an HTTP core adapted from dusty, nghttp2, BoringSSL, ngtcp2 and nghttp3), and Zig compiles every C dependency, so there is nothing to install but Zig. Every bundled library sits behind a build flag; what is off is neither downloaded nor compiled.

Install

zig fetch --save git+https://github.com/xuckless/anole#v0.1.0

Then make build.zig one call:

_ = @import("anole").addApp(b, .{ .name = "api", .root_source_file = b.path("src/main.zig") });

Getting started goes from zig init to a running JSON API, then WebSockets, TLS, gRPC and deploying.

Highlights

Protocols

  • HTTP/1.1 with keep-alive and pipelining, a router with path parameters and wildcards, nested groups and middleware, per-phase timeouts and body limits, static files with ranges, ETags and precompressed variants.
  • HTTP/2 on nghttp2 1.70.0 (with an RFC 9113 strictness patch), over TLS via ALPN and over cleartext with prior knowledge; h2spec passes every case in strict mode.
  • HTTP/3 on ngtcp2 1.25.0 and nghttp3 1.18.0: the same handlers over QUIC, Alt-Svc, opt-in 0-RTT with RFC 8470's replay rules, connection migration, and one UDP socket per core on Linux with connection-ID steering. The QUIC interop runner passes every server case it is given.
  • Response compression with zstd, gzip (zlib-ng) and, with -Dbrotli, Brotli; the PROXY protocol and X-Forwarded-* from trusted proxies.

TLS

  • BoringSSL built from source by Zig: TLS 1.3 and 1.2, ALPN, mutual TLS on HTTP/1.1, HTTP/2 and HTTP/3, stateless session tickets, certificate reload without a restart (also on SIGHUP), and an in-memory development certificate.

WebSocket and WebTransport

  • WebSocket over HTTP/1.1 (RFC 6455), HTTP/2 (RFC 8441) and HTTP/3 (RFC 9220) behind one upgrade, with permessage-deflate, a rooms helper, app.ws for a message loop and app.wsCallbacks for callbacks. Autobahn passes every case.
  • WebTransport over HTTP/3 (draft-02, what current browsers speak), server and client: streams, datagrams, close and drain.

gRPC

  • Server and client over HTTP/2, all four call modes, deadlines, metadata, gzip and cancellation; interop-tested against grpc-go both ways.
  • gRPC-Web, Buf's Connect protocol, the grpc.health.v1 service, and JSON transcoding from google.api.http annotations.
  • Protobuf code generated inside zig build (addApp, addProtoGen, addProtoModule), with protoc pinned and fetched for you.

Auth

  • JWT verification with JWKS keyrings and a bearer-token middleware, OIDC sign-in as a relying party (Google and Apple presets), sessions in memory, Redis/Valkey or sealed cookies, CSRF tokens, Argon2id passwords, API keys, RBAC, and rate limiting in memory or Redis.

Databases

  • PostgreSQL, SQLite, MongoDB and Redis/Valkey connectors with one shape: a pool per core, calls that take the request first, rows as your structs in the request's arena, request deadlines that cancel queries, and errors that map to HTTP statuses.
  • Opt-in query coalescing, per-core result caches and an HTTP response cache, all off unless asked for.

Observability

  • Prometheus /metrics, OpenTelemetry tracing (W3C traceparent, OTLP/HTTP export), JSON or text access logs with request and trace IDs, /healthz and /readyz; the database connectors report into all three.

Operations

  • One pinned zio executor per core with connections that stay on the core that accepted them, a graceful drain with a hard deadline, idle HTTP/1.1 and callback WebSocket connections that park without a coroutine, several listeners per server, and a connection limit that follows the open-file limit.
  • Zero-downtime restart on SIGUSR2 (listening sockets, HTTP/3's included, are handed to the new process), systemd socket activation and readiness notification without libsystemd, and an opt-in blocking pool for CPU-heavy calls.

The full list, including the API renames made before this release, is in the CHANGELOG.

Requirements

  • Zig 0.17.x (tested on 0.17.0). The build stops with an error on any other minor version.
  • Linux or macOS. Windows is not supported yet; use WSL2 or Docker until it is (#47).

Status

Anole is pre-1.0: the API is not stable and may change in any 0.x release (the CHANGELOG lists breaking changes). Known limitations and planned work are tracked in GitHub Issues. Results from HttpArena, an independent benchmark, will follow this release.

Links

Assets 2
Loading