Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -0,0 +1,215 @@
|
||||
/**
|
||||
* 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;
|
||||
}
|
||||
Reference in new issue
Block a user