@flowdular/sdk 0.2.4 → 0.3.1

package/modules/search/src/services/search-service.ts

@@ -0,0 +1,442 @@
+import { randomUUID } from 'node:crypto';
+import { serverLogger } from '@flowdular/sdk/server';
+import {
+	SEARCH_PROVIDER_LIMITS,
+	type SearchHit,
+	type SearchPrincipal,
+	type SearchProviderPage,
+} from '../domain/providers.ts';
+import {
+	SEARCH_LIMITS,
+	type RecentQuery,
+	type SearchCursor,
+	type SearchProviderSummary,
+	type SearchResultHit,
+	type SearchResultPage,
+} from '../domain/types.ts';
+import type { RegisteredSearchProvider } from './provider-registry.ts';
+import type { MutableSearchProviderRegistry } from './provider-registry.ts';
+import type { SearchRepository } from './repository.ts';
+import { bounded, SearchServiceError } from './service-error.ts';
+
+/** A workspace-relative path and nothing else: no scheme, no host, no `//`. */
+const ROUTE = /^\/(?!\/)[\w\-./~%!$&'()*+,;=:@?#[\]]*$/;
+const VIEW_ID = /^[a-z][a-z0-9-]*$/;
+
+export interface SearchBudget {
+	/** Time one provider gets for one query. */
+	readonly providerTimeoutMs: number;
+	/** Hits one provider may answer with per page. */
+	readonly hitsPerProvider: number;
+}
+
+export interface SearchQueryInput {
+	readonly principal: SearchPrincipal;
+	readonly query: string;
+	readonly limit: number;
+	/** Narrows the fan-out to one provider key. */
+	readonly provider?: string | undefined;
+	readonly cursor?: SearchCursor | null;
+	/**
+	 * Keeps the query in the member's recall list. Off by default: a debounced
+	 * prefix is a keystroke, not a search the member meant to run, so only a
+	 * deliberate submit or opening a hit asks for it.
+	 */
+	readonly remember?: boolean;
+}
+
+export interface SearchServiceOptions {
+	readonly registry: MutableSearchProviderRegistry;
+	readonly repository: SearchRepository;
+	/** Read live, so a settings change applies to the next query. */
+	readonly budget: () => SearchBudget;
+	readonly now?: () => number;
+}
+
+function summary(provider: RegisteredSearchProvider): SearchProviderSummary {
+	return {
+		key: provider.key,
+		moduleId: provider.moduleId,
+		label: provider.label,
+		permission: provider.permission,
+	};
+}
+
+/**
+ * Collapses runs of whitespace so the same words always produce the same recent
+ * query row and the same provider input. Over the bound is a refusal; under the
+ * minimum is not an error, it just asks nobody.
+ */
+export function normalizeQuery(raw: unknown): string {
+	if (typeof raw !== 'string') {
+		throw new SearchServiceError('INVALID_INPUT', 'q must be text.');
+	}
+	if (raw.length > SEARCH_LIMITS.queryMaximum * 4) {
+		throw new SearchServiceError(
+			'QUERY_TOO_LONG',
+			`q must contain at most ${SEARCH_LIMITS.queryMaximum} characters.`,
+		);
+	}
+	const normalized = raw.replace(/\s+/gu, ' ').trim();
+	if (normalized.length > SEARCH_LIMITS.queryMaximum) {
+		throw new SearchServiceError(
+			'QUERY_TOO_LONG',
+			`q must contain at most ${SEARCH_LIMITS.queryMaximum} characters.`,
+		);
+	}
+	if (normalized.includes('\u0000')) {
+		throw new SearchServiceError(
+			'INVALID_INPUT',
+			'q contains an unsupported character.',
+		);
+	}
+	return normalized;
+}
+
+function readHit(value: SearchHit, providerKey: string): SearchResultHit {
+	const route = String(value?.route ?? '');
+	if (
+		route.length > SEARCH_PROVIDER_LIMITS.route ||
+		!ROUTE.test(route) ||
+		!VIEW_ID.test(String(value?.viewId ?? ''))
+	) {
+		throw new SearchServiceError(
+			'PROVIDER_HIT_INVALID',
+			`Search provider "${providerKey}" returned a hit with an unusable destination.`,
+			502,
+		);
+	}
+	const score = Number(value.score);
+	if (!Number.isFinite(score)) {
+		throw new SearchServiceError(
+			'PROVIDER_HIT_INVALID',
+			`Search provider "${providerKey}" returned a hit without a score.`,
+			502,
+		);
+	}
+	return {
+		provider: providerKey,
+		ref: bounded(value.ref, 'ref', 1, SEARCH_PROVIDER_LIMITS.ref),
+		title: bounded(value.title, 'title', 1, SEARCH_PROVIDER_LIMITS.title),
+		snippet:
+			value.snippet === undefined || value.snippet === null
+				? ''
+				: bounded(value.snippet, 'snippet', 0, SEARCH_PROVIDER_LIMITS.snippet),
+		viewId: value.viewId,
+		route,
+		score,
+	};
+}
+
+/**
+ * What a provider answered, checked and ordered. A provider is foreign code on
+ * a request path: nothing it returns reaches a response before it is read here,
+ * and anything unreadable makes that provider unavailable rather than failing
+ * the search.
+ */
+function readPage(
+	page: SearchProviderPage,
+	provider: RegisteredSearchProvider,
+	limit: number,
+): { readonly hits: readonly SearchResultHit[]; readonly nextCursor: string } {
+	if (!page || !Array.isArray(page.hits) || page.hits.length > limit) {
+		throw new SearchServiceError(
+			'PROVIDER_PAGE_INVALID',
+			`Search provider "${provider.key}" answered with more than ${limit} hits.`,
+			502,
+		);
+	}
+	const cursor = page.nextCursor ?? '';
+	if (
+		typeof cursor !== 'string' ||
+		cursor.length > SEARCH_PROVIDER_LIMITS.cursor
+	) {
+		throw new SearchServiceError(
+			'PROVIDER_PAGE_INVALID',
+			`Search provider "${provider.key}" answered with an oversized cursor.`,
+			502,
+		);
+	}
+	const hits = page.hits.map((hit) => readHit(hit, provider.key));
+	/* Sorted here, not trusted from the provider: the resume offset counts into
+	   this order, so it has to be the same for the same batch every time. */
+	hits.sort(
+		(left, right) =>
+			right.score - left.score || left.ref.localeCompare(right.ref),
+	);
+	return { hits, nextCursor: cursor };
+}
+
+/**
+ * One provider call, bounded by the time budget. The losing side of the race is
+ * always settled, so an abandoned provider cannot surface later as an unhandled
+ * rejection, and the abort listener is removed either way.
+ */
+async function runProvider(
+	provider: RegisteredSearchProvider,
+	input: Omit<Parameters<RegisteredSearchProvider['search']>[0], 'signal'>,
+	timeoutMs: number,
+): Promise<SearchProviderPage> {
+	const signal = AbortSignal.timeout(timeoutMs);
+	let onAbort: (() => void) | undefined;
+	const expiry = new Promise<never>((_resolve, reject) => {
+		onAbort = () =>
+			reject(
+				new SearchServiceError(
+					'PROVIDER_TIMEOUT',
+					`Search provider "${provider.key}" exceeded its ${timeoutMs} ms budget.`,
+					504,
+				),
+			);
+		signal.addEventListener('abort', onAbort, { once: true });
+	});
+	expiry.catch(() => undefined);
+	try {
+		return await Promise.race([provider.search({ ...input, signal }), expiry]);
+	} finally {
+		if (onAbort) signal.removeEventListener('abort', onAbort);
+	}
+}
+
+export class SearchService {
+	readonly #registry: MutableSearchProviderRegistry;
+	readonly #repository: SearchRepository;
+	readonly #budget: () => SearchBudget;
+	readonly #now: () => number;
+
+	constructor(options: SearchServiceOptions) {
+		this.#registry = options.registry;
+		this.#repository = options.repository;
+		this.#budget = options.budget;
+		this.#now = options.now ?? Date.now;
+	}
+
+	/** Every provider whose permission this principal holds, in merge order. */
+	providers(principal: SearchPrincipal): readonly SearchProviderSummary[] {
+		return this.#permitted(principal).map(summary);
+	}
+
+	async search(input: SearchQueryInput): Promise<SearchResultPage> {
+		const principal = input.principal;
+		const permitted = this.#permitted(principal, input.provider);
+		const providers = permitted.map(summary);
+		if (input.query.length < SEARCH_LIMITS.queryMinimum) {
+			return { hits: [], nextCursor: null, providers, unavailable: [] };
+		}
+		const budget = this.#readBudget();
+		const start = this.#resumeIndex(permitted, input.cursor ?? null);
+		const targets = permitted.slice(start.index);
+		const settled = await Promise.allSettled(
+			targets.map((provider, offset) =>
+				runProvider(
+					provider,
+					{
+						tenantId: principal.tenantId,
+						principal,
+						query: input.query,
+						limit: budget.hitsPerProvider,
+						...(offset === 0 && start.cursor !== ''
+							? { cursor: start.cursor }
+							: {}),
+					},
+					budget.providerTimeoutMs,
+				),
+			),
+		);
+
+		const unavailable: string[] = [];
+		const pages = settled.map((result, offset) => {
+			const provider = targets[offset]!;
+			if (result.status !== 'fulfilled') {
+				unavailable.push(provider.key);
+				return null;
+			}
+			try {
+				return readPage(result.value, provider, budget.hitsPerProvider);
+			} catch {
+				/* A provider that answers nonsense is unavailable for this query; it
+				   never turns the member's whole search into an error. */
+				unavailable.push(provider.key);
+				return null;
+			}
+		});
+
+		const page = this.#merge(targets, pages, start, input.limit);
+		if (input.cursor == null && input.remember === true) {
+			await this.#remember(principal, input.query);
+		}
+		return { ...page, providers, unavailable };
+	}
+
+	/**
+	 * Keeps one query in the member's own recall list without searching. The
+	 * screen uses it when the member opens a hit: the view is already navigating
+	 * away, so re-running the whole search only to set the flag would race the
+	 * page it is leaving. A query under the minimum is not a search and is not
+	 * kept; the answer says whether a row was written.
+	 */
+	async remember(principal: SearchPrincipal, query: string): Promise<boolean> {
+		if (query.length < SEARCH_LIMITS.queryMinimum) return false;
+		return this.#remember(principal, query);
+	}
+
+	recent(tenantId: string, accountId: string): Promise<readonly RecentQuery[]> {
+		return this.#repository.listRecent(
+			bounded(tenantId, 'tenantId', 1, SEARCH_LIMITS.tenantId),
+			bounded(accountId, 'accountId', 1, SEARCH_LIMITS.accountId),
+			SEARCH_LIMITS.recentPerMember,
+		);
+	}
+
+	clearRecent(tenantId: string, accountId: string): Promise<number> {
+		return this.#repository.clearRecent(
+			bounded(tenantId, 'tenantId', 1, SEARCH_LIMITS.tenantId),
+			bounded(accountId, 'accountId', 1, SEARCH_LIMITS.accountId),
+		);
+	}
+
+	#permitted(
+		principal: SearchPrincipal,
+		key?: string | undefined,
+	): readonly RegisteredSearchProvider[] {
+		const granted = new Set(principal.scopes);
+		return this.#registry
+			.list()
+			.filter(
+				(provider) =>
+					granted.has(provider.permission) &&
+					(key === undefined || provider.key === key),
+			);
+	}
+
+	#readBudget(): SearchBudget {
+		const budget = this.#budget();
+		return {
+			providerTimeoutMs: Math.min(
+				10_000,
+				Math.max(200, Math.trunc(budget.providerTimeoutMs)),
+			),
+			hitsPerProvider: Math.min(
+				100,
+				Math.max(5, Math.trunc(budget.hitsPerProvider)),
+			),
+		};
+	}
+
+	#resumeIndex(
+		permitted: readonly RegisteredSearchProvider[],
+		cursor: SearchCursor | null,
+	): {
+		readonly index: number;
+		readonly cursor: string;
+		readonly skip: number;
+	} {
+		if (!cursor) return { index: 0, cursor: '', skip: 0 };
+		const index = permitted.findIndex(
+			(provider) => provider.key === cursor.provider,
+		);
+		if (index === -1) {
+			throw new SearchServiceError(
+				'CURSOR_INVALID',
+				'The page cursor does not belong to this search.',
+			);
+		}
+		return { index, cursor: cursor.cursor, skip: cursor.skip };
+	}
+
+	/**
+	 * Provider-major merge: everything the first provider still has, then the
+	 * next. That keeps the resume position to one provider key, one provider
+	 * cursor and one offset, whatever the number of providers.
+	 *
+	 * A cursor is never emitted past a provider that was unavailable on this
+	 * request: it would move the position beyond records the member never saw
+	 * and can no longer page to. The page ends instead, with the provider named
+	 * in `unavailable`, and searching again asks it from the start.
+	 */
+	#merge(
+		targets: readonly RegisteredSearchProvider[],
+		pages: readonly ({
+			readonly hits: readonly SearchResultHit[];
+			readonly nextCursor: string;
+		} | null)[],
+		start: { readonly cursor: string; readonly skip: number },
+		limit: number,
+	): {
+		readonly hits: readonly SearchResultHit[];
+		readonly nextCursor: SearchCursor | null;
+	} {
+		const hits: SearchResultHit[] = [];
+		let skipped = false;
+		for (let index = 0; index < targets.length; index += 1) {
+			const page = pages[index];
+			if (!page) {
+				skipped = true;
+				continue;
+			}
+			const provider = targets[index]!;
+			const consumed = index === 0 ? start.skip : 0;
+			const available = page.hits.slice(consumed);
+			const room = limit - hits.length;
+			if (available.length > room) {
+				hits.push(...available.slice(0, room));
+				return {
+					hits,
+					nextCursor: skipped
+						? null
+						: {
+								provider: provider.key,
+								cursor: index === 0 ? start.cursor : '',
+								skip: consumed + room,
+							},
+				};
+			}
+			hits.push(...available);
+			if (hits.length < limit) continue;
+			if (skipped) return { hits, nextCursor: null };
+			if (page.nextCursor !== '') {
+				return {
+					hits,
+					nextCursor: {
+						provider: provider.key,
+						cursor: page.nextCursor,
+						skip: 0,
+					},
+				};
+			}
+			const following = targets[index + 1];
+			return {
+				hits,
+				nextCursor: following
+					? { provider: following.key, cursor: '', skip: 0 }
+					: null,
+			};
+		}
+		return { hits, nextCursor: null };
+	}
+
+	/**
+	 * Recall is a convenience, so a failed write is logged and the member still
+	 * gets the hits; it is never allowed to turn a working search into an error.
+	 * The answer is what was written, for the caller that has only this to report.
+	 */
+	async #remember(principal: SearchPrincipal, query: string): Promise<boolean> {
+		try {
+			await this.#repository.recordQuery({
+				id: randomUUID(),
+				tenantId: principal.tenantId,
+				accountId: principal.accountId,
+				query,
+				ranAt: this.#now(),
+				keep: SEARCH_LIMITS.recentPerMember,
+			});
+			return true;
+		} catch (error) {
+			serverLogger().warn('recent query not recorded', {
+				module: 'search.core',
+				err: error,
+			});
+			return false;
+		}
+	}
+}

