@graphoria/server 0.1.0

package/src/queues/rabbitmq.ts

@@ -0,0 +1,331 @@
+import { connect } from "amqplib";
+import { nanoid } from "nanoid";
+
+import type { Channel, ChannelModel, ConsumeMessage } from "amqplib";
+import type { RabbitMQConfig } from "../types/zod/queue";
+
+import { queryEventEmitter } from "../configuration/gql/handleGraphQLSubscriptionFactory";
+import { InvalidationHelper } from "../singletons/cache/registry";
+import { logger } from "../logging";
+
+// ============================================================================
+// Reconnection Configuration
+// ============================================================================
+
+const RECONNECT_INITIAL_DELAY = 1000; // 1 second
+const RECONNECT_MAX_DELAY = 30000; // 30 seconds
+const RECONNECT_MULTIPLIER = 2;
+
+const sendMessage = (connectionName: string, name: string, msg: ConsumeMessage) => {
+  queryEventEmitter.sendDataUpdate(`${connectionName}_${name}`, {
+    data: {
+      message: msg.content.toString(),
+      id: msg.fields.deliveryTag,
+    },
+  });
+};
+
+export const startConsumer = async (
+  connectionName: string,
+  name: string,
+  queueName: string,
+  channel: Channel,
+  handler?: (
+    message: unknown,
+    context: {
+      cache: {
+        invalidate: (operationName: string, pattern?: Record<string, unknown>) => Promise<boolean>;
+      };
+    },
+  ) => Promise<void> | void,
+) => {
+  const log = logger("rabbitmq").child({ queue: connectionName, consumer: name });
+
+  channel.consume(queueName, async (msg) => {
+    if (msg !== null) {
+      try {
+        sendMessage(connectionName, name, msg);
+
+        if (handler) {
+          let parsedMessage = msg.content.toString();
+          try {
+            parsedMessage = JSON.parse(parsedMessage);
+          } catch {
+            // message is not JSON, proceed with raw string
+          }
+
+          await handler(parsedMessage, { cache: InvalidationHelper });
+        }
+
+        channel.ack(msg);
+      } catch (error) {
+        log.error({ err: error }, "message processing failed");
+
+        channel.nack(msg);
+      }
+    }
+  });
+};
+
+export type RabbitMQPublisher = {
+  name: string;
+  routingKey: string;
+  exchangeName: string;
+  send: (message: string | object) => boolean;
+};
+
+export type RabbitMQQueue = RabbitMQConfig;
+
+// ============================================================================
+// RabbitMQ Connection Manager with Reconnection
+// ============================================================================
+
+type RabbitMQConnectionState = {
+  connection: ChannelModel | null;
+  channel: Channel | null;
+  isConnecting: boolean;
+  publishers: Record<string, RabbitMQPublisher>;
+};
+
+export type RabbitMQConnectionManager = {
+  connect: () => Promise<void>;
+  getPublishers: () => Record<string, RabbitMQPublisher>;
+  isConnected: () => boolean;
+  cleanup: () => Promise<void>;
+  onPublishersChanged: (callback: () => void) => void;
+};
+
+export type RabbitMQConnectionManagerOptions = {
+  connect?: typeof connect;
+  setTimeout?: typeof setTimeout;
+};
+
+export const createRabbitMQConnectionManager = (
+  queueConfig: RabbitMQQueue,
+  options: RabbitMQConnectionManagerOptions = {},
+): RabbitMQConnectionManager => {
+  const log = logger("rabbitmq").child({ queue: queueConfig.name });
+  const connectFn = options.connect ?? connect;
+  const setTimeoutFn = options.setTimeout ?? setTimeout;
+  const state: RabbitMQConnectionState = {
+    connection: null,
+    channel: null,
+    isConnecting: false,
+    publishers: {},
+  };
+
+  // Callback to notify when publishers change (connect/reconnect)
+  let publishersChangedCallback: (() => void) | null = null;
+
+  let reconnectAttempts = 0;
+
+  const setupConnection = async (): Promise<void> => {
+    if (state.isConnecting) return;
+    state.isConnecting = true;
+
+    try {
+      log.info("connecting");
+
+      const rmqConnection = await connectFn(queueConfig.connection);
+      const channel = await rmqConnection.createChannel();
+
+      // Set up error handlers for reconnection
+      rmqConnection.on("error", (err) => {
+        log.error({ err }, "connection error");
+      });
+
+      rmqConnection.on("close", () => {
+        log.warn("connection closed, reconnecting");
+        state.connection = null;
+        state.channel = null;
+        scheduleReconnect();
+      });
+
+      channel.on("error", (err) => {
+        log.error({ err }, "channel error");
+      });
+
+      channel.on("close", () => {
+        log.warn("channel closed");
+        state.channel = null;
+      });
+
+      // Set up exchanges and publishers
+      for (const exchange of queueConfig.exchanges) {
+        if (queueConfig.autoSetup) {
+          await channel.assertExchange(exchange.name, exchange.type, exchange.options);
+        }
+
+        for (const p of exchange.publishers) {
+          state.publishers[`${queueConfig.name}_${p.name}`] = {
+            name: p.name,
+            routingKey: p.routingKey,
+            exchangeName: exchange.name,
+            send: (message: string | object) => {
+              if (!state.channel) {
+                log.error("cannot send: channel not available");
+                return false;
+              }
+              return state.channel.publish(
+                exchange.name,
+                p.routingKey,
+                Buffer.from(typeof message === "string" ? message : JSON.stringify(message)),
+                p.options,
+              );
+            },
+          };
+        }
+      }
+
+      // Set up queues and consumers
+      for (const route of queueConfig.queues) {
+        const queueName = route.queue ?? `${route.name}-${nanoid(10)}`;
+
+        const durable = route.queueOptions?.durable ?? !!route.queue;
+        const autoDelete = route.queueOptions?.autoDelete ?? !route.queue;
+
+        if (!route.queue || (route.queue && queueConfig.autoSetup)) {
+          await channel.assertQueue(queueName, {
+            ...route.queueOptions,
+            durable,
+            autoDelete,
+          });
+
+          for (const binding of route.bindings) {
+            await channel.bindQueue(queueName, binding.exchange, binding.pattern);
+          }
+        }
+
+        await startConsumer(queueConfig.name, route.name, queueName, channel, route.handler);
+      }
+
+      state.connection = rmqConnection;
+      state.channel = channel;
+      reconnectAttempts = 0;
+
+      // Notify that publishers have changed
+      if (publishersChangedCallback) {
+        publishersChangedCallback();
+      }
+
+      log.info("connected");
+    } catch (error) {
+      log.error({ err: error }, "connection failed");
+      scheduleReconnect();
+    } finally {
+      state.isConnecting = false;
+    }
+  };
+
+  const scheduleReconnect = () => {
+    const delay = Math.min(
+      RECONNECT_INITIAL_DELAY * Math.pow(RECONNECT_MULTIPLIER, reconnectAttempts),
+      RECONNECT_MAX_DELAY,
+    );
+    reconnectAttempts++;
+
+    log.info({ delay, attempt: reconnectAttempts }, "scheduling reconnect");
+
+    setTimeoutFn(() => {
+      void setupConnection().catch((error) => {
+        log.error({ err: error }, "reconnect attempt failed");
+      });
+    }, delay);
+  };
+
+  const cleanup = async () => {
+    try {
+      if (state.channel) {
+        await state.channel.close();
+      }
+      if (state.connection) {
+        await state.connection.close();
+      }
+    } catch (error) {
+      log.error({ err: error }, "error during cleanup");
+    }
+  };
+
+  return {
+    connect: setupConnection,
+    getPublishers: () => state.publishers,
+    isConnected: () => state.connection !== null && state.channel !== null,
+    cleanup,
+    onPublishersChanged: (callback: () => void) => {
+      publishersChangedCallback = callback;
+    },
+  };
+};
+
+// ============================================================================
+// Main Entry Point
+// ============================================================================
+
+export const startRabbitMQConnections = async (queues: RabbitMQQueue[]) => {
+  const log = logger("rabbitmq");
+  const managers = queues.map((queue) => createRabbitMQConnectionManager(queue));
+
+  // Cached publisher map with dirty flag for optimization
+  let cachedPublisherMap: Record<string, RabbitMQPublisher> = {};
+  let isPublisherMapDirty = true;
+
+  const markDirty = () => {
+    isPublisherMapDirty = true;
+  };
+
+  // Register change callbacks for each manager
+  for (const manager of managers) {
+    manager.onPublishersChanged(markDirty);
+  }
+
+  // Start connection attempts for all queues (non-blocking)
+  // This allows the app to start even if RabbitMQ isn't immediately available
+  // Failed connections will automatically retry in the background
+  for (const manager of managers) {
+    manager.connect().catch((error) => {
+      log.warn({ err: error }, "initial connection failed, will retry");
+    });
+  }
+
+  // Get publisher map - rebuilds only when dirty
+  const getPublisherMap = () => {
+    if (isPublisherMapDirty) {
+      cachedPublisherMap = managers.reduce<Record<string, RabbitMQPublisher>>(
+        (acc, manager) => ({ ...acc, ...manager.getPublishers() }),
+        {},
+      );
+      isPublisherMapDirty = false;
+    }
+    return cachedPublisherMap;
+  };
+
+  const sendMessage = (publisherName: string, message: string | object, _key?: string) => {
+    const publisherMap = getPublisherMap();
+    const publisher = publisherMap[publisherName];
+
+    if (!publisher) {
+      log.error({ publisher: publisherName }, "publisher not found");
+      return false;
+    }
+
+    const result = publisher.send(message);
+
+    if (!result) {
+      log.error({ publisher: publisherName }, "failed to publish message");
+      return false;
+    }
+
+    return true;
+  };
+
+  const cleanup = async () => {
+    await Promise.all(managers.map((manager) => manager.cleanup()));
+  };
+
+  return {
+    managers,
+    publisherMap: getPublisherMap,
+    sendMessage,
+    cleanup,
+  };
+};

