Files
outline/server/utils/BaseSearchProvider.ts
Tom Moor fc4fe65155 feat: Filter DSL (#12176)
* feat: Normalized filter DSL for documents.list and search

Add a structured filter expression language (field/operator/value leaves
composed with AND/OR groups) shared by documents.list, documents.search and
documents.searchTitles. Values are validated against each field's column type
and per-field operator allowlists at the input layer, and translated to
Sequelize where-clauses server-side.

Supersedes the ad-hoc statusFilter/dateFilter/collectionId/userId parameters,
adds ISO 8601 duration matching for date fields, documentId subtree expansion
for search, and preserves draft visibility and collection authorization.

* chore: Fix flaky Encrypted "different key" test

AES-256-CBC is unauthenticated, so decrypting with the wrong key only
raises "bad decrypt" when the garbage plaintext has invalid PKCS#7 padding
(~255/256 of the time). Roughly 1 in 245 runs it decrypts to a non-matching
value instead of throwing, failing the strict toThrow assertion. Accept
either outcome, mirroring the adjacent tampered-data test.

* Hardening
2026-08-15 13:25:10 -04:00

146 lines
4.4 KiB
TypeScript

import type { Filter } from "@shared/helpers/FilterHelper";
import type { SearchableModel } from "@shared/types";
import type { DirectionFilter, SortFilter } from "@shared/types";
import type Collection from "@server/models/Collection";
import type Comment from "@server/models/Comment";
import type Document from "@server/models/Document";
import type Share from "@server/models/Share";
import type Team from "@server/models/Team";
import type User from "@server/models/User";
export interface SearchResponse {
results: {
/** The search ranking, for sorting results. */
ranking: number;
/** A snippet of contextual text around the search result. */
context?: string;
/** The document result. */
document: Document;
}[];
/** The total number of results for the search query without pagination. */
total: number;
}
export interface SearchOptions {
/** The query limit for pagination. */
limit?: number;
/** The query offset for pagination. */
offset?: number;
/** The text to search for. */
query?: string;
/**
* A filter expression scoping results. Authorization for any auth-bearing
* fields (e.g. collectionId) is presumed to have been done before reaching
* the provider.
*/
filter?: Filter;
/** Limit results to a shared document. */
share?: Share;
/** The minimum number of words to be returned in the contextual snippet. */
snippetMinWords?: number;
/** The maximum number of words to be returned in the contextual snippet. */
snippetMaxWords?: number;
/** The field to sort results by. */
sort?: SortFilter;
/** The sort direction. */
direction?: DirectionFilter;
/** Whether to boost results by popularity score. Defaults to true. */
usePopularityBoost?: boolean;
}
/**
* Abstract base class for search providers. Implementations handle full-text
* search, title search, collection search, and index management.
*/
export abstract class BaseSearchProvider {
/** Unique identifier for this provider, matched against `SEARCH_PROVIDER` env var. */
abstract id: string;
/**
* Perform a full-text search scoped to a user's accessible documents.
*
* @param user - the user performing the search.
* @param options - search options.
* @returns search results with ranking and context.
*/
abstract searchForUser(
user: User,
options?: SearchOptions
): Promise<SearchResponse>;
/**
* Perform a full-text search scoped to a team (used for shared document search).
*
* @param team - the team to search within.
* @param options - search options.
* @returns search results with ranking and context.
*/
abstract searchForTeam(
team: Team,
options?: SearchOptions
): Promise<SearchResponse>;
/**
* Search document titles for a user (used for link suggestions, quick search).
*
* @param user - the user performing the search.
* @param options - search options.
* @returns matching documents.
*/
abstract searchTitlesForUser(
user: User,
options?: SearchOptions
): Promise<Document[]>;
/**
* Search collections for a user.
*
* @param user - the user performing the search.
* @param options - search options.
* @returns matching collections.
*/
abstract searchCollectionsForUser(
user: User,
options?: SearchOptions
): Promise<Collection[]>;
/**
* Index or re-index a searchable item. For providers that rely on database
* triggers (e.g. PostgreSQL tsvector), this may be a no-op.
*
* @param model - the type of model being indexed.
* @param item - the model instance to index.
*/
abstract index(
model: SearchableModel,
item: Document | Collection | Comment
): Promise<void>;
/**
* Remove an item from the search index.
*
* @param model - the type of model being removed.
* @param id - the id of the item to remove.
* @param teamId - the team id the item belongs to.
*/
abstract remove(
model: SearchableModel,
id: string,
teamId: string
): Promise<void>;
/**
* Update metadata for an indexed item without re-indexing the full content.
* Useful for permission changes, moves, archive/unarchive.
*
* @param model - the type of model being updated.
* @param id - the id of the item to update.
* @param metadata - the metadata fields to update.
*/
abstract updateMetadata(
model: SearchableModel,
id: string,
metadata: Record<string, unknown>
): Promise<void>;
}