@meego-harness/event-relay

event-relay provides a small public HTTP/websocket relay for deployments where Meego can reach a public server but the gateway runs inside a private network.

The relay receives webhook requests, queues them in memory, and forwards each event over a single authenticated websocket client connection. The internal gateway connects out to the relay through gateway.eventRelay.

Install

pnpm add @meego-harness/event-relay

CLI

Run the relay on the public server:

pnpm exec meego-harness-event-relay run --config-file ./relay.config.json

Example config:

{
  "host": "127.0.0.1",
  "port": 4100,
  "webhookPath": "/public-webhook",
  "websocketPath": "/relay-ws",
  "clientToken": "change-me",
  "maxQueuedEvents": 100,
  "maxBodyBytes": 262144
}

Use the printed webhookUrl as the Meego webhook callback URL.

Programmatic Usage

import { EventRelayServer } from '@meego-harness/event-relay'

const relay = new EventRelayServer({
  port: 4100,
  webhookPath: '/public-webhook',
  websocketPath: '/relay-ws',
  clientToken: process.env.RELAY_CLIENT_TOKEN!,
  maxQueuedEvents: 100,
  maxBodyBytes: 262144,
})

await relay.start()

Internal consumers can use EventRelayClient directly when not relying on gateway config:

import { EventRelayClient } from '@meego-harness/event-relay'

const client = new EventRelayClient({
  serverUrl: 'ws://relay.example.com/relay-ws',
  clientToken: process.env.RELAY_CLIENT_TOKEN!,
  async handleEvent(event) {
    const response = await fetch('http://127.0.0.1:3000/webhook', {
      method: 'POST',
      body: event.rawBody,
    })
    return { ok: response.ok, status: response.status }
  },
})

await client.start()

Operational Notes

• Queue state is in memory; if the relay process exits, queued events are lost.
• Only one websocket client is active at a time.
• Events are acknowledged after the client reports a successful local handler result.
• maxBodyBytes rejects oversized webhook bodies before they enter the queue.
• clientToken protects the websocket relay channel; do not reuse it as a Meego webhook token.