package/src/remoteREST/index.ts

@@ -0,0 +1,46 @@
+import type { RemoteRESTConfig } from "../config";
+import type { RemoteRESTResolved } from "./types";
+
+import { parseRemoteOpenAPI } from "./parse";
+import { transformRemoteREST } from "./transform";
+import { logger } from "../logging";
+
+/**
+ * Resolve a single remote REST API: parse spec → transform → produce RemoteRESTResolved
+ */
+export const resolveRemoteREST = async (config: RemoteRESTConfig): Promise<RemoteRESTResolved> => {
+  const spec = await parseRemoteOpenAPI(config);
+  return transformRemoteREST(spec, config);
+};
+
+/**
+ * Resolve all enabled remote REST APIs in parallel.
+ * Returns an array of successfully resolved APIs; logs warnings for failures.
+ */
+export const resolveRemoteRESTApis = async (
+  configs: RemoteRESTConfig[],
+): Promise<RemoteRESTResolved[]> => {
+  const enabled = configs.filter((c) => c.enabled !== false);
+
+  if (enabled.length === 0) return [];
+
+  const results = await Promise.allSettled(enabled.map((config) => resolveRemoteREST(config)));
+
+  const resolved: RemoteRESTResolved[] = [];
+
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
+    if (result.status === "fulfilled") {
+      resolved.push(result.value);
+    } else {
+      logger("remote-rest").warn(
+        { api: enabled[i].name, err: result.reason },
+        "failed to resolve remote REST API",
+      );
+    }
+  }
+
+  return resolved;
+};
+
+export type { RemoteRESTResolved } from "./types";

