@jasonwch/nodebb-plugin-meilisearch-r 1.1.2 → 1.2.1

package/lib/reindex.js

@@ -0,0 +1,311 @@
+'use strict';
+
+const _ = nodebb.require('lodash');
+const winston = nodebb.require('winston');
+const db = nodebb.require('./src/database');
+const batch = nodebb.require('./src/batch');
+const Posts = nodebb.require('./src/posts');
+const Topics = nodebb.require('./src/topics');
+const Messaging = nodebb.require('./src/messaging');
+const pubsub = nodebb.require('./src/pubsub');
+const settings = nodebb.require('./src/meta/settings');
+const {
+	REINDEX_BATCH_SIZE, REINDEX_LOCK_KEY, REINDEX_LOCK_TTL, LOCK_REFRESH_INTERVAL, REPLAY_OPS,
+} = require('./constants');
+const { isSemanticSearchEnabled } = require('./embedder');
+const { waitForSucceededTask } = require('./client');
+
+// Full reindex of posts, topics, and chat messages, guarded by a cross-instance lock.
+module.exports = function attachReindex(plugin) {
+	const emitProgress = _.throttle(() => {
+		pubsub.publish('meilisearch:reindex', plugin.indexing);
+	}, 500, { leading: true, trailing: true });
+
+	async function acquireReindexLock() {
+		const ttl = await db.ttl(REINDEX_LOCK_KEY);
+		if (ttl > 0) {
+			winston.warn('[plugin/meilisearch] Reindex lock held by another instance');
+			return false;
+		}
+		await db.set(REINDEX_LOCK_KEY, String(Date.now()));
+		await db.expire(REINDEX_LOCK_KEY, REINDEX_LOCK_TTL);
+		plugin.reindexLockRefresh = setInterval(() => {
+			db.expire(REINDEX_LOCK_KEY, REINDEX_LOCK_TTL).catch(err =>
+				winston.error(`[plugin/meilisearch] lock refresh failed: ${err.message}`));
+		}, LOCK_REFRESH_INTERVAL);
+		return true;
+	}
+
+	async function releaseReindexLock() {
+		if (plugin.reindexLockRefresh) {
+			clearInterval(plugin.reindexLockRefresh);
+			plugin.reindexLockRefresh = null;
+		}
+		try {
+			await db.delete(REINDEX_LOCK_KEY);
+		} catch (err) {
+			winston.warn(`[plugin/meilisearch] Could not release reindex lock: ${err.message}`);
+		}
+	}
+
+	async function runReindex(force) {
+		let succeeded = false;
+		let errorMsg = null;
+		let skippedDeletedTopics = 0;
+		let skippedDeletedPosts = 0;
+		let skippedDeletedMessages = 0;
+		let skippedSystemMessages = 0;
+		let skippedOrphanMessages = 0;
+		const locked = await acquireReindexLock();
+		if (!locked) {
+			plugin.indexing.running = false;
+			return;
+		}
+		pubsub.publish('meilisearch:init', true);
+		plugin.initializingOnAnotherInstance = true;
+		try {
+			if (force) {
+				plugin.reindexingForced = true;
+				if (await isSemanticSearchEnabled(plugin)) {
+					// Every document added back after this will need a fresh embedding call
+					// against the configured (often paid) embedding API - there is no way
+					// around that once the documents themselves are gone, so surface it here.
+					winston.warn('[plugin/meilisearch] Force reindex with semantic search enabled: all vector embeddings will be regenerated from scratch via the embedding API.');
+				}
+				const postTask = await plugin.client.index('post').deleteAllDocuments();
+				const topicTask = await plugin.client.index('topic').deleteAllDocuments();
+				const messageTask = await plugin.client.index('chat_message').deleteAllDocuments();
+				await waitForSucceededTask(plugin, postTask.taskUid, { timeout: 600000, interval: 200 });
+				await waitForSucceededTask(plugin, topicTask.taskUid, { timeout: 600000, interval: 200 });
+				await waitForSucceededTask(plugin, messageTask.taskUid, { timeout: 600000, interval: 200 });
+			}
+			const [postSettingsTask, topicSettingsTask, messageSettingsTask] = await plugin.updateIndexSettings();
+			await waitForSucceededTask(plugin, postSettingsTask.taskUid, { timeout: 600000, interval: 200 });
+			await waitForSucceededTask(plugin, topicSettingsTask.taskUid, { timeout: 600000, interval: 200 });
+			await waitForSucceededTask(plugin, messageSettingsTask.taskUid, { timeout: 600000, interval: 200 });
+			// Explicit, deliberate part of a reindex run - ensures the embedder config
+			// matches current ACP settings before documents start flowing back in. Gated
+			// internally (plugin.updateEmbedders) so it's a no-op unless something about
+			// the semantic search config actually changed since it was last applied.
+			await plugin.updateEmbedders();
+			plugin.indexing.topic_progress.total = await db.sortedSetCard('topics:tid') || 0;
+			plugin.indexing.post_progress.total = await db.sortedSetCard('posts:pid') || 0;
+			plugin.indexing.message_progress.total = await db.sortedSetCard('messages:mid') || 0;
+			emitProgress();
+			await Promise.all([
+				batch.processSortedSet(
+					'topics:tid',
+					async (tids) => {
+						plugin.indexing.topic_progress.current += tids.length;
+						emitProgress();
+						const topics = await Topics.getTopicsFields(tids, ['tid', 'cid', 'uid', 'mainPid', 'title', 'timestamp', 'deleted']);
+						const activeTopics = [];
+						const deletedTids = [];
+						topics.forEach((topic) => {
+							if (parseInt(topic.deleted, 10) === 1) {
+								deletedTids.push(topic.tid);
+							} else {
+								activeTopics.push(topic);
+							}
+						});
+						skippedDeletedTopics += deletedTids.length;
+						if (deletedTids.length) {
+							await plugin.client.index('topic').deleteDocuments(deletedTids);
+						}
+						if (!activeTopics.length) return;
+						await plugin.client.index('topic').updateDocuments(
+							activeTopics.map(topic => ({
+								tid: topic.tid,
+								cid: topic.cid,
+								uid: topic.uid,
+								mainPid: topic.mainPid,
+								title: topic.title,
+								timestamp: topic.timestamp,
+							})),
+							{ primaryKey: 'tid' },
+						);
+					},
+					{
+						batch: REINDEX_BATCH_SIZE,
+						progress: plugin.indexing.topic_progress,
+					},
+				),
+				batch.processSortedSet(
+					'posts:pid',
+					async (pids) => {
+						plugin.indexing.post_progress.current += pids.length;
+						emitProgress();
+						const posts = await Posts.getPostsFields(pids, ['pid', 'tid', 'uid', 'content', 'timestamp', 'deleted']);
+						// Fetch topic deleted status for posts in this batch
+						const tids = [...new Set(posts.map(p => p && p.tid).filter(Boolean))];
+						const topicsData = tids.length ? await Topics.getTopicsFields(tids, ['tid', 'deleted']) : [];
+						const tidToDeleted = {};
+						topicsData.forEach((t) => { tidToDeleted[t.tid] = parseInt(t.deleted, 10) === 1; });
+
+						const activePosts = [];
+						const deletedPids = [];
+						posts.forEach((post) => {
+							if (parseInt(post.deleted, 10) === 1 || tidToDeleted[post.tid]) {
+								deletedPids.push(post.pid);
+							} else {
+								activePosts.push(post);
+							}
+						});
+						skippedDeletedPosts += deletedPids.length;
+						if (deletedPids.length) {
+							await plugin.client.index('post').deleteDocuments(deletedPids);
+						}
+						const activePids = activePosts.map(p => p.pid);
+						const cids = activePids.length ? await Posts.getCidsByPids(activePids) : [];
+						await plugin.client.index('post').updateDocuments(
+							activePosts.map((post, index) => ({
+								pid: post.pid,
+								tid: post.tid,
+								cid: cids[index],
+								uid: post.uid,
+								content: post.content,
+								timestamp: post.timestamp,
+							})),
+							{ primaryKey: 'pid' },
+						);
+					},
+					{
+						batch: REINDEX_BATCH_SIZE,
+						progress: plugin.indexing.post_progress,
+					},
+				),
+			]);
+			// Reindex chat messages SEQUENTIALLY after topics+posts (keeps Meilisearch enqueue rate bounded).
+			// Option B: cross-check each batch's roomIds against existing rooms and deindex orphan messages
+			// whose room was deleted via admin (messaging.deleteRooms fires no message hook and leaves
+			// message:${mid} objects + messages:mid entries, so they would otherwise be re-indexed as orphans).
+			await batch.processSortedSet(
+				'messages:mid',
+				async (mids) => {
+					plugin.indexing.message_progress.current += mids.length;
+					emitProgress();
+					const messages = await Messaging.getMessagesFields(mids, ['mid', 'content', 'roomId', 'fromuid', 'timestamp', 'deleted', 'system']);
+					// Resolve deleted/system messages and orphan rooms in one pass.
+					const seenRoomIds = [...new Set(messages.map(m => m && m.roomId).filter(rid => rid != null && rid !== ''))];
+					const roomsData = seenRoomIds.length ? await Messaging.getRoomsData(seenRoomIds) : [];
+					const roomIdToExists = {};
+					roomsData.forEach((room) => {
+						if (room && room.roomId != null) roomIdToExists[room.roomId] = true;
+					});
+					const activeMessages = [];
+					const deletedMids = [];
+					const systemMids = [];
+					const orphanMids = [];
+					messages.forEach((msg) => {
+						if (!msg || !msg.mid) return;
+						if (parseInt(msg.deleted, 10) === 1) {
+							deletedMids.push(msg.mid);
+						} else if (parseInt(msg.system, 10) === 1) {
+							systemMids.push(msg.mid);
+						} else if (!roomIdToExists[msg.roomId]) {
+							orphanMids.push(msg.mid);
+						} else {
+							activeMessages.push(msg);
+						}
+					});
+					skippedDeletedMessages += deletedMids.length;
+					skippedSystemMessages += systemMids.length;
+					skippedOrphanMessages += orphanMids.length;
+					const allDeindexMids = [...deletedMids, ...systemMids, ...orphanMids];
+					if (allDeindexMids.length) {
+						await plugin.client.index('chat_message').deleteDocuments(allDeindexMids);
+					}
+					if (!activeMessages.length) return;
+					await plugin.client.index('chat_message').updateDocuments(
+						activeMessages.map(msg => ({
+							mid: msg.mid,
+							roomId: msg.roomId,
+							uid: msg.fromuid,
+							content: msg.content,
+							timestamp: msg.timestamp,
+						})),
+						{ primaryKey: 'mid' },
+					);
+				},
+				{ batch: REINDEX_BATCH_SIZE, progress: plugin.indexing.message_progress },
+			);
+			succeeded = true;
+			winston.info('[plugin/meilisearch] Indexing of posts, topics and chat messages complete');
+		} catch (err) {
+			winston.error(`[plugin/meilisearch] Indexing failed: ${err.message}`);
+			errorMsg = err.message;
+		} finally {
+			plugin.indexing.running = false;
+			plugin.reindexingForced = false;
+			plugin.initializingOnAnotherInstance = false;
+			pubsub.publish('meilisearch:init', false);
+			await releaseReindexLock();
+			emitProgress.flush();
+			const pending = plugin.pendingDuringReindex.splice(0);
+			for (const { op, payload } of pending) {
+				if (!REPLAY_OPS.includes(op)) continue;
+				try {
+					await plugin[op](payload);
+				} catch (err) {
+					winston.error(`[plugin/meilisearch] replay ${op} failed: ${err.message}`);
+				}
+			}
+			const lastIndexResult = {
+				success: succeeded,
+				finishedAt: Date.now(),
+				topic_progress: {
+					current: plugin.indexing.topic_progress.current,
+					total: plugin.indexing.topic_progress.total,
+				},
+				post_progress: {
+					current: plugin.indexing.post_progress.current,
+					total: plugin.indexing.post_progress.total,
+				},
+				message_progress: {
+					current: plugin.indexing.message_progress.current,
+					total: plugin.indexing.message_progress.total,
+				},
+				skippedDeletedTopics,
+				skippedDeletedPosts,
+				skippedDeletedMessages,
+				skippedSystemMessages,
+				skippedOrphanMessages,
+				error: errorMsg,
+			};
+			try {
+				await settings.set(plugin.id, { lastReindexResult: lastIndexResult }, true);
+				if (succeeded) {
+					await settings.set(plugin.id, { indexed: true }, true);
+				}
+			} catch (err) {
+				winston.error(`[plugin/meilisearch] Failed to persist reindex result: ${err.message}`);
+			}
+		}
+	}
+
+	plugin.reindex = async function (force = false) {
+		if (plugin.indexing.running) {
+			winston.warn('[plugin/meilisearch] Already indexing');
+			return;
+		}
+		plugin.indexing = {
+			running: true,
+			topic_progress: {
+				current: 0,
+				total: 0,
+			},
+			post_progress: {
+				current: 0,
+				total: 0,
+			},
+			message_progress: {
+				current: 0,
+				total: 0,
+			},
+		};
+		emitProgress();
+		winston.info(`[plugin/meilisearch] Indexing posts, topics and chat messages${force ? ' (forced)' : ''}`);
+		plugin._reindexPromise = runReindex(force);
+		return plugin._reindexPromise;
+	};
+};

