@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, 06:00 UTC

main
ts 1,197 lines 40.7 KB
Raw
1 import * as file from "@distilled.cloud/gcp/file_v1";
2 import type { GcpOpContext } from "@distilled.cloud/gcp/Protocol";
3 import { Unowned } from "alchemy/AdoptPolicy";
4 import { isResolved } from "alchemy/Diff";
5 import { createPhysicalName } from "alchemy/PhysicalName";
6 import * as Provider from "alchemy/Provider";
7 import { Resource } from "alchemy/Resource";
8 import { tagRecord } from "alchemy/Tags";
9 import * as Data from "effect/Data";
10 import * as Effect from "effect/Effect";
11 import * as Schedule from "effect/Schedule";
12 import * as Stream from "effect/Stream";
13 import { GcpEnvironment } from "../Environment.ts";
14 import {
15 createInternalLabels,
16 diffLabels,
17 hasAlchemyLabels,
18 stripInternalLabels,
19 toLabels,
20 } from "../Labels.ts";
21 import { waitForOperation as waitForLongRunningOperation } from "../Operation.ts";
22 import type { Providers } from "../Providers.ts";
23
24 const DEFAULT_ZONAL_LOCATION = "us-central1-a";
25 const DEFAULT_TIER = "BASIC_HDD";
26 const DEFAULT_PROTOCOL = "NFS_V3";
27 const DEFAULT_CONNECT_MODE = "DIRECT_PEERING";
28 const DEFAULT_NETWORK = "default";
29 const DEFAULT_SHARE_NAME = "share1";
30 const DEFAULT_MODE = "MODE_IPV4";
31 const MAX_NAME_LENGTH = 63;
32
33 const REGIONAL_TIERS = new Set(["ENTERPRISE", "REGIONAL"]);
34
35 export type PscConfig = {
36 /**
37 * Consumer service project for the Private Service Connect endpoint
38 * (Shared VPC). Defaults to the VPC host project.
39 */
40 endpointProject?: string;
41 };
42
43 export type NetworkConfig = {
44 /**
45 * VPC network name (`default`) or path
46 * (`projects/{project}/global/networks/{network}`). Immutable.
47 * @default "default"
48 */
49 network?: string;
50 /**
51 * Internet protocol versions assigned to the instance.
52 * @default ["MODE_IPV4"]
53 */
54 modes?: Array<file.NetworkConfigModesItemEnum | (string & {})>;
55 /**
56 * Reserved IP CIDR (`DIRECT_PEERING`) or allocated range name
57 * (`PRIVATE_SERVICE_ACCESS`). Immutable. BASIC uses a /29, Enterprise a
58 * /26, High Scale a /24. If omitted, Filestore picks a free block.
59 */
60 reservedIpRange?: string;
61 /**
62 * Network connect mode. Immutable.
63 * @default "DIRECT_PEERING"
64 */
65 connectMode?: file.NetworkConfigConnectModeEnum | (string & {});
66 /**
67 * Private Service Connect configuration. Set only when `connectMode` is
68 * `PRIVATE_SERVICE_CONNECT`.
69 */
70 pscConfig?: PscConfig;
71 };
72
73 export type NfsExportOptions = {
74 /**
75 * Root squash. `NO_ROOT_SQUASH` (default) allows root; `ROOT_SQUASH`
76 * maps root to `anonUid`/`anonGid`.
77 */
78 squashMode?: file.NfsExportOptionsSquashModeEnum | (string & {});
79 /**
80 * Source VPC for `ipRanges`. Required for Private Service Connect.
81 * Must match `NetworkConfig.network` when set.
82 */
83 network?: string;
84 /**
85 * Anonymous group id used with `ROOT_SQUASH`. Default 65534.
86 */
87 anonGid?: number;
88 /**
89 * IPv4 addresses or CIDR ranges allowed to mount the share. Max 64
90 * across all export options on a share. Overlaps are rejected.
91 */
92 ipRanges?: string[];
93 /**
94 * Mount access. `READ_WRITE` (default) or `READ_ONLY`.
95 */
96 accessMode?: file.NfsExportOptionsAccessModeEnum | (string & {});
97 /**
98 * Anonymous user id used with `ROOT_SQUASH`. Default 65534.
99 */
100 anonUid?: number;
101 };
102
103 export type FileShareConfig = {
104 /**
105 * Share name. 1-16 characters for Basic, 1-63 otherwise. Lowercase
106 * letters, numbers, and underscores; must start with a letter.
107 * Immutable — changing it replaces the instance.
108 * @default "share1"
109 */
110 name?: string;
111 /**
112 * Capacity in GiB (1024^3 bytes). BASIC_HDD minimum is 1024, BASIC_SSD
113 * 2560, HIGH_SCALE_SSD 10240. Omit to use the tier minimum.
114 */
115 capacityGb?: number;
116 /**
117 * NFS export options. Max 10 per share. Omit to allow all clients with
118 * `READ_WRITE` and `NO_ROOT_SQUASH`.
119 */
120 nfsExportOptions?: NfsExportOptions[];
121 /**
122 * Filestore backup to restore
123 * (`projects/{project}/locations/{location}/backups/{backup}`).
124 * Immutable.
125 */
126 sourceBackup?: string;
127 /**
128 * BackupDR backup to restore. Immutable.
129 */
130 sourceBackupdrBackup?: string;
131 };
132
133 export type IopsPerTb = {
134 /** Maximum IOPS per TiB of capacity. */
135 maxIopsPerTb?: number;
136 };
137
138 export type FixedIops = {
139 /** Fixed provisioned IOPS. Must be a multiple of 1000. */
140 maxIops?: number;
141 };
142
143 export type PerformanceConfig = {
144 /**
145 * Provision IOPS as `capacityTiB * maxIopsPerTb`. Mutually exclusive
146 * with `fixedIops`.
147 */
148 iopsPerTb?: IopsPerTb;
149 /**
150 * Fixed provisioned IOPS, independent of capacity. Mutually exclusive
151 * with `iopsPerTb`.
152 */
153 fixedIops?: FixedIops;
154 };
155
156 export type LdapConfig = {
157 /** LDAP servers as DNS names or IP addresses (one format, not mixed). */
158 servers?: string[];
159 /** LDAP domain (`example.com`). */
160 domain?: string;
161 /** Optional groups OU to speed LDAP lookups. */
162 groupsOu?: string;
163 /** Optional users OU to speed LDAP lookups. */
164 usersOu?: string;
165 };
166
167 export type DirectoryServicesConfig = {
168 /** LDAP configuration for NFSv4.1 Kerberos. */
169 ldap?: LdapConfig;
170 };
171
172 export type ReplicaConfig = {
173 /**
174 * Source instance
175 * (`projects/{project}/locations/{location}/instances/{instance}`).
176 * Required when creating a standby replica.
177 */
178 peerInstance?: string;
179 };
180
181 export type Replication = {
182 /** Replication role. New replicas must set `STANDBY`. */
183 role?: file.ReplicationRoleEnum | (string & {});
184 /** Replica peers. The API supports a single replica. */
185 replicas?: ReplicaConfig[];
186 };
187
188 export type PerformanceLimits = {
189 /** Maximum read IOPS. */
190 maxReadIops: number | undefined;
191 /** Maximum read throughput in bytes per second. */
192 maxReadThroughputBps: number | undefined;
193 /** Maximum IOPS. */
194 maxIops: number | undefined;
195 /** Maximum write IOPS. */
196 maxWriteIops: number | undefined;
197 /** Maximum write throughput in bytes per second. */
198 maxWriteThroughputBps: number | undefined;
199 };
200
201 export type InstanceProps = {
202 /**
203 * Instance id (the `{instance}` segment of
204 * `projects/{project}/locations/{location}/instances/{instance}`).
205 * If omitted, a unique RFC1035 name is generated from the stack, stage,
206 * and logical id. Must be 1-63 characters, start with a letter, and end
207 * with a letter or digit. Immutable — changing it replaces the instance.
208 */
209 instanceId?: string;
210 /**
211 * Location of the instance. Basic, Zonal, and High Scale use a zone
212 * (`us-central1-a`). Enterprise and Regional use a region
213 * (`us-central1`). Immutable — changing it replaces the instance.
214 * `US-CENTRAL1-A` is accepted and normalized to `us-central1-a`.
215 * @default "us-central1-a" (zonal tiers) or the stack's GCP region
216 * (`GCP.Region`, profile region, `us-central1`) for regional tiers
217 */
218 location?: string;
219 /**
220 * Service tier. Immutable — changing it replaces the instance.
221 * `STANDARD` is an alias for `BASIC_HDD`; `PREMIUM` for `BASIC_SSD`.
222 * @default "BASIC_HDD"
223 */
224 tier?: file.InstanceTierEnum | (string & {});
225 /**
226 * File protocol for every share. Immutable.
227 * @default "NFS_V3"
228 */
229 protocol?: file.InstanceProtocolEnum | (string & {});
230 /**
231 * Human-readable description (2048 characters or less).
232 */
233 description?: string;
234 /**
235 * User labels. Alchemy ownership labels are merged in automatically.
236 */
237 labels?: Record<string, string>;
238 /**
239 * File shares. The API supports a single share. Omit to create
240 * `share1` at the tier minimum capacity.
241 */
242 fileShares?: FileShareConfig[];
243 /**
244 * VPC networks. The API supports a single network. Immutable — changing
245 * network, modes, connect mode, or reserved range replaces the instance.
246 * @default [{ network: "default", modes: ["MODE_IPV4"] }]
247 */
248 networks?: NetworkConfig[];
249 /**
250 * Customer-managed KMS key for at-rest encryption
251 * (`projects/{project}/locations/{location}/keyRings/{keyRing}/cryptoKeys/{cryptoKey}`).
252 * Immutable.
253 */
254 kmsKeyName?: string;
255 /**
256 * Custom performance. Only for tiers that report
257 * `customPerformanceSupported`.
258 */
259 performanceConfig?: PerformanceConfig;
260 /**
261 * Directory Services (LDAP) for `NFS_V4_1`. Immutable.
262 */
263 directoryServices?: DirectoryServicesConfig;
264 /**
265 * Block `instances.delete` until protection is cleared.
266 * @default false
267 */
268 deletionProtectionEnabled?: boolean;
269 /**
270 * Reason recorded when deletion protection is enabled.
271 */
272 deletionProtectionReason?: string;
273 /**
274 * Replication configuration. Create-time only; new replicas set
275 * `role: "STANDBY"`.
276 */
277 replication?: Replication;
278 /**
279 * Resource Manager tags (namespaced key to short value). Input-only and
280 * immutable.
281 */
282 tags?: Record<string, string>;
283 };
284
285 export type Instance = Resource<
286 "GCP.Filestore.Instance",
287 InstanceProps,
288 {
289 /** Full resource name `projects/{project}/locations/{location}/instances/{instance}`. */
290 name: string;
291 /** Instance id (last path segment). */
292 instanceId: string;
293 /** Project id. */
294 project: string;
295 /** Location id (zone or region). */
296 location: string;
297 /** Human-readable description. */
298 description: string | undefined;
299 /** User labels (Alchemy ownership labels stripped). */
300 labels: Record<string, string>;
301 /** Service tier. */
302 tier: string;
303 /** File protocol. */
304 protocol: string | undefined;
305 /** Server-reported state (`READY`, `CREATING`, …). */
306 state: string | undefined;
307 /** Extra status text, if any. */
308 statusMessage: string | undefined;
309 /** File shares currently configured. */
310 fileShares: FileShareConfig[];
311 /** VPC networks, including assigned `ipAddresses`. */
312 networks: Array<
313 NetworkConfig & {
314 /** Assigned IPv4/IPv6 addresses. */
315 ipAddresses: string[];
316 }
317 >;
318 /** Customer-managed KMS key, if any. */
319 kmsKeyName: string | undefined;
320 /** Custom performance configuration currently applied. */
321 performanceConfig: PerformanceConfig | undefined;
322 /** Enforced performance limits. */
323 performanceLimits: PerformanceLimits | undefined;
324 /** Directory Services configuration. */
325 directoryServices: DirectoryServicesConfig | undefined;
326 /** Whether deletion protection is enabled. */
327 deletionProtectionEnabled: boolean;
328 /** Reason for deletion protection. */
329 deletionProtectionReason: string | undefined;
330 /** Whether the instance accepts `performanceConfig`. */
331 customPerformanceSupported: boolean | undefined;
332 /** Minimum capacity in GiB. */
333 minCapacityGb: number | undefined;
334 /** Maximum capacity in GiB. */
335 maxCapacityGb: number | undefined;
336 /** Capacity step size in GiB. */
337 capacityStepSizeGb: number | undefined;
338 /** Server etag. */
339 etag: string | undefined;
340 /** RFC3339 creation timestamp. */
341 createTime: string | undefined;
342 /** Replication configuration currently applied. */
343 replication: Replication | undefined;
344 /** Reasons the instance is `SUSPENDED`, if any. */
345 suspensionReasons: string[];
346 },
347 never,
348 Providers
349 >;
350
351 /**
352 * A Cloud Filestore instance (NFS file share).
353 *
354 * Changing `instanceId`, `location`, `tier`, `protocol`, `kmsKeyName`,
355 * share `name`/`sourceBackup`, or network identity (network, modes,
356 * connect mode, reserved range) replaces the instance. Description,
357 * labels, share capacity, NFS export options, performance, and deletion
358 * protection update in place.
359 *
360 * Provisioning a Basic HDD 1 TiB instance typically takes 5-10 minutes.
361 *
362 * ### Creating an Instance
363 * **Example:** Generated name, Basic HDD 1 TiB
364 * ```typescript
365 * const nfs = yield* GCP.Filestore.Instance("Nfs", {});
366 * ```
367 *
368 * **Example:** Explicit id, labels, and description
369 * ```typescript
370 * const nfs = yield* GCP.Filestore.Instance("Nfs", {
371 * instanceId: "app-nfs",
372 * location: "us-central1-a",
373 * tier: "BASIC_HDD",
374 * fileShares: [{ name: "share1", capacityGb: 1024 }],
375 * networks: [{ network: "default", modes: ["MODE_IPV4"] }],
376 * description: "app file share",
377 * labels: { env: "prod" },
378 * });
379 * ```
380 *
381 * ### NFS export options
382 * **Example:** Restrict clients and enable root squash
383 * ```typescript
384 * const nfs = yield* GCP.Filestore.Instance("Nfs", {
385 * fileShares: [{
386 * name: "share1",
387 * capacityGb: 1024,
388 * nfsExportOptions: [{
389 * accessMode: "READ_WRITE",
390 * squashMode: "ROOT_SQUASH",
391 * ipRanges: ["10.0.0.0/8"],
392 * }],
393 * }],
394 * });
395 * ```
396 *
397 * @resource
398 * @category Filestore
399 */
400 export const Instance = Resource<Instance>("GCP.Filestore.Instance");
401
402 export class InstanceNotResolved extends Data.TaggedError("GCP.Filestore.InstanceNotResolved")<{
403 resourceName: string;
404 }> {}
405
406 export class InstanceNotReady extends Data.TaggedError("GCP.Filestore.InstanceNotReady")<{
407 resourceName: string;
408 state: string;
409 }> {}
410
411 export class InstanceFailed extends Data.TaggedError("GCP.Filestore.InstanceFailed")<{
412 resourceName: string;
413 state: string;
414 statusMessage: string | undefined;
415 }> {}
416
417 export class InstanceStillExists extends Data.TaggedError("GCP.Filestore.InstanceStillExists")<{
418 resourceName: string;
419 }> {}
420
421 const lastSegment = (value: string) => {
422 const trimmed = value.replace(/\/+$/, "");
423 const parts = trimmed.split("/");
424 return parts[parts.length - 1] || trimmed;
425 };
426
427 const canonicalizeTier = (tier: string | undefined) => {
428 const value = (tier ?? DEFAULT_TIER).toUpperCase();
429 if (value === "TIER_UNSPECIFIED") return DEFAULT_TIER;
430 if (value === "STANDARD") return "BASIC_HDD";
431 if (value === "PREMIUM") return "BASIC_SSD";
432 return value;
433 };
434
435 const isRegionalTier = (tier: string | undefined) => REGIONAL_TIERS.has(canonicalizeTier(tier));
436
437 const defaultLocationFor = (tier: string | undefined, region: string) =>
438 isRegionalTier(tier) ? region : DEFAULT_ZONAL_LOCATION;
439
440 const normalizeLocation = (
441 location: string | undefined,
442 tier: string | undefined,
443 region: string,
444 ) => lastSegment(location ?? defaultLocationFor(tier, region)).toLowerCase();
445
446 const normalizeProtocol = (protocol: string | undefined) => {
447 const value = (protocol ?? DEFAULT_PROTOCOL).toUpperCase();
448 return value === "FILE_PROTOCOL_UNSPECIFIED" ? DEFAULT_PROTOCOL : value;
449 };
450
451 const normalizeConnectMode = (mode: string | undefined) => {
452 const value = (mode ?? DEFAULT_CONNECT_MODE).toUpperCase();
453 return value === "CONNECT_MODE_UNSPECIFIED" ? DEFAULT_CONNECT_MODE : value;
454 };
455
456 const defaultCapacityGb = (tier: string | undefined) => {
457 const value = canonicalizeTier(tier);
458 if (value === "BASIC_SSD") return 2560;
459 if (value === "HIGH_SCALE_SSD") return 10240;
460 return 1024;
461 };
462
463 const rfc1035 = (name: string): string => {
464 let next = name
465 .toLowerCase()
466 .replace(/[^a-z0-9-]/g, "-")
467 .replace(/-+/g, "-")
468 .replace(/^-+|-+$/g, "");
469 if (!/^[a-z]/.test(next)) next = `f${next}`;
470 next = next.slice(0, MAX_NAME_LENGTH).replace(/-+$/g, "");
471 if (next.length === 0) return "instance";
472 if (!/[a-z0-9]$/.test(next)) next = `${next.slice(0, MAX_NAME_LENGTH - 1)}0`;
473 return next.slice(0, MAX_NAME_LENGTH);
474 };
475
476 const resourceName = (project: string, location: string, instanceId: string) =>
477 `projects/${project}/locations/${location}/instances/${instanceId}`;
478
479 const parseName = (name: string) => {
480 const parts = name.split("/").filter((part) => part.length > 0);
481 const instancesAt = parts.lastIndexOf("instances");
482 const locationsAt = parts.lastIndexOf("locations");
483 const projectsAt = parts.lastIndexOf("projects");
484 return {
485 project: projectsAt >= 0 && parts[projectsAt + 1] ? parts[projectsAt + 1]! : "",
486 location:
487 locationsAt >= 0 && parts[locationsAt + 1] ? parts[locationsAt + 1]! : DEFAULT_ZONAL_LOCATION,
488 instanceId:
489 instancesAt >= 0 && parts[instancesAt + 1] ? parts[instancesAt + 1]! : lastSegment(name),
490 };
491 };
492
493 const userLabels = (
494 labels: Record<string, string | undefined> | null | undefined,
495 ): Record<string, string> => stripInternalLabels(tagRecord(labels));
496
497 const toId = (id: string, instanceId: string | undefined, existing?: string) =>
498 Effect.gen(function* () {
499 return (
500 instanceId ??
501 existing ??
502 rfc1035(
503 yield* createPhysicalName({
504 id,
505 maxLength: MAX_NAME_LENGTH,
506 lowercase: true,
507 }),
508 )
509 );
510 });
511
512 const asNumber = (value: string | number | undefined): number | undefined => {
513 if (value === undefined) return undefined;
514 const n = typeof value === "number" ? value : Number(value);
515 return Number.isFinite(n) ? n : undefined;
516 };
517
518 const asIntString = (value: number | string | undefined): string | undefined =>
519 value === undefined ? undefined : String(value);
520
521 const stringsOf = (values: ReadonlyArray<string | undefined> | null | undefined): string[] =>
522 (values ?? []).filter((value): value is string => value !== undefined);
523
524 const networkId = (network: string | undefined) => lastSegment(network ?? DEFAULT_NETWORK);
525
526 const modesOf = (modes: ReadonlyArray<string | undefined> | null | undefined): string[] => {
527 const values = stringsOf(modes).map((mode) => mode.toUpperCase());
528 return values.length > 0 ? values : [DEFAULT_MODE];
529 };
530
531 const modesKey = (modes: ReadonlyArray<string | undefined> | null | undefined) =>
532 [...modesOf(modes)].sort().join("\0");
533
534 const nfsOf = (options: file.NfsExportOptions | NfsExportOptions): NfsExportOptions => ({
535 squashMode: options.squashMode,
536 network: options.network,
537 anonGid: asNumber(options.anonGid),
538 ipRanges: options.ipRanges ? [...options.ipRanges] : undefined,
539 accessMode: options.accessMode,
540 anonUid: asNumber(options.anonUid),
541 });
542
543 const nfsKey = (options: NfsExportOptions) =>
544 JSON.stringify({
545 squashMode: (options.squashMode ?? "NO_ROOT_SQUASH").toUpperCase(),
546 network: options.network ?? "",
547 anonGid: options.anonGid ?? "",
548 ipRanges: [...(options.ipRanges ?? [])].sort(),
549 accessMode: (options.accessMode ?? "READ_WRITE").toUpperCase(),
550 anonUid: options.anonUid ?? "",
551 });
552
553 const shareOf = (
554 share: file.FileShareConfig | FileShareConfig,
555 tier: string | undefined,
556 ): FileShareConfig => ({
557 name: share.name ?? DEFAULT_SHARE_NAME,
558 capacityGb: asNumber(share.capacityGb) ?? defaultCapacityGb(tier),
559 nfsExportOptions: share.nfsExportOptions?.map(nfsOf),
560 sourceBackup: share.sourceBackup,
561 sourceBackupdrBackup: share.sourceBackupdrBackup,
562 });
563
564 const sharesOf = (
565 shares: ReadonlyArray<file.FileShareConfig | FileShareConfig> | undefined,
566 tier: string | undefined,
567 ): FileShareConfig[] => {
568 if (shares === undefined || shares.length === 0) {
569 return [
570 {
571 name: DEFAULT_SHARE_NAME,
572 capacityGb: defaultCapacityGb(tier),
573 },
574 ];
575 }
576 return shares.map((share) => shareOf(share, tier));
577 };
578
579 const shareIdentityKey = (share: FileShareConfig) =>
580 JSON.stringify({
581 name: share.name ?? DEFAULT_SHARE_NAME,
582 sourceBackup: share.sourceBackup ?? "",
583 sourceBackupdrBackup: share.sourceBackupdrBackup ?? "",
584 });
585
586 const shareCapacity = (share: FileShareConfig) => share.capacityGb ?? 0;
587
588 const networkOf = (
589 network: file.NetworkConfig | NetworkConfig,
590 ): NetworkConfig & { ipAddresses: string[] } => ({
591 network: network.network ?? DEFAULT_NETWORK,
592 modes: modesOf(network.modes),
593 reservedIpRange: network.reservedIpRange,
594 connectMode: network.connectMode,
595 pscConfig: network.pscConfig ? { endpointProject: network.pscConfig.endpointProject } : undefined,
596 ipAddresses: "ipAddresses" in network ? stringsOf(network.ipAddresses) : [],
597 });
598
599 const networksOf = (
600 networks: ReadonlyArray<file.NetworkConfig | NetworkConfig> | undefined,
601 ): Array<NetworkConfig & { ipAddresses: string[] }> => {
602 if (networks === undefined || networks.length === 0) {
603 return [
604 {
605 network: DEFAULT_NETWORK,
606 modes: [DEFAULT_MODE],
607 ipAddresses: [],
608 },
609 ];
610 }
611 return networks.map(networkOf);
612 };
613
614 const networkIdentityKey = (network: NetworkConfig, options?: { includeReserved?: boolean }) =>
615 JSON.stringify({
616 network: networkId(network.network),
617 modes: modesKey(network.modes),
618 connectMode: normalizeConnectMode(network.connectMode),
619 reservedIpRange: options?.includeReserved === true ? (network.reservedIpRange ?? "") : "",
620 endpointProject: network.pscConfig?.endpointProject ?? "",
621 });
622
623 const performanceOf = (
624 config: file.PerformanceConfig | PerformanceConfig | undefined,
625 ): PerformanceConfig | undefined => {
626 if (config === undefined) return undefined;
627 const iopsPerTb = config.iopsPerTb
628 ? { maxIopsPerTb: asNumber(config.iopsPerTb.maxIopsPerTb) }
629 : undefined;
630 const fixedIops = config.fixedIops ? { maxIops: asNumber(config.fixedIops.maxIops) } : undefined;
631 if (iopsPerTb === undefined && fixedIops === undefined) return undefined;
632 return { iopsPerTb, fixedIops };
633 };
634
635 const performanceKey = (config: file.PerformanceConfig | PerformanceConfig | undefined) =>
636 JSON.stringify({
637 iopsPerTb: performanceOf(config)?.iopsPerTb?.maxIopsPerTb ?? "",
638 fixedIops: performanceOf(config)?.fixedIops?.maxIops ?? "",
639 });
640
641 const ldapOf = (ldap: file.LdapConfig | LdapConfig | undefined): LdapConfig | undefined => {
642 if (ldap === undefined) return undefined;
643 return {
644 servers: ldap.servers ? [...ldap.servers] : undefined,
645 domain: ldap.domain,
646 groupsOu: ldap.groupsOu,
647 usersOu: ldap.usersOu,
648 };
649 };
650
651 const directoryOf = (
652 config: file.DirectoryServicesConfig | DirectoryServicesConfig | undefined,
653 ): DirectoryServicesConfig | undefined => {
654 if (config === undefined) return undefined;
655 const ldap = ldapOf(config.ldap);
656 if (ldap === undefined) return undefined;
657 return { ldap };
658 };
659
660 const directoryKey = (config: file.DirectoryServicesConfig | DirectoryServicesConfig | undefined) =>
661 JSON.stringify({
662 servers: [...(directoryOf(config)?.ldap?.servers ?? [])].sort(),
663 domain: directoryOf(config)?.ldap?.domain ?? "",
664 groupsOu: directoryOf(config)?.ldap?.groupsOu ?? "",
665 usersOu: directoryOf(config)?.ldap?.usersOu ?? "",
666 });
667
668 const replicationOf = (
669 config: file.Replication | Replication | undefined,
670 ): Replication | undefined => {
671 if (config === undefined) return undefined;
672 return {
673 role: config.role,
674 replicas: config.replicas?.map((replica) => ({
675 peerInstance: replica.peerInstance,
676 })),
677 };
678 };
679
680 const replicationKey = (config: file.Replication | Replication | undefined) =>
681 JSON.stringify({
682 role: (replicationOf(config)?.role ?? "").toUpperCase(),
683 peers: (replicationOf(config)?.replicas ?? [])
684 .map((replica) => replica.peerInstance ?? "")
685 .sort(),
686 });
687
688 const limitsOf = (limits: file.PerformanceLimits | undefined): PerformanceLimits | undefined => {
689 if (limits === undefined) return undefined;
690 return {
691 maxReadIops: asNumber(limits.maxReadIops),
692 maxReadThroughputBps: asNumber(limits.maxReadThroughputBps),
693 maxIops: asNumber(limits.maxIops),
694 maxWriteIops: asNumber(limits.maxWriteIops),
695 maxWriteThroughputBps: asNumber(limits.maxWriteThroughputBps),
696 };
697 };
698
699 const toApiNfs = (options: NfsExportOptions): file.NfsExportOptions => ({
700 squashMode: options.squashMode,
701 network: options.network,
702 anonGid: asIntString(options.anonGid),
703 ipRanges: options.ipRanges,
704 accessMode: options.accessMode,
705 anonUid: asIntString(options.anonUid),
706 });
707
708 const toApiShare = (share: FileShareConfig): file.FileShareConfig => ({
709 name: share.name,
710 capacityGb: asIntString(share.capacityGb),
711 nfsExportOptions: share.nfsExportOptions?.map(toApiNfs),
712 sourceBackup: share.sourceBackup,
713 sourceBackupdrBackup: share.sourceBackupdrBackup,
714 });
715
716 const toApiNetwork = (network: NetworkConfig): file.NetworkConfig => ({
717 network: network.network,
718 modes: network.modes,
719 reservedIpRange: network.reservedIpRange,
720 connectMode: network.connectMode,
721 pscConfig: network.pscConfig,
722 });
723
724 const toApiPerformance = (
725 config: PerformanceConfig | undefined,
726 ): file.PerformanceConfig | undefined => {
727 if (config === undefined) return undefined;
728 return {
729 iopsPerTb:
730 config.iopsPerTb === undefined
731 ? undefined
732 : { maxIopsPerTb: asIntString(config.iopsPerTb.maxIopsPerTb) },
733 fixedIops:
734 config.fixedIops === undefined
735 ? undefined
736 : { maxIops: asIntString(config.fixedIops.maxIops) },
737 };
738 };
739
740 const toAttrs = (instance: file.Instance, project: string) => {
741 const name = instance.name ?? "";
742 const parsed = parseName(name);
743 const tier = canonicalizeTier(instance.tier);
744 return {
745 name,
746 instanceId: parsed.instanceId,
747 project: parsed.project || project,
748 location: parsed.location,
749 description: instance.description,
750 labels: userLabels(instance.labels),
751 tier,
752 protocol: instance.protocol,
753 state: instance.state,
754 statusMessage: instance.statusMessage,
755 fileShares: sharesOf(instance.fileShares, tier),
756 networks: networksOf(instance.networks),
757 kmsKeyName: instance.kmsKeyName,
758 performanceConfig: performanceOf(instance.performanceConfig),
759 performanceLimits: limitsOf(instance.performanceLimits),
760 directoryServices: directoryOf(instance.directoryServices),
761 deletionProtectionEnabled: instance.deletionProtectionEnabled === true,
762 deletionProtectionReason: instance.deletionProtectionReason,
763 customPerformanceSupported: instance.customPerformanceSupported,
764 minCapacityGb: asNumber(instance.minCapacityGb),
765 maxCapacityGb: asNumber(instance.maxCapacityGb),
766 capacityStepSizeGb: asNumber(instance.capacityStepSizeGb),
767 etag: instance.etag,
768 createTime: instance.createTime,
769 replication: replicationOf(instance.replication),
770 suspensionReasons: stringsOf(instance.suspensionReasons),
771 };
772 };
773
774 const isPlaceholder = (instance: file.Instance) => {
775 const name = instance.name ?? "";
776 return name.length === 0 || name.endsWith("/instances/-") || name.endsWith("/instances/");
777 };
778
779 const getByName = (name: string) =>
780 file
781 .getProjectsLocationsInstances({ name })
782 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
783
784 /**
785 * Wait on a Filestore instance long-running operation (5–20 minutes).
786 * `ALREADY_EXISTS` (a create race) counts as success; so does `NOT_FOUND`
787 * when `notFoundOk` (deletes). Returns the final operation.
788 */
789 const waitForOperation = (operation: file.Operation, options?: { notFoundOk?: boolean }) =>
790 Effect.suspend(() => {
791 let latest = operation;
792 return waitForLongRunningOperation(
793 operation,
794 (name) => {
795 const get = file.getProjectsLocationsOperations({ name }).pipe(
796 Effect.tap((current) =>
797 Effect.sync(() => {
798 latest = current;
799 }),
800 ),
801 );
802 const observe: Effect.Effect<
803 file.Operation,
804 file.GetProjectsLocationsOperationsError,
805 GcpOpContext
806 > =
807 options?.notFoundOk === true
808 ? get.pipe(
809 Effect.catchTag("NotFound", () =>
810 Effect.succeed<file.Operation>({ name, done: true }),
811 ),
812 )
813 : get.pipe(
814 // A just-returned operation can briefly 404 on read.
815 Effect.retry({
816 while: (error) => error._tag === "NotFound",
817 times: 5,
818 schedule: Schedule.exponential("250 millis"),
819 }),
820 );
821 return observe;
822 },
823 { budget: "30 minutes", interval: "10 seconds" },
824 ).pipe(
825 Effect.map(() => latest),
826 // google.rpc.Code ALREADY_EXISTS = 6, NOT_FOUND = 5.
827 Effect.catchTag("GCP.OperationFailed", (error) =>
828 error.code === 6 || (options?.notFoundOk === true && error.code === 5)
829 ? Effect.succeed(latest)
830 : Effect.fail(error),
831 ),
832 );
833 });
834
835 const waitUntilExists = (name: string) =>
836 getByName(name).pipe(
837 Effect.flatMap((instance) =>
838 instance
839 ? Effect.succeed(instance)
840 : Effect.fail(new InstanceNotResolved({ resourceName: name })),
841 ),
842 Effect.retry({
843 while: (error) => error._tag === "GCP.Filestore.InstanceNotResolved",
844 times: 8,
845 schedule: Schedule.spaced("1 second"),
846 }),
847 );
848
849 const waitUntilReady = (name: string) =>
850 getByName(name).pipe(
851 Effect.filterOrFail(
852 (instance): instance is file.Instance => instance !== undefined,
853 () => new InstanceNotResolved({ resourceName: name }),
854 ),
855 Effect.filterOrFail(
856 (instance) => (instance.state ?? "") !== "ERROR",
857 (instance) =>
858 new InstanceFailed({
859 resourceName: name,
860 state: instance.state ?? "ERROR",
861 statusMessage: instance.statusMessage,
862 }),
863 ),
864 Effect.filterOrFail(
865 (instance) => (instance.state ?? "STATE_UNSPECIFIED") === "READY",
866 (instance) =>
867 new InstanceNotReady({
868 resourceName: name,
869 state: instance.state ?? "STATE_UNSPECIFIED",
870 }),
871 ),
872 Effect.retry({
873 while: (error) =>
874 error._tag === "GCP.Filestore.InstanceNotReady" ||
875 error._tag === "GCP.Filestore.InstanceNotResolved",
876 // Instances take 5–20 minutes to provision.
877 times: 120,
878 schedule: Schedule.spaced("10 seconds"),
879 }),
880 );
881
882 const waitUntilGone = (name: string) =>
883 getByName(name).pipe(
884 Effect.flatMap((instance) =>
885 instance === undefined
886 ? Effect.void
887 : Effect.fail(new InstanceStillExists({ resourceName: name })),
888 ),
889 Effect.retry({
890 while: (error) => error._tag === "GCP.Filestore.InstanceStillExists",
891 // Instance deletion takes several minutes.
892 times: 120,
893 schedule: Schedule.spaced("10 seconds"),
894 }),
895 );
896
897 const desiredShares = (news: InstanceProps, tier: string): FileShareConfig[] =>
898 sharesOf(news.fileShares, tier);
899
900 const desiredNetworks = (news: InstanceProps) => networksOf(news.networks);
901
902 const toCreateBody = (
903 news: InstanceProps,
904 desiredLabels: Record<string, string>,
905 tier: string,
906 protocol: string,
907 ): file.Instance => ({
908 description: news.description,
909 labels: desiredLabels,
910 tier,
911 protocol,
912 fileShares: desiredShares(news, tier).map(toApiShare),
913 networks: desiredNetworks(news).map(toApiNetwork),
914 kmsKeyName: news.kmsKeyName,
915 performanceConfig: toApiPerformance(news.performanceConfig),
916 directoryServices: news.directoryServices,
917 deletionProtectionEnabled: news.deletionProtectionEnabled === true,
918 deletionProtectionReason: news.deletionProtectionReason,
919 replication: news.replication,
920 tags: news.tags,
921 });
922
923 const sharesIdentityChanged = (observed: FileShareConfig[], desired: FileShareConfig[]) =>
924 observed.length !== desired.length ||
925 observed.some((share, index) => shareIdentityKey(share) !== shareIdentityKey(desired[index]!));
926
927 const sharesMutableChanged = (observed: FileShareConfig[], desired: FileShareConfig[]) =>
928 observed.length !== desired.length ||
929 observed.some((share, index) => {
930 const next = desired[index];
931 if (next === undefined) return true;
932 if (shareCapacity(share) !== shareCapacity(next)) return true;
933 if (next.nfsExportOptions === undefined) return false;
934 return (
935 (share.nfsExportOptions ?? []).map(nfsKey).join("\0") !==
936 next.nfsExportOptions.map(nfsKey).join("\0")
937 );
938 });
939
940 const sharesForPatch = (
941 desired: FileShareConfig[],
942 observed: FileShareConfig[],
943 ): FileShareConfig[] =>
944 desired.map((share, index) => ({
945 ...share,
946 nfsExportOptions: share.nfsExportOptions ?? observed[index]?.nfsExportOptions,
947 }));
948
949 const networksIdentityChanged = (observed: Array<NetworkConfig>, desired: Array<NetworkConfig>) => {
950 if (observed.length !== desired.length) return true;
951 return observed.some((network, index) => {
952 const next = desired[index]!;
953 const includeReserved = next.reservedIpRange !== undefined;
954 return (
955 networkIdentityKey(network, { includeReserved }) !==
956 networkIdentityKey(next, { includeReserved })
957 );
958 });
959 };
960
961 export const InstanceProvider = () =>
962 Provider.succeed(Instance, {
963 stables: ["name", "instanceId", "project", "location", "createTime"],
964
965 diff: Effect.fn(function* ({ news, olds, output }) {
966 if (!isResolved(news)) return undefined;
967 const env = yield* GcpEnvironment.current;
968
969 const previousId = olds?.instanceId ?? output?.instanceId;
970 const nextId = news.instanceId ?? previousId;
971 const previousTier = canonicalizeTier(olds?.tier ?? output?.tier);
972 const nextTier = canonicalizeTier(news.tier ?? output?.tier);
973 const previousLocation = normalizeLocation(
974 olds?.location ?? output?.location,
975 previousTier,
976 env.region,
977 );
978 const nextLocation = normalizeLocation(
979 news.location ?? output?.location,
980 nextTier,
981 env.region,
982 );
983 const previousProtocol = normalizeProtocol(olds?.protocol ?? output?.protocol);
984 const nextProtocol = normalizeProtocol(news.protocol ?? output?.protocol);
985 const previousKey = olds?.kmsKeyName ?? output?.kmsKeyName ?? "";
986 const nextKey = news.kmsKeyName ?? previousKey;
987 const previousShares = sharesOf(olds?.fileShares ?? output?.fileShares, previousTier);
988 const nextShares = sharesOf(
989 news.fileShares ?? olds?.fileShares ?? output?.fileShares,
990 nextTier,
991 );
992 const previousNetworks = networksOf(olds?.networks ?? output?.networks);
993 const nextNetworks = networksOf(news.networks ?? olds?.networks ?? output?.networks);
994 const previousDirectory = directoryKey(olds?.directoryServices ?? output?.directoryServices);
995 const nextDirectory = directoryKey(
996 news.directoryServices ?? olds?.directoryServices ?? output?.directoryServices,
997 );
998 const previousReplication = replicationKey(olds?.replication ?? output?.replication);
999 const nextReplication = replicationKey(
1000 news.replication ?? olds?.replication ?? output?.replication,
1001 );
1002
1003 const replace =
1004 (previousId !== undefined && nextId !== undefined && nextId !== previousId) ||
1005 previousLocation !== nextLocation ||
1006 previousTier !== nextTier ||
1007 previousProtocol !== nextProtocol ||
1008 previousKey !== nextKey ||
1009 sharesIdentityChanged(previousShares, nextShares) ||
1010 networksIdentityChanged(previousNetworks, nextNetworks) ||
1011 previousDirectory !== nextDirectory ||
1012 previousReplication !== nextReplication;
1013
1014 if (!replace) return undefined;
1015 return {
1016 action: "replace" as const,
1017 deleteFirst:
1018 previousLocation === nextLocation && previousId !== undefined && nextId === previousId,
1019 };
1020 }),
1021
1022 read: Effect.fn(function* ({ id, olds, output }) {
1023 const env = yield* GcpEnvironment.current;
1024 const instanceId = yield* toId(id, olds?.instanceId, output?.instanceId);
1025 const tier = canonicalizeTier(olds?.tier ?? output?.tier);
1026 const location = normalizeLocation(olds?.location ?? output?.location, tier, env.region);
1027 const name = output?.name ?? resourceName(env.project, location, instanceId);
1028 const existing = yield* getByName(name);
1029 if (existing === undefined) return undefined;
1030 const attrs = toAttrs(existing, env.project);
1031 return (yield* hasAlchemyLabels(id, tagRecord(existing.labels))) ? attrs : Unowned(attrs);
1032 }),
1033
1034 list: () =>
1035 Effect.gen(function* () {
1036 const env = yield* GcpEnvironment.current;
1037 return yield* file.listProjectsLocationsInstances
1038 .pages({
1039 parent: `projects/${env.project}/locations/-`,
1040 pageSize: 1000,
1041 })
1042 .pipe(
1043 Stream.flatMap((page) => Stream.fromIterable(page.instances ?? [])),
1044 Stream.filter(
1045 (instance) =>
1046 !isPlaceholder(instance) &&
1047 Object.keys(instance.labels ?? {}).some((key) => key.startsWith("alchemy-")),
1048 ),
1049 Stream.map((instance) => toAttrs(instance, env.project)),
1050 Stream.runCollect,
1051 Effect.map((chunk) => Array.from(chunk)),
1052 Effect.catchTag("NotFound", () => Effect.succeed([])),
1053 );
1054 }),
1055
1056 reconcile: Effect.fn(function* ({ id, news, output }) {
1057 const env = yield* GcpEnvironment.current;
1058 const instanceId = yield* toId(id, news.instanceId, output?.instanceId);
1059 const tier = canonicalizeTier(news.tier);
1060 const location = normalizeLocation(news.location ?? output?.location, tier, env.region);
1061 const protocol = normalizeProtocol(news.protocol);
1062 const name = resourceName(env.project, location, instanceId);
1063 const desiredLabels = {
1064 ...toLabels(news.labels),
1065 ...(yield* createInternalLabels(id)),
1066 };
1067 const desiredProtection = news.deletionProtectionEnabled === true;
1068
1069 let current = yield* getByName(output?.name ?? name);
1070
1071 if (current !== undefined && (current.state ?? "") === "DELETING") {
1072 yield* waitUntilGone(current.name ?? name);
1073 current = undefined;
1074 }
1075
1076 if (current === undefined) {
1077 const created = yield* file
1078 .createProjectsLocationsInstances({
1079 parent: `projects/${env.project}/locations/${location}`,
1080 instanceId,
1081 body: toCreateBody(news, desiredLabels, tier, protocol),
1082 })
1083 .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
1084 if (created !== undefined) {
1085 yield* waitForOperation(created);
1086 }
1087 current = yield* waitUntilExists(name);
1088 }
1089
1090 if (current === undefined) {
1091 return yield* new InstanceNotResolved({ resourceName: name });
1092 }
1093
1094 if ((current.state ?? "") === "ERROR") {
1095 return yield* new InstanceFailed({
1096 resourceName: name,
1097 state: current.state ?? "ERROR",
1098 statusMessage: current.statusMessage,
1099 });
1100 }
1101
1102 if ((current.state ?? "") !== "READY") {
1103 current = yield* waitUntilReady(name);
1104 }
1105
1106 const observedLabels = tagRecord(current.labels);
1107 const { upsert, removed } = diffLabels(observedLabels, desiredLabels);
1108 const labelsChanged = upsert.length > 0 || removed.length > 0;
1109 const descriptionChanged = (current.description ?? "") !== (news.description ?? "");
1110 const protectionChanged = (current.deletionProtectionEnabled === true) !== desiredProtection;
1111 const reasonChanged =
1112 (current.deletionProtectionReason ?? "") !== (news.deletionProtectionReason ?? "");
1113 const observedShares = sharesOf(current.fileShares, tier);
1114 const nextShares = desiredShares(news, tier);
1115 const fileSharesChanged =
1116 news.fileShares !== undefined && sharesMutableChanged(observedShares, nextShares);
1117 const performanceChanged =
1118 news.performanceConfig !== undefined &&
1119 performanceKey(current.performanceConfig) !== performanceKey(news.performanceConfig);
1120
1121 if (
1122 labelsChanged ||
1123 descriptionChanged ||
1124 protectionChanged ||
1125 reasonChanged ||
1126 fileSharesChanged ||
1127 performanceChanged
1128 ) {
1129 const updateMask = [
1130 labelsChanged ? "labels" : undefined,
1131 descriptionChanged ? "description" : undefined,
1132 fileSharesChanged ? "file_shares" : undefined,
1133 performanceChanged ? "performance_config" : undefined,
1134 protectionChanged ? "deletion_protection_enabled" : undefined,
1135 reasonChanged ? "deletion_protection_reason" : undefined,
1136 ].filter((field): field is string => field !== undefined);
1137
1138 const patched = yield* file.patchProjectsLocationsInstances({
1139 name,
1140 updateMask: updateMask.join(","),
1141 body: {
1142 name,
1143 labels: desiredLabels,
1144 description: news.description,
1145 fileShares: sharesForPatch(nextShares, observedShares).map(toApiShare),
1146 performanceConfig: toApiPerformance(news.performanceConfig),
1147 deletionProtectionEnabled: desiredProtection,
1148 deletionProtectionReason: news.deletionProtectionReason,
1149 },
1150 });
1151 yield* waitForOperation(patched);
1152 current = yield* waitUntilReady(name);
1153 }
1154
1155 return toAttrs(current, env.project);
1156 }),
1157
1158 delete: Effect.fn(function* ({ output }) {
1159 const existing = yield* getByName(output.name);
1160 if (existing === undefined) return;
1161
1162 if (existing.deletionProtectionEnabled === true) {
1163 const patched = yield* file
1164 .patchProjectsLocationsInstances({
1165 name: output.name,
1166 updateMask: "deletion_protection_enabled,deletion_protection_reason",
1167 body: {
1168 name: output.name,
1169 deletionProtectionEnabled: false,
1170 deletionProtectionReason: "",
1171 },
1172 })
1173 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
1174 if (patched !== undefined) {
1175 yield* waitForOperation(patched, { notFoundOk: true });
1176 }
1177 }
1178
1179 const operation = yield* file
1180 .deleteProjectsLocationsInstances({
1181 name: output.name,
1182 force: true,
1183 })
1184 .pipe(
1185 Effect.catchTag("NotFound", () => Effect.undefined),
1186 Effect.retry({
1187 while: (error) => error._tag === "Conflict",
1188 times: 8,
1189 schedule: Schedule.spaced("5 seconds"),
1190 }),
1191 );
1192 if (operation !== undefined) {
1193 yield* waitForOperation(operation, { notFoundOk: true });
1194 }
1195 yield* waitUntilGone(output.name);
1196 }),
1197 });