package/src/remoteREST/parse.ts

@@ -0,0 +1,68 @@
+import type { RemoteRESTConfig } from "../config";
+import type { OpenAPIV3_1 } from "openapi-types";
+
+/**
+ * Parse an OpenAPI spec from a remote URL or local file path.
+ * Supports both JSON and YAML formats.
+ */
+export const parseRemoteOpenAPI = async (
+  config: RemoteRESTConfig,
+): Promise<OpenAPIV3_1.Document> => {
+  let rawText: string;
+
+  if (config.specUrl) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), config.timeout ?? 10000);
+
+    try {
+      const response = await fetch(config.specUrl, {
+        headers: config.headers,
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`Remote REST "${config.name}" spec fetch failed: HTTP ${response.status}`);
+      }
+
+      rawText = await response.text();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  } else if (config.specPath) {
+    const file = Bun.file(config.specPath);
+    const exists = await file.exists();
+
+    if (!exists) {
+      throw new Error(`Remote REST "${config.name}" spec file not found: ${config.specPath}`);
+    }
+
+    rawText = await file.text();
+  } else {
+    throw new Error(`Remote REST "${config.name}" requires either specUrl or specPath`);
+  }
+
+  return parseSpecText(rawText, config.name);
+};
+
+/**
+ * Parse raw text as JSON or YAML OpenAPI spec
+ */
+const parseSpecText = (text: string, name: string): OpenAPIV3_1.Document => {
+  const trimmed = text.trimStart();
+
+  // Try JSON first (starts with { or [)
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      return JSON.parse(text) as OpenAPIV3_1.Document;
+    } catch {
+      throw new Error(`Remote REST "${name}" spec is not valid JSON`);
+    }
+  }
+
+  // Otherwise, parse as YAML using Bun's built-in YAML parser
+  try {
+    return Bun.YAML.parse(text) as OpenAPIV3_1.Document;
+  } catch {
+    throw new Error(`Remote REST "${name}" spec is not valid YAML`);
+  }
+};