package/lib/routes.js

@@ -0,0 +1,129 @@
+'use strict';
+
+const winston = nodebb.require('winston');
+const routeHelpers = nodebb.require('./src/routes/helpers');
+const settings = nodebb.require('./src/meta/settings');
+
+// Plugin lifecycle + HTTP surface: static:app.load init, the reindex REST API,
+// the ACP nav entry, and the admin-notices health line.
+module.exports = function attachRoutes(plugin) {
+	plugin.init = async function (params) {
+		const { router } = params;
+		winston.debug('[plugin/meilisearch] Initializing MeiliSearch plugin');
+		routeHelpers.setupAdminPageRoute(router, '/admin/plugins/meilisearch', [], async (req, res) => {
+			const topicTotal = Number(plugin.indexing.topic_progress.total) || 0;
+			const topicCurrent = Number(plugin.indexing.topic_progress.current) || 0;
+			const postTotal = Number(plugin.indexing.post_progress.total) || 0;
+			const postCurrent = Number(plugin.indexing.post_progress.current) || 0;
+			const messageTotal = Number(plugin.indexing.message_progress.total) || 0;
+			const messageCurrent = Number(plugin.indexing.message_progress.current) || 0;
+			const topicPercent = topicTotal > 0 ? Math.min(100, Math.max(0, Math.round(100 * topicCurrent / topicTotal))) : 0;
+			const postPercent = postTotal > 0 ? Math.min(100, Math.max(0, Math.round(100 * postCurrent / postTotal))) : 0;
+			const messagePercent = messageTotal > 0 ? Math.min(100, Math.max(0, Math.round(100 * messageCurrent / messageTotal))) : 0;
+			const lastReindexResult = await settings.getOne(plugin.id, 'lastReindexResult') || {};
+			res.render('admin/plugins/meilisearch', {
+				title: '[[meilisearch:admin.settings]]',
+				indexing: plugin.indexing,
+				topicPercent,
+				postPercent,
+				messagePercent,
+				lastReindexResult,
+			});
+		});
+		await settings.setOnEmpty(plugin.id, plugin.defaults);
+		await plugin.prepareSearch();
+		await plugin.ensureChatMessageIndex();
+		plugin.patchTopicsSearch();
+		plugin.initialized = true;
+	};
+
+	plugin.addRoutes = async function ({ router, middleware, helpers }) {
+		const middlewares = [
+			middleware.ensureLoggedIn,
+			middleware.admin.checkPrivileges,
+		];
+		routeHelpers.setupApiRoute(router, 'get', '/meilisearch/reindex', middlewares, async (req, res) => {
+			helpers.formatApiResponse(200, res, {
+				indexing: plugin.indexing,
+				healthy: plugin.healthy,
+				lastReindexResult: await settings.getOne(plugin.id, 'lastReindexResult') || {},
+			});
+		});
+
+		routeHelpers.setupApiRoute(router, 'post', '/meilisearch/reindex', middlewares, async (req, res) => {
+			await settings.set(plugin.id, { indexed: false }, true);
+			plugin.reindex(false);
+			helpers.formatApiResponse(202, res, plugin.indexing);
+		});
+		routeHelpers.setupApiRoute(router, 'delete', '/meilisearch/reindex', middlewares, async (req, res) => {
+			await settings.set(plugin.id, { indexed: false }, true);
+			plugin.reindex(true);
+			helpers.formatApiResponse(202, res, plugin.indexing);
+		});
+
+		// Pure A: Ollama reachability probe. NodeBB container makes a 5s HTTP GET to
+		// <url>/api/version (or http://localhost:11434/api/version if URL is blank — the
+		// lib/embedder.js default). Used by static/lib/admin.js saveSettings to show a
+		// modal when Ollama is unreachable from NodeBB. Test runs from NodeBB's container,
+		// not Meilisearch's — admin is informed of this in the modal text so they can
+		// override with "Save anyway" if they're confident Meilisearch can reach Ollama
+		// on a different network path (e.g. Meilisearch runs with --network=host).
+		routeHelpers.setupApiRoute(router, 'post', '/meilisearch/test-ollama', middlewares, async (req, res) => {
+			const rawUrl = (req.body && typeof req.body.url === 'string') ? req.body.url : '';
+			// Default URL mirrors lib/embedder.js ollama fallback
+			const ollamaUrl = rawUrl || 'http://localhost:11434/api/embeddings';
+			// Strip /api/embeddings suffix if admin included it, then append /api/version probe path
+			const ollamaBase = ollamaUrl.replace(/\/api\/embeddings\/?$/, '').replace(/\/$/, '');
+			const probeUrl = `${ollamaBase}/api/version`;
+			// Declare controller/timeout above the try block so the finally clause can always
+			// clear the timer — even if the synchronous URL parsing or fetch setup throws
+			// before the await resolves (e.g. malformed URL → `new URL()` throws inside fetch).
+			const controller = new AbortController();
+			const timeout = setTimeout(() => controller.abort(), 5000);
+			try {
+				const response = await fetch(probeUrl, { signal: controller.signal });
+				if (!response.ok) {
+					return helpers.formatApiResponse(200, res, {
+						reachable: false,
+						error: `Ollama responded HTTP ${response.status} ${response.statusText}`,
+						probeUrl,
+					});
+				}
+				const data = await response.json().catch(() => ({}));
+				return helpers.formatApiResponse(200, res, {
+					reachable: true,
+					version: data.version,
+					probeUrl,
+				});
+			} catch (err) {
+				return helpers.formatApiResponse(200, res, {
+					reachable: false,
+					error: err.name === 'AbortError' ? 'Timeout after 5s' : err.message,
+					probeUrl,
+				});
+			} finally {
+				clearTimeout(timeout);
+			}
+		});
+	};
+
+	plugin.addAdminNavigation = function (header) {
+		header.plugins.push({
+			route: '/plugins/meilisearch',
+			icon: 'fa-tint',
+			name: 'Meilisearch',
+		});
+
+		return header;
+	};
+
+	plugin.getNotices = async function (notices) {
+		const checkHealth = await plugin.checkHealth();
+		notices.push({
+			done: checkHealth,
+			doneText: 'MeiliSearch connection OK',
+			notDoneText: 'Could not connect to MeiliSearch',
+		});
+		return notices;
+	};
+};