package/modules/search/src/services/service-error.ts

@@ -0,0 +1,35 @@
+export class SearchServiceError extends Error {
+	constructor(
+		readonly code: string,
+		message: string,
+		readonly status = 400,
+	) {
+		super(message);
+		this.name = 'SearchServiceError';
+	}
+}
+
+export function bounded(
+	value: unknown,
+	field: string,
+	minimum: number,
+	maximum: number,
+): string {
+	if (typeof value !== 'string') {
+		throw new SearchServiceError('INVALID_INPUT', `${field} must be text.`);
+	}
+	const normalized = value.trim();
+	if (normalized.length < minimum || normalized.length > maximum) {
+		throw new SearchServiceError(
+			'INVALID_INPUT',
+			`${field} must contain between ${minimum} and ${maximum} characters.`,
+		);
+	}
+	if (normalized.includes('\u0000')) {
+		throw new SearchServiceError(
+			'INVALID_INPUT',
+			`${field} contains an unsupported character.`,
+		);
+	}
+	return normalized;
+}

package/modules/search/src/settings.ts

@@ -0,0 +1,68 @@
+import {
+	defineModuleSettings,
+	PLATFORM_SETTINGS_TENANT,
+	type ModuleSettingsRuntime,
+} from '@flowdular/sdk/kernel';
+import type { SearchBudget } from './services/search-service.ts';
+
+export const SEARCH_MODULE_ID = 'search.core';
+
+export const SEARCH_MODULE_SETTINGS = defineModuleSettings({
+	moduleId: SEARCH_MODULE_ID,
+	settings: {
+		providerTimeoutMs: {
+			type: 'number',
+			defaultValue: 1_500,
+			min: 200,
+			max: 10_000,
+			visibility: 'shared',
+			client: false,
+			scope: 'platform',
+			labelKey: 'search.settings.providerTimeoutMs.label',
+			label: 'Provider time budget (ms)',
+			descriptionKey: 'search.settings.providerTimeoutMs.description',
+			description:
+				'Time one provider gets per query before it is reported unavailable.',
+		},
+		hitsPerProvider: {
+			type: 'number',
+			defaultValue: 20,
+			min: 5,
+			max: 100,
+			visibility: 'shared',
+			client: false,
+			scope: 'platform',
+			labelKey: 'search.settings.hitsPerProvider.label',
+			label: 'Hits per provider',
+			descriptionKey: 'search.settings.hitsPerProvider.description',
+			description: 'Hits one provider may answer with per page.',
+		},
+	},
+});
+
+const DEFAULTS = SEARCH_MODULE_SETTINGS.settings;
+
+/* A settings read must never take a request down, so each accessor falls back
+   to the declared default when the runtime has not registered it yet. */
+function value(
+	settings: ModuleSettingsRuntime,
+	key: keyof typeof DEFAULTS,
+	fallback: number,
+): number {
+	try {
+		return settings.get<number>(
+			PLATFORM_SETTINGS_TENANT,
+			SEARCH_MODULE_ID,
+			key,
+		);
+	} catch {
+		return fallback;
+	}
+}
+
+export function searchBudget(settings: ModuleSettingsRuntime): SearchBudget {
+	return {
+		providerTimeoutMs: value(settings, 'providerTimeoutMs', 1_500),
+		hitsPerProvider: value(settings, 'hitsPerProvider', 20),
+	};
+}

