@flowerforce/flowerbase 1.7.5-beta.3 → 1.7.5-beta.5

package/dist/features/functions/controller.d.ts

@@ -1,4 +1,6 @@
 import { FunctionController } from './interface';
+export declare const mapWatchFilterToChangeStreamMatch: (value: unknown) => unknown;
+export declare const mapWatchFilterToDocumentQuery: (value: unknown) => unknown;
 /**
  * > Creates a pre handler for every query
  * @param app -> the fastify instance

package/dist/features/functions/controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../../src/features/functions/controller.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAgGhD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,kBAsPjC,CAAA"}
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../../src/features/functions/controller.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAmHhD,eAAO,MAAM,iCAAiC,GAAI,OAAO,OAAO,KAAG,OA0BlE,CAAA;AAID,eAAO,MAAM,6BAA6B,GAAI,OAAO,OAAO,KAAG,OAgD9D,CAAA;AAqHD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,kBAoRjC,CAAA"}

package/dist/features/functions/controller.js

@@ -20,7 +20,7 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.functionsController = void 0;
+exports.functionsController = exports.mapWatchFilterToDocumentQuery = exports.mapWatchFilterToChangeStreamMatch = void 0;
 const bson_1 = require("bson");
 const services_1 = require("../../services");
 const context_1 = require("../../utils/context");
@@ -58,6 +58,12 @@ const isReturnedError = (value) => {
 };
 const serializeEjson = (value) => JSON.stringify(bson_1.EJSON.serialize(value, { relaxed: false }));
 const isRecord = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const isPlainRecord = (value) => {
+    if (!isRecord(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
 const isCursorLike = (value) => {
     if (!value || typeof value !== 'object')
         return false;
@@ -70,12 +76,187 @@ const normalizeFunctionResult = (value) => __awaiter(void 0, void 0, void 0, fun
 });
 const sharedWatchStreams = new Map();
 let watchSubscriberCounter = 0;
+const maxSharedWatchStreams = Number(process.env.MAX_SHARED_WATCH_STREAMS || 200);
+const debugWatchStreams = process.env.DEBUG_FUNCTIONS === 'true';
+const changeEventRootKeys = new Set([
+    '_id',
+    'operationType',
+    'clusterTime',
+    'txnNumber',
+    'lsid',
+    'ns',
+    'documentKey',
+    'fullDocument',
+    'updateDescription'
+]);
+const isChangeEventPath = (key) => {
+    if (changeEventRootKeys.has(key))
+        return true;
+    return (key.startsWith('ns.') ||
+        key.startsWith('documentKey.') ||
+        key.startsWith('fullDocument.') ||
+        key.startsWith('updateDescription.'));
+};
+const isOpaqueChangeEventObjectKey = (key) => key === 'ns' || key === 'documentKey' || key === 'fullDocument' || key === 'updateDescription';
+const mapWatchFilterToChangeStreamMatch = (value) => {
+    if (Array.isArray(value)) {
+        return value.map((item) => (0, exports.mapWatchFilterToChangeStreamMatch)(item));
+    }
+    if (!isPlainRecord(value))
+        return value;
+    return Object.entries(value).reduce((acc, [key, current]) => {
+        if (key.startsWith('$')) {
+            acc[key] = (0, exports.mapWatchFilterToChangeStreamMatch)(current);
+            return acc;
+        }
+        if (isOpaqueChangeEventObjectKey(key)) {
+            acc[key] = current;
+            return acc;
+        }
+        if (isChangeEventPath(key)) {
+            acc[key] = (0, exports.mapWatchFilterToChangeStreamMatch)(current);
+            return acc;
+        }
+        acc[`fullDocument.${key}`] = (0, exports.mapWatchFilterToChangeStreamMatch)(current);
+        return acc;
+    }, {});
+};
+exports.mapWatchFilterToChangeStreamMatch = mapWatchFilterToChangeStreamMatch;
+const isLogicalOperator = (key) => key === '$and' || key === '$or' || key === '$nor';
+const mapWatchFilterToDocumentQuery = (value) => {
+    if (Array.isArray(value)) {
+        const mapped = value
+            .map((item) => (0, exports.mapWatchFilterToDocumentQuery)(item))
+            .filter((item) => !(isRecord(item) && Object.keys(item).length === 0));
+        return mapped;
+    }
+    if (!isPlainRecord(value))
+        return value;
+    return Object.entries(value).reduce((acc, [key, current]) => {
+        if (key.startsWith('$')) {
+            const mapped = (0, exports.mapWatchFilterToDocumentQuery)(current);
+            if (isLogicalOperator(key) && Array.isArray(mapped)) {
+                if (mapped.length > 0) {
+                    acc[key] = mapped;
+                }
+                return acc;
+            }
+            if (typeof mapped !== 'undefined') {
+                acc[key] = mapped;
+            }
+            return acc;
+        }
+        if (key === 'fullDocument') {
+            if (!isPlainRecord(current))
+                return acc;
+            const mapped = (0, exports.mapWatchFilterToDocumentQuery)(current);
+            if (isRecord(mapped)) {
+                Object.assign(acc, mapped);
+            }
+            return acc;
+        }
+        if (key.startsWith('fullDocument.')) {
+            const docKey = key.slice('fullDocument.'.length);
+            if (!docKey)
+                return acc;
+            acc[docKey] = (0, exports.mapWatchFilterToDocumentQuery)(current);
+            return acc;
+        }
+        if (isChangeEventPath(key)) {
+            return acc;
+        }
+        acc[key] = (0, exports.mapWatchFilterToDocumentQuery)(current);
+        return acc;
+    }, {});
+};
+exports.mapWatchFilterToDocumentQuery = mapWatchFilterToDocumentQuery;
+const toStableValue = (value) => {
+    if (Array.isArray(value)) {
+        return value.map((item) => toStableValue(item));
+    }
+    if (!isPlainRecord(value))
+        return value;
+    const sortedEntries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+    return sortedEntries.reduce((acc, [key, current]) => {
+        acc[key] = toStableValue(current);
+        return acc;
+    }, {});
+};
+const stableSerialize = (value) => {
+    const serialized = bson_1.EJSON.serialize(value, { relaxed: false });
+    return JSON.stringify(toStableValue(serialized));
+};
+const getWatchPermissionContext = (user) => ({
+    role: user.role,
+    roles: user.roles,
+    data: user.data,
+    custom_data: user.custom_data,
+    user_data: user.user_data
+});
+const resolveWatchStream = (database, collection, watchArgs, user) => {
+    const keys = Object.keys(watchArgs);
+    const hasOnlyAllowedKeys = keys.every((key) => key === 'filter' || key === 'ids');
+    if (!hasOnlyAllowedKeys) {
+        throw new Error('watch options support only "filter" or "ids"');
+    }
+    const extraFilter = parseWatchFilter(watchArgs);
+    const ids = watchArgs.ids;
+    if (extraFilter && typeof ids !== 'undefined') {
+        throw new Error('watch options cannot include both "ids" and "filter"');
+    }
+    const pipeline = [];
+    if (extraFilter) {
+        pipeline.push({ $match: (0, exports.mapWatchFilterToChangeStreamMatch)(extraFilter) });
+    }
+    if (typeof ids !== 'undefined') {
+        if (!Array.isArray(ids)) {
+            throw new Error('watch ids must be an array');
+        }
+        pipeline.push({
+            $match: {
+                $or: [
+                    { 'documentKey._id': { $in: ids } },
+                    { 'fullDocument._id': { $in: ids } }
+                ]
+            }
+        });
+    }
+    const options = { fullDocument: 'updateLookup' };
+    const streamKey = stableSerialize({
+        database,
+        collection,
+        pipeline,
+        options,
+        permissionContext: getWatchPermissionContext(user)
+    });
+    return { extraFilter, options, pipeline, streamKey };
+};
+const getWatchStats = () => {
+    let subscribers = 0;
+    for (const hub of sharedWatchStreams.values()) {
+        subscribers += hub.subscribers.size;
+    }
+    return {
+        hubs: sharedWatchStreams.size,
+        subscribers
+    };
+};
+const logWatchStats = (event, details) => {
+    if (!debugWatchStreams)
+        return;
+    const stats = getWatchStats();
+    console.log('[watch-pool]', event, Object.assign({ hubs: stats.hubs, subscribers: stats.subscribers }, details));
+};
 const parseWatchFilter = (args) => {
-    var _a;
     if (!isRecord(args))
         return undefined;
-    const candidate = (_a = (isRecord(args.filter) ? args.filter : undefined)) !== null && _a !== void 0 ? _a : (isRecord(args.query) ? args.query : undefined);
-    return candidate ? candidate : undefined;
+    const candidate = isRecord(args.filter) ? args.filter : undefined;
+    if (!candidate)
+        return undefined;
+    if ('$match' in candidate) {
+        throw new Error('watch filter must be a query object, not a $match stage');
+    }
+    return candidate;
 };
 const isReadableDocumentResult = (value) => !!value &&
     typeof value === 'object' &&
@@ -176,7 +357,8 @@ const functionsController = (app_1, _a) => __awaiter(void 0, [app_1, _a], void 0
         const { baas_request, stitch_request } = query;
         const decodedConfig = JSON.parse(Buffer.from(baas_request || stitch_request || '', 'base64').toString('utf8'));
         const config = bson_1.EJSON.deserialize(decodedConfig);
-        const [_a] = config.arguments, { database, collection } = _a, watchArgs = __rest(_a, ["database", "collection"]);
+        const [_a] = config.arguments, { database, collection } = _a, watchArgsInput = __rest(_a, ["database", "collection"]);
+        const watchArgs = isRecord(watchArgsInput) ? watchArgsInput : {};
         const headers = {
             'Content-Type': 'text/event-stream',
             'Cache-Control': 'no-cache',
@@ -185,17 +367,27 @@ const functionsController = (app_1, _a) => __awaiter(void 0, [app_1, _a], void 0
             "access-control-allow-origin": '*',
             "access-control-allow-headers": "X-Stitch-Location, X-Baas-Location, Location",
         };
-        res.raw.writeHead(200, headers);
-        res.raw.flushHeaders();
-        const streamKey = `${database}::${collection}`;
         const subscriberId = `${Date.now()}-${watchSubscriberCounter++}`;
-        const extraFilter = parseWatchFilter(watchArgs);
-        const mongoClient = app.mongo.client;
+        const { streamKey, extraFilter, options: watchOptions, pipeline: watchPipeline } = resolveWatchStream(database, collection, watchArgs, user);
         let hub = sharedWatchStreams.get(streamKey);
         if (!hub) {
-            const stream = mongoClient.db(database).collection(collection).watch([], {
-                fullDocument: 'whenAvailable'
-            });
+            if (sharedWatchStreams.size >= maxSharedWatchStreams) {
+                res.status(503);
+                return JSON.stringify({
+                    error: JSON.stringify({
+                        message: 'Watch stream limit reached',
+                        name: 'WatchStreamLimitError'
+                    }),
+                    error_code: 'WatchStreamLimitError'
+                });
+            }
+            const stream = services_1.services['mongodb-atlas'](app, {
+                user,
+                rules
+            })
+                .db(database)
+                .collection(collection)
+                .watch(watchPipeline, watchOptions);
             hub = {
                 database,
                 collection,
@@ -203,7 +395,13 @@ const functionsController = (app_1, _a) => __awaiter(void 0, [app_1, _a], void 0
                 subscribers: new Map()
             };
             sharedWatchStreams.set(streamKey, hub);
+            logWatchStats('hub-created', { streamKey, database, collection });
+        }
+        else {
+            logWatchStats('hub-reused', { streamKey, database, collection });
         }
+        res.raw.writeHead(200, headers);
+        res.raw.flushHeaders();
         const ensureHubListeners = (currentHub) => {
             if (currentHub.listenersBound) {
                 return;
@@ -212,6 +410,7 @@ const functionsController = (app_1, _a) => __awaiter(void 0, [app_1, _a], void 0
                 currentHub.stream.off('change', onHubChange);
                 currentHub.stream.off('error', onHubError);
                 sharedWatchStreams.delete(streamKey);
+                logWatchStats('hub-closed', { streamKey, database, collection });
                 try {
                     yield currentHub.stream.close();
                 }
@@ -226,13 +425,14 @@ const functionsController = (app_1, _a) => __awaiter(void 0, [app_1, _a], void 0
                     const subscriberRes = subscriber.response;
                     if (subscriberRes.writableEnded || subscriberRes.destroyed) {
                         currentHub.subscribers.delete(subscriber.id);
+                        logWatchStats('subscriber-auto-removed', { streamKey, subscriberId: subscriber.id });
                         return;
                     }
                     const docId = (_b = (_a = change === null || change === void 0 ? void 0 : change.documentKey) === null || _a === void 0 ? void 0 : _a._id) !== null && _b !== void 0 ? _b : (_c = change === null || change === void 0 ? void 0 : change.fullDocument) === null || _c === void 0 ? void 0 : _c._id;
                     if (typeof docId === 'undefined')
                         return;
-                    const readQuery = subscriber.extraFilter
-                        ? { $and: [subscriber.extraFilter, { _id: docId }] }
+                    const readQuery = subscriber.documentFilter
+                        ? { $and: [subscriber.documentFilter, { _id: docId }] }
                         : { _id: docId };
                     try {
                         const readableDoc = yield services_1.services['mongodb-atlas'](app, {
@@ -250,6 +450,7 @@ const functionsController = (app_1, _a) => __awaiter(void 0, [app_1, _a], void 0
                         subscriberRes.write(`event: error\ndata: ${formatFunctionExecutionError(error)}\n\n`);
                         subscriberRes.end();
                         currentHub.subscribers.delete(subscriber.id);
+                        logWatchStats('subscriber-error-removed', { streamKey, subscriberId: subscriber.id });
                     }
                 })));
                 if (!currentHub.subscribers.size) {
@@ -276,17 +477,27 @@ const functionsController = (app_1, _a) => __awaiter(void 0, [app_1, _a], void 0
             id: subscriberId,
             user,
             response: res.raw,
-            extraFilter
+            documentFilter: (() => {
+                if (!extraFilter)
+                    return undefined;
+                const mapped = (0, exports.mapWatchFilterToDocumentQuery)(extraFilter);
+                if (!isRecord(mapped) || Object.keys(mapped).length === 0)
+                    return undefined;
+                return mapped;
+            })()
         };
         hub.subscribers.set(subscriberId, subscriber);
+        logWatchStats('subscriber-added', { streamKey, subscriberId });
         req.raw.on('close', () => {
             const currentHub = sharedWatchStreams.get(streamKey);
             if (!currentHub)
                 return;
             currentHub.subscribers.delete(subscriberId);
+            logWatchStats('subscriber-closed', { streamKey, subscriberId });
             if (!currentHub.subscribers.size) {
                 void currentHub.stream.close();
                 sharedWatchStreams.delete(streamKey);
+                logWatchStats('hub-empty-closed', { streamKey });
             }
         });
     }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowerforce/flowerbase",
-  "version": "1.7.5-beta.3",
+  "version": "1.7.5-beta.5",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/features/functions/__tests__/watch-filter.test.ts

@@ -0,0 +1,116 @@
+import { ObjectId } from 'mongodb'
+import { mapWatchFilterToChangeStreamMatch, mapWatchFilterToDocumentQuery } from '../controller'
+
+describe('watch filter mapping', () => {
+  it('keeps change-event fields untouched and prefixes only document fields', () => {
+    const input = {
+      accountId: '699efbc09729e3b79f79e9b4',
+      $and: [
+        {
+          $or: [
+            { requestId: '69a282a75cd849c244e001ca' },
+            { 'fullDocument.requestId': '69a282a75cd849c244e001ca' }
+          ]
+        },
+        {
+          $or: [
+            { operationType: 'insert' },
+            { operationType: 'replace' },
+            {
+              operationType: 'update',
+              'updateDescription.updatedFields.stage': { $exists: true }
+            }
+          ]
+        }
+      ]
+    }
+
+    const output = mapWatchFilterToChangeStreamMatch(input)
+
+    expect(output).toEqual({
+      'fullDocument.accountId': '699efbc09729e3b79f79e9b4',
+      $and: [
+        {
+          $or: [
+            { 'fullDocument.requestId': '69a282a75cd849c244e001ca' },
+            { 'fullDocument.requestId': '69a282a75cd849c244e001ca' }
+          ]
+        },
+        {
+          $or: [
+            { operationType: 'insert' },
+            { operationType: 'replace' },
+            {
+              operationType: 'update',
+              'updateDescription.updatedFields.stage': { $exists: true }
+            }
+          ]
+        }
+      ]
+    })
+
+    const outputJson = JSON.stringify(output)
+    expect(outputJson).not.toContain('fullDocument.fullDocument.')
+    expect(outputJson).not.toContain('fullDocument.operationType')
+  })
+
+  it('supports stage-change filters and strips event-only clauses for document readability checks', () => {
+    const input = {
+      'fullDocument.accountId': '699efbc09729e3b79f79e9b4',
+      $and: [
+        {
+          $or: [
+            { 'fullDocument.requestId': '69a282a75cd849c244e001ca' },
+            { 'fullDocument.requestId': '69a282a75cd849c244e001ca' }
+          ]
+        },
+        {
+          $or: [
+            { operationType: 'insert' },
+            { operationType: 'replace' },
+            {
+              operationType: 'update',
+              'updateDescription.updatedFields.stage': { $exists: true }
+            }
+          ]
+        }
+      ]
+    }
+
+    const watchMatch = mapWatchFilterToChangeStreamMatch(input)
+    expect(watchMatch).toEqual(input)
+
+    const documentQuery = mapWatchFilterToDocumentQuery(input)
+    expect(documentQuery).toEqual({
+      accountId: '699efbc09729e3b79f79e9b4',
+      $and: [
+        {
+          $or: [
+            { requestId: '69a282a75cd849c244e001ca' },
+            { requestId: '69a282a75cd849c244e001ca' }
+          ]
+        }
+      ]
+    })
+
+    const documentQueryJson = JSON.stringify(documentQuery)
+    expect(documentQueryJson).not.toContain('operationType')
+    expect(documentQueryJson).not.toContain('updateDescription')
+  })
+
+  it('preserves ObjectId values in both change-stream and document mappings', () => {
+    const id = new ObjectId('69a282a75cd849c244e001ca')
+    const input = {
+      'fullDocument._id': id,
+      operationType: 'update',
+      'updateDescription.updatedFields.stage': { $exists: true }
+    }
+
+    const watchMatch = mapWatchFilterToChangeStreamMatch(input) as Record<string, unknown>
+    expect(watchMatch['fullDocument._id']).toEqual(id)
+
+    const documentQuery = mapWatchFilterToDocumentQuery(input) as Record<string, unknown>
+    expect(documentQuery._id).toEqual(id)
+    expect(documentQuery.operationType).toBeUndefined()
+  })
+})

package/src/features/functions/controller.ts

@@ -54,6 +54,12 @@ const serializeEjson = (value: unknown) =>
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   !!value && typeof value === 'object' && !Array.isArray(value)
 
+const isPlainRecord = (value: unknown): value is Record<string, unknown> => {
+  if (!isRecord(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
 const isCursorLike = (
   value: unknown
 ): value is { toArray: () => Promise<unknown> | unknown } => {
@@ -70,7 +76,7 @@ type WatchSubscriber = {
   id: string
   user: Record<string, any>
   response: ServerResponse
-  extraFilter?: Document
+  documentFilter?: Document
 }
 
 type SharedWatchStream = {
@@ -86,13 +92,221 @@ type SharedWatchStream = {
 
 const sharedWatchStreams = new Map<string, SharedWatchStream>()
 let watchSubscriberCounter = 0
+const maxSharedWatchStreams = Number(process.env.MAX_SHARED_WATCH_STREAMS || 200)
+const debugWatchStreams = process.env.DEBUG_FUNCTIONS === 'true'
+
+const changeEventRootKeys = new Set([
+  '_id',
+  'operationType',
+  'clusterTime',
+  'txnNumber',
+  'lsid',
+  'ns',
+  'documentKey',
+  'fullDocument',
+  'updateDescription'
+])
+
+const isChangeEventPath = (key: string) => {
+  if (changeEventRootKeys.has(key)) return true
+  return (
+    key.startsWith('ns.') ||
+    key.startsWith('documentKey.') ||
+    key.startsWith('fullDocument.') ||
+    key.startsWith('updateDescription.')
+  )
+}
+
+const isOpaqueChangeEventObjectKey = (key: string) =>
+  key === 'ns' || key === 'documentKey' || key === 'fullDocument' || key === 'updateDescription'
+
+export const mapWatchFilterToChangeStreamMatch = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map((item) => mapWatchFilterToChangeStreamMatch(item))
+  }
+
+  if (!isPlainRecord(value)) return value
+
+  return Object.entries(value).reduce<Record<string, unknown>>((acc, [key, current]) => {
+    if (key.startsWith('$')) {
+      acc[key] = mapWatchFilterToChangeStreamMatch(current)
+      return acc
+    }
+
+    if (isOpaqueChangeEventObjectKey(key)) {
+      acc[key] = current
+      return acc
+    }
+
+    if (isChangeEventPath(key)) {
+      acc[key] = mapWatchFilterToChangeStreamMatch(current)
+      return acc
+    }
+
+    acc[`fullDocument.${key}`] = mapWatchFilterToChangeStreamMatch(current)
+    return acc
+  }, {})
+}
+
+const isLogicalOperator = (key: string) => key === '$and' || key === '$or' || key === '$nor'
+
+export const mapWatchFilterToDocumentQuery = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    const mapped = value
+      .map((item) => mapWatchFilterToDocumentQuery(item))
+      .filter((item) => !(isRecord(item) && Object.keys(item).length === 0))
+    return mapped
+  }
+
+  if (!isPlainRecord(value)) return value
+
+  return Object.entries(value).reduce<Record<string, unknown>>((acc, [key, current]) => {
+    if (key.startsWith('$')) {
+      const mapped = mapWatchFilterToDocumentQuery(current)
+      if (isLogicalOperator(key) && Array.isArray(mapped)) {
+        if (mapped.length > 0) {
+          acc[key] = mapped
+        }
+        return acc
+      }
+      if (typeof mapped !== 'undefined') {
+        acc[key] = mapped
+      }
+      return acc
+    }
+
+    if (key === 'fullDocument') {
+      if (!isPlainRecord(current)) return acc
+      const mapped = mapWatchFilterToDocumentQuery(current)
+      if (isRecord(mapped)) {
+        Object.assign(acc, mapped)
+      }
+      return acc
+    }
+
+    if (key.startsWith('fullDocument.')) {
+      const docKey = key.slice('fullDocument.'.length)
+      if (!docKey) return acc
+      acc[docKey] = mapWatchFilterToDocumentQuery(current)
+      return acc
+    }
+
+    if (isChangeEventPath(key)) {
+      return acc
+    }
+
+    acc[key] = mapWatchFilterToDocumentQuery(current)
+    return acc
+  }, {})
+}
+
+const toStableValue = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map((item) => toStableValue(item))
+  }
+  if (!isPlainRecord(value)) return value
+
+  const sortedEntries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right))
+  return sortedEntries.reduce<Record<string, unknown>>((acc, [key, current]) => {
+    acc[key] = toStableValue(current)
+    return acc
+  }, {})
+}
+
+const stableSerialize = (value: unknown) => {
+  const serialized = EJSON.serialize(value, { relaxed: false })
+  return JSON.stringify(toStableValue(serialized))
+}
+
+const getWatchPermissionContext = (user: Record<string, any>) => ({
+  role: user.role,
+  roles: user.roles,
+  data: user.data,
+  custom_data: user.custom_data,
+  user_data: user.user_data
+})
+
+const resolveWatchStream = (
+  database: string,
+  collection: string,
+  watchArgs: Record<string, unknown>,
+  user: Record<string, any>
+) => {
+  const keys = Object.keys(watchArgs)
+  const hasOnlyAllowedKeys = keys.every((key) => key === 'filter' || key === 'ids')
+  if (!hasOnlyAllowedKeys) {
+    throw new Error('watch options support only "filter" or "ids"')
+  }
+
+  const extraFilter = parseWatchFilter(watchArgs)
+  const ids = watchArgs.ids
+  if (extraFilter && typeof ids !== 'undefined') {
+    throw new Error('watch options cannot include both "ids" and "filter"')
+  }
+
+  const pipeline: Document[] = []
+  if (extraFilter) {
+    pipeline.push({ $match: mapWatchFilterToChangeStreamMatch(extraFilter) as Document })
+  }
+
+  if (typeof ids !== 'undefined') {
+    if (!Array.isArray(ids)) {
+      throw new Error('watch ids must be an array')
+    }
+    pipeline.push({
+      $match: {
+        $or: [
+          { 'documentKey._id': { $in: ids } },
+          { 'fullDocument._id': { $in: ids } }
+        ]
+      }
+    })
+  }
+
+  const options = { fullDocument: 'updateLookup' }
+  const streamKey = stableSerialize({
+    database,
+    collection,
+    pipeline,
+    options,
+    permissionContext: getWatchPermissionContext(user)
+  })
+
+  return { extraFilter, options, pipeline, streamKey }
+}
+
+const getWatchStats = () => {
+  let subscribers = 0
+  for (const hub of sharedWatchStreams.values()) {
+    subscribers += hub.subscribers.size
+  }
+  return {
+    hubs: sharedWatchStreams.size,
+    subscribers
+  }
+}
+
+const logWatchStats = (
+  event: string,
+  details?: Record<string, unknown>
+) => {
+  if (!debugWatchStreams) return
+  const stats = getWatchStats()
+  console.log('[watch-pool]', event, {
+    hubs: stats.hubs,
+    subscribers: stats.subscribers,
+    ...details
+  })
+}
 
 const parseWatchFilter = (args: unknown): Document | undefined => {
   if (!isRecord(args)) return undefined
-  const candidate =
-    (isRecord(args.filter) ? args.filter : undefined) ??
-    (isRecord(args.query) ? args.query : undefined)
-  return candidate ? (candidate as Document) : undefined
+  const candidate = isRecord(args.filter) ? args.filter : undefined
+  if (!candidate) return undefined
+  if ('$match' in candidate) {
+    throw new Error('watch filter must be a query object, not a $match stage')
+  }
+  return candidate as Document
 }
 
 const isReadableDocumentResult = (value: unknown) =>
@@ -224,7 +438,8 @@ export const functionsController: FunctionController = async (
     )
     const config = EJSON.deserialize(decodedConfig) as Base64Function
 
-    const [{ database, collection, ...watchArgs }] = config.arguments
+    const [{ database, collection, ...watchArgsInput }] = config.arguments
+    const watchArgs = isRecord(watchArgsInput) ? watchArgsInput : {}
 
     const headers = {
       'Content-Type': 'text/event-stream',
@@ -235,21 +450,33 @@ export const functionsController: FunctionController = async (
       "access-control-allow-headers": "X-Stitch-Location, X-Baas-Location, Location",
     };
 
-    res.raw.writeHead(200, headers)
-    res.raw.flushHeaders();
-
-    const streamKey = `${database}::${collection}`
     const subscriberId = `${Date.now()}-${watchSubscriberCounter++}`
-    const extraFilter = parseWatchFilter(watchArgs)
-    const mongoClient = app.mongo.client as unknown as {
-      db: (name: string) => { collection: (name: string) => { watch: (...args: any[]) => any } }
-    }
+    const {
+      streamKey,
+      extraFilter,
+      options: watchOptions,
+      pipeline: watchPipeline
+    } = resolveWatchStream(database, collection, watchArgs, user)
 
     let hub = sharedWatchStreams.get(streamKey)
     if (!hub) {
-      const stream = mongoClient.db(database).collection(collection).watch([], {
-        fullDocument: 'whenAvailable'
+      if (sharedWatchStreams.size >= maxSharedWatchStreams) {
+        res.status(503)
+        return JSON.stringify({
+          error: JSON.stringify({
+            message: 'Watch stream limit reached',
+            name: 'WatchStreamLimitError'
+          }),
+          error_code: 'WatchStreamLimitError'
+        })
+      }
+      const stream = services['mongodb-atlas'](app, {
+        user,
+        rules
       })
+        .db(database)
+        .collection(collection)
+        .watch(watchPipeline, watchOptions)
       hub = {
         database,
         collection,
@@ -257,8 +484,14 @@ export const functionsController: FunctionController = async (
         subscribers: new Map<string, WatchSubscriber>()
       }
       sharedWatchStreams.set(streamKey, hub)
+      logWatchStats('hub-created', { streamKey, database, collection })
+    } else {
+      logWatchStats('hub-reused', { streamKey, database, collection })
     }
 
+    res.raw.writeHead(200, headers)
+    res.raw.flushHeaders();
+
     const ensureHubListeners = (currentHub: SharedWatchStream) => {
       if ((currentHub as SharedWatchStream & { listenersBound?: boolean }).listenersBound) {
         return
@@ -268,6 +501,7 @@ export const functionsController: FunctionController = async (
         currentHub.stream.off('change', onHubChange)
         currentHub.stream.off('error', onHubError)
         sharedWatchStreams.delete(streamKey)
+        logWatchStats('hub-closed', { streamKey, database, collection })
         try {
           await currentHub.stream.close()
         } catch {
@@ -281,6 +515,7 @@ export const functionsController: FunctionController = async (
           const subscriberRes = subscriber.response
           if (subscriberRes.writableEnded || subscriberRes.destroyed) {
             currentHub.subscribers.delete(subscriber.id)
+            logWatchStats('subscriber-auto-removed', { streamKey, subscriberId: subscriber.id })
             return
           }
 
@@ -289,8 +524,8 @@ export const functionsController: FunctionController = async (
             (change as { fullDocument?: { _id?: unknown } })?.fullDocument?._id
           if (typeof docId === 'undefined') return
 
-          const readQuery = subscriber.extraFilter
-            ? ({ $and: [subscriber.extraFilter, { _id: docId }] } as Document)
+          const readQuery = subscriber.documentFilter
+            ? ({ $and: [subscriber.documentFilter, { _id: docId }] } as Document)
             : ({ _id: docId } as Document)
 
           try {
@@ -308,6 +543,7 @@ export const functionsController: FunctionController = async (
             subscriberRes.write(`event: error\ndata: ${formatFunctionExecutionError(error)}\n\n`)
             subscriberRes.end()
             currentHub.subscribers.delete(subscriber.id)
+            logWatchStats('subscriber-error-removed', { streamKey, subscriberId: subscriber.id })
           }
         }))
 
@@ -339,17 +575,25 @@ export const functionsController: FunctionController = async (
       id: subscriberId,
       user,
       response: res.raw,
-      extraFilter
+      documentFilter: (() => {
+        if (!extraFilter) return undefined
+        const mapped = mapWatchFilterToDocumentQuery(extraFilter)
+        if (!isRecord(mapped) || Object.keys(mapped).length === 0) return undefined
+        return mapped as Document
+      })()
     }
     hub.subscribers.set(subscriberId, subscriber)
+    logWatchStats('subscriber-added', { streamKey, subscriberId })
 
     req.raw.on('close', () => {
       const currentHub = sharedWatchStreams.get(streamKey)
       if (!currentHub) return
       currentHub.subscribers.delete(subscriberId)
+      logWatchStats('subscriber-closed', { streamKey, subscriberId })
       if (!currentHub.subscribers.size) {
         void currentHub.stream.close()
         sharedWatchStreams.delete(streamKey)
+        logWatchStats('hub-empty-closed', { streamKey })
       }
     })
   })