package/src/remoteREST/proxy.ts

@@ -0,0 +1,92 @@
+import type { RemoteRESTResolved, RemoteRESTRoute } from "./types";
+
+/**
+ * Build headers for the remote request by merging:
+ * 1. Static headers from configuration
+ * 2. Forwarded headers from the client request
+ */
+const buildHeaders = (
+  resolved: RemoteRESTResolved,
+  clientRequest: Request,
+): Record<string, string> => {
+  const headers: Record<string, string> = {
+    ...(resolved.config.headers ?? {}),
+  };
+
+  if (resolved.config.forwardHeaders?.length) {
+    for (const headerName of resolved.config.forwardHeaders) {
+      const value = clientRequest.headers.get(headerName);
+      if (value) {
+        headers[headerName] = value;
+      }
+    }
+  }
+
+  return headers;
+};
+
+/**
+ * Convert an OpenAPI path template to a URL by substituting path parameters.
+ * e.g. /users/{id} with { id: "123" } → /users/123
+ */
+const substitutePathParams = (path: string, params: Record<string, string>): string =>
+  path.replace(/\{([^}]+)\}/g, (_, key: string) => {
+    const value = params[key];
+    if (value === undefined) {
+      throw new Error(`Missing path parameter: ${key}`);
+    }
+    return encodeURIComponent(value);
+  });
+
+/**
+ * Proxy a request to a remote REST API endpoint.
+ */
+export const proxyRemoteRESTRequest = async (
+  route: RemoteRESTRoute,
+  resolved: RemoteRESTResolved,
+  clientRequest: Request,
+  pathParams: Record<string, string>,
+  queryString: string,
+): Promise<Response> => {
+  const targetPath = substitutePathParams(route.originalPath, pathParams);
+  const targetUrl = `${resolved.baseUrl}${targetPath}${queryString ? `?${queryString}` : ""}`;
+
+  const headers = buildHeaders(resolved, clientRequest);
+
+  // Forward content-type from the client request if present
+  const contentType = clientRequest.headers.get("content-type");
+  if (contentType) {
+    headers["content-type"] = contentType;
+  }
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), resolved.config.timeout ?? 10000);
+
+  try {
+    const fetchInit: RequestInit = {
+      method: route.method.toUpperCase(),
+      headers,
+      signal: controller.signal,
+    };
+
+    // Forward body for methods that support it
+    if (clientRequest.body && ["post", "put", "patch"].includes(route.method)) {
+      fetchInit.body = clientRequest.body;
+      // @ts-expect-error: Bun supports duplex for streaming
+      fetchInit.duplex = "half";
+    }
+
+    const response = await fetch(targetUrl, fetchInit);
+
+    // Return the response with the same status and body
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: {
+        "content-type": response.headers.get("content-type") ?? "application/json",
+      },
+    });
+  } finally {
+    clearTimeout(timeoutId);
+  }
+};

package/src/remoteREST/transform.ts