package/modules/search/translations/en.json

@@ -0,0 +1,45 @@
+{
+	"action.loadMore": "Load more",
+	"action.loadingMore": "Loading…",
+	"action.search": "Search",
+	"action.searching": "Searching…",
+	"common.filters": "Filters",
+	"denied.hint": "You do not have permission to search records in this workspace.",
+	"denied.title": "Access denied",
+	"error.clearRecent": "Could not clear recent searches.",
+	"error.code.CURSOR_INVALID": "The result page expired. Search again.",
+	"error.code.INVALID_INPUT": "The search request was not accepted.",
+	"error.code.QUERY_TOO_LONG": "The search text is too long.",
+	"error.load": "Could not search records.",
+	"error.request": "The search operation failed.",
+	"filter.allProviders": "All providers",
+	"filter.provider": "Provider",
+	"module.name": "Search",
+	"navigation.description": "Find records across modules from one search box.",
+	"navigation.label": "Search",
+	"notice.unavailable": "These providers did not answer in time: {providers}.",
+	"page.description": "Every module that registered a provider searches its own records under your permissions.",
+	"page.eyebrow": "Workspace",
+	"page.title": "Search",
+	"recent.clear": "Clear",
+	"recent.count": "{count} kept",
+	"recent.title": "Recent searches",
+	"search.label": "Search records",
+	"search.placeholder": "Search records…",
+	"settings.hitsPerProvider.description": "Hits one provider may answer with per page.",
+	"settings.hitsPerProvider.label": "Hits per provider",
+	"settings.providerTimeoutMs.description": "Time one provider gets per query before it is reported unavailable.",
+	"settings.providerTimeoutMs.label": "Provider time budget (ms)",
+	"table.caption": "Search hits",
+	"table.column.provider": "Provider",
+	"table.column.record": "Record",
+	"table.count": "{count} hits",
+	"table.emptyHint": "Type at least two characters to search records.",
+	"table.emptyTitle": "Nothing searched yet",
+	"table.loading": "Searching records…",
+	"table.noMatchHint": "No record matches \"{query}\" in the providers you may see.",
+	"table.noMatchTitle": "No records match",
+	"table.note": "Each provider searches its own records under the permission it declares.",
+	"table.title": "Records",
+	"table.tooShort": "Type at least {count} characters to search records."
+}

