fix(api-search): ZMS-94: keep $text queries plannable inside OR branches

MongoDB resolves $text through the compound `fulltext` index, which is prefixed
with `user`, so a $text clause nested in an $or needs its own equality on
`user`, and every sibling branch of that $or has to be index backed. Neither
held, so any search mixing a header keyword with a fulltext term under OR
returned a 500.

applyTextIndexPrefix stamps the user id onto every branch of every $or that
wraps a $text clause. The filter already requires `user` at the top level, so
the repeated equality does not change what it matches. Both filter builders
call it, so the or.* API params are covered as well, not only the q syntax.

MongoDB also accepts a single $text expression per query, and the builder
emitted two whenever text terms landed in different OR branches. Terms that
cannot claim the one slot now fall back to the regex matching quoted phrases
already use, keeping AND semantics for a merged AND term and keeping negated
terms excluding rather than widening the match.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0179oqSvLfdTeNBTsSPVmp4m

Author: andris9

lib/prepare-search-filter.js

@@ -12,6 +12,51 @@ const toMongoAndTextSearch = value =>
         .map(term => `"${term.replace(/(["\\])/g, '\\$1')}"`)
         .join(' ');
 
+// MongoDB rejects $text inside $not and $nor, so an $and or an $or branch list are the
+// only places a nested $text clause can show up.
+const TEXT_QUERY_BRANCHES = ['$and', '$or'];
+
+// MongoDB resolves a $text expression through the compound `fulltext` index, which is
+// prefixed with `user`, so the branch holding $text must also match on `user`. On top of
+// that MongoDB only plans an $or holding a $text clause when every branch of that $or is
+// index backed. Stamping the user id on each branch of every $or that wraps the $text
+// clause satisfies both rules. The filter always requires `user` at the top level, so the
+// repeated equality never changes what the filter matches.
+// Returns true when the subtree holds a $text clause.
+const applyTextIndexPrefix = (filter, user) => {
+    if (!filter || typeof filter !== 'object') {
+        return false;
+    }
+
+    if (Array.isArray(filter)) {
+        let branchWithTextQuery = false;
+        for (let branch of filter) {
+            if (applyTextIndexPrefix(branch, user)) {
+                branchWithTextQuery = true;
+            }
+        }
+        return branchWithTextQuery;
+    }
+
+    let hasTextQuery = filter.$text !== undefined;
+
+    for (let key of TEXT_QUERY_BRANCHES) {
+        if (filter[key] === undefined || !applyTextIndexPrefix(filter[key], user)) {
+            continue;
+        }
+
+        hasTextQuery = true;
+
+        if (key === '$or') {
+            for (let branch of filter.$or) {
+                branch.user = user;
+            }
+        }
+    }
+
+    return hasTextQuery;
+};
+
 const SEARCHABLE_MAILBOX_SPECIAL_USE = ['\\Junk', '\\Trash'];
 const SEARCHABLE_MAILBOX_IN_THRESHOLD = 200;
 
@@ -356,7 +401,9 @@ const prepareSearchFilter = async (db, user, payload) => {
         filter.$or = orQuery;
     }
 
+    applyTextIndexPrefix(filter, user);
+
     return { filter, query };
 };
 
-module.exports = { uidRangeStringToQuery, prepareSearchFilter, toMongoAndTextSearch, getSearchableMailboxQuery };
+module.exports = { uidRangeStringToQuery, prepareSearchFilter, toMongoAndTextSearch, getSearchableMailboxQuery, applyTextIndexPrefix };

lib/search-query.js

@@ -3,7 +3,7 @@
 const SearchString = require('search-string').default;
 const parser = require('logic-query-parser');
 const { escapeRegexStr } = require('./tools');
