@terreno/api 0.13.2 → 0.14.0

package/src/realtime/queryMatcher.ts

@@ -0,0 +1,179 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: MongoDB query matcher evaluates dynamic filter shapes
+/**
+ * Simple in-memory MongoDB query matcher.
+ * Evaluates a MongoDB-style query object against a document without hitting the database.
+ *
+ * Supports: equality, $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $and, $or, $not.
+ */
+
+// biome-ignore lint/suspicious/noExplicitAny: traversing arbitrary nested document fields by user-supplied dotted path
+const getNestedValue = (doc: any, path: string): any => {
+  const parts = path.split(".");
+  let current = doc;
+  for (const part of parts) {
+    if (current === null || current === undefined) {
+      return undefined;
+    }
+    current = current[part];
+  }
+  return current;
+};
+
+// biome-ignore lint/suspicious/noExplicitAny: value may be any document field type (string, number, ObjectId, etc.)
+const normalize = (value: any): any => {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  // Handle ObjectId-like objects with toString
+  if (
+    typeof value === "object" &&
+    typeof value.toString === "function" &&
+    value.constructor?.name !== "Object" &&
+    !Array.isArray(value)
+  ) {
+    return value.toString();
+  }
+  return value;
+};
+
+// biome-ignore lint/suspicious/noExplicitAny: rawValue is an arbitrary document field, condition is an arbitrary user query operand
+const matchesCondition = (rawValue: any, condition: any): boolean => {
+  const value = normalize(rawValue);
+
+  // Direct equality (non-object condition)
+  if (condition === null || condition === undefined || typeof condition !== "object") {
+    const normalizedCondition = normalize(condition);
+    return value === normalizedCondition || String(value) === String(normalizedCondition);
+  }
+
+  // Array equality
+  if (Array.isArray(condition)) {
+    return JSON.stringify(value) === JSON.stringify(condition);
+  }
+
+  // Operator object
+  for (const [op, operand] of Object.entries(condition)) {
+    const normOp = normalize(operand);
+
+    switch (op) {
+      case "$eq":
+        if (value !== normOp && String(value) !== String(normOp)) {
+          return false;
+        }
+        break;
+      case "$ne":
+        if (value === normOp || String(value) === String(normOp)) {
+          return false;
+        }
+        break;
+      case "$gt":
+        if (!(value > normOp)) {
+          return false;
+        }
+        break;
+      case "$gte":
+        if (!(value >= normOp)) {
+          return false;
+        }
+        break;
+      case "$lt":
+        if (!(value < normOp)) {
+          return false;
+        }
+        break;
+      case "$lte":
+        if (!(value <= normOp)) {
+          return false;
+        }
+        break;
+      case "$in": {
+        if (!Array.isArray(operand)) {
+          return false;
+        }
+        const inValues = operand.map(normalize);
+        // biome-ignore lint/suspicious/noExplicitAny: normalized value of arbitrary document field
+        if (!inValues.some((v: any) => v === value || String(v) === String(value))) {
+          return false;
+        }
+        break;
+      }
+      case "$nin": {
+        if (!Array.isArray(operand)) {
+          return false;
+        }
+        const ninValues = operand.map(normalize);
+        // biome-ignore lint/suspicious/noExplicitAny: normalized value of arbitrary document field
+        if (ninValues.some((v: any) => v === value || String(v) === String(value))) {
+          return false;
+        }
+        break;
+      }
+      case "$exists":
+        if (operand && rawValue === undefined) {
+          return false;
+        }
+        if (!operand && rawValue !== undefined) {
+          return false;
+        }
+        break;
+      case "$not":
+        if (matchesCondition(rawValue, operand)) {
+          return false;
+        }
+        break;
+      default:
+        // Unknown operator — fail closed to avoid leaking data
+        return false;
+    }
+  }
+
+  return true;
+};
+
+/**
+ * Check if a document matches a MongoDB-style query in memory.
+ *
+ * @param doc - The document to test (plain object or Mongoose document)
+ * @param query - MongoDB-style query object
+ * @returns true if the document matches all query conditions
+ */
+// biome-ignore lint/suspicious/noExplicitAny: doc is arbitrary; query values are arbitrary user-supplied JSON
+export const matchesQuery = (doc: any, query: Record<string, any>): boolean => {
+  for (const [key, condition] of Object.entries(query)) {
+    if (key === "$and") {
+      if (!Array.isArray(condition)) {
+        return false;
+      }
+      for (const subQuery of condition) {
+        if (!matchesQuery(doc, subQuery)) {
+          return false;
+        }
+      }
+      continue;
+    }
+
+    if (key === "$or") {
+      if (!Array.isArray(condition)) {
+        return false;
+      }
+      let matched = false;
+      for (const subQuery of condition) {
+        if (matchesQuery(doc, subQuery)) {
+          matched = true;
+          break;
+        }
+      }
+      if (!matched) {
+        return false;
+      }
+      continue;
+    }
+
+    const value = getNestedValue(doc, key);
+    if (!matchesCondition(value, condition)) {
+      return false;
+    }
+  }
+
+  return true;
+};

