1import type * as Credentials from "@distilled.cloud/aws/Credentials";
2import type * as SigV4 from "@distilled.cloud/aws/SigV4";
3import type * as Effect from "effect/Effect";
4import * as Binding from "../../Binding.ts";
5import type {
6 CountRequest,
7 CountResponse,
8 GetDocumentResponse,
9 OpenSearchApiError,
10 SearchRequest,
11 SearchResponse,
12} from "./DataPlaneTypes.ts";
13import type { Domain } from "./Domain.ts";
14
15/** Runtime client for read-only access to a domain's REST data plane. */
16export interface ReadDomainClient {
17 /**
18 * Run a Query-DSL search (`GET …/_search`). The body travels in the
19 * `source` query parameter so the request stays on `es:ESHttpGet` — no
20 * write-method IAM action is required to search.
21 */
22 search<TDoc = unknown>(
23 request?: SearchRequest,
24 ): Effect.Effect<
25 SearchResponse<TDoc>,
26 OpenSearchApiError | Credentials.CredentialsError | SigV4.SigningError
27 >;
28 /** Count documents matching a Query-DSL body (`GET …/_count`). */
29 count(
30 request?: CountRequest,
31 ): Effect.Effect<
32 CountResponse,
33 OpenSearchApiError | Credentials.CredentialsError | SigV4.SigningError
34 >;
35 /**
36 * Fetch one document by id (`GET /{index}/_doc/{id}`). A missing document
37 * is not an error — the response carries `found: false`.
38 */
39 getDocument<TDoc = unknown>(
40 index: string,
41 id: string,
42 ): Effect.Effect<
43 GetDocumentResponse<TDoc>,
44 OpenSearchApiError | Credentials.CredentialsError | SigV4.SigningError
45 >;
46 /** Check whether a document exists (`HEAD /{index}/_doc/{id}`). */
47 existsDocument(
48 index: string,
49 id: string,
50 ): Effect.Effect<
51 boolean,
52 OpenSearchApiError | Credentials.CredentialsError | SigV4.SigningError
53 >;
54 /**
55 * Raw read-only escape hatch — a SigV4-signed `GET` against any data-plane
56 * path (e.g. `_cluster/health`, `_cat/indices?format=json`).
57 */
58 get(
59 path: string,
60 query?: Record<string, string | undefined>,
61 ): Effect.Effect<
62 unknown,
63 OpenSearchApiError | Credentials.CredentialsError | SigV4.SigningError
64 >;
65}
66
67/**
68 * Runtime binding for read-only access to an OpenSearch {@link Domain}'s
69 * REST data plane (IAM actions `es:ESHttpGet` and `es:ESHttpHead` on the
70 * domain and its paths).
71 *
72 * Every request is a SigV4-signed HTTP call (service `es`) against the
73 * domain's endpoint, made with the host Function's own credentials — the
74 * domain's access policy must allow the function's role. Provide the
75 * implementation with `Effect.provide(AWS.OpenSearch.DomainReadHttp)`.
76 * ### Searching a Domain
77 * **Example:** Search Documents
78 * ```typescript
79 * // init — grants es:ESHttpGet/es:ESHttpHead on the domain
80 * const search = yield* AWS.OpenSearch.DomainRead(domain);
81 *
82 * // runtime
83 * const result = yield* search.search<{ title: string }>({
84 * index: "songs",
85 * body: { query: { match: { title: "wind" } } },
86 * });
87 * const titles = result.hits.hits.map((hit) => hit._source.title);
88 * ```
89 *
90 * **Example:** Fetch One Document
91 * ```typescript
92 * const doc = yield* search.getDocument<{ title: string }>("songs", "1");
93 * if (doc.found) yield* Effect.log(doc._source?.title);
94 * ```
95 *
96 * @binding
97 */
98export interface DomainRead extends Binding.Service<
99 DomainRead,
100 "AWS.OpenSearch.DomainRead",
101 (domain: Domain) => Effect.Effect<ReadDomainClient>
102> {}
103export const DomainRead = Binding.Service<DomainRead>(
104 "AWS.OpenSearch.DomainRead",
105);