Development #
The Workers #
The public API and website, the search transport and the image renderer are
Cloudflare Workers in src/. Install Bun and
just:
bun install
bunx wrangler dev
just check
just check is what CI runs: type-check, lint, bun test, the route tool's
tests, the slot supervisor's tests, the smoke suite's own tests, and a dry-run
build of all three Workers. It needs python3, jq and bash 5.2 or newer
(on macOS, brew install bash). It contacts nothing remote.
For preview cards and PNG icons locally, run the renderer in another terminal.
Wrangler connects the public Worker's IMAGE_RENDERER binding to it.
bunx wrangler dev -c deploy/image-renderer/wrangler.jsonc --port 8788
The slot's programs #
A slot runs a store process written in Zig (services/src/) and a search
engine written in Rust on Tantivy (services/tantivy/). They need Zig 0.17.0,
Rust with Cargo, a C compiler and Python.
just test-services # Zig unit tests: store, index bridge, control loop, normalizer
just --no-dotenv test-tantivy # the search engine against built binaries
just --no-dotenv test-bridge # store to search engine, against a real local engine
just test-supervise # the slot's supervisor against stand-in processes
just test-route # the route tool against an in-memory bucket
Changes to matching or ranking also need just --no-dotenv test-tantivy,
which CI runs on main.
The store process is the binary in services/, started with MODE=store.
A bare zig build run sets no mode and exits. The slot image is
built from deploy/slot/Dockerfile:
docker build --platform linux/amd64 -f deploy/slot/Dockerfile -t typeahead-slot:local .
Deploying #
just deploy-worker # public Worker, then smoke
just deploy-search-transport # transport, then smoke
just deploy-image-renderer # renderer, then image smoke
fly deploy . --config deploy/slot/fly.toml -a <standby app>
Push first. Deploys are run by hand; CI builds and tests only. A slot image goes to the standby first and reaches the serving slot only after a flip: operating has the steps.
Checking production #
These read production and default to it. Check the target before running a benchmark; do not load-test the serving slot.
just smoke # response shape, ranking position, moderation, admin API
just index-status # build, account count and versions on the serving slot
just bench # edge latency beside Bluesky for the same queries
just bench-ranking # ranking against Bluesky as the oracle
Repository instructions say which of these a change needs.
Run just eval-serve and open http://127.0.0.1:18790/eval to inspect the
retained initial run. just eval-tick performs a daily collection only when
due, then prepares local snapshots. Viewing the charts sends no upstream
queries. Evaluation covers score weights, retained history,
the isolated runner and the production import procedure.
The pictures #
docs/diagrams/build.py writes the five SVG files in docs/diagrams/. Edit
the script and run it; do not edit the SVG files.