package/src/realtime/queryStore.ts

@@ -0,0 +1,132 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: query filters are dynamic MongoDB query objects
+/**
+ * Manages query subscriptions for Socket.io clients.
+ *
+ * When a client subscribes to a query (e.g., `{completed: false}` on the "todos" collection),
+ * the query is stored here. The change stream watcher consults this store to determine
+ * which query rooms should receive a given change event.
+ */
+
+interface QuerySubscription {
+  collection: string;
+  // biome-ignore lint/suspicious/noExplicitAny: MongoDB query filter values are arbitrary user-supplied JSON
+  query: Record<string, any>;
+  queryId: string;
+}
+
+/**
+ * Compute a deterministic queryId from collection and query on the server side.
+ * This prevents clients from hijacking other subscriptions by providing a colliding queryId.
+ */
+export const computeQueryId = (
+  collection: string,
+  // biome-ignore lint/suspicious/noExplicitAny: MongoDB query filter values are arbitrary user-supplied JSON
+  query: Record<string, any>
+): string => {
+  const sortedKeys = Object.keys(query).sort();
+  // biome-ignore lint/suspicious/noExplicitAny: mirrors the input query value shape
+  const normalized: Record<string, any> = {};
+  for (const key of sortedKeys) {
+    normalized[key] = query[key];
+  }
+  return `${collection}:${JSON.stringify(normalized)}`;
+};
+
+/** queryId → query subscription details (shared across all sockets in that room) */
+const querySubscriptions = new Map<string, QuerySubscription>();
+
+/** socketId → set of queryIds that socket is subscribed to */
+const socketQueries = new Map<string, Set<string>>();
+
+/**
+ * Register a query subscription for a socket.
+ * The socket joins the `query:{queryId}` room (handled by the caller).
+ */
+export const addQuerySubscription = (
+  socketId: string,
+  collection: string,
+  // biome-ignore lint/suspicious/noExplicitAny: MongoDB query filter values are arbitrary user-supplied JSON
+  query: Record<string, any>,
+  queryId: string
+): void => {
+  querySubscriptions.set(queryId, {collection, query, queryId});
+
+  if (!socketQueries.has(socketId)) {
+    socketQueries.set(socketId, new Set());
+  }
+  socketQueries.get(socketId)?.add(queryId);
+};
+
+/**
+ * Remove a single query subscription for a socket.
+ */
+export const removeQuerySubscription = (socketId: string, queryId: string): void => {
+  socketQueries.get(socketId)?.delete(queryId);
+
+  // Check if any other socket still has this query
+  let stillUsed = false;
+  for (const [, queryIds] of socketQueries) {
+    if (queryIds.has(queryId)) {
+      stillUsed = true;
+      break;
+    }
+  }
+
+  if (!stillUsed) {
+    querySubscriptions.delete(queryId);
+  }
+};
+
+/**
+ * Remove all query subscriptions for a disconnected socket.
+ */
+export const removeAllSocketQueries = (socketId: string): void => {
+  const queryIds = socketQueries.get(socketId);
+  if (!queryIds) {
+    return;
+  }
+
+  socketQueries.delete(socketId);
+
+  // Clean up any queries that no longer have subscribers
+  for (const queryId of queryIds) {
+    let stillUsed = false;
+    for (const [, otherQueryIds] of socketQueries) {
+      if (otherQueryIds.has(queryId)) {
+        stillUsed = true;
+        break;
+      }
+    }
+    if (!stillUsed) {
+      querySubscriptions.delete(queryId);
+    }
+  }
+};
+
+/**
+ * Get all unique query subscriptions for a given collection.
+ * Used by the change stream watcher to evaluate which query rooms to emit to.
+ */
+export const getQuerySubscriptionsForCollection = (
+  collection: string
+  // biome-ignore lint/suspicious/noExplicitAny: MongoDB query filter values are arbitrary user-supplied JSON
+): {queryId: string; query: Record<string, any>}[] => {
+  // biome-ignore lint/suspicious/noExplicitAny: MongoDB query filter values are arbitrary user-supplied JSON
+  const result: {queryId: string; query: Record<string, any>}[] = [];
+
+  for (const [queryId, sub] of querySubscriptions) {
+    if (sub.collection === collection) {
+      result.push({query: sub.query, queryId});
+    }
+  }
+
+  return result;
+};
+
+/**
+ * Clear all subscriptions (for testing).
+ */
+export const clearQueryStore = (): void => {
+  querySubscriptions.clear();
+  socketQueries.clear();
+};