Tangled Spindle built on Cloudflare Workers
treadle AGENTS.md
3.2 kB · 36 lines
Markdown

treadle #

A Tangled CI runner (spindle) on Cloudflare Workers. It runs engine: buildkite workflows as Buildkite builds and engine: cloudflare workflows in Cloudflare Containers (the Runner Durable Object). It serves org.tangled.ci.* and org.tangled.secret.* XRPC, GET /docs, and a read-only MCP server at /mcp.

Rules #

  • Single-tenant: act only on repos owned by OWNER_DID. Every entry point that acts on a repo goes through admitRepo or servedRepo.
  • Untrusted runs (PRs from others before Approve) never get secrets or the trusted snapshot.
  • No special cases for one workflow or repo. A rule applies to all workflows, or a workflow field configures it.
  • Rate-limit unauthenticated endpoints that make upstream requests. XRPC methods that start work call claimToken.
  • MCP tools are read-only and expose only what XRPC and the log stream already serve.

References #

Pitfalls #

  • Deploys roll out with mixed versions, so a new Worker can call an old Durable Object for minutes. Keep RPCs and schema additive. A later alarm must repair state that a failed call leaves.
  • Durable Objects are in the wrangler exports map (no migrations) and reached through ctx.exports. The Store keeps its schema version in ctx.storage.kv, because PRAGMA user_version is not allowed.
  • Buildkite does not retry webhooks (the Store alarm checks open builds), and allows 50 requests a minute for all callers. Back off on RateLimit-*.
  • Containers: start() returns at once and the first exec() is the readiness check. destroy() is SIGKILL; stop gracefully with signal(15) and monitor(). A container lives only as long as its Durable Object, and each run starts a fresh one. cloudflare/debian-trixie has no git, curl or CA certificates.
  • After close(), a hibernated WebSocket stays in getWebSockets() until the peer answers, and send() on it throws. Check readyState.
  • Outbound WebSockets do not hibernate and drop on deploy. Use short connections from an alarm with a stored cursor.
  • Web Crypto has no secp256k1. Use @noble/curves.

Workflow #

  • Use Durable Object tests only for storage and alarm logic.
  • Tests are hermetic: no network, no host tools. vitest.config.ts answers unstubbed requests with 599. Create mock Response objects inside the fetch handler. assertOutput checks XRPC outputs against test/fixtures/lexicons.
  • Run pnpm check before you finish, and pnpm types after you change wrangler.jsonc.
  • Push only master. A push to master deploys through treadle's own deploy.yml; a manual pnpm wrangler deploy is only a fallback. The deployed treadle runs the workflows of each pushed commit, so a workflow change that needs new code goes in a later commit.
  • Debug production with Workers Observability, service treadle.