@@ -0,0 +1,121 @@
+import type { RemoteRESTConfig } from "../config";
+import type { OpenAPIV3_1 } from "openapi-types";
+import type { RemoteRESTResolved, RemoteRESTRoute } from "./types";
+
+const HTTP_METHODS = ["get", "post", "put", "delete", "patch", "head", "options"] as const;
+
+/**
+ * Resolve the base URL for proxying from config or spec
+ */
+const resolveBaseUrl = (config: RemoteRESTConfig, spec: OpenAPIV3_1.Document): string => {
+  if (config.url) return config.url.replace(/\/$/, "");
+
+  const serverUrl = spec.servers?.[0]?.url;
+  if (serverUrl) return serverUrl.replace(/\/$/, "");
+
+  throw new Error(
+    `Remote REST "${config.name}" requires a base URL: set "url" in config or ensure the spec has a "servers" entry`,
+  );
+};
+
+/**
+ * Prefix all $ref strings in an object tree: #/components/schemas/Foo becomes #/components/schemas/{prefix}_Foo
+ */
+const prefixRefs = (obj: unknown, prefix: string): unknown => {
+  if (obj === null || obj === undefined) return obj;
+  if (typeof obj === "string") return obj;
+  if (Array.isArray(obj)) return obj.map((item) => prefixRefs(item, prefix));
+
+  if (typeof obj === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+      if (
+        key === "$ref" &&
+        typeof value === "string" &&
+        value.startsWith("#/components/schemas/")
+      ) {
+        const schemaName = value.slice("#/components/schemas/".length);
+        result[key] = `#/components/schemas/${prefix}_${schemaName}`;
+      } else {
+        result[key] = prefixRefs(value, prefix);
+      }
+    }
+    return result;
+  }
+
+  return obj;
+};
+
+/**
+ * Transform a parsed OpenAPI spec into a RemoteRESTResolved with prefixed paths and schemas
+ */
+export const transformRemoteREST = (
+  spec: OpenAPIV3_1.Document,
+  config: RemoteRESTConfig,
+): RemoteRESTResolved => {
+  const prefix = config.prefix ?? config.name;
+  const baseUrl = resolveBaseUrl(config, spec);
+
+  const routes: RemoteRESTRoute[] = [];
+  const openApiPaths: Record<string, OpenAPIV3_1.PathItemObject> = {};
+  const openApiSchemas: Record<string, OpenAPIV3_1.SchemaObject> = {};
+
+  // Extract and prefix paths
+  if (spec.paths) {
+    for (const [path, pathItem] of Object.entries(spec.paths)) {
+      if (!pathItem) continue;
+
+      const prefixedPath = `/${prefix}${path}`;
+      const prefixedPathItem: OpenAPIV3_1.PathItemObject = {};
+
+      for (const method of HTTP_METHODS) {
+        const operation = (pathItem as Record<string, unknown>)[method] as
+          | OpenAPIV3_1.OperationObject
+          | undefined;
+        if (!operation) continue;
+
+        routes.push({
+          method,
+          originalPath: path,
+          prefixedPath,
+          operationId: operation.operationId,
+          description: operation.summary ?? operation.description,
+          tags: operation.tags,
+        });
+
+        // Prefix $refs in the operation and add remote API tag
+        const prefixedOperation = prefixRefs(operation, prefix) as OpenAPIV3_1.OperationObject;
+        prefixedOperation.tags = [prefix];
+
+        (prefixedPathItem as Record<string, unknown>)[method] = prefixedOperation;
+      }
+
+      // Copy shared parameters (path-level) if they exist
+      if (pathItem.parameters) {
+        prefixedPathItem.parameters = prefixRefs(
+          pathItem.parameters,
+          prefix,
+        ) as OpenAPIV3_1.ParameterObject[];
+      }
+
+      openApiPaths[prefixedPath] = prefixedPathItem;
+    }
+  }
+
+  // Extract and prefix component schemas
+  if (spec.components?.schemas) {
+    for (const [name, schema] of Object.entries(spec.components.schemas)) {
+      if (!schema) continue;
+      openApiSchemas[`${prefix}_${name}`] = prefixRefs(schema, prefix) as OpenAPIV3_1.SchemaObject;
+    }
+  }
+
+  return {
+    config,
+    prefix,
+    baseUrl,
+    routes,
+    openApiPaths,
+    openApiSchemas,
+  };
+};

package/src/remoteREST/types.ts

@@ -0,0 +1,38 @@
+import type { RemoteRESTConfig } from "../config";
+import type { OpenAPIV3_1 } from "openapi-types";
+
+/**
+ * A single route extracted from a remote OpenAPI spec
+ */
+export type RemoteRESTRoute = {
+  /** HTTP method (lowercase) */
+  method: string;
+  /** Original path from the spec (e.g. /users/{id}) */
+  originalPath: string;
+  /** Path with prefix (e.g. /payments/users/{id}) */
+  prefixedPath: string;
+  /** operationId from the spec, if present */
+  operationId?: string;
+  /** Human-readable description */
+  description?: string;
+  /** Tags from the spec */
+  tags?: string[];
+};
+
+/**
+ * Fully resolved remote REST API after spec parsing and transformation
+ */
+export type RemoteRESTResolved = {
+  /** The original configuration */
+  config: RemoteRESTConfig;
+  /** Effective prefix (subpath under /rest) */
+  prefix: string;
+  /** Base URL for proxying requests */
+  baseUrl: string;
+  /** All routes extracted from the spec */
+  routes: RemoteRESTRoute[];
+  /** Prefixed OpenAPI paths for merging into the unified spec */
+  openApiPaths: Record<string, OpenAPIV3_1.PathItemObject>;
+  /** Prefixed component schemas for merging */
+  openApiSchemas: Record<string, OpenAPIV3_1.SchemaObject>;
+};