[[https://github.com/Kiyomi-Computation-Systems/chez-http-server/actions/workflows/ci.yml][https://github.com/Kiyomi-Computation-Systems/chez-http-server/actions/workflows/ci.yml/badge.svg]]
An HTTP 1.1 Server for Chez Scheme built on libuv.
#+begin_quote
✨ AI Disclosure: LLMs are used extensively in the planning and development of this project.
#+end_quote
** Features
- HTTP/1.0 and 1.1 on libuv.
serve runs your handler for each request,
one at a time per connection, with keep-alive. A request in HTTP/1.2 to 1.9
is served as 1.1.
- Bounded by default. Every limit and timeout has an nginx-style default and
an environment override, and a client that stalls is closed (see
[[file:docs/configuration.md][docs/configuration.md]]).
- Streaming both ways. A handler reads a request's body as it arrives and
can stream its response, so a big upload or download is never held in
memory whole. It hears when its response is done, and how it ended, so it
can log it or close the file it streamed from (see
[[file:docs/handlers.md][docs/handlers.md]]).
- Handlers that wait. A handler can wait for another request, a time, a
deadline, a name's lookup or its own body, read a piece at a time or
through a port, and is told when its client leaves (see
[[file:docs/waiting.md][docs/waiting.md]]).
- Upgrades. A handler can take an upgrade, a WebSocket's say, and speak the
new protocol over the connection itself; its close is as gentle as the
server's own.
- Handlers tested without a socket.
(http-server testing) runs a handler,
waits and all, against a scripted client, on a clock the test moves (see
[[file:docs/testing.md][docs/testing.md]]).
- Graceful shutdown. Sent SIGTERM or SIGINT (Ctrl-C), it finishes the
requests in flight, closes the rest after
CHEZ_HTTP_DRAIN_TIMEOUT, and
serve returns (see [[file:docs/connections.md][docs/connections.md]]).
- Tested against the real thing. curl, ApacheBench, vtest2's scripts and an
oha load test run against the server. llhttp's and libhtp's request
corpora, AWS http-desync-guardian's cases, the strict request tests of
Kestrel, Apache httpd and lighttpd, and request-smuggling vectors check what
it accepts and refuses.
The API may change in any release before 1.0. [[file:CHANGELOG.md][CHANGELOG.md]] lists what each
release changes.
** Quick start
#+begin_src scheme
(import (rnrs) (http-server))
(serve
(lambda (request)
(make-response 200 #f '() (string->utf8 "Hello\n"))))
#+end_src
Save it as hello.sps, start it with make run PROGRAM=hello.sps, and
curl http://127.0.0.1:8080/. The [[file:docs/quickstart.md][quickstart]] goes on from there.
To use it from a project of your own, put its libraries on Chez's library
path, or install it with [[https://akkuscm.org][Akku]]; [[file:docs/installing.md][installing]] says how.
** Build and test
Prerequisites:
- Chez Scheme 10.4.1 or later, threaded build (the binary is
chez)
- libuv 1.48 or later that
pkg-config can see (brew install libuv, or
apt install libuv1-dev on Ubuntu 24.04 or later), plus a C compiler — the
chez-libuv shim is built from source. With no libuv, or an older one such as
Debian 12's 1.44, chez-libuv builds its own, which needs CMake 3.10 or later
(Debian 12's own builds it)
- For
make test, the real clients the tests run against the server: curl,
ab (apache2-utils on Linux), vtest2, which make vtest builds from
source with pcre2 that pkg-config can see and zlib (brew install
pcre2 or apt install libpcre2-dev zlib1g-dev), python3 and awk, and
oha, the load test's client, whose release binary make oha downloads and
checks (macOS and Linux, amd64 and arm64)
Dependencies are pinned git submodules under vendor/ (chez-libuv,
chez-httparse, uriparse, chez-srfi and vtest2 for the tests; byte-machine
arrives under chez-httparse):
#+begin_src sh
git clone --recursive https://github.com/Kiyomi-Computation-Systems/chez-http-server.git
cd chez-http-server
make build # builds the chez-libuv shim and assembles the one library path
make test # runs every tests/test-*.sps
#+end_src
make test builds vtest2 and downloads oha itself the first time.
make help lists every target; make check-pins verifies each submodule sits
at its pinned release commit, and Akku.manifest's dependencies at the same
versions.
With Docker, scripts/docker-env make test runs it in a container that
holds every prerequisite, and on a machine with Guix scripts/guix-env make
test does the same in a pinned one; see "In Docker" and "On a Guix host" in
[[file:docs/building.md][docs/building.md]].
** Examples
[[file:examples/][examples/]] holds small servers to copy from, each one file: a hello world,
reading bodies, streaming and server-sent events, a long poll, and a file
server that does what python3 -m http.server does:
#+begin_src sh
make run PROGRAM=examples/file-server.sps ARGS="8000 --directory ."
#+end_src
** Documentation
The guides are in [[file:docs/README.md][docs/]]: [[file:docs/installing.md][installing]], a [[file:docs/quickstart.md][quickstart]], [[file:docs/handlers.md][handlers]],
[[file:docs/bodies.md][bodies and streaming]], [[file:docs/waiting.md][waiting]], [[file:docs/upgrades.md][upgrades]], [[file:docs/testing.md][testing handlers]], [[file:docs/requests.md][requests]], [[file:docs/responses.md][responses]],
[[file:docs/connections.md][connections]], [[file:docs/configuration.md][configuration]], [[file:docs/deploying.md][deploying]], [[file:docs/how-it-works.md][how it works]], [[file:docs/performance.md][performance]],
and the [[file:docs/reference.md][API reference]]. Each release publishes them as a
website: [[https://kiyomi-computation-systems.github.io/chez-http-server/]].
** Contributing
[[file:CONTRIBUTING.md][CONTRIBUTING.md]] says how to set up, which checks a pull request must pass,
and the house rules.
** Security
Report a vulnerability privately; [[file:SECURITY.md][SECURITY.md]] says how.
** License
© [[https://kiyomicomputation.systems/][Kiyomi Computation Systems LLC]]. Licensed under BSD 3-Clause — see
[[file:LICENSE][LICENSE]]. Third-party components and their licenses are listed in
[[file:NOTICE][NOTICE]].