-const { uidRangeStringToQuery, toMongoAndTextSearch, getSearchableMailboxQuery } = require('./prepare-search-filter');
+const { uidRangeStringToQuery, toMongoAndTextSearch, getSearchableMailboxQuery, applyTextIndexPrefix } = require('./prepare-search-filter');
 const { ObjectId } = require('mongodb');
 
 const getBooleanValue = value => {
@@ -43,17 +43,15 @@ const getDateValue = value => {
     return isNaN(date.getTime()) ? false : date;
 };
 
-const createMongoTextQuery = (user, searchValue) => ({
-    // Keep the compound text index prefix in the same logical branch as $text.
-    // MongoDB does not propagate the top-level predicate into a nested $or
-    // branch when selecting the text index.
-    user,
+const createMongoTextQuery = searchValue => ({
     $text: {
         $search: searchValue
     }
 });
 
-const formatTextSearchValue = (value, opts = {}) => (opts.useAndSearch === true && opts.mode !== 'or' ? toMongoAndTextSearch(value) : value);
+const isAndSearch = (opts = {}) => opts.useAndSearch === true && opts.mode !== 'or';
+
+const formatTextSearchValue = (value, opts = {}) => (isAndSearch(opts) ? toMongoAndTextSearch(value) : value);
 
 const createPhraseRegexClauses = value => {
     const regex = escapeRegexStr(value).replace(/\s+/g, '\\s+');
@@ -290,22 +288,47 @@ const getMongoDBQuery = async (db, user, queryStr, opts = {}) => {
         const searchValue = getTextSearchValue(entry);
         return {
             ...entry,
-            query: createMongoTextQuery(user, searchValue)
+            query: createMongoTextQuery(searchValue)
         };
     };
     const isTextEntry = entry => !!entry?.isTextQuery;
-    const unwrapQueryEntry = entry => (isTextEntry(entry) ? entry.query : entry);
     const createTextRegexQuery = entry => createPhraseQuery(entry.textValue, entry.negated);
-    const createRawTextRegexQuery = entry => ({ $or: entry.entries.map(createTextRegexQuery) });
+    const createRawTextRegexQuery = entry => {
+        const included = entry.entries.filter(item => !item.negated).map(createTextRegexQuery);
+        const excluded = entry.entries.filter(item => item.negated).map(createTextRegexQuery);
+        // $text applies negated terms as exclusions, so those stay ANDed even when the
+        // remaining terms are ORed
+        const clauses = (entry.andSearch || included.length < 2 ? included : [{ $or: included }]).concat(excluded);
+
+        return clauses.length === 1 ? clauses[0] : { $and: clauses };
+    };
+    // MongoDB allows a single $text expression per query. The first text term the walk
+    // reaches claims it, the ones that can not be merged into it, eg. because they sit in
+    // a different OR branch, fall back to the same regex matching quoted phrases use.
+    let textQueryUsed = false;
+    const unwrapQueryEntry = entry => {
+        if (!isTextEntry(entry)) {
+            return entry;
+        }
+
+        if (textQueryUsed) {
+            return entry.rawSearch ? createRawTextRegexQuery(entry) : createTextRegexQuery(entry);
+        }
+
+        textQueryUsed = true;
+        return entry.query;
+    };
     const mergeTextEntries = (entries, queryOpts = opts) => {
         const searchValue = entries.map(entry => getTextSearchValue(entry, queryOpts)).join(' ');
         return {
             isTextQuery: true,
             textValue: searchValue,
             negated: false,
             rawSearch: true,
+            // remember how the merged terms are combined, the regex fallback has to match it
+            andSearch: isAndSearch(queryOpts),
             entries,
-            query: createMongoTextQuery(user, searchValue)
+            query: createMongoTextQuery(searchValue)
         };
     };
 
@@ -352,10 +375,7 @@ const getMongoDBQuery = async (db, user, queryStr, opts = {}) => {
                     let directTextTerms = textTerms.filter(entry => !entry.rawSearch);
 
                     if (rawTextTerms.length) {
-                        branch.$and = [unwrapQueryEntry(rawTextTerms.shift())]
-                            .concat(rawTextTerms.map(createRawTextRegexQuery))
-                            .concat(directTextTerms.map(createTextRegexQuery))
-                            .concat(nonTextTerms);
+                        branch.$and = rawTextTerms.concat(directTextTerms).map(unwrapQueryEntry).concat(nonTextTerms);
                     } else {
                         branch.$and = [unwrapQueryEntry(mergeTextEntries(textTerms))].concat(nonTextTerms);
                     }
@@ -745,6 +765,8 @@ const getMongoDBQuery = async (db, user, queryStr, opts = {}) => {
             extras.searchable = true;
         }
 
+        applyTextIndexPrefix(filter, user);
+
         return { user: null, ...filter, ...extras };
     }