package/lib/search.js

@@ -0,0 +1,249 @@
+'use strict';
+
+const winston = nodebb.require('winston');
+const settings = nodebb.require('./src/meta/settings');
+const plugins = nodebb.require('./src/plugins');
+const { resolveMinTermLength } = require('./settings-helpers');
+const { EMBEDDER_NAME, isSemanticSearchEnabled, getSemanticRatio, getSemanticScoreThreshold } = require('./embedder');
+const { redactSecrets } = require('./redact');
+
+// rankingScoreThreshold is a top-level search parameter (a sibling of "hybrid", not nested
+// inside it) - Meilisearch defaults it to 0 (no filtering) when omitted, which is why
+// unfiltered vector search returns its full `limit` regardless of how unrelated the tail is.
+async function buildSemanticSearchExtras(plugin) {
+	if (!(await isSemanticSearchEnabled(plugin))) return {};
+	return {
+		hybrid: { embedder: EMBEDDER_NAME, semanticRatio: await getSemanticRatio(plugin) },
+		rankingScoreThreshold: await getSemanticScoreThreshold(plugin),
+	};
+}
+
+// Runs a Meilisearch query and never lets it throw past this point: a broken/misconfigured
+// embedder (e.g. "Cannot find embedder with name `default`") must not take down normal
+// keyword search or callers like Topics.getSuggestedTopics, which propagate rejections
+// straight up through NodeBB's hook chain. If hybrid search fails, retries once as a plain
+// keyword search so users still get results instead of nothing; if that also fails (e.g.
+// Meilisearch itself is down), logs + alerts once (throttled) and returns null so the
+// caller can fall back to its original, unmodified data.
+async function safeSearch(plugin, indexName, term, opts) {
+	try {
+		return await plugin.client.index(indexName).search(term, opts);
+	} catch (err) {
+		const reason = err?.message || String(err);
+		// B1 fix: redact any apiKey Meilisearch may echo in search error responses.
+		// Search errors typically return code+message rather than echoing credentials,
+		// but uniform posture with the embedder-task paths is cheap defense-in-depth.
+		// A3-style inner try/catch preserves safeSearch's "never throw" contract: if
+		// redaction itself fails, fall back to the raw reason rather than rejecting.
+		let safeReason;
+		try {
+			safeReason = await redactSecrets(reason, plugin);
+		} catch {
+			safeReason = reason;
+		}
+		if (opts.hybrid) {
+			winston.error(`[plugin/meilisearch] Hybrid search on "${indexName}" failed (${safeReason}); falling back to keyword-only search`);
+			plugin.notifyAdmins(`search:${indexName}`, {
+				type: 'danger',
+				titleKey: '[[meilisearch:admin.semanticSearchDegraded]]',
+				message: `${indexName}: ${safeReason}`,
+			});
+			// rankingScoreThreshold is tuned for hybrid/vector scores - drop it too, or a
+			// keyword-only fallback could wrongly filter out valid BM25-style matches.
+			const { hybrid, rankingScoreThreshold, ...keywordOnly } = opts;
+			try {
+				return await plugin.client.index(indexName).search(term, keywordOnly);
+			} catch (fallbackErr) {
+				const fallbackReason = fallbackErr?.message || String(fallbackErr);
+				let safeFallbackReason;
+				try {
+					safeFallbackReason = await redactSecrets(fallbackReason, plugin);
+				} catch {
+					safeFallbackReason = fallbackReason;
+				}
+				winston.error(`[plugin/meilisearch] Keyword-only fallback search on "${indexName}" also failed: ${safeFallbackReason}`);
+				return null;
+			}
+		}
+		winston.error(`[plugin/meilisearch] Search on "${indexName}" failed: ${safeReason}`);
+		plugin.notifyAdmins(`search:${indexName}`, {
+			type: 'danger',
+			titleKey: '[[meilisearch:admin.semanticSearchDegraded]]',
+			message: `${indexName}: ${safeReason}`,
+		});
+		return null;
+	}
+}
+
+// Core search integration: filter:search.query / filter:topic.search / filter:messaging.searchMessages.
+module.exports = function attachSearch(plugin) {
+	plugin.checkConflict = function () {
+		const hooksToCheck = [
+			'filter:search.query',
+			'filter:topic.search',
+			'filter:messaging.searchMessages',
+		];
+		// blacklist, in case someone makes a plugin using these hooks that doesn't conflict.
+		// also, outside of dbsearch the user is expected to realize they installed two search plugins.
+		const conflictingPlugins = [
+			'nodebb-plugin-dbsearch',
+			'nodebb-plugin-solr',
+			'nodebb-plugin-elasticsearch',
+			'nodebb-plugin-search-elasticsearch',
+		];
+		for (const hook of hooksToCheck) {
+			if ((plugins.loadedHooks[hook] || []).filter(hookData => conflictingPlugins.includes(hookData.id)).length >= 1) {
+				return true;
+			}
+		}
+		return false;
+	};
+
+	plugin.searchMessages = async function (data) {
+		if (!data || !data.content) {
+			return data;
+		}
+		if (plugin.checkConflict()) {
+			winston.warn('[plugin/meilisearch] Another search plugin (most likely dbsearch) is enabled, so chat search via Meilisearch was aborted.');
+			return data;
+		}
+		if (!plugin.healthy && !(await plugin.checkHealth())) {
+			winston.warn('[plugin/meilisearch] Meilisearch instance did not return a healthy response, so chat search via Meilisearch was aborted.');
+			return data;
+		}
+		const rawQuery = String(data.content).trim();
+		const minTermLength = await resolveMinTermLength(plugin);
+		if (!rawQuery || !rawQuery.split(' ').some(word => word.length >= minTermLength)) {
+			winston.debug(`[plugin/meilisearch] Skipping chat search: no query word >= ${minTermLength} char(s)`);
+			return data;
+		}
+		const num = (v) => {
+			const n = parseInt(v, 10);
+			return Number.isFinite(n) ? n : null;
+		};
+		const filter = [];
+		// Core passes roomId/uid as arrays (filter:messaging.searchMessages payload in src/api/search.js).
+		const roomIds = Array.isArray(data.roomId) ? data.roomId : [data.roomId];
+		const roomNums = roomIds.map(num).filter(r => r !== null);
+		// Fail closed: if no valid roomId, return no results rather than searching globally across all rooms.
+		if (!roomNums.length) {
+			winston.warn('[plugin/meilisearch] searchMessages called with no valid roomId; returning no results');
+			return data;
+		}
+		filter.push(roomNums.map(rid => `roomId = ${rid}`));
+		// uid is an optional sender filter (message author, not the searcher); never populated by core callers.
+		const uids = Array.isArray(data.uid) ? data.uid : [data.uid];
+		const uidNums = uids.map(num).filter(u => u !== null);
+		if (uidNums.length) {
+			filter.push(uidNums.map(u => `uid = ${u}`));
+		}
+		const limit = parseInt(await settings.getOne(plugin.id, 'maxDocuments') || 100, 10);
+		winston.debug(`[plugin/meilisearch] Searching chat messages for "${rawQuery}" in room ${roomNums.join(',')}`);
+		const result = await safeSearch(plugin, 'chat_message', rawQuery, {
+			attributesToRetrieve: ['mid'],
+			limit: Math.min(limit, 100),
+			filter: filter.length ? filter : undefined,
+			matchingStrategy: data.matchWords === 'all' ? 'all' : 'last',
+			...(await buildSemanticSearchExtras(plugin)),
+		});
+		if (!result) return data;
+		data.ids = data.ids.concat(result.hits.map(hit => hit.mid));
+		return data;
+	};
+
+	plugin.search = async function (data) {
+		if (plugin.checkConflict()) {
+			// The dbsearch plugin was detected, abort search!
+			winston.warn(
+				'[plugin/meilisearch] Another search plugin (most likely dbsearch) is enabled, so search via Meilisearch was aborted.',
+			);
+			return data;
+		}
+		if (!plugin.healthy && !(await plugin.checkHealth())) {
+			winston.warn(
+				'[plugin/meilisearch] Meilisearch instance did not return a healthy response, so search via Meilisearch was aborted.',
+			);
+			return data;
+		}
+		const rawQuery = (data.term || data.content || '').trim();
+		const minTermLength = await resolveMinTermLength(plugin);
+		if (!rawQuery || !rawQuery.split(' ').some(word => word.length >= minTermLength)) {
+			winston.debug(`[plugin/meilisearch] Skipping search: no query word >= ${minTermLength} char(s)`);
+			return data;
+		}
+		// #6: Use local variables instead of mutating the shared payload.
+		const content = data.term || data.content;
+		const searchData = data.term ? { tid: data.tid } : data?.searchData;
+		const rawIndex = Array.isArray(data?.index) ? data.index[0] : data.index;
+		const ALLOWED_INDEXES = { post: 'pid', topic: 'tid' };
+		const index = ALLOWED_INDEXES[rawIndex] ? rawIndex : 'post';
+		const id = ALLOWED_INDEXES[index];
+		winston.debug(`[plugin/meilisearch] Searching for ${content} in ${index}`);
+		const result = await safeSearch(plugin, index, content, {
+			attributesToRetrieve: [id],
+			limit: parseInt(await settings.getOne(plugin.id, 'maxDocuments') || 500, 10),
+			filter: plugin.buildFilter(
+				data.cid,
+				data.uid,
+				searchData?.timeFilter,
+				searchData?.timeRange,
+				searchData?.tid,
+			),
+			sort: plugin.buildSort(searchData?.sortBy, searchData?.sortDirection),
+			matchingStrategy: data.matchWords === 'all' ? 'all' : 'last',
+			...(await buildSemanticSearchExtras(plugin)),
+		});
+		if (!result) return data;
+		data.ids = result.hits.map(hit => hit[id]);
+		return data;
+	};
+
+	plugin.buildFilter = function (categories, postedBy, timeFilter, timeRange, tid) {
+		const num = (v) => {
+			const n = parseInt(v, 10);
+			return Number.isFinite(n) ? n : null;
+		};
+		const filter = [];
+		if (categories?.length) {
+			const cids = categories.map(num).filter(c => c !== null);
+			if (cids.length) filter.push(cids.map(cid => `cid = ${cid}`));
+		}
+		if (postedBy?.length) {
+			const uids = postedBy.map(num).filter(u => u !== null);
+			if (uids.length) filter.push(uids.map(uid => `uid = ${uid}`));
+		}
+		if (timeFilter && timeRange) {
+			const range = num(timeRange);
+			if (range !== null) {
+				filter.push(`timestamp ${timeFilter === 'newer' ? '>' : '<'} ${Date.now() - (range * 1000)}`);
+			}
+		}
+		const numericTid = num(tid);
+		if (numericTid !== null) {
+			filter.push(`tid = ${numericTid}`);
+		}
+		return filter.length ? filter : undefined;
+	};
+
+	plugin.buildSort = function (sortBy, sortDirection) {
+		let field = '';
+		switch (sortBy) {
+			case 'timestamp':
+				field = 'timestamp';
+				break;
+			case 'topic.title':
+				field = 'title';
+				break;
+			case 'category':
+				field = 'cid';
+				break;
+			default:
+				return undefined;
+		}
+		return [`${field}:${sortDirection === 'ascending' ? 'asc' : 'desc'}`];
+	};
+};
+
+// Exposed so other direct-search call sites (lib/chat-search-global.js) get the same
+// crash-proofing/degrade-and-alert behavior instead of duplicating or, worse, skipping it.
+module.exports.safeSearch = safeSearch;