Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

9.6 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.

import type {
  RealtimeTable,
  RouteRealtimeTable
} from "@carbon/database/realtime-tables";
import { useRevalidator } from "@carbon/react";
import {
  useCallback,
  useEffect,
  useMemo,
  useRef,
  useSyncExternalStore
} from "react";
import { useMatches } from "react-router";
import { getClientCache } from "./cache";
import { invalidateLoaderEntries } from "./invalidation";
import { matchesFilter } from "./realtimeFilter";
import { useRealtimeChannel } from "./useRealtimeChannel";

/** What `broadcast_table_changes` sends: no row data, only which rows changed. */
export type BroadcastChange = {
  table: string;
  op: "INSERT" | "UPDATE" | "DELETE";
  /** Null when more than 100 rows changed, or the table has no `id`: resync. */
  ids: string[] | null;
  /**
   * The records the rows belong to: each `<name>Id` column and its values.
   * Null with `ids`; a column with more than 20 values is left out.
   */
  parents?: Record<string, string[]> | null;
};

const DEFAULT_DEBOUNCE_MS = 300;
// A table that changes more often than its debounce would never reload.
const MAX_WAIT_MS = 5000;

/** The topic `broadcast_table_changes` sends a company's changes to a table on. */
export const companyTopic = (companyId: string, table: string) =>
  `company:${companyId}:${table}`;

/** Marks every cached loader entry stale (`cachedClientLoader`, `useLoaderQuery`). */
const invalidateLoaders = () => invalidateLoaderEntries(getClientCache());

// ─── One channel per topic ───────────────────────────────────────────────────
//
// The Realtime client hands back the SAME channel for a topic it already has, so
// two hooks that each opened `company:<id>:customer` would share one channel and
// the first to unmount would close it for the other. Instead every interested
// component registers a listener here, and `RouteRealtime` (rendered once, in
// the shell) owns exactly one channel per topic that has listeners.

/** `null` after a reconnect: nothing is replayed, so the listener catches up. */
type Listener = (change: BroadcastChange | null) => void;

const listeners = new Map<string, Set<Listener>>();
const watchers = new Set<() => void>();
const NO_TOPICS: string[] = [];
let topics: string[] = NO_TOPICS;

const publishTopics = () => {
  topics = [...listeners.keys()].sort();
  for (const notify of watchers) notify();
};

const dispatch = (topic: string, change: BroadcastChange | null) => {
  for (const listener of listeners.get(topic) ?? []) listener(change);
};

function listen(topic: string, listener: Listener) {
  const existing = listeners.get(topic);
  if (existing) {
    existing.add(listener);
  } else {
    listeners.set(topic, new Set([listener]));
    publishTopics();
  }
  return () => {
    const set = listeners.get(topic);
    set?.delete(listener);
    if (set?.size === 0) {
      listeners.delete(topic);
      publishTopics();
    }
  };
}

/**
 * Listen to a private broadcast topic. Any number of components may listen to
 * one topic; they share its channel. `onMessage(null)` means "reconnected".
 */
export function useTopic(topic: string, onMessage: Listener, enabled = true) {
  const onMessageRef = useRef(onMessage);
  onMessageRef.current = onMessage;

  useEffect(() => {
    if (!enabled) return;
    return listen(topic, (change) => onMessageRef.current(change));
  }, [topic, enabled]);
}

function TopicChannel({ topic }: { topic: string }) {
  useRealtimeChannel({
    topic,
    private: true,
    dependencies: [topic],
    onSubscribed: (isReconnect) => {
      if (isReconnect) dispatch(topic, null);
    },
    setup(channel) {
      return channel.on("broadcast", { event: "*" }, ({ payload }) => {
        dispatch(topic, payload as BroadcastChange);
      });
    }
  });
  return null;
}

function TopicChannels() {
  const active = useSyncExternalStore(
    (notify) => {
      watchers.add(notify);
      return () => watchers.delete(notify);
    },
    () => topics,
    () => NO_TOPICS
  );
  return (
    <>
      {active.map((topic) => (
        <TopicChannel key={topic} topic={topic} />
      ))}
    </>
  );
}

// A route and a component on it may both follow one table, and one write often
// touches several tables a page follows. Their timers fire together; the page
// is reloaded once.
let revalidation: ReturnType<typeof setTimeout> | null = null;
const requestRevalidation = (revalidate: () => void) => {
  if (revalidation) clearTimeout(revalidation);
  revalidation = setTimeout(() => {
    revalidation = null;
    revalidate();
  }, 50);
};

/**
 * The page reload a realtime change asks for: debounced across the tables a
 * page follows, and held while a save is in flight (see `useRevalidator`).
 */
