GET /xrpc/tech.waow.typeahead.searchActors typeahead.waow.tech
typeahead docs development.md
3.3 kB · 88 lines
Markdown
at main

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.