-
Database Settings
+
Database Settings
{databaseType === 'MongoDB'
- ? 'Configure MongoDB replica set read preferences, write concern, and read concern levels for your deployment.'
+ ? 'Configure live updates, replica set read preferences, write concern, and read concern.'
: 'Database replication settings for your deployment.'}
@@ -53,6 +57,7 @@ export const Settings = ({ data, databaseType }: Props) => {
setEdit={setEdit}
reset={reset}
databaseType={databaseType}
+ realtimeStatus={realtimeStatus}
/>
diff --git a/src/components/database/settings/settingsForm.tsx b/src/components/database/settings/settingsForm.tsx
index 570567f9c..ff07ca7b2 100644
--- a/src/components/database/settings/settingsForm.tsx
+++ b/src/components/database/settings/settingsForm.tsx
@@ -14,7 +14,9 @@ import {
SelectValue,
} from '@/components/ui/select';
import { Alert, AlertDescription } from '@/components/ui/alert';
+import { Switch } from '@/components/ui/switch';
import { SettingsFormActions } from '@/components/settings/SettingsFormActions';
+import type { DatabaseRealtimeStatus } from '@/lib/models/database';
interface Props {
control: any;
@@ -23,6 +25,36 @@ interface Props {
setEdit: (arg0: boolean) => void;
reset: any;
databaseType: string;
+ realtimeStatus?: DatabaseRealtimeStatus | null;
+}
+
+function realtimeStatusCopy(status: DatabaseRealtimeStatus | null | undefined) {
+ if (!status) {
+ return 'Runtime status is unavailable for this backend.';
+ }
+ switch (status.status) {
+ case 'live':
+ return `Live · ${status.activeSchemaCount} opted-in ${
+ status.activeSchemaCount === 1 ? 'schema' : 'schemas'
+ }`;
+ case 'starting':
+ return 'Starting the change-stream listener.';
+ case 'idle':
+ return (
+ status.message ??
+ 'Waiting for a replica set and at least one opted-in schema.'
+ );
+ case 'disabled':
+ return 'Live updates are turned off for this module.';
+ case 'degraded':
+ return status.message ?? 'The change-stream listener is degraded.';
+ case 'unsupported':
+ return status.message ?? 'Live updates require MongoDB.';
+ default: {
+ const _exhaustive: never = status.status;
+ return _exhaustive;
+ }
+ }
}
export const SettingsForm = ({
@@ -32,13 +64,14 @@ export const SettingsForm = ({
setEdit,
reset,
databaseType,
+ realtimeStatus,
}: Props) => {
if (databaseType !== 'MongoDB') {
return (
- Replica set read preferences are only available for MongoDB
- deployments. Your current database type is{' '}
+ Live updates and replica set read preferences are only available for
+ MongoDB deployments. Your current database type is{' '}
{databaseType}.
@@ -47,7 +80,37 @@ export const SettingsForm = ({
return (
<>
-
+
+
(
+
+
+
+ Live updates
+
+
+ Watch opted-in schemas through MongoDB change streams. Schemas
+ must also enable live updates. Data Explorer never
+ auto-refreshes.
+
+
+ {realtimeStatusCopy(realtimeStatus)}
+
+
{});
+socket.emit('unsubscribe', relayId, resourceId);`;
+
+const STEPS = [
+ {
+ title: 'Bus event',
+ body: 'A module publishes JSON on an exact Redis channel — for example database realtime or a custom module.',
+ },
+ {
+ title: 'Active relay',
+ body: 'The matching relay reads the resource id from the payload and renders the message template.',
+ },
+ {
+ title: 'ReBAC subscribe',
+ body: 'Clients never pick a room name. Subscribe succeeds only if the user has the relay permission on that resource.',
+ },
+ {
+ title: 'Socket emit',
+ body: 'Router emits socketEvent to the hashed /events/ room. Delivery is ephemeral — missed events are gone.',
+ },
+] as const;
+
+const SCOPE = [
+ {
+ title: 'Use when',
+ body: 'You already publish JSON on an exact Redis bus channel and need live, per-resource UI updates with a ReBAC check.',
+ },
+ {
+ title: 'Skip when',
+ body: 'You need replay, history, guaranteed delivery, wildcard channels, or a broadcast with no permission check. Relays are not a queue.',
+ },
+ {
+ title: 'Requires',
+ body: 'Router sockets enabled, the Authorization module available, and something publishing on that exact channel.',
+ },
+] as const;
+
+interface EventRelayDocsProps {
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+}
+
+export function EventRelayDocs({ open, onOpenChange }: EventRelayDocsProps) {
+ return (
+
+
+ svg]:rotate-180'
+ )}
+ >
+
+
+ How Event Relays work
+
+
+ Forward an exact bus event to permission-scoped socket
+ subscribers. Not a queue, and not a generic websocket broadcast.
+
+
+
+
+
+
+
+ Scope
+
+ {SCOPE.map(item => (
+
+
+ {item.title}
+
+
+ {item.body}
+
+
+ ))}
+
+
+
+
+ How a message moves
+
+
+ {STEPS.map((step, index) => (
+ -
+
+ {index + 1}
+
+
+
+ {step.title}
+
+
+ {step.body}
+
+
+ ))}
+
+
+
+
+
+ Configure a relay
+
+
+ Example: notify clients when an Order document changes.
+
+
+
+
+
+
+
+
+
+
+
+
+ Subscribe from a client
+
+
+ Connect to {'/events/'} with{' '}
+ {'path: /realtime'} and a user bearer token. Then
+ subscribe with the relay id and resource id.
+
+
+ {CLIENT_SNIPPET}
+
+
+
+
+ Limits
+
+ -
+ Bus channels must match exactly. Patterns like{' '}
+
{'database:change:*'} are not supported.
+
+ -
+ Subscribe fails closed if Authorization is unavailable or the
+ user lacks permission.
+
+ -
+ Turn a relay off with Active to stop forwarding without
+ deleting it. Deleting drops current subscribers immediately.
+
+
+
+
+
+ {name}
+
+
+ {value}
+ {hint}
+
+
+ {children}
+
+ );
+}
diff --git a/src/components/router/event-relays/event-relay-form.tsx b/src/components/router/event-relays/event-relay-form.tsx
new file mode 100644
index 000000000..92694b7e3
--- /dev/null
+++ b/src/components/router/event-relays/event-relay-form.tsx
@@ -0,0 +1,213 @@
+'use client';
+
+import { useMemo } from 'react';
+import { useForm, useWatch } from 'react-hook-form';
+import { rhfZodResolver } from '@/lib/zod-form';
+import { Form } from '@/components/ui/form';
+import { InputField } from '@/components/ui/form-inputs/InputField';
+import SwitchField from '@/components/ui/form-inputs/SwitchField';
+import { CodeField } from '@/components/ui/form-inputs/CodeField';
+import { Button } from '@/components/ui/button';
+import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
+import {
+ EventRelayFormSchema,
+ EventRelayFormValues,
+ parseJsonField,
+} from '@/components/router/event-relays/zod';
+import { previewEventRelay } from '@/lib/event-relays/preview';
+import { EventRelay, EventRelayWriteRequest } from '@/lib/models/Router';
+
+const DEFAULT_TEMPLATE = '{\n "id": "{{payload._id}}"\n}';
+const DEFAULT_SAMPLE =
+ '{\n "_id": "64f1c0a2b4d0e1f2a3b4c5d6",\n "status": "paid"\n}';
+
+interface EventRelayFormProps {
+ relay?: EventRelay | null;
+ onSubmit: (data: EventRelayWriteRequest) => Promise;
+ onCancel: () => void;
+ isSaving?: boolean;
+}
+
+export function EventRelayForm({
+ relay,
+ onSubmit,
+ onCancel,
+ isSaving,
+}: EventRelayFormProps) {
+ const form = useForm({
+ resolver: rhfZodResolver(EventRelayFormSchema),
+ defaultValues: {
+ name: relay?.name ?? '',
+ notes: relay?.notes ?? '',
+ active: relay?.active ?? true,
+ busEvent: relay?.busEvent ?? '',
+ socketEvent: relay?.socketEvent ?? '',
+ resourceType: relay?.resourceType ?? '',
+ resourceIdPath: relay?.resourceIdPath ?? '_id',
+ permission: relay?.permission ?? 'read',
+ messageTemplate: relay
+ ? JSON.stringify(relay.messageTemplate, null, 2)
+ : DEFAULT_TEMPLATE,
+ samplePayload: DEFAULT_SAMPLE,
+ },
+ });
+
+ const watched = useWatch({ control: form.control });
+ const preview = useMemo(() => {
+ try {
+ const template = parseJsonField(
+ watched.messageTemplate ?? '',
+ 'Message template'
+ );
+ const sample = parseJsonField(
+ watched.samplePayload?.trim() || '{}',
+ 'Sample payload'
+ );
+ return previewEventRelay({
+ resourceIdPath: watched.resourceIdPath || '_id',
+ messageTemplate: template,
+ samplePayload: sample,
+ });
+ } catch (err) {
+ return {
+ error: err instanceof Error ? err.message : String(err),
+ };
+ }
+ }, [watched.messageTemplate, watched.samplePayload, watched.resourceIdPath]);
+
+ const handleSubmit = form.handleSubmit(async values => {
+ const messageTemplate = parseJsonField(
+ values.messageTemplate,
+ 'Message template'
+ );
+ const notes = values.notes?.trim();
+ await onSubmit({
+ name: values.name,
+ notes: notes || undefined,
+ active: values.active,
+ busEvent: values.busEvent,
+ socketEvent: values.socketEvent,
+ resourceType: values.resourceType,
+ resourceIdPath: values.resourceIdPath,
+ permission: values.permission,
+ messageTemplate,
+ });
+ });
+
+ return (
+
+
+ );
+}
diff --git a/src/components/router/event-relays/event-relay-list.tsx b/src/components/router/event-relays/event-relay-list.tsx
new file mode 100644
index 000000000..c64e5a456
--- /dev/null
+++ b/src/components/router/event-relays/event-relay-list.tsx
@@ -0,0 +1,304 @@
+'use client';
+
+import { useCallback, useMemo, useState } from 'react';
+import { ColumnDef } from '@tanstack/react-table';
+import { BookOpen, Plus, Radio, Zap } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { Badge } from '@/components/ui/badge';
+import { DataTable } from '@/components/ui/data-table';
+import { EmptyState } from '@/components/ui/empty-state';
+import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
+import {
+ Dialog,
+ DialogContent,
+ DialogDescription,
+ DialogHeader,
+ DialogTitle,
+} from '@/components/ui/dialog';
+import {
+ Tooltip,
+ TooltipContent,
+ TooltipProvider,
+ TooltipTrigger,
+} from '@/components/ui/tooltip';
+import {
+ PageActions,
+ PageDescription,
+ PageHeader,
+ PageTitle,
+} from '@/components/ui/page-header';
+import { SearchInput } from '@/components/ui/form-inputs/SearchInput';
+import { DeleteAlert } from '@/components/helpers/delete';
+import { EventRelayDocs } from '@/components/router/event-relays/event-relay-docs';
+import { EventRelayForm } from '@/components/router/event-relays/event-relay-form';
+import { EventRelay, EventRelayWriteRequest } from '@/lib/models/Router';
+import {
+ createEventRelay,
+ deleteEventRelay,
+ patchEventRelay,
+} from '@/lib/api/router';
+import { useSettingsSave } from '@/lib/hooks/use-settings-save';
+import { useRouter } from 'next/navigation';
+
+interface EventRelayListProps {
+ relays: EventRelay[];
+ count: number;
+ socketsEnabled: boolean;
+}
+
+export function EventRelayList({
+ relays,
+ count,
+ socketsEnabled,
+}: EventRelayListProps) {
+ const router = useRouter();
+ const [isCreateOpen, setIsCreateOpen] = useState(false);
+ const [editing, setEditing] = useState(null);
+ const [docsOpen, setDocsOpen] = useState(count === 0);
+ const { save, isSaving } = useSettingsSave('Event Relay');
+
+ const toggleDocs = useCallback(() => {
+ setDocsOpen(open => {
+ const next = !open;
+ if (next) {
+ requestAnimationFrame(() => {
+ document
+ .getElementById('event-relay-docs')
+ ?.scrollIntoView({ behavior: 'smooth', block: 'start' });
+ });
+ }
+ return next;
+ });
+ }, []);
+
+ const refresh = useCallback(() => {
+ router.refresh();
+ }, [router]);
+
+ const handleCreate = async (data: EventRelayWriteRequest) => {
+ const result = await save({
+ action: async () => {
+ await createEventRelay(data);
+ await refresh();
+ },
+ successMessage: 'Event relay created',
+ });
+ if (result.ok) {
+ setIsCreateOpen(false);
+ }
+ };
+
+ const handleUpdate = async (data: EventRelayWriteRequest) => {
+ if (!editing) return;
+ const result = await save({
+ action: async () => {
+ await patchEventRelay(editing._id, data);
+ await refresh();
+ },
+ successMessage: 'Event relay updated',
+ });
+ if (result.ok) {
+ setEditing(null);
+ }
+ };
+
+ const columns = useMemo[]>(
+ () => [
+ {
+ accessorKey: 'name',
+ header: 'Name',
+ cell: ({ row }) => (
+
+
{row.original.name}
+ {row.original.notes ? (
+
+ {row.original.notes}
+
+ ) : null}
+
+ {row.original.busEvent}
+
+ ),
+ },
+ {
+ accessorKey: 'socketEvent',
+ header: 'Socket event',
+ cell: ({ row }) => (
+
+ {row.original.socketEvent}
+
+ ),
+ },
+ {
+ accessorKey: 'resourceType',
+ header: 'Resource',
+ cell: ({ row }) => (
+
+ {row.original.resourceType}:{row.original.permission}
+
+ ),
+ },
+ {
+ accessorKey: 'active',
+ header: 'Status',
+ cell: ({ row }) => (
+
+ {row.original.active ? 'Active' : 'Disabled'}
+
+ ),
+ },
+ {
+ id: 'actions',
+ cell: ({ row }) => (
+
+
+
+ save({
+ action: async () => {
+ await deleteEventRelay(row.original._id);
+ await refresh();
+ },
+ successMessage: 'Event relay deleted',
+ })
+ }
+ />
+
+ ),
+ },
+ ],
+ [save, refresh]
+ );
+
+ return (
+
+
+
+
Event Relays
+
+ Send a templated socket message when an exact bus event arrives.
+ Subscribers join resource rooms on /events/ after a ReBAC check.
+
+
+
+ {!socketsEnabled ? (
+
+
+ WebSockets are disabled
+
+ Enable sockets in Router Settings before clients can subscribe to
+ relays.
+
+
+ ) : null}
+
+
+
+
+
+
+
+ {relays.length === 0 ? (
+
setIsCreateOpen(true)}>
+
+ New relay
+
+ }
+ />
+ ) : (
+
+ )}
+
+
+
+
+