safsaf/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Safsaf is a web framework for Guile Scheme, built on Guile Fibers
using the Guile Knots web server.

## Environment Setup

The project uses `direnv` with Guix. The `.envrc` runs `use guix -D -f guix-dev.scm`, which pulls in all dependencies: `guile-knots`, `guile-webutils`, `guile-lib`, `guile-json-4`, `guile-squee`, `guile-sqlite3`, `guile-gcrypt`.

Run `direnv allow` to activate the environment. All Guile dependencies are on `GUILE_LOAD_PATH` via the Guix profile.

## Key Dependencies

### Guile Knots
- `(knots web-server)` — `run-knots-web-server`: the HTTP server. Handler signature is `(request body-port) → (values response body)`. `body-port` is the port for reading the request body lazily.
- `(knots resource-pool)` — `with-resource-from-pool`: DB/resource connection pooling.
- `(knots parallelism)` — `fibers-let`, `fibers-parallel`, `fibers-map`: concurrent work in handlers.
- `(knots thread-pool)` — `call-with-thread`: offload blocking/CPU-bound work.
- `(knots timeout)` — `with-fibers-timeout`, `with-port-timeouts`: request and I/O timeouts.
- `(knots web)` — `call-with-connection-cache`: outbound HTTP with connection pooling.
- `(knots)` — `call-with-sigint`, `format/knots`, `spawn-fiber/knots`.
- `(knots web-server)` also exports `make-chunked-output-port/knots`, `sanitize-response`, `request-body-port/knots`, `read-request-body/knots`.

### Guile Webutils
- `(webutils multipart)` — `parse-request-body`, `<part>` record, `parts-ref`, `parts-ref-string`.
- `(webutils cookie)` — `set-cookie`, `delete-cookie`. Registers `Cookie`/`Set-Cookie` header parsers with `(web http)`.
- `(webutils sessions)` — `<session-manager>`, HMAC-signed cookie sessions. Format: `signature$expires$base64-data`.
- `(webutils date)` — RFC3339 and HTTP date conversions.

### Guile JSON (v4.7.3)
- `(json)` — Re-exports everything from parser, builder, and record modules.
- `(json parser)` — `json->scm` (from port), `json-string->scm` (from string). Options: `#:null` (default `'null`), `#:ordered` (preserve key order).
- `(json builder)` — `scm->json` (to port), `scm->json-string` (to string). Options: `#:pretty`, `#:unicode`, `#:validate`.
- `(json record)` — `define-json-mapping`: bidirectional SRFI-9 record ↔ JSON conversion.
- Data mapping: objects ↔ alists, arrays ↔ vectors, strings ↔ strings, numbers ↔ numbers, `true`/`false` ↔ `#t`/`#f`, `null` ↔ `'null`.

### Guile Gcrypt
- `(gcrypt random)` — cryptographic random bytes (used for CSRF token generation).

### Guile Lib
- `(htmlprag)` — HTML/SHTML parsing and generation. `html->shtml`: parse HTML to SXML. `shtml->html`: render SXML to HTML string. `write-shtml-as-html`: write SXML to port.
- `(logging logger)` — Logging framework. `(logging port-log)` — log to ports. `(logging rotating-log)` — rotating file logs.
- `(md5)` — MD5 hashing.
- `(container async-queue)` — `make-async-queue`, `async-enqueue!`, `async-dequeue!`.
- `(string transform)`, `(string wrap)`, `(string completion)` — String utilities.

### Guile Standard Library
- `(web request)`, `(web response)`, `(web uri)`, `(web http)` — Guile's built-in HTTP types.
- `(srfi srfi-9)` — Record types. `(srfi srfi-64)` — Test framework. `(srfi srfi-71)` — Extended `let` with multiple values; prefer over `(srfi srfi-11)` `let-values`.

## Architecture

Handler signature throughout is `(request body-port) → (values response body)`, using Guile's `<request>` directly. `body-port` is the port for reading the request body lazily. Context is threaded via Guile parameters, not a wrapper record.

Safsaf wraps `run-knots-web-server` with:

1. **Parameters for context** — `current-route-params` (alist of matched route bindings), `current-reverse-routes` (for `path-for`). Handler wrappers add their own parameters (e.g. `current-csrf-token`, `current-session`).
2. **Router** — data-driven route table using `(route method pattern handler)`. Patterns are lists of segments: strings (literal match), symbols (capture), or `(predicate name)` pairs. Dotted-tail patterns (e.g. `'("api" . rest)`) capture remaining segments. Routes can be organized with `(route-group prefix ...)`. Named routes support reverse routing via `path-for`.
3. **Handler wrappers** — convention: `(foo-handler-wrapper handler) → handler'`. A handler wrapper transforms the request on the way in and the response/body on the way out. Wrappers that need configuration provide a `(make-foo-handler-wrapper ...)` constructor. Applied to route trees via `wrap-routes`, which accepts one or more wrappers.
4. **Entry point** — `(run-safsaf routes #:key host port method-not-allowed? method-not-allowed-handler connection-buffer-size)` compiles the route table, builds the dispatch handler, and starts the HTTP server via `run-knots-web-server`. When called outside a Fibers scheduler, it wraps everything in `run-fibers` and blocks until Ctrl-C. When called inside an existing scheduler (e.g. within `run-fibers`), it just starts the server and returns immediately. `method-not-allowed?` defaults to `#t`, enabling automatic 405 responses. Handler wrappers are applied to routes via `wrap-routes` before passing to `run-safsaf`.

## Finding Guile Library Sources

To read source code for Guile dependencies, look them up via `GUILE_LOAD_PATH`. The first entry is the project's Guix profile directory containing all dependencies. Do **not** search `/gnu/store` directly — it is slow and noisy.

A Guile module path like `(knots web-server)` maps to the file `knots/web-server.scm` under a load path directory. To find it:

```
ls "$GUILE_LOAD_PATH" | head   # see what's available
cat "$(echo $GUILE_LOAD_PATH | cut -d: -f1)/knots/web-server.scm"  # read a specific module
```

Or use the Read/Glob tools directly against the first `GUILE_LOAD_PATH` entry (e.g. `/gnu/store/...-profile/share/guile/site/3.0/`). Module path segments map to directories, with the final segment as `<name>.scm`. For example:

- `(json parser)` → `json/parser.scm`
- `(webutils multipart)` → `webutils/multipart.scm`
- `(srfi srfi-9)` → `srfi/srfi-9.scm`

## Guile Conventions

- Predicates end with `?`. Setters use `set-` prefix. Constructors use `make-`.
- Records defined with `define-record-type` from `(srfi srfi-9)`.
- Modules use `define-module` with `#:use-module` and `#:export`.
- Use `values` for multiple return values, `call-with-values` or `receive` to consume them.