Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(dashboard): dial the socket at the API origin in split builds

Yudhi Armyndharis720e01229c2a
diff --git a/dashboard/README.md b/dashboard/README.md
index 47b81bfa4..c74f7d113 100644
--- a/dashboard/README.md
+++ b/dashboard/README.md
@@ -90,7 +90,7 @@ For a **split-origin** deployment (dashboard hosted separately from the API), se
```bash
VITE_API_URL=http://localhost:2785
-# real-time events (WebSocket) origin; defaults to the page origin
+# real-time events (WebSocket) origin; defaults to VITE_API_URL, else the page origin
VITE_WS_URL=http://localhost:2785
```
diff --git a/dashboard/src/hooks/useWebSocket.ts b/dashboard/src/hooks/useWebSocket.ts
index 098561ffa..767ca2c25 100644
--- a/dashboard/src/hooks/useWebSocket.ts
+++ b/dashboard/src/hooks/useWebSocket.ts
@@ -1,6 +1,7 @@
import { useEffect, useRef, useCallback, useState } from 'react';
import { io, Socket } from 'socket.io-client';
-import { warnIfInsecureHttpUrl } from '../utils/urlSecurity';
+import { API_ORIGIN } from '../services/api';
+import { resolveSocketUrl, warnIfInsecureHttpUrl } from '../utils/urlSecurity';
interface SessionStatusEvent {
sessionId: string;
@@ -137,11 +138,12 @@ interface ServerErrorFrame {
message?: string;
}
-// Use current origin for WebSocket (goes through nginx proxy in Docker)
-// Falls back to env var or localhost for development
-const SOCKET_URL = import.meta.env.VITE_WS_URL || window.location.origin;
-// Warn when the WebSocket origin is an insecure http:// URL on a non-localhost host.
-warnIfInsecureHttpUrl(SOCKET_URL, 'VITE_WS_URL');
+// VITE_WS_URL when set, else the API origin (a split-origin build names it in VITE_API_URL), else the
+// page's own origin (the single-container setup, or nginx proxying /socket.io in Docker).
+const SOCKET_URL = resolveSocketUrl(import.meta.env.VITE_WS_URL, API_ORIGIN, window.location.origin);
+// Warn when VITE_WS_URL is an insecure http:// URL on a non-localhost host; api.ts already warns
+// about VITE_API_URL under its own name.
+if (import.meta.env.VITE_WS_URL) warnIfInsecureHttpUrl(SOCKET_URL, 'VITE_WS_URL');
export function useWebSocket(events: WebSocketEvents = {}) {
const socketRef = useRef<Socket | null>(null);
diff --git a/dashboard/src/services/api.ts b/dashboard/src/services/api.ts
index ae3d101dd..b2ed20777 100644
--- a/dashboard/src/services/api.ts
+++ b/dashboard/src/services/api.ts
@@ -12,7 +12,7 @@ import { warnIfInsecureHttpUrl } from '../utils/urlSecurity';
// same-origin '/api' and a split deployment failed with "Invalid API Key" (#91).
// Exported so direct fetches (e.g. auth/validate in Login.tsx / App.tsx) honor VITE_API_URL
// too — otherwise split-origin deployments break. Empty VITE_API_URL → '/api'.
-const API_ORIGIN = (import.meta.env.VITE_API_URL ?? '').replace(/\/+$/, '');
+export const API_ORIGIN = (import.meta.env.VITE_API_URL ?? '').replace(/\/+$/, '');
export const API_BASE_URL = `${API_ORIGIN}/api`;
// Warn (not refuse — would break dev + TLS-terminating-proxy) when the API origin is an
// insecure http:// URL pointing at a non-localhost host (API keys sent in cleartext).
diff --git a/dashboard/src/utils/urlSecurity.test.ts b/dashboard/src/utils/urlSecurity.test.ts
index a35e7bcb1..e6b794a1c 100644
--- a/dashboard/src/utils/urlSecurity.test.ts
+++ b/dashboard/src/utils/urlSecurity.test.ts
@@ -1,6 +1,6 @@
import { test } from 'node:test';
import assert from 'node:assert/strict';
-import { isLocalhostHost, warnIfInsecureHttpUrl } from './urlSecurity.ts';
+import { isLocalhostHost, resolveSocketUrl, warnIfInsecureHttpUrl } from './urlSecurity.ts';
test('isLocalhostHost recognizes loopback hosts', () => {
assert.ok(isLocalhostHost('localhost'));
@@ -56,3 +56,12 @@ test('warnIfInsecureHttpUrl is silent on https', () => {
test('warnIfInsecureHttpUrl returns the URL unchanged (does not throw)', () => {
assert.equal(warnIfInsecureHttpUrl('http://gateway.example.com', 'x'), 'http://gateway.example.com');
});
+
+test('resolveSocketUrl prefers VITE_WS_URL, then the API origin, then the page origin', () => {
+ const page = 'https://dashboard.example.com';
+ const api = 'https://api.example.com';
+ assert.equal(resolveSocketUrl(undefined, '', page), page);
+ assert.equal(resolveSocketUrl('', '', page), page);
+ assert.equal(resolveSocketUrl(undefined, api, page), api);
+ assert.equal(resolveSocketUrl('https://ws.example.com', api, page), 'https://ws.example.com');
+});
diff --git a/dashboard/src/utils/urlSecurity.ts b/dashboard/src/utils/urlSecurity.ts
index 154153ad7..db180d768 100644
--- a/dashboard/src/utils/urlSecurity.ts
+++ b/dashboard/src/utils/urlSecurity.ts
@@ -25,3 +25,12 @@ export function warnIfInsecureHttpUrl(url: string, label: string): string {
}
return url;
}
+
+/**
+ * The origin the realtime socket dials: VITE_WS_URL when set, else the API origin VITE_API_URL
+ * names (a split-origin build serves the socket from the API, not from the dashboard's host), else
+ * the page's own origin.
+ */
+export function resolveSocketUrl(wsUrl: string | undefined, apiOrigin: string, pageOrigin: string): string {
+ return wsUrl || apiOrigin || pageOrigin;
+}
diff --git a/docs/17-dashboard-design.md b/docs/17-dashboard-design.md
index ae3a99599..43d473052 100644
--- a/docs/17-dashboard-design.md
+++ b/docs/17-dashboard-design.md
@@ -549,8 +549,8 @@ Real-time updates use **socket.io** (`socket.io-client`), not a raw browser `Web
`src/hooks/useWebSocket.ts`. Key facts:
- **Namespace `/events`** (not `/ws`). The client connects to
- `${VITE_WS_URL || window.location.origin}/events` — same-origin by default; `VITE_WS_URL` only
- overrides it for split-origin deployments.
+ `${VITE_WS_URL || VITE_API_URL || window.location.origin}/events` — same-origin by default; a split-origin build
+ follows the `VITE_API_URL` origin, and `VITE_WS_URL` overrides both.
- **API key via the socket.io `auth` payload (and an `X-API-Key` header for proxies), deliberately
_not_ in the query string** — a key in the handshake URL would leak into access logs / `Referer`.
- **Reconnection is socket.io's built-in mechanism** — `reconnectionAttempts: 5`,
@@ -566,8 +566,11 @@ Real-time updates use **socket.io** (`socket.io-client`), not a raw browser `Web
// src/hooks/useWebSocket.ts (abridged)
import { useEffect, useRef, useCallback, useState } from 'react';
import { io, Socket } from 'socket.io-client';
+import { API_ORIGIN } from '../services/api';
+import { resolveSocketUrl } from '../utils/urlSecurity';
-const SOCKET_URL = import.meta.env.VITE_WS_URL || window.location.origin;
+// VITE_WS_URL, else the VITE_API_URL origin, else the page origin.
+const SOCKET_URL = resolveSocketUrl(import.meta.env.VITE_WS_URL, API_ORIGIN, window.location.origin);
interface ServerEventEnvelope {
type: string; // 'event'
@@ -746,7 +749,7 @@ VITE_API_URL=https://api.example.com npm run build # in dashboard/
```
`dashboard/src/services/api.ts` reads `VITE_API_URL` and calls that origin instead of same-origin
-`/api`. Set `SERVE_DASHBOARD=false` on the API so it stops serving its own copy. Remember to add the
+`/api`. The realtime socket follows the same origin unless `VITE_WS_URL` overrides it. Set `SERVE_DASHBOARD=false` on the API so it stops serving its own copy. Remember to add the
dashboard's origin to `CORS_ORIGINS` on the API.
For TLS or public exposure of the default single-port setup, terminate at your own reverse proxy