Safsaf

A web framework for GNU Guile, using Guile Fibers and the Guile Knots web server.

Developed based off of the Guix Data Service and Nar Herder codebases, written using Claude Code running Claude Opus 4.6.

Quick Example

(use-modules (safsaf)
             (safsaf router)
             (safsaf response-helpers))

(define routes
  (list
   (route 'GET '() (lambda (request body-port)
                     (text-response "Hello, world!")))
   (route '* '* (lambda (request body-port)
                  (not-found-response)))))

(run-safsaf routes #:port 8080)

Design

Safsaf aims for functional over imperitive configuration and to be minimal but very extensible.

Suspendable ports in Guile plus Guile Fibers is used both for Safsaf internals, but should also be used for user applications where possible and suitable.

Features

• Request router with parameterised segments, wildcards, nested groups, and reverse routing (path-for)
• Handler wrappers (middleware) applied per-route or per-group via wrap-routes
• Included handler wrappers: logging, CORS, CSRF protection, sessions (signed cookies), flash messages, security headers, trailing-slash normalization, canonical host redirects, exception handling
• Request helpers: form body parsing, multipart parsing, query strings, cookies
• Response helpers: HTML/SHTML, JSON, redirects, plain text, static files with Last-Modified / Cache-Control
• Server-Sent Events (SSE): streaming text/event-stream responses with keepalives and Last-Event-ID replay
• Parameter parsing: declarative param specs with built-in processors, CSRF integration, and error inspection
• Internationalisation: gettext-style t / tn helpers backed by an in-Scheme catalog loaded from .po files, with a locale handler wrapper that selects per-request from route params, cookie, or Accept-Language

Wishlist

• WebSockets support

Other Guile web frameworks

• GNU Artanis https://artanis.dev/
• schingle https://github.com/petelliott/schingle

Dependencies

• GNU Guile 3.0+
• Guile Fibers (the scheduler everything runs on)
• Guile Knots (web server, thread and resource pools; manual)
• Guile Webutils (multipart parsing, cookie headers, signed-cookie sessions)
• Guile JSON 4.x (the Scheme to JSON conversion the JSON response helpers use)
• Guile Lib (htmlprag for SHTML, logging for the logger run-safsaf installs, md5 for ETags and asset fingerprints)
• Guile Gcrypt (CSRF token randomness, SHA-1 and SHA-256 hashing)

The manual's Dependencies chapter says which of these an application imports itself and what each one is used for.

A Guix development environment is provided via guix-dev.scm and .envrc (direnv).

License

LGPL-3.0-or-later