@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 673 lines 22.5 KB
Raw
1 import * as opensearch from "@distilled.cloud/aws/opensearch";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import { createPhysicalName } from "alchemy/PhysicalName";
5 import * as Provider from "alchemy/Provider";
6 import { Resource } from "alchemy/Resource";
7 import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
8 import { subsetDiffers } from "alchemy/Util/equal";
9 import * as Data from "effect/Data";
10 import * as Effect from "effect/Effect";
11 import type { PolicyDocument } from "../IAM/Policy.ts";
12 import { normalizePolicyDocument, stringifyPolicyDocument } from "../IAM/Policy.ts";
13 import type { Providers } from "../Providers.ts";
14 import {
15 domainEndpoint,
16 isDomainActive,
17 isDomainDeletable,
18 readDomainTags,
19 repeatUntilDomainState,
20 } from "./internal.ts";
21
22 export class OpenSearchDomainUnexpectedResponse extends Data.TaggedError(
23 "OpenSearchDomainUnexpectedResponse",
24 )<{
25 readonly message: string;
26 readonly cause?: unknown;
27 }> {}
28
29 export interface DomainClusterConfig {
30 /**
31 * Instance type of the data nodes, e.g. `"t3.small.search"` (the cheapest
32 * general-purpose type) or `"r7g.large.search"`.
33 * @default "t3.small.search"
34 */
35 instanceType?: opensearch.OpenSearchPartitionInstanceType;
36 /**
37 * Number of data nodes in the cluster.
38 * @default 1
39 */
40 instanceCount?: number;
41 /**
42 * Whether dedicated master nodes are enabled.
43 */
44 dedicatedMasterEnabled?: boolean;
45 /**
46 * Instance type of the dedicated master nodes.
47 */
48 dedicatedMasterType?: opensearch.OpenSearchPartitionInstanceType;
49 /**
50 * Number of dedicated master nodes (3 or 5 recommended).
51 */
52 dedicatedMasterCount?: number;
53 /**
54 * Whether data is distributed across multiple Availability Zones.
55 */
56 zoneAwarenessEnabled?: boolean;
57 /**
58 * Number of Availability Zones (2 or 3) when zone awareness is enabled.
59 */
60 availabilityZoneCount?: number;
61 /**
62 * Whether UltraWarm storage is enabled. Not supported on t2/t3 instances.
63 */
64 warmEnabled?: boolean;
65 /**
66 * Instance type of the UltraWarm nodes.
67 */
68 warmType?: opensearch.OpenSearchWarmPartitionInstanceType;
69 /**
70 * Number of UltraWarm nodes.
71 */
72 warmCount?: number;
73 /**
74 * Whether the domain runs in Multi-AZ with Standby mode.
75 */
76 multiAZWithStandbyEnabled?: boolean;
77 }
78
79 export interface DomainEbsOptions {
80 /**
81 * Whether EBS volumes are attached to the data nodes. Required for
82 * EBS-only instance types like `t3.small.search`.
83 * @default true
84 */
85 enabled?: boolean;
86 /**
87 * EBS volume type.
88 * @default "gp3"
89 */
90 volumeType?: opensearch.VolumeType;
91 /**
92 * EBS volume size in GiB per data node.
93 * @default 10
94 */
95 volumeSize?: number;
96 /**
97 * Provisioned IOPS (io1/gp3 volumes).
98 */
99 iops?: number;
100 /**
101 * Provisioned throughput in MiB/s (gp3 volumes).
102 */
103 throughput?: number;
104 }
105
106 export interface DomainEncryptionAtRestOptions {
107 /**
108 * Whether encryption at rest is enabled. Enabling on an existing domain is
109 * an in-place update; DISABLING it is not supported and replaces the
110 * domain. Not supported on t2 instance types.
111 * @default true when `encryptionAtRest` is specified
112 */
113 enabled?: boolean;
114 /**
115 * Customer-managed KMS key ID used for encryption.
116 * @default the AWS-owned aws/es key
117 */
118 kmsKeyId?: string;
119 }
120
121 export interface DomainEndpointOptionsProps {
122 /**
123 * Whether all traffic to the domain must arrive over HTTPS.
124 */
125 enforceHTTPS?: boolean;
126 /**
127 * Minimum TLS version for HTTPS connections, e.g.
128 * `"Policy-Min-TLS-1-2-2019-07"`.
129 */
130 tlsSecurityPolicy?: opensearch.TLSSecurityPolicy;
131 /**
132 * Whether a custom endpoint is enabled for the domain.
133 */
134 customEndpointEnabled?: boolean;
135 /**
136 * Fully qualified custom endpoint, e.g. `"search.example.com"`.
137 */
138 customEndpoint?: string;
139 /**
140 * ACM certificate ARN for the custom endpoint.
141 */
142 customEndpointCertificateArn?: string;
143 }
144
145 export interface DomainSnapshotOptions {
146 /**
147 * Hour of the day (0-23, UTC) when automated snapshots are taken.
148 */
149 automatedSnapshotStartHour?: number;
150 }
151
152 export interface DomainVpcOptions {
153 /**
154 * Subnet IDs the domain's endpoints are placed into. One subnet unless
155 * zone awareness is enabled.
156 */
157 subnetIds?: string[];
158 /**
159 * Security group IDs applied to the domain's network interfaces.
160 */
161 securityGroupIds?: string[];
162 }
163
164 export interface DomainProps {
165 /**
166 * Name of the domain. 3-28 characters; lowercase letters, numbers, and
167 * hyphens; must start with a lowercase letter. If omitted, a deterministic
168 * physical name is generated. Changing the name replaces the domain.
169 */
170 domainName?: string;
171 /**
172 * Engine version, e.g. `"OpenSearch_2.19"` or `"Elasticsearch_7.10"`.
173 * Raising the version triggers an in-place engine upgrade.
174 * @default the latest OpenSearch version
175 */
176 engineVersion?: string;
177 /**
178 * Cluster topology: data node type/count, dedicated masters, zone
179 * awareness, and UltraWarm.
180 * @default a single t3.small.search data node
181 */
182 clusterConfig?: DomainClusterConfig;
183 /**
184 * EBS storage attached to each data node.
185 * @default 10 GiB gp3
186 */
187 ebsOptions?: DomainEbsOptions;
188 /**
189 * IAM resource-based access policy document controlling who can reach the
190 * domain endpoint, either as a structured {@link PolicyDocument} or a raw
191 * JSON string (escape hatch / adoption of pre-existing policies).
192 */
193 accessPolicies?: PolicyDocument | string;
194 /**
195 * IP address type of the endpoint — `"ipv4"` or `"dualstack"`.
196 */
197 ipAddressType?: opensearch.IPAddressType;
198 /**
199 * VPC placement for the domain endpoints. Omit for a public endpoint.
200 */
201 vpcOptions?: DomainVpcOptions;
202 /**
203 * Encryption of data at rest. Disabling on an existing domain replaces it.
204 */
205 encryptionAtRest?: DomainEncryptionAtRestOptions;
206 /**
207 * Whether node-to-node (in transit) encryption is enabled. Disabling on an
208 * existing domain replaces it.
209 */
210 nodeToNodeEncryption?: boolean;
211 /**
212 * Advanced OpenSearch settings, e.g.
213 * `{ "rest.action.multi.allow_explicit_index": "true" }`.
214 */
215 advancedOptions?: Record<string, string>;
216 /**
217 * HTTPS enforcement, TLS policy, and custom endpoint configuration.
218 */
219 domainEndpointOptions?: DomainEndpointOptionsProps;
220 /**
221 * Automated snapshot configuration.
222 */
223 snapshotOptions?: DomainSnapshotOptions;
224 /**
225 * User-defined tags for the domain.
226 */
227 tags?: Record<string, string>;
228 }
229
230 export interface Domain extends Resource<
231 "AWS.OpenSearch.Domain",
232 DomainProps,
233 {
234 /**
235 * Name of the domain.
236 */
237 domainName: string;
238 /**
239 * ARN of the domain.
240 */
241 domainArn: string;
242 /**
243 * Unique identifier of the domain (`account-id/domain-name`).
244 */
245 domainId: string;
246 /**
247 * Engine version running on the domain (e.g. `OpenSearch_2.19`).
248 */
249 engineVersion: string | undefined;
250 /**
251 * Domain-specific HTTPS endpoint for search and index requests.
252 */
253 endpoint: string | undefined;
254 /**
255 * Whether domain creation has completed.
256 */
257 created: boolean;
258 /**
259 * Whether a configuration change is currently being applied.
260 */
261 processing: boolean;
262 /**
263 * Tags on the domain.
264 */
265 tags: Record<string, string>;
266 },
267 never,
268 Providers
269 > {}
270
271 /**
272 * An Amazon OpenSearch Service domain — a managed OpenSearch/Elasticsearch
273 * cluster with a search/HTTP endpoint.
274 *
275 * Domains take roughly 15-25 minutes to provision (and about as long for
276 * blue/green configuration changes) and are billed per instance-hour while
277 * they exist. Destroy domains you are not using.
278 * ### Creating a Domain
279 * **Example:** Minimal Domain
280 * ```typescript
281 * // A single t3.small.search node with 10 GiB of gp3 EBS storage.
282 * const domain = yield* Domain("Search", {});
283 * ```
284 *
285 * **Example:** Encrypted Domain with Access Policy
286 * ```typescript
287 * const domain = yield* Domain("Search", {
288 * engineVersion: "OpenSearch_2.19",
289 * clusterConfig: { instanceType: "t3.small.search", instanceCount: 1 },
290 * ebsOptions: { volumeType: "gp3", volumeSize: 10 },
291 * encryptionAtRest: { enabled: true },
292 * nodeToNodeEncryption: true,
293 * domainEndpointOptions: {
294 * enforceHTTPS: true,
295 * tlsSecurityPolicy: "Policy-Min-TLS-1-2-2019-07",
296 * },
297 * accessPolicies: {
298 * Version: "2012-10-17",
299 * Statement: [
300 * {
301 * Effect: "Allow",
302 * Principal: { AWS: `arn:aws:iam::${accountId}:root` },
303 * Action: ["es:*"],
304 * Resource: `arn:aws:es:${region}:${accountId}:domain/*`,
305 * },
306 * ],
307 * },
308 * });
309 * ```
310 *
311 * ### Multi-AZ Cluster
312 * **Example:** Zone-Aware Cluster
313 * ```typescript
314 * const domain = yield* Domain("Search", {
315 * clusterConfig: {
316 * instanceType: "r7g.large.search",
317 * instanceCount: 2,
318 * zoneAwarenessEnabled: true,
319 * availabilityZoneCount: 2,
320 * },
321 * });
322 * ```
323 *
324 * @resource
325 */
326 export const Domain = Resource<Domain>("AWS.OpenSearch.Domain");
327
328 const DEFAULT_INSTANCE_TYPE = "t3.small.search";
329
330 const toClusterConfig = (config: DomainClusterConfig | undefined): opensearch.ClusterConfig => ({
331 InstanceType: config?.instanceType ?? DEFAULT_INSTANCE_TYPE,
332 InstanceCount: config?.instanceCount ?? 1,
333 DedicatedMasterEnabled: config?.dedicatedMasterEnabled,
334 DedicatedMasterType: config?.dedicatedMasterType,
335 DedicatedMasterCount: config?.dedicatedMasterCount,
336 ZoneAwarenessEnabled: config?.zoneAwarenessEnabled,
337 ZoneAwarenessConfig:
338 config?.availabilityZoneCount !== undefined
339 ? { AvailabilityZoneCount: config.availabilityZoneCount }
340 : undefined,
341 WarmEnabled: config?.warmEnabled,
342 WarmType: config?.warmType,
343 WarmCount: config?.warmCount,
344 MultiAZWithStandbyEnabled: config?.multiAZWithStandbyEnabled,
345 });
346
347 const toEbsOptions = (ebs: DomainEbsOptions | undefined): opensearch.EBSOptions =>
348 ebs?.enabled === false
349 ? { EBSEnabled: false }
350 : {
351 EBSEnabled: true,
352 VolumeType: ebs?.volumeType ?? "gp3",
353 VolumeSize: ebs?.volumeSize ?? 10,
354 Iops: ebs?.iops,
355 Throughput: ebs?.throughput,
356 };
357
358 const toEndpointOptions = (
359 options: DomainEndpointOptionsProps | undefined,
360 ): opensearch.DomainEndpointOptions | undefined =>
361 options === undefined
362 ? undefined
363 : {
364 EnforceHTTPS: options.enforceHTTPS,
365 TLSSecurityPolicy: options.tlsSecurityPolicy,
366 CustomEndpointEnabled: options.customEndpointEnabled,
367 CustomEndpoint: options.customEndpoint,
368 CustomEndpointCertificateArn: options.customEndpointCertificateArn,
369 };
370
371 const toAccessPolicies = (policy: PolicyDocument | string | undefined): string | undefined =>
372 policy === undefined
373 ? undefined
374 : typeof policy === "string"
375 ? policy
376 : stringifyPolicyDocument(policy);
377
378 const toVpcOptions = (options: DomainVpcOptions | undefined): opensearch.VPCOptions | undefined =>
379 options === undefined
380 ? undefined
381 : {
382 SubnetIds: options.subnetIds,
383 SecurityGroupIds: options.securityGroupIds,
384 };
385
386 export const DomainProvider = () =>
387 Provider.effect(
388 Domain,
389 Effect.gen(function* () {
390 const toName = (id: string, props: DomainProps) =>
391 props.domainName
392 ? Effect.succeed(props.domainName)
393 : createPhysicalName({ id, maxLength: 28, lowercase: true });
394
395 const readDomain = Effect.fn(function* (name: string) {
396 return yield* opensearch.describeDomain({ DomainName: name }).pipe(
397 Effect.map((response) => response.DomainStatus),
398 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
399 );
400 });
401
402 const waitForActive = Effect.fn(function* (name: string) {
403 const domain = yield* repeatUntilDomainState(readDomain(name), isDomainActive);
404 if (domain === undefined) {
405 return yield* new OpenSearchDomainUnexpectedResponse({
406 message: `OpenSearch domain '${name}' not found while waiting`,
407 });
408 }
409 return domain;
410 });
411
412 const toAttrs = Effect.fn(function* (domain: opensearch.DomainStatus) {
413 return {
414 domainName: domain.DomainName,
415 domainArn: domain.ARN,
416 domainId: domain.DomainId,
417 engineVersion: domain.EngineVersion,
418 endpoint: domainEndpoint(domain),
419 created: domain.Created === true,
420 processing: domain.Processing === true,
421 tags: yield* readDomainTags(domain.ARN),
422 };
423 });
424
425 return {
426 stables: ["domainName", "domainArn", "domainId"],
427
428 diff: Effect.fn(function* ({ id, olds, news }) {
429 if (!isResolved(news)) return undefined;
430 const o: DomainProps = olds ?? {};
431 const n: DomainProps = news ?? {};
432 if ((yield* toName(id, o)) !== (yield* toName(id, n))) {
433 return { action: "replace" } as const;
434 }
435 // Encryption at rest and node-to-node encryption can be ENABLED
436 // in place but never disabled — disabling replaces the domain.
437 if (
438 o.encryptionAtRest?.enabled !== false &&
439 o.encryptionAtRest !== undefined &&
440 n.encryptionAtRest?.enabled === false
441 ) {
442 return { action: "replace" } as const;
443 }
444 if (o.nodeToNodeEncryption === true && n.nodeToNodeEncryption === false) {
445 return { action: "replace" } as const;
446 }
447 // Moving a domain between public and VPC endpoints replaces it.
448 if ((o.vpcOptions === undefined) !== (n.vpcOptions === undefined)) {
449 return { action: "replace" } as const;
450 }
451 }),
452
453 read: Effect.fn(function* ({ id, olds, output }) {
454 const name = output?.domainName ?? (yield* toName(id, olds ?? {}));
455 const domain = yield* readDomain(name);
456 if (domain === undefined) return undefined;
457 const attrs = yield* toAttrs(domain);
458 return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
459 }),
460
461 reconcile: Effect.fn(function* ({ id, news, output, session }) {
462 const props = news!;
463 const name = output?.domainName ?? (yield* toName(id, props));
464 const internalTags = yield* createInternalTags(id);
465 const desiredTags = { ...internalTags, ...props.tags };
466
467 // 1. Observe — cloud state is authoritative.
468 let observed = yield* readDomain(name);
469
470 // 2. Ensure — create if missing; tolerate AlreadyExists as a race.
471 if (observed === undefined) {
472 yield* opensearch
473 .createDomain({
474 DomainName: name,
475 EngineVersion: props.engineVersion,
476 ClusterConfig: toClusterConfig(props.clusterConfig),
477 EBSOptions: toEbsOptions(props.ebsOptions),
478 AccessPolicies: toAccessPolicies(props.accessPolicies),
479 IPAddressType: props.ipAddressType,
480 SnapshotOptions:
481 props.snapshotOptions !== undefined
482 ? {
483 AutomatedSnapshotStartHour:
484 props.snapshotOptions.automatedSnapshotStartHour,
485 }
486 : undefined,
487 VPCOptions: toVpcOptions(props.vpcOptions),
488 EncryptionAtRestOptions:
489 props.encryptionAtRest !== undefined
490 ? {
491 Enabled: props.encryptionAtRest.enabled ?? true,
492 KmsKeyId: props.encryptionAtRest.kmsKeyId,
493 }
494 : undefined,
495 NodeToNodeEncryptionOptions:
496 props.nodeToNodeEncryption !== undefined
497 ? { Enabled: props.nodeToNodeEncryption }
498 : undefined,
499 AdvancedOptions: props.advancedOptions,
500 DomainEndpointOptions: toEndpointOptions(props.domainEndpointOptions),
501 TagList: Object.entries(desiredTags).map(([Key, Value]) => ({
502 Key,
503 Value,
504 })),
505 })
506 .pipe(Effect.catchTag("ResourceAlreadyExistsException", () => Effect.void));
507 }
508
509 // Provisioning and blue/green config changes both surface as
510 // Processing=true; wait (bounded) so config updates do not fail.
511 observed = yield* waitForActive(name);
512
513 // 3. Sync — compute the update delta from OBSERVED state.
514 const update: opensearch.UpdateDomainConfigRequest = {
515 DomainName: name,
516 };
517 let mutated = false;
518
519 const desiredCluster = toClusterConfig(props.clusterConfig);
520 if (subsetDiffers(desiredCluster, observed.ClusterConfig)) {
521 update.ClusterConfig = desiredCluster;
522 mutated = true;
523 }
524 const desiredEbs = toEbsOptions(props.ebsOptions);
525 if (subsetDiffers(desiredEbs, observed.EBSOptions)) {
526 update.EBSOptions = desiredEbs;
527 mutated = true;
528 }
529 // Drift-compare canonicalized documents so key order / encoding
530 // differences in what OpenSearch echoes back never cause a
531 // spurious blue/green config change on re-deploy.
532 if (
533 props.accessPolicies !== undefined &&
534 normalizePolicyDocument(props.accessPolicies) !==
535 normalizePolicyDocument(observed.AccessPolicies ?? "")
536 ) {
537 update.AccessPolicies = toAccessPolicies(props.accessPolicies);
538 mutated = true;
539 }
540 if (props.ipAddressType !== undefined && props.ipAddressType !== observed.IPAddressType) {
541 update.IPAddressType = props.ipAddressType;
542 mutated = true;
543 }
544 if (
545 props.snapshotOptions?.automatedSnapshotStartHour !== undefined &&
546 props.snapshotOptions.automatedSnapshotStartHour !==
547 observed.SnapshotOptions?.AutomatedSnapshotStartHour
548 ) {
549 update.SnapshotOptions = {
550 AutomatedSnapshotStartHour: props.snapshotOptions.automatedSnapshotStartHour,
551 };
552 mutated = true;
553 }
554 const desiredVpc = toVpcOptions(props.vpcOptions);
555 if (
556 desiredVpc !== undefined &&
557 subsetDiffers(desiredVpc, {
558 SubnetIds: observed.VPCOptions?.SubnetIds,
559 SecurityGroupIds: observed.VPCOptions?.SecurityGroupIds,
560 })
561 ) {
562 update.VPCOptions = desiredVpc;
563 mutated = true;
564 }
565 if (
566 props.advancedOptions !== undefined &&
567 subsetDiffers(props.advancedOptions, observed.AdvancedOptions)
568 ) {
569 update.AdvancedOptions = props.advancedOptions;
570 mutated = true;
571 }
572 const desiredEndpointOptions = toEndpointOptions(props.domainEndpointOptions);
573 if (
574 desiredEndpointOptions !== undefined &&
575 subsetDiffers(desiredEndpointOptions, observed.DomainEndpointOptions)
576 ) {
577 update.DomainEndpointOptions = desiredEndpointOptions;
578 mutated = true;
579 }
580 // Encryption can only be enabled in place (disable = replacement,
581 // handled by diff).
582 if (
583 props.encryptionAtRest !== undefined &&
584 props.encryptionAtRest.enabled !== false &&
585 observed.EncryptionAtRestOptions?.Enabled !== true
586 ) {
587 update.EncryptionAtRestOptions = {
588 Enabled: true,
589 KmsKeyId: props.encryptionAtRest.kmsKeyId,
590 };
591 mutated = true;
592 }
593 if (
594 props.nodeToNodeEncryption === true &&
595 observed.NodeToNodeEncryptionOptions?.Enabled !== true
596 ) {
597 update.NodeToNodeEncryptionOptions = { Enabled: true };
598 mutated = true;
599 }
600
601 if (mutated) {
602 yield* opensearch.updateDomainConfig(update);
603 observed = yield* waitForActive(name);
604 }
605
606 // 3b. Engine upgrades run through the dedicated upgrade API.
607 if (
608 props.engineVersion !== undefined &&
609 observed.EngineVersion !== undefined &&
610 observed.EngineVersion !== props.engineVersion
611 ) {
612 yield* opensearch.upgradeDomain({
613 DomainName: name,
614 TargetVersion: props.engineVersion,
615 });
616 observed = yield* waitForActive(name);
617 }
618
619 // 3c. Sync tags — diff against OBSERVED cloud tags.
620 const observedTags = yield* readDomainTags(observed.ARN);
621 const { removed, upsert } = diffTags(observedTags, desiredTags);
622 if (upsert.length > 0) {
623 yield* opensearch.addTags({ ARN: observed.ARN, TagList: upsert });
624 }
625 if (removed.length > 0) {
626 yield* opensearch.removeTags({
627 ARN: observed.ARN,
628 TagKeys: removed,
629 });
630 }
631
632 yield* session.note(name);
633 return yield* toAttrs(observed);
634 }),
635
636 delete: Effect.fn(function* ({ output }) {
637 const name = output.domainName;
638 // A domain mid-create/config-change may reject deletion — wait
639 // (bounded, tolerant) for it to settle first. Already deleting
640 // (or gone) is success.
641 yield* repeatUntilDomainState(readDomain(name), isDomainDeletable).pipe(
642 Effect.orElseSucceed(() => undefined),
643 );
644 yield* opensearch
645 .deleteDomain({ DomainName: name })
646 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
647 }),
648
649 list: () =>
650 opensearch.listDomainNames({}).pipe(
651 Effect.map((response) =>
652 (response.DomainNames ?? [])
653 .map((info) => info.DomainName)
654 .filter((name): name is string => name !== undefined),
655 ),
656 Effect.flatMap(
657 Effect.forEach(
658 (name) =>
659 opensearch.describeDomain({ DomainName: name }).pipe(
660 Effect.map((response) => response.DomainStatus),
661 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
662 ),
663 { concurrency: 4 },
664 ),
665 ),
666 Effect.map((domains) =>
667 domains.filter((domain): domain is opensearch.DomainStatus => domain !== undefined),
668 ),
669 Effect.flatMap(Effect.forEach((domain) => toAttrs(domain), { concurrency: 4 })),
670 ),
671 };
672 }),
673 );