export function useRealtimeRevalidator() {
  const { revalidate } = useRevalidator();
  return useCallback(() => requestRevalidation(revalidate), [revalidate]);
}

/**
 * Calls `onChange` for each change to `table` in the company, and with `null`
 * after a reconnect (nothing is replayed, so the caller catches up).
 */
export function useTableChanges({
  companyId,
  table,
  enabled = true,
  onChange
}: {
  companyId: string;
  table: RealtimeTable;
  enabled?: boolean;
  onChange: (change: BroadcastChange | null) => void;
}) {
  useTopic(companyTopic(companyId, table), onChange, enabled);
}

/**
 * Reloads the page's data when `table` changes in the company. A burst of
 * changes inside `debounceMs` is one reload.
 */
export function useRealtimeTable({
  companyId,
  table,
  filter,
  debounceMs = DEFAULT_DEBOUNCE_MS,
  enabled = true
}: {
  companyId: string;
  table: RealtimeTable;
  /**
   * `id=eq.<id>`, `id=in.(<ids>)`, or the same on a `<name>Id` column
   * (`jobId=eq.<id>`). A filter on any other column is ignored.
   */
  filter?: string;
  debounceMs?: number;
  enabled?: boolean;
}) {
  const revalidate = useRealtimeRevalidator();
  const timeout = useRef<ReturnType<typeof setTimeout> | null>(null);
  const waitingSince = useRef<number | null>(null);

  useEffect(
    () => () => {
      if (timeout.current) clearTimeout(timeout.current);
    },
    []
  );

  useTableChanges({
    companyId,
    table,
    enabled,
    onChange: (change) => {
      if (change && !matchesFilter(filter, change)) return;
      if (timeout.current) clearTimeout(timeout.current);
      waitingSince.current ??= performance.now();
      const waited = performance.now() - waitingSince.current;
      timeout.current = setTimeout(
        () => {
          waitingSince.current = null;
          invalidateLoaders();
          revalidate();
        },
        Math.max(0, Math.min(debounceMs, MAX_WAIT_MS - waited))
      );
    }
  });
}

function TableSubscription(props: {
  companyId: string;
  table: RealtimeTable;
  filter?: string;
}) {
  useRealtimeTable(props);
  return null;
}

/**
 * Keeps the matched routes live: each route names the tables it shows in
 * `handle.realtime`, and this subscribes to them for as long as it is matched.
 * An entry `{ table, column, param }` follows only the rows whose `column` is
 * the route's `param` (a job page: its own operations, not every job's), and
 * `{ table, filter }` builds the filter from the route's loader data.
 * It also owns every realtime channel of the page (see "One channel per topic"):
 * nothing is delivered to any listener unless this is mounted.
 * It also follows the company's reference lists, which are read through cached
 * `api+` loaders rather than a matched route. Render it once, in the shell.
 */
export function RouteRealtime({ companyId }: { companyId: string }) {
  // Mounted for the whole session, so a held revalidation always has a caller
  // left to run it.
  useRevalidator();
  const matches = useMatches();
  const tables = useMemo(() => {
    const followed = new Map<
      string,
      { table: RealtimeTable; filter?: string }
    >();
    for (const match of matches) {
      const entries =
        (match.handle as { realtime?: RouteRealtimeTable[] } | undefined)
          ?.realtime ?? [];
      for (const entry of entries) {
        if (typeof entry === "string") {
          followed.set(entry, { table: entry });
          continue;
        }
        let filter: string | undefined | false;
        if ("filter" in entry) {
          filter = entry.filter({
            params: match.params,
            data: match.loaderData ?? match.data
          });
        } else {
          const value = match.params[entry.param];
          filter = value ? `${entry.column}=eq.${value}` : undefined;
        }
        if (filter === false) continue;
        followed.set(`${entry.table}:${filter ?? ""}`, {
          table: entry.table,
          filter
        });
      }
    }
    return [...followed.entries()].sort(([a], [b]) => a.localeCompare(b));
  }, [matches]);

  const timeout = useRef<ReturnType<typeof setTimeout> | null>(null);
  useEffect(
    () => () => {
      if (timeout.current) clearTimeout(timeout.current);
    },
    []
  );
  useTopic(`company:${companyId}:reference`, (change) => {
    if (!change) {
      invalidateLoaders();
      return;
    }
    if (timeout.current) clearTimeout(timeout.current);
    timeout.current = setTimeout(invalidateLoaders, DEFAULT_DEBOUNCE_MS);
  });

  return (
    <>
      {tables.map(([key, { table, filter }]) => (
        <TableSubscription
          key={key}
          companyId={companyId}
          table={table}
          filter={filter}
        />
      ))}
      <TopicChannels />
    </>
  );
}