Skip to content

feat(relay): add self-hosted path relay - #116

Open
Zoupers wants to merge 8 commits into
VirtualBeingsResearch:mainfrom
Zoupers:feat/path-relay-v1
Open

feat(relay): add self-hosted path relay#116
Zoupers wants to merge 8 commits into
VirtualBeingsResearch:mainfrom
Zoupers:feat/path-relay-v1

Conversation

@Zoupers

@Zoupers Zoupers commented Jul 27, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • add the self-hosted path-based Go Relay and built-in Python Relay Client for Desktop status, registration, messaging, SSE, and signed updates
  • provide pairing, WSS tunneling, verifier-based edge authentication, Coworker's existing second authentication, rate limits, persistent bans/unbans, and optional-to-required update authentication migration
  • complete the Relay lifecycle with cascading revocation, garbage collection, staged credential rotation, graceful drain, schema checks, backup/restore, readiness, Prometheus metrics, and hardened Compose initialization
  • publish multi-architecture GHCR Relay images and cross-platform coworker-relay / relayctl archives with checksums, SBOM/provenance, Dependabot, govulncheck, and Trivy coverage
  • document the protocol, privacy boundary, single-node topology, deployment, upgrades, capacity, and recovery in Chinese and English

Validation

  • go test -race ./...
  • go vet ./...
  • go run golang.org/x/vuln/cmd/govulncheck@v1.1.4 ./... (0 affected vulnerabilities)
  • Go fuzz run for path routing (437,112 executions)
  • devcontainer: Ruff and mypy
  • devcontainer: Relay/admin/i18n/documentation tests (94 passed)
  • devcontainer: full Python suite excluding the pre-existing equal-mtime pruning test (1454 passed, 1 skipped, 1 deselected)
  • real Go ↔ Python TLS/WSS contract: enrollment, verifier sync, request forwarding, staged credential rotation, reconnect, and post-rotation request
  • Relay Docker image build and version/non-root/healthcheck inspection
  • generated relayctl init deployment validated with docker compose config
  • web build; Desktop tests (89 passed) and build
  • workflow and Dependabot YAML parsing

Security and compatibility

  • Relay terminates TLS and can see Bearer tokens, headers, paths, and bodies while forwarding; it does not persist message, attachment, or SSE content and is not advertised as E2EE
  • instance credentials rotate with a pending digest and promote only after a successful new WSS login, preventing response-loss lockout
  • the initial vulnerability scan found reachable x/net and x/text ACME issues; dependencies and the minimum Go version were upgraded, and the final scan reports zero affected vulnerabilities
  • v1 is deliberately single-node and does not provide E2EE, P2P, generic proxying, offline message storage, RBAC, or active-active HA
  • request bodies are buffered up to 32 MiB; responses stream with bounded backpressure; ordinary requests are not replayed after tunnel loss

Known check

  • tests/unit/test_desktop_dispatcher.py::test_detail_files_are_pruned_by_count remains a pre-existing container-filesystem ordering failure when multiple files have identical mtimes; it is unrelated to Relay and was not changed in this PR

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant