PUB/SUB COMPATIBILITY GATEWAY

relay-pubsub

Google Pub/Sub APIs in. Relay events out. Speak familiar Pub/Sub gRPC and REST while the gateway handles translation, TLS, and metrics in front of Zyvor Relay's real event system.

v0.4.0 TLS-only Apache-2.0

Get the highlights.

• v0.4.01
  Current release — client conformance matrix, Helm console + PVC
• 402
  Relay event types pre-registered across 4 catalogs at startup
• 33
  Pluggable backends — memory, http (legacy), relay-events (production)
• 04
  Reverse proxies needed — both gRPC and REST terminate TLS natively

• 🚀

  Getting started

  From zero to a working publish/pull round-trip in minutes.

  →
• 📦

  Installation

  Install relay-pubsub from source, Docker/GHCR, systemd, or Kubernetes.

  →
• 🏗

  Architecture

  How relay-pubsub stays separate from Relay core — and where relay-edge fits.

  →
• 🔎

  Filters & schemas

  Attribute filters, topic schema enforcement, and CloudEvents attribute projection.

  →
• ❓

  FAQ

  Questions people evaluating relay-pubsub actually ask, before they've decided to adopt it.

  →

---

Start here

I want to…	Go to
Install (Docker, GHCR, systemd, k8s)	Installation
Test / verify an install	Testing
Run locally in 2 minutes	Getting started
Wire up Relay's real API (relay-events)	Relay events backend
Deploy notes (lab template)	Deployment
Understand the architecture	Architecture
Use attribute filters, schemas, CloudEvents	Filters & schemas
Integrate with relay-edge simulators	Integration with relay-edge
Stack test results (relay-edge repo)	relay-edge TEST_RESULTS
Release history	Changelog
SPDX headers on source	License headers

---

What this gateway does

Applications speak Google Pub/Sub (gRPC or REST). The gateway translates to Zyvor Relay through a pluggable backend.

  Your app                relay-pubsub              Zyvor Relay
  ────────                ──────────────            ───────────
  Publish topic      →    RelayBackend         →    POST /v1/events
  Pull subscription  ←    (memory / http /          Action Gateway
                           relay-events)            ← POST /v1/actions

• memory Demos, CI, k3s smoke, offline edge — no Relay needed.
• http Legacy invented topics API — rarely needed, prefer relay-events.
• relay-events Production — Relay's real /v1/events API.

Runs as Docker, systemd, or Kubernetes — see Installation.

---

TLS built in

Both gRPC and REST listeners are TLS-only. No nginx required.

On first start the gateway generates a self-signed cert, persists it, and reuses it across restarts. Clients use curl -k or RELAY_TLS_INSECURE=1 for outbound calls.

In Kubernetes, an emptyDir volume holds cert material for the pod lifetime.

---

Event catalogs (relay-events)

Topic name = Relay event type. 40 types pre-registered at startup:

Catalog	Topics	Source
Farm	10	Fasal accommodation
Edge / firewater	18	relay-edge firewater simulator
Remote edge	6	relay-edge remote-edge simulator
Fleet	6	relay-edge fleet simulator

Publishing to any other topic name still works — catalog is for admin UI visibility. The product console Generate tab can seed the same catalogs into memory.

---

Ops console

Product UI (Incoming / Outgoing / Stored / Configure / Logs) on a separate systemd unit — Installation § Console and Testing § Console.

Admin helpers: GET /admin/v1/inventory, GET /admin/v1/logs, POST /admin/v1/push-config.

---

Integration with relay-edge

relay-edge stamps farm/simulator events and publishes via this gateway:

  relay-edge  ──HTTPS──▶  relay-pubsub  ──relay-events──▶  Relay
  (simulators)            (topic = type)

Deploy both as Kubernetes pods:

# From relay-edge repo:
RELAY_AUTH_TOKEN="$(cat /tmp/lab-relay.jwt)" \
  ./deploy/scripts/deploy-k8s-remote.sh <HOST> [USER]

Full event verification: relay-edge docs/EVENT_MATRIX.md

Latest stack test (2026-08-28): all gates PASS — relay-edge TEST_RESULTS.md (covers pubsub health, farm Act via /v1/actions, and full Forge path).

---

Scripts cheat sheet

bash scripts/smoke.sh                    # memory: publish + pull
bash scripts/conformance-smoke.sh        # pagination, snapshots, IAM, schemas, push
bash scripts/smoke-relay-events.sh       # relay-events: single publish
bash scripts/fasal-catalog-smoke.sh      # all 10 farm types + Act
bash scripts/deploy-remote.sh HOST USER  # systemd deploy
bash scripts/deploy-console-remote.sh HOST USER
bash deploy/scripts/deploy-k3s.sh        # local k3s + memory
bash deploy/scripts/ci-k3s-e2e.sh        # verify k3s deploy
bash scripts/selftest.sh                 # host binary + unit + smoke

Image: ghcr.io/zyvorai/relay-pubsub:0.4.0 · Console: ghcr.io/zyvorai/relay-pubsub-console:0.4.0

bash scripts/client-matrix.sh            # REST + Python/Node/Go lanes

---

Related projects

• relay — control plane
• relay-edge — domain + simulators
• zyvor.dev — Zyvor

1. v0.4.0 added the client conformance matrix (REST + Python/Node/Go) and Helm console + PVC. See Architecture — Compatibility roadmap. ↩
2. 40 topics pre-registered across 4 catalogs: Farm (10), Edge/firewater (18), Remote edge (6), Fleet (6). Publishing to any other topic still works. See Event catalogs. ↩
3. memory (demos/CI, no Relay needed), http (legacy invented API), and relay-events (production, Relay's real /v1/events API). See What this gateway does. ↩
4. Both gRPC and REST listeners are TLS-only; the gateway generates and reuses a self-signed certificate on first start. See TLS built in. ↩