paseo-relay

汉语

Self-hosted Paseo relay.

This repository packages the upstream getpaseo/paseo @getpaseo/relay/cloudflare adapter as a thin deployment wrapper. It does not implement a custom relay protocol, admin API, or auth layer. The runtime contract stays aligned with upstream Paseo while this repo owns deployment, validation, and operational packaging.

What This Repo Provides

• A minimal Worker entrypoint that re-exports the upstream relay worker and RelayDurableObject
• Durable Object wiring through Wrangler
• Local validation with Bun, TypeScript, Vitest, and Wrangler dry-runs
• An OCI image that runs the bundled Worker on workerd
• GitHub Actions for PR validation, main branch deploys, and OCI publishing

Runtime Contract

The public runtime surface is intentionally small:

• GET /health returns 200 with {"status":"ok"}
• GET /ws?... handles relay and WebSocket traffic

This repo does not add any repo-specific API endpoints.

Quick Start

Prerequisites

• Bun 1.3.12
• Docker, if you want to build or run the OCI image
• A Cloudflare account, if you want to deploy the Worker

Install

bun install

Run validation

bun run check

This runs:

• Worker type generation
• TypeScript checks
• Vitest Worker tests
• Generated type drift checks
• wrangler deploy --dry-run

Local Worker development

bun run dev

Build and run the OCI image

bun run oci:build
bun run oci:run

The OCI image exposes the relay on port 8080.

Run the prebuilt OCI image

Prebuilt images are published to GHCR:

docker pull ghcr.io/xixu-me/paseo-relay:main
docker run --rm -p 8080:8080 -v paseo-relay-data:/var/lib/paseo-relay/do ghcr.io/xixu-me/paseo-relay:main

Cloudflare Deployment

wrangler.jsonc is the source of truth for the Worker deployment:

• entrypoint: src/index.ts
• Durable Object binding: RELAY
• Durable Object class: RelayDurableObject
• SQLite-backed Durable Object migration: v1

Deploy with:

bun run deploy

Note

workers.dev is useful for initial verification, but the intended production path is a custom domain.

Connecting a Paseo Daemon

Paseo expects relay endpoints in host:port form.

Warning

Do not use https://relay.example.com here. Use relay.example.com:443.

Example:

export PASEO_RELAY_ENDPOINT="relay.example.com:443"
export PASEO_RELAY_PUBLIC_ENDPOINT="relay.example.com:443"

• PASEO_RELAY_ENDPOINT is the address the daemon connects to
• PASEO_RELAY_PUBLIC_ENDPOINT is the address embedded into pairing links and QR codes

Testing

The Worker test suite covers:

• /health returns 200
• unknown paths return 404
• missing serverId returns 400
• invalid relay version returns 400
• non-WebSocket relay requests are rejected
• valid WebSocket upgrade requests succeed

The OCI validation path additionally checks:

• container startup
• /health over HTTP
• a v2 WebSocket upgrade smoke test against the containerized runtime

CI/CD

The repository uses four workflows:

• validate-reusable.yml: the single validation source of truth
• ci.yml: runs validation for pull requests and merge groups
• release.yml: validates, then deploys from main and publishes the OCI image
• auto-merge.yml: enables auto-merge only for Dependabot PRs labeled dependencies

Release behavior

• pushes to main that change release-relevant files run validation, then deploy the Worker and publish ghcr.io/xixu-me/paseo-relay:main
• manual workflow_dispatch runs can selectively deploy the Worker and/or publish the OCI image

Required secrets

Worker deployment requires:

• CLOUDFLARE_API_TOKEN
• CLOUDFLARE_ACCOUNT_ID

OCI publishing uses the built-in GITHUB_TOKEN.

OCI Notes

The image is built from the Worker bundle generated by Wrangler and served by workerd. Prebuilt images are published as ghcr.io/xixu-me/paseo-relay:main. The runtime image:

• listens on :8080
• persists Durable Object state under /var/lib/paseo-relay/do
• runs as a non-root user

Design Goals

• Stay as close as possible to the upstream Paseo relay architecture
• Keep repository-owned logic limited to deployment, validation, and packaging
• Make Worker and OCI paths testable through the same contract