package/modules/search/translations/pl.json

@@ -0,0 +1,45 @@
+{
+	"action.loadMore": "Załaduj więcej",
+	"action.loadingMore": "Wczytywanie…",
+	"action.search": "Szukaj",
+	"action.searching": "Szukanie…",
+	"common.filters": "Filtry",
+	"denied.hint": "Nie masz uprawnień do wyszukiwania rekordów w tym obszarze roboczym.",
+	"denied.title": "Brak dostępu",
+	"error.clearRecent": "Nie udało się wyczyścić ostatnich wyszukiwań.",
+	"error.code.CURSOR_INVALID": "Strona wyników wygasła. Wyszukaj ponownie.",
+	"error.code.INVALID_INPUT": "Żądanie wyszukiwania nie zostało przyjęte.",
+	"error.code.QUERY_TOO_LONG": "Wyszukiwany tekst jest za długi.",
+	"error.load": "Nie udało się wyszukać rekordów.",
+	"error.request": "Operacja wyszukiwania nie powiodła się.",
+	"filter.allProviders": "Wszyscy dostawcy",
+	"filter.provider": "Dostawca",
+	"module.name": "Wyszukiwanie",
+	"navigation.description": "Znajdź rekordy w modułach z jednego pola wyszukiwania.",
+	"navigation.label": "Wyszukiwanie",
+	"notice.unavailable": "Ci dostawcy nie odpowiedzieli na czas: {providers}.",
+	"page.description": "Każdy moduł, który zarejestrował dostawcę, przeszukuje własne rekordy w zakresie Twoich uprawnień.",
+	"page.eyebrow": "Obszar roboczy",
+	"page.title": "Wyszukiwanie",
+	"recent.clear": "Wyczyść",
+	"recent.count": "zapisano {count}",
+	"recent.title": "Ostatnie wyszukiwania",
+	"search.label": "Szukaj rekordów",
+	"search.placeholder": "Szukaj rekordów…",
+	"settings.hitsPerProvider.description": "Liczba wyników, jaką dostawca może zwrócić na stronę.",
+	"settings.hitsPerProvider.label": "Wyniki na dostawcę",
+	"settings.providerTimeoutMs.description": "Czas, jaki dostawca dostaje na zapytanie, zanim zostanie uznany za niedostępnego.",
+	"settings.providerTimeoutMs.label": "Budżet czasu dostawcy (ms)",
+	"table.caption": "Wyniki wyszukiwania",
+	"table.column.provider": "Dostawca",
+	"table.column.record": "Rekord",
+	"table.count": "wyniki: {count}",
+	"table.emptyHint": "Wpisz co najmniej dwa znaki, aby wyszukać rekordy.",
+	"table.emptyTitle": "Nic jeszcze nie wyszukano",
+	"table.loading": "Szukanie rekordów…",
+	"table.noMatchHint": "Żaden rekord nie pasuje do \"{query}\" u dostawców, których możesz widzieć.",
+	"table.noMatchTitle": "Brak pasujących rekordów",
+	"table.note": "Każdy dostawca przeszukuje własne rekordy w zakresie deklarowanego uprawnienia.",
+	"table.title": "Rekordy",
+	"table.tooShort": "Wpisz co najmniej {count} znaki, aby wyszukać rekordy."
+}

package/modules/system/module.json

@@ -3,7 +3,7 @@
 	"schemaVersion": 1,
 	"id": "system.core",
 	"package": "@flowdular/module-system",
-	"version": "0.5.0",
+	"version": "0.7.3",
 	"profile": "full",
 	"capabilities": ["api", "client", "translations"],
 	"platform": {
@@ -14,5 +14,5 @@
 	"tenancy": "required",
 	"locales": ["en", "pl"],
 	"stability": "experimental",
-	"platformApi": "0.1.0"
+	"platformApi": "^0.1.0"
 }

package/modules/system/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@flowdular/module-system",
-	"version": "0.5.0",
+	"version": "0.7.3",
 	"type": "module",
 	"exports": {
 		".": "./src/index.ts",