166 lines
4.3 KiB
Markdown
166 lines
4.3 KiB
Markdown
# paseo-relay
|
|
|
|
**_[汉语](./README.zh.md)_**
|
|
|
|
Self-hosted Paseo relay.
|
|
|
|
This repository packages the upstream [`getpaseo/paseo`](https://github.com/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
|
|
|
|
```bash
|
|
bun install
|
|
```
|
|
|
|
### Run validation
|
|
|
|
```bash
|
|
bun run check
|
|
```
|
|
|
|
This runs:
|
|
|
|
- Worker type generation
|
|
- TypeScript checks
|
|
- Vitest Worker tests
|
|
- Generated type drift checks
|
|
- `wrangler deploy --dry-run`
|
|
|
|
### Local Worker development
|
|
|
|
```bash
|
|
bun run dev
|
|
```
|
|
|
|
### Build and run the OCI image
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|