Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/search/src/query.ts
T

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;
}