@crowi/plugin-search-elasticsearch 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Sotaro KARASAWA <sotaro.k@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# @crowi/plugin-search-elasticsearch
+
+Elasticsearch 9 search driver for Crowi 2.0. Indexes pages on create /
+update / delete, serves the wiki search box, and rebuilds the whole
+index from scratch on demand. Targets a `<indexName>-current` alias so
+a rebuild can swap the underlying index atomically.
+
+## Install
+
+```bash
+crowi-admin plugin add @crowi/plugin-search-elasticsearch
+```
+
+(or, in dev: `pnpm --filter @crowi/api add -D @crowi/plugin-search-elasticsearch`)
+
+## Configure
+
+### 1. Activate the driver in `crowi.config.json`
+
+```jsonc
+{
+  "plugins": ["@crowi/plugin-search-elasticsearch"],
+  "search": { "driver": "elasticsearch" }
+}
+```
+
+A server restart is required when `search.driver` changes — Crowi
+reads this file once at boot.
+
+### 2. Fill in connection settings in the admin UI
+
+Open `/admin/plugins` and edit `@crowi/plugin-search-elasticsearch`:
+
+- **`url`** — `https://[user:pass@]host[:port][/indexName]`. The URL
+  embeds the cluster password (Bonsai-style), so it is encrypted at
+  rest with `CROWI_ENCRYPTION_KEY`.
+- **`indexName`** — base index name (default `crowi`). The driver
+  reads / writes the `<indexName>-current` alias.
+- **`requestTimeout`** — per-request timeout in ms (default `5000`).
+- **`analyzer`** — `default` / `kuromoji` / `sudachi` (see below).
+
+## Hot-reload (no restart needed)
+
+This plugin implements `reconfigure`, so **saving connection settings
+in the admin UI applies without a server restart**. When you save:
+
+- the `url` / `indexName` / `requestTimeout` / `analyzer` changes are
+  picked up by the live driver,
+- a fresh Elasticsearch client is built and the previous one is closed
+  in the background (its HTTP keep-alive pool drains),
+- the admin UI shows a "saved — applied immediately" toast.
+
+Mechanics: the driver holds a module-scope state ref; each operation
+(`query` / `index` / `remove` / `rebuild`) snapshots the state once at
+the top of the call, so a save that lands mid-request cannot retarget
+an inflight operation onto a different cluster. The next request sees
+the new settings.
+
+### Caveats
+
+- **Analyzer changes need a manual rebuild.** Switching `analyzer`
+  (`default` ↔ `kuromoji` ↔ `sudachi`) updates the setting immediately,
+  but the **existing index keeps its old analyzer** — Elasticsearch
+  analyzers are fixed at index-creation time. Run a full rebuild from
+  `/admin/search` (or the rebuild action) to create a new index with
+  the new analyzer and swap the alias to it.
+- **Empty `url` → configured `url` is restart-only.** If `url` was
+  empty at boot, the driver is not registered and there is nothing for
+  `reconfigure` to mutate; configure a `url` and restart once. After
+  that, all further changes hot-reload. Clearing a configured `url`
+  (configured → empty) *is* handled live — search requests then fail
+  with a clear `Search not configured` error until a `url` is set again.
+- A rebuild that is already running when you reconfigure runs to
+  completion against the cluster / index name it started with.
+
+## Analyzer flavours
+
+| Analyzer | Cluster requirement |
+|---|---|
+| `default` | No extra Elasticsearch plugin. |
+| `kuromoji` | `analysis-kuromoji` plugin (Elastic-distributed). The dev image (`elasticsearch.Dockerfile`) preinstalls it. |
+| `sudachi` | Third-party `analysis-sudachi` plugin + dictionary. **Not** bundled in the dev image — operators must build a derived image. Picking this without the plugin makes `rebuild()` fail. |
+
+## Verifying hot-reload in dev
+
+The dev `docker compose` stack includes an Elasticsearch service, so
+you can exercise the hot-reload path end to end:
+
+1. `docker compose up -d` — brings up mongo / redis / elasticsearch.
+2. `pnpm dev` — starts api + web.
+3. In `/admin/plugins`, set `@crowi/plugin-search-elasticsearch`'s
+   `url` to `http://elasticsearch:9200/crowi` and save; restart once if
+   the driver was previously unconfigured.
+4. From `/admin/search`, run a rebuild to populate the index.
+5. Change `requestTimeout` (or point `indexName` at a freshly rebuilt
+   index) and save **without restarting**. The next search query uses
+   the new settings — confirmed by the api log line
+   `reconfigured elasticsearch search driver (...)`.
+
+## See also
+
+- RFC-0001 §"Search" for the migration story from the legacy ES7 indexer.
+- [`@crowi/plugin-storage-aws-s3`](../plugin-storage-aws-s3) — the
+  reference implementation of the same state-ref + snapshot hot-reload
+  pattern.

package/dist/index.d.mts

@@ -0,0 +1,250 @@
+import { z } from 'zod/v3';
+import { SearchDriver, PluginLogger, SearchQueryViewer, SearchQueryGrants, CrowiPlugin } from '@crowi/plugin-api';
+import { Client } from '@elastic/elasticsearch';
+
+/**
+ * Elasticsearch 9 driver implementing the `SearchDriver` contract.
+ * Owns the Client, the `${indexName}-current` alias (legacy ops
+ * compat), single-doc index / remove, query against the alias, and
+ * rebuild-from-scratch in 2k-doc bulk batches with bookmark counts
+ * pre-fetched in one aggregate. Document field shape (path / body /
+ * username / grant / granted_users / *_count / *_at) matches the
+ * legacy ES7 indexer for reindex-free migration.
+ */
+
+type Analyzer = 'default' | 'kuromoji' | 'sudachi';
+interface ElasticsearchDriverConfig {
+    url: string;
+    indexName: string;
+    requestTimeout: number;
+    analyzer: Analyzer;
+}
+interface ElasticsearchDriverDeps {
+    log?: PluginLogger;
+    /**
+     * Iterate every page in the Mongo Page collection in cursor-style.
+     * Plugin can't import the Page model directly, so the manager wires
+     * this in from `ctx.model('Page')`. Each yielded doc is the lean
+     * shape produced by `Page.getStreamOfFindAll({ publicOnly: false })`.
+     */
+    iteratePages?: (handler: (page: PageStreamDoc) => Promise<void>) => Promise<void>;
+    /** Total page count, used for progress reporting. */
+    countAllPages?: () => Promise<number>;
+    /**
+     * Bulk-fetch bookmark counts for every page in one Mongo aggregate.
+     * Avoids the per-doc N+1 lookup the legacy rebuild used. Returns a
+     * `Map<pageId, count>`; pages without bookmarks may be absent
+     * (caller defaults to 0).
+     */
+    getBookmarkCountsBulk?: () => Promise<Map<string, number>>;
+    /** Total user count, used to scale the bookmark-count factor. */
+    countUsers?: () => Promise<number>;
+}
+/** The lean Page document shape we expect from the rebuild stream. */
+interface PageStreamDoc {
+    _id: {
+        toString: () => string;
+    } | string;
+    path: string;
+    redirectTo: string | null;
+    status: string;
+    grant: number;
+    grantedUsers?: Array<{
+        toString: () => string;
+    } | string>;
+    creator?: {
+        username?: string;
+    };
+    revision?: {
+        body?: string;
+    };
+    liker?: unknown[];
+    commentCount?: number;
+    bookmarkCount?: number;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+interface ElasticsearchDriver extends SearchDriver {
+    /** Currently-targeted alias name (`<indexName>-current`). Exposed for tests / admin UI. */
+    readonly aliasName: string;
+    /** ES node URI parsed out of `config.url`. */
+    readonly node: string;
+    /** Base index name (without timestamp / `-current` suffix). */
+    readonly baseIndexName: string;
+    /** Test-only handle to the underlying client. */
+    readonly client: Client;
+}
+/**
+ * Mutable driver state. `createElasticsearchDriver` receives a ref to
+ * this; each driver method snapshots the fields it needs *once at the
+ * top* of the call, so a concurrent `reconfigure` cannot swap the
+ * client / index name mid-operation. `reconfigure` mutates the fields
+ * in place via {@link applyConfigInPlace}; the next call sees the new
+ * values. An empty `url` leaves `client` as `null` — the methods then
+ * throw a `Search not configured` error rather than touching a stale
+ * client.
+ */
+interface ESDriverState {
+    /** `null` when `url` is empty (driver configured-but-disabled). */
+    client: Client | null;
+    /** ES node URI parsed out of `config.url`; empty string when `url` is empty. */
+    node: string;
+    /** Base index name (without timestamp / `-current` suffix). */
+    baseIndexName: string;
+    /** Runtime alias the driver reads / writes (`<baseIndexName>-current`). */
+    aliasName: string;
+    analyzer: Analyzer;
+    requestTimeout: number;
+}
+/**
+ * Build a fresh {@link ESDriverState} from a config. An empty `url`
+ * yields a disabled state (`client: null`) instead of throwing — the
+ * driver stays registered but every method rejects with a
+ * `Search not configured` error.
+ */
+declare function applyConfig(config: ElasticsearchDriverConfig): ESDriverState;
+/**
+ * Mutate `target` in place to reflect `config`. Used by `reconfigure`:
+ * the old client reference is returned so the caller can `close()` it
+ * (fire-and-forget) once the swap is done — inflight operations have
+ * already snapshotted the old client and will run to completion.
+ */
+declare function applyConfigInPlace(target: ESDriverState, config: ElasticsearchDriverConfig): {
+    oldClient: Client | null;
+};
+/**
+ * Build the search driver around a {@link ESDriverState} ref. Methods
+ * snapshot `state` *once at the top* — a `reconfigure` running
+ * concurrently with an inflight call cannot swap the client mid-call;
+ * the next call sees the new client / index name.
+ */
+declare function createElasticsearchDriver(state: ESDriverState, deps?: ElasticsearchDriverDeps): ElasticsearchDriver;
+
+/**
+ * Search-string parser for the Elasticsearch driver.
+ *
+ * Splits a free-form query into positive / negative keywords and
+ * phrases. Lifted from the legacy `packages/api/src/service/query.ts`
+ * with no behaviour changes — preserved here as a plugin-private
+ * helper because the parser is currently ES-specific (the +/- and
+ * `"phrase"` syntax maps directly to ES `multi_match` queries). When
+ * a future driver wants the same shape, factor it back into
+ * `@crowi/plugin-api`.
+ */
+type PositiveAndNegative<T> = {
+    positive: T;
+    negative: T;
+};
+type ParsedSearchQuery = {
+    keywords: PositiveAndNegative<string[]>;
+    phrases: PositiveAndNegative<string[]>;
+};
+declare const parseQuery: (query: string) => ParsedSearchQuery;
+
+/**
+ * Build an Elasticsearch 8 search request body from the SearchQuery
+ * shape exposed by `@crowi/plugin-api`. The driver passes a parsed
+ * keyword/phrase tree plus the viewer + grants from the original
+ * SearchQuery; this module composes them into a single bool query.
+ *
+ * Design notes:
+ *   - All filters are composed at the top-level `bool`. We never nest
+ *     a second `bool` for the same operator type (must / filter /
+ *     should / must_not), so the generated body is small and easy to
+ *     diff in tests.
+ *   - The grant filter mirrors the legacy ES Searcher precisely:
+ *     a non-public page (RESTRICTED / SPECIFIED / OWNER) is hidden
+ *     unless its `username` field matches the viewer's username.
+ *     For SPECIFIED / OWNER / RESTRICTED pages, we additionally allow
+ *     the page through if `granted_users` contains the viewer id —
+ *     the legacy query only checked `username`, but the new
+ *     SearchableDoc lets us index `granted_users` precisely so we
+ *     can express "shared with me" as well.
+ *   - Type filter (portal / public / user) reproduces the legacy
+ *     `path.raw` regex / prefix queries.
+ */
+
+type FunctionScoreParams = {
+    fieldValueFactor: {
+        field: string;
+        factor?: number;
+        modifier?: 'log' | 'log1p' | 'log2p' | 'ln' | 'ln1p' | 'ln2p' | 'square' | 'sqrt' | 'reciprocal' | 'none';
+        missing: number;
+    };
+    boostMode: 'multiply' | 'replace' | 'sum' | 'avg' | 'max' | 'min';
+};
+interface BuildSearchBodyParams {
+    parsed: ParsedSearchQuery;
+    pathPrefix?: string;
+    viewer?: SearchQueryViewer;
+    grants?: SearchQueryGrants;
+    functionScore?: FunctionScoreParams;
+    from: number;
+    size: number;
+}
+/**
+ * Build the ES9 search request body. Returns an object suitable for
+ * `client.search({ index, ...body })`.
+ */
+declare function buildSearchBody(params: BuildSearchBodyParams): {
+    from: number;
+    size: number;
+    sort: Array<Record<string, unknown>>;
+    highlight: Record<string, unknown>;
+    query: Record<string, unknown>;
+    _source: string[];
+};
+
+/**
+ * @crowi/plugin-search-elasticsearch — search driver registering
+ * `'elasticsearch'` against the SearchRegistry.
+ *
+ * Activation: add this plugin to the runner's `crowi.config.json`
+ * `plugins` array and set `search.driver: 'elasticsearch'`. Configure
+ * via the Mongo Config namespace `plugin:@crowi/plugin-search-elasticsearch:*`
+ * — operators set the connection URL exclusively from the admin UI.
+ */
+
+declare const ElasticsearchConfigSchema: z.ZodObject<{
+    /**
+     * `https://[user:pass@]host[:port][/indexName]`. Empty string keeps
+     * the driver registered but disabled — `query()` will throw a
+     * helpful error and `index()` becomes a no-op.
+     *
+     * Marked `@sensitive` because the URL embeds the cluster password
+     * (Bonsai-style `https://USER:PASS@HOST/INDEX`); we don't want
+     * Mongo to keep it in plaintext.
+     */
+    url: z.ZodDefault<z.ZodString>;
+    /**
+     * Base index name. Used as the `indexName` if not provided in the
+     * URL path. The runtime alias `${indexName}-current` is what the
+     * driver actually targets for read / write.
+     */
+    indexName: z.ZodDefault<z.ZodString>;
+    requestTimeout: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Mapping flavour. Cluster requirements:
+     *   - `default`: no extra ES plugin.
+     *   - `kuromoji`: `analysis-kuromoji` plugin (Elastic-distributed).
+     *     The dev image (`elasticsearch.Dockerfile`) preinstalls it.
+     *   - `sudachi`: third-party `analysis-sudachi` plugin + dictionary.
+     *     NOT bundled in the dev image; operators must build a derived
+     *     image. Picking this without the plugin makes `rebuild()` fail.
+     */
+    analyzer: z.ZodDefault<z.ZodEnum<["default", "kuromoji", "sudachi"]>>;
+}, "strict", z.ZodTypeAny, {
+    url: string;
+    indexName: string;
+    requestTimeout: number;
+    analyzer: "default" | "kuromoji" | "sudachi";
+}, {
+    url?: string | undefined;
+    indexName?: string | undefined;
+    requestTimeout?: number | undefined;
+    analyzer?: "default" | "kuromoji" | "sudachi" | undefined;
+}>;
+type ElasticsearchConfig = z.infer<typeof ElasticsearchConfigSchema>;
+declare const plugin: CrowiPlugin;
+
+export { type Analyzer, type ESDriverState, type ElasticsearchConfig, ElasticsearchConfigSchema, type ElasticsearchDriver, type ElasticsearchDriverConfig, type ElasticsearchDriverDeps, type PageStreamDoc, applyConfig, applyConfigInPlace, buildSearchBody, createElasticsearchDriver, plugin as default, parseQuery };

package/dist/index.d.ts

@@ -0,0 +1,250 @@
+import { z } from 'zod/v3';
+import { SearchDriver, PluginLogger, SearchQueryViewer, SearchQueryGrants, CrowiPlugin } from '@crowi/plugin-api';
+import { Client } from '@elastic/elasticsearch';
+
+/**
+ * Elasticsearch 9 driver implementing the `SearchDriver` contract.
+ * Owns the Client, the `${indexName}-current` alias (legacy ops
+ * compat), single-doc index / remove, query against the alias, and
+ * rebuild-from-scratch in 2k-doc bulk batches with bookmark counts
+ * pre-fetched in one aggregate. Document field shape (path / body /
+ * username / grant / granted_users / *_count / *_at) matches the
+ * legacy ES7 indexer for reindex-free migration.
+ */
+
+type Analyzer = 'default' | 'kuromoji' | 'sudachi';
+interface ElasticsearchDriverConfig {
+    url: string;
+    indexName: string;
+    requestTimeout: number;
+    analyzer: Analyzer;
+}
+interface ElasticsearchDriverDeps {
+    log?: PluginLogger;
+    /**
+     * Iterate every page in the Mongo Page collection in cursor-style.
+     * Plugin can't import the Page model directly, so the manager wires
+     * this in from `ctx.model('Page')`. Each yielded doc is the lean
+     * shape produced by `Page.getStreamOfFindAll({ publicOnly: false })`.
+     */
+    iteratePages?: (handler: (page: PageStreamDoc) => Promise<void>) => Promise<void>;
+    /** Total page count, used for progress reporting. */
+    countAllPages?: () => Promise<number>;
+    /**
+     * Bulk-fetch bookmark counts for every page in one Mongo aggregate.
+     * Avoids the per-doc N+1 lookup the legacy rebuild used. Returns a
+     * `Map<pageId, count>`; pages without bookmarks may be absent
+     * (caller defaults to 0).
+     */
+    getBookmarkCountsBulk?: () => Promise<Map<string, number>>;
+    /** Total user count, used to scale the bookmark-count factor. */
+    countUsers?: () => Promise<number>;
+}
+/** The lean Page document shape we expect from the rebuild stream. */
+interface PageStreamDoc {
+    _id: {
+        toString: () => string;
+    } | string;
+    path: string;
+    redirectTo: string | null;
+    status: string;
+    grant: number;
+    grantedUsers?: Array<{
+        toString: () => string;
+    } | string>;
+    creator?: {
+        username?: string;
+    };
+    revision?: {
+        body?: string;
+    };
+    liker?: unknown[];
+    commentCount?: number;
+    bookmarkCount?: number;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+interface ElasticsearchDriver extends SearchDriver {
+    /** Currently-targeted alias name (`<indexName>-current`). Exposed for tests / admin UI. */
+    readonly aliasName: string;
+    /** ES node URI parsed out of `config.url`. */
+    readonly node: string;
+    /** Base index name (without timestamp / `-current` suffix). */
+    readonly baseIndexName: string;
+    /** Test-only handle to the underlying client. */
+    readonly client: Client;
+}
+/**
+ * Mutable driver state. `createElasticsearchDriver` receives a ref to
+ * this; each driver method snapshots the fields it needs *once at the
+ * top* of the call, so a concurrent `reconfigure` cannot swap the
+ * client / index name mid-operation. `reconfigure` mutates the fields
+ * in place via {@link applyConfigInPlace}; the next call sees the new
+ * values. An empty `url` leaves `client` as `null` — the methods then
+ * throw a `Search not configured` error rather than touching a stale
+ * client.
+ */
+interface ESDriverState {
+    /** `null` when `url` is empty (driver configured-but-disabled). */
+    client: Client | null;
+    /** ES node URI parsed out of `config.url`; empty string when `url` is empty. */
+    node: string;
+    /** Base index name (without timestamp / `-current` suffix). */
+    baseIndexName: string;
+    /** Runtime alias the driver reads / writes (`<baseIndexName>-current`). */
+    aliasName: string;
+    analyzer: Analyzer;
+    requestTimeout: number;
+}
+/**
+ * Build a fresh {@link ESDriverState} from a config. An empty `url`
+ * yields a disabled state (`client: null`) instead of throwing — the
+ * driver stays registered but every method rejects with a
+ * `Search not configured` error.
+ */
+declare function applyConfig(config: ElasticsearchDriverConfig): ESDriverState;
+/**
+ * Mutate `target` in place to reflect `config`. Used by `reconfigure`:
+ * the old client reference is returned so the caller can `close()` it
+ * (fire-and-forget) once the swap is done — inflight operations have
+ * already snapshotted the old client and will run to completion.
+ */
+declare function applyConfigInPlace(target: ESDriverState, config: ElasticsearchDriverConfig): {
+    oldClient: Client | null;
+};
+/**
+ * Build the search driver around a {@link ESDriverState} ref. Methods
+ * snapshot `state` *once at the top* — a `reconfigure` running
+ * concurrently with an inflight call cannot swap the client mid-call;
+ * the next call sees the new client / index name.
+ */
+declare function createElasticsearchDriver(state: ESDriverState, deps?: ElasticsearchDriverDeps): ElasticsearchDriver;
+
+/**
+ * Search-string parser for the Elasticsearch driver.
+ *
+ * Splits a free-form query into positive / negative keywords and
+ * phrases. Lifted from the legacy `packages/api/src/service/query.ts`
+ * with no behaviour changes — preserved here as a plugin-private
+ * helper because the parser is currently ES-specific (the +/- and
+ * `"phrase"` syntax maps directly to ES `multi_match` queries). When
+ * a future driver wants the same shape, factor it back into
+ * `@crowi/plugin-api`.
+ */
+type PositiveAndNegative<T> = {
+    positive: T;
+    negative: T;
+};
+type ParsedSearchQuery = {
+    keywords: PositiveAndNegative<string[]>;
+    phrases: PositiveAndNegative<string[]>;
+};
+declare const parseQuery: (query: string) => ParsedSearchQuery;
+
+/**
+ * Build an Elasticsearch 8 search request body from the SearchQuery
+ * shape exposed by `@crowi/plugin-api`. The driver passes a parsed
+ * keyword/phrase tree plus the viewer + grants from the original
+ * SearchQuery; this module composes them into a single bool query.
+ *
+ * Design notes:
+ *   - All filters are composed at the top-level `bool`. We never nest
+ *     a second `bool` for the same operator type (must / filter /
+ *     should / must_not), so the generated body is small and easy to
+ *     diff in tests.
+ *   - The grant filter mirrors the legacy ES Searcher precisely:
+ *     a non-public page (RESTRICTED / SPECIFIED / OWNER) is hidden
+ *     unless its `username` field matches the viewer's username.
+ *     For SPECIFIED / OWNER / RESTRICTED pages, we additionally allow
+ *     the page through if `granted_users` contains the viewer id —
+ *     the legacy query only checked `username`, but the new
+ *     SearchableDoc lets us index `granted_users` precisely so we
+ *     can express "shared with me" as well.
+ *   - Type filter (portal / public / user) reproduces the legacy
+ *     `path.raw` regex / prefix queries.
+ */
+
+type FunctionScoreParams = {
+    fieldValueFactor: {
+        field: string;
+        factor?: number;
+        modifier?: 'log' | 'log1p' | 'log2p' | 'ln' | 'ln1p' | 'ln2p' | 'square' | 'sqrt' | 'reciprocal' | 'none';
+        missing: number;
+    };
+    boostMode: 'multiply' | 'replace' | 'sum' | 'avg' | 'max' | 'min';
+};
+interface BuildSearchBodyParams {
+    parsed: ParsedSearchQuery;
+    pathPrefix?: string;
+    viewer?: SearchQueryViewer;
+    grants?: SearchQueryGrants;
+    functionScore?: FunctionScoreParams;
+    from: number;
+    size: number;
+}
+/**
+ * Build the ES9 search request body. Returns an object suitable for
+ * `client.search({ index, ...body })`.
+ */
+declare function buildSearchBody(params: BuildSearchBodyParams): {
+    from: number;
+    size: number;
+    sort: Array<Record<string, unknown>>;
+    highlight: Record<string, unknown>;
+    query: Record<string, unknown>;
+    _source: string[];
+};
+
+/**
+ * @crowi/plugin-search-elasticsearch — search driver registering
+ * `'elasticsearch'` against the SearchRegistry.
+ *
+ * Activation: add this plugin to the runner's `crowi.config.json`
+ * `plugins` array and set `search.driver: 'elasticsearch'`. Configure
+ * via the Mongo Config namespace `plugin:@crowi/plugin-search-elasticsearch:*`
+ * — operators set the connection URL exclusively from the admin UI.
+ */
+
+declare const ElasticsearchConfigSchema: z.ZodObject<{
+    /**
+     * `https://[user:pass@]host[:port][/indexName]`. Empty string keeps
+     * the driver registered but disabled — `query()` will throw a
+     * helpful error and `index()` becomes a no-op.
+     *
+     * Marked `@sensitive` because the URL embeds the cluster password
+     * (Bonsai-style `https://USER:PASS@HOST/INDEX`); we don't want
+     * Mongo to keep it in plaintext.
+     */
+    url: z.ZodDefault<z.ZodString>;
+    /**
+     * Base index name. Used as the `indexName` if not provided in the
+     * URL path. The runtime alias `${indexName}-current` is what the
+     * driver actually targets for read / write.
+     */
+    indexName: z.ZodDefault<z.ZodString>;
+    requestTimeout: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Mapping flavour. Cluster requirements:
+     *   - `default`: no extra ES plugin.
+     *   - `kuromoji`: `analysis-kuromoji` plugin (Elastic-distributed).
+     *     The dev image (`elasticsearch.Dockerfile`) preinstalls it.
+     *   - `sudachi`: third-party `analysis-sudachi` plugin + dictionary.
+     *     NOT bundled in the dev image; operators must build a derived
+     *     image. Picking this without the plugin makes `rebuild()` fail.
+     */
+    analyzer: z.ZodDefault<z.ZodEnum<["default", "kuromoji", "sudachi"]>>;
+}, "strict", z.ZodTypeAny, {
+    url: string;
+    indexName: string;
+    requestTimeout: number;
+    analyzer: "default" | "kuromoji" | "sudachi";
+}, {
+    url?: string | undefined;
+    indexName?: string | undefined;
+    requestTimeout?: number | undefined;
+    analyzer?: "default" | "kuromoji" | "sudachi" | undefined;
+}>;
+type ElasticsearchConfig = z.infer<typeof ElasticsearchConfigSchema>;
+declare const plugin: CrowiPlugin;
+
+export { type Analyzer, type ESDriverState, type ElasticsearchConfig, ElasticsearchConfigSchema, type ElasticsearchDriver, type ElasticsearchDriverConfig, type ElasticsearchDriverDeps, type PageStreamDoc, applyConfig, applyConfigInPlace, buildSearchBody, createElasticsearchDriver, plugin as default, parseQuery };