216 lines
8.3 KiB
TypeScript
216 lines
8.3 KiB
TypeScript
/**
|
|
* Tenant-scoped search query helpers.
|
|
*
|
|
* These functions are the only sanctioned read/write surface — domain
|
|
* code that imports `@toolctrl/search` reaches Meilisearch through them
|
|
* and nothing else. Every call requires an explicit tenantId; the
|
|
* wrapper translates that into the Meilisearch filter expression
|
|
* `tenantId = "<id>"` and AND-merges it with any caller-supplied
|
|
* filters. Special characters in the tenantId are escaped to prevent
|
|
* filter injection.
|
|
*/
|
|
|
|
import type { IndexSearchOptions, SearchClient, SearchDocument, SearchHits } from "./client.js";
|
|
import { sanitizeDocument } from "./sanitize.js";
|
|
import type { SearchIndexSchema } from "./schemas/index.js";
|
|
|
|
const ORIGINAL_PRIMARY_KEY_FIELD = "__toolctrlOriginalPrimaryKey";
|
|
|
|
export class TenantScopeError extends Error {
|
|
override readonly name = "TenantScopeError";
|
|
readonly code: "MISSING_TENANT" | "INVALID_TENANT";
|
|
constructor(message: string, code: TenantScopeError["code"] = "MISSING_TENANT") {
|
|
super(message);
|
|
this.code = code;
|
|
}
|
|
}
|
|
|
|
export interface SearchInIndexInput {
|
|
readonly client: SearchClient;
|
|
readonly schema: SearchIndexSchema;
|
|
readonly tenantId: string;
|
|
readonly query: string;
|
|
readonly options?: Omit<IndexSearchOptions, "filter"> & { extraFilters?: string | readonly string[] };
|
|
}
|
|
|
|
export async function searchInIndex<TDocument extends SearchDocument = SearchDocument>(
|
|
input: SearchInIndexInput
|
|
): Promise<SearchHits<TDocument>> {
|
|
assertTenantId(input.tenantId);
|
|
const handle = input.client.index<TDocument>(input.schema.name);
|
|
const filter = buildFilter(input.tenantId, input.options?.extraFilters);
|
|
const attributesToRetrieve = input.options?.attributesToRetrieve;
|
|
const opts: IndexSearchOptions = {
|
|
...(input.options ?? {}),
|
|
filter,
|
|
...(attributesToRetrieve && !attributesToRetrieve.includes("*")
|
|
? { attributesToRetrieve: unique([...attributesToRetrieve, input.schema.primaryKey, ORIGINAL_PRIMARY_KEY_FIELD]) }
|
|
: {}),
|
|
};
|
|
// strip our internal extraFilters key (it isn't part of IndexSearchOptions on the client)
|
|
delete (opts as { extraFilters?: unknown }).extraFilters;
|
|
const result = await handle.search(input.query ?? "", opts);
|
|
return {
|
|
...result,
|
|
hits: result.hits.map((hit) => ({
|
|
...hit,
|
|
document: restoreDocumentPrimaryKey(input.schema, hit.document),
|
|
})),
|
|
};
|
|
}
|
|
|
|
export interface BulkIndexInput<TDocument extends SearchDocument = SearchDocument> {
|
|
readonly client: SearchClient;
|
|
readonly schema: SearchIndexSchema;
|
|
readonly tenantId: string;
|
|
readonly documents: readonly TDocument[];
|
|
}
|
|
|
|
export async function bulkIndex<TDocument extends SearchDocument = SearchDocument>(
|
|
input: BulkIndexInput<TDocument>
|
|
): Promise<void> {
|
|
assertTenantId(input.tenantId);
|
|
if (input.documents.length === 0) return;
|
|
const sanitized = input.documents.map((doc) => {
|
|
if ("tenantId" in doc && doc.tenantId !== input.tenantId) {
|
|
throw new TenantScopeError(
|
|
`bulkIndex received a document whose tenantId differs from the call-site tenantId.`,
|
|
"INVALID_TENANT"
|
|
);
|
|
}
|
|
const projected = sanitizeDocument(input.schema, { ...doc, tenantId: input.tenantId });
|
|
if (projected.tenantId !== input.tenantId) {
|
|
throw new TenantScopeError(
|
|
`bulkIndex received a document whose tenantId differs from the call-site tenantId.`,
|
|
"INVALID_TENANT"
|
|
);
|
|
}
|
|
return scopeDocumentPrimaryKey(input.schema, input.tenantId, projected);
|
|
});
|
|
const handle = input.client.index<TDocument>(input.schema.name);
|
|
await handle.upsert(sanitized as readonly TDocument[]);
|
|
}
|
|
|
|
export interface DeleteFromIndexInput {
|
|
readonly client: SearchClient;
|
|
readonly schema: SearchIndexSchema;
|
|
readonly tenantId: string;
|
|
readonly documentIds: readonly (string | number)[];
|
|
}
|
|
|
|
export async function deleteFromIndex(input: DeleteFromIndexInput): Promise<void> {
|
|
assertTenantId(input.tenantId);
|
|
if (input.documentIds.length === 0) return;
|
|
const handle = input.client.index(input.schema.name);
|
|
await handle.delete(input.documentIds.map((documentId) => buildScopedPrimaryKey(input.tenantId, documentId)));
|
|
}
|
|
|
|
export interface SearchFallback<TDocument extends SearchDocument = SearchDocument> {
|
|
(input: { query: string; tenantId: string }): Promise<SearchHits<TDocument>>;
|
|
}
|
|
|
|
export interface SearchWithFallbackInput<TDocument extends SearchDocument = SearchDocument> extends SearchInIndexInput {
|
|
readonly fallback: SearchFallback<TDocument>;
|
|
/** Optional hook fired when the fallback path engages — useful for
|
|
* Sentry tagging or Prometheus counters. */
|
|
readonly onFallback?: (info: { reason: "search-error"; error: unknown }) => void;
|
|
}
|
|
|
|
export async function searchWithFallback<TDocument extends SearchDocument = SearchDocument>(
|
|
input: SearchWithFallbackInput<TDocument>
|
|
): Promise<SearchHits<TDocument>> {
|
|
try {
|
|
return await searchInIndex<TDocument>(input);
|
|
} catch (error) {
|
|
if (error instanceof TenantScopeError) throw error;
|
|
if (!isMeiliConnectivityError(error)) throw error;
|
|
input.onFallback?.({ reason: "search-error", error });
|
|
return input.fallback({ query: input.query, tenantId: input.tenantId });
|
|
}
|
|
}
|
|
|
|
export async function health(client: SearchClient): Promise<{ status: "available" | "unavailable" }> {
|
|
try {
|
|
return await client.health();
|
|
} catch {
|
|
return { status: "unavailable" };
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Escape characters that have special meaning inside a Meilisearch
|
|
* filter expression. The wrapper always quotes the value, so we just
|
|
* need to neutralise quotes and backslashes — the rest is plain text.
|
|
*/
|
|
function escapeFilterValue(value: string): string {
|
|
return value.replace(/\\/gu, "\\\\").replace(/"/gu, '\\"');
|
|
}
|
|
|
|
function buildFilter(tenantId: string, extra: string | readonly string[] | undefined): string {
|
|
const base = `tenantId = "${escapeFilterValue(tenantId)}"`;
|
|
if (!extra) return base;
|
|
if (Array.isArray(extra)) {
|
|
const trimmed = extra.map((f) => f.trim()).filter((f) => f.length > 0);
|
|
if (trimmed.length === 0) return base;
|
|
return `${base} AND ${trimmed.map((f) => `(${f})`).join(" AND ")}`;
|
|
}
|
|
const single = (extra as string).trim();
|
|
return single.length === 0 ? base : `${base} AND (${single})`;
|
|
}
|
|
|
|
function scopeDocumentPrimaryKey<TDocument extends SearchDocument>(
|
|
schema: SearchIndexSchema,
|
|
tenantId: string,
|
|
document: TDocument
|
|
): TDocument {
|
|
const primaryKey = document[schema.primaryKey];
|
|
if (typeof primaryKey !== "string" && typeof primaryKey !== "number") {
|
|
throw new Error(`Document primary key "${schema.primaryKey}" must be string or number.`);
|
|
}
|
|
return {
|
|
...document,
|
|
[schema.primaryKey]: buildScopedPrimaryKey(tenantId, primaryKey),
|
|
[ORIGINAL_PRIMARY_KEY_FIELD]: primaryKey,
|
|
} as TDocument;
|
|
}
|
|
|
|
function restoreDocumentPrimaryKey<TDocument extends SearchDocument>(
|
|
schema: SearchIndexSchema,
|
|
document: TDocument
|
|
): TDocument {
|
|
if (!(ORIGINAL_PRIMARY_KEY_FIELD in document)) {
|
|
return document;
|
|
}
|
|
const { [ORIGINAL_PRIMARY_KEY_FIELD]: originalPrimaryKey, ...rest } = document;
|
|
if (typeof originalPrimaryKey !== "string" && typeof originalPrimaryKey !== "number") {
|
|
return rest as TDocument;
|
|
}
|
|
return {
|
|
...rest,
|
|
[schema.primaryKey]: originalPrimaryKey,
|
|
} as TDocument;
|
|
}
|
|
|
|
function buildScopedPrimaryKey(tenantId: string, documentId: string | number): string {
|
|
return `${encodeURIComponent(tenantId)}:${encodeURIComponent(String(documentId))}`;
|
|
}
|
|
|
|
function unique<T>(values: readonly T[]): T[] {
|
|
return Array.from(new Set(values));
|
|
}
|
|
|
|
function assertTenantId(tenantId: unknown): asserts tenantId is string {
|
|
if (typeof tenantId !== "string" || tenantId.length === 0) {
|
|
throw new TenantScopeError("Search calls require a non-empty tenantId.", "MISSING_TENANT");
|
|
}
|
|
}
|
|
|
|
function isMeiliConnectivityError(error: unknown): boolean {
|
|
if (!error || typeof error !== "object") return false;
|
|
const candidate = error as { code?: string; name?: string; message?: string };
|
|
if (typeof candidate.code === "string" && /ECONN|ETIMEDOUT|ENOTFOUND|FETCH/iu.test(candidate.code)) return true;
|
|
if (typeof candidate.name === "string" && /FetchError|MeiliSearchCommunicationError|MeiliSearchTimeOutError|AbortError/iu.test(candidate.name)) return true;
|
|
if (typeof candidate.message === "string" && /fetch failed|network|unavailable|connect|timeout/iu.test(candidate.message)) return true;
|
|
return false;
|
|
}
|