sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ Memcache/ Instance.ts

import * as memcache from "@distilled.cloud/gcp/memcache_v1";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { tagRecord } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { GcpEnvironment } from "../Environment.ts";
import {
  createInternalLabels,
  diffLabels,
  hasAlchemyLabels,
  stripInternalLabels,
  toLabels,
} from "../Labels.ts";
import { waitForOperation as waitForGcpOperation } from "../Operation.ts";
import type { Providers } from "../Providers.ts";

const DEFAULT_NODE_COUNT = 1;
const DEFAULT_CPU_COUNT = 1;
const DEFAULT_MEMORY_SIZE_MB = 1024;
const MAX_NAME_LENGTH = 40;

export type TimeOfDay = {
  /** Hours of day in 24-hour format (`0`–`23`). */
  hours?: number;
  /** Minutes of hour (`0`–`59`). */
  minutes?: number;
  /** Seconds of minute (`0`–`59`). */
  seconds?: number;
  /** Fractional seconds, in nanoseconds. */
  nanos?: number;
};

export type WeeklyMaintenanceWindow = {
  /** Day of week that maintenance occurs (`MONDAY` … `SUNDAY`). */
  day?: memcache.WeeklyMaintenanceWindowDayEnum | (string & {});
  /** Start time of the window in UTC. */
  startTime?: TimeOfDay;
  /** Window length as a duration string (e.g. `"10800s"` for 3 hours). */
  duration?: string;
};

export type MaintenancePolicy = {
  /** Description of the policy. Max 512 characters. */
  description?: string;
  /** Weekly windows. Current API maximum is one window. */
  weeklyMaintenanceWindow?: WeeklyMaintenanceWindow[];
};

export type NodeConfig = {
  /**
   * vCPUs per Memcached node.
   * @default 1
   */
  cpuCount?: number;
  /**
   * Memory per node in MiB.
   * @default 1024
   */
  memorySizeMb?: number;
};

export type InstanceProps = {
  /**
   * Instance id (the `{instance}` segment of
   * `projects/{project}/locations/{location}/instances/{instance}`).
   * If omitted, a unique name is generated from the stack, stage, and
   * logical id. Must match `^[a-z][a-z0-9-]{0,38}[a-z0-9]

	
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
	.repos/alchemy-effect/packages/gcp/src/Memcache/Instance.ts at main · sailfork/t3code-github · Sailfork
	
		
(1-40 * characters). Immutable — changing it replaces the instance. */ instanceId?: string; /** * Region (`us-central1`, `us-east1`, …). Immutable — changing it * replaces the instance. `US-CENTRAL1` is accepted and normalized to * `us-central1`. * @default the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`) */ location?: string; /** * User-facing display name. Max 80 characters. */ displayName?: string; /** * User labels. Alchemy ownership labels are merged in automatically. */ labels?: Record<string, string>; /** * VPC network * (`projects/{project}/global/networks/{network}`). Immutable. Defaults * to the project `default` network. */ authorizedNetwork?: string; /** * Zones to place nodes in. Nodes are spread evenly. Immutable. If * omitted, Memorystore uses every zone in the region. */ zones?: string[]; /** * Number of Memcached nodes. * @default 1 */ nodeCount?: number; /** * Per-node CPU and memory. Immutable — changing it replaces the * instance. */ nodeConfig?: NodeConfig; /** * Memcached software version (`MEMCACHE_1_5`, `MEMCACHE_1_6_15`). * Upgrading uses `instances.upgrade`; downgrading replaces the instance. */ memcacheVersion?: memcache.InstanceMemcacheVersionEnum | (string & {}); /** * User-defined memcached process parameters (`max_item_size`, …). * Staged with `updateParameters` and applied with `applyParameters`. */ parameters?: Record<string, string>; /** * Maintenance policy. If omitted, Memorystore may perform maintenance * at any time. */ maintenancePolicy?: MaintenancePolicy; /** * Allocated private-service-access range ids (e.g. `"default"`). * Immutable. */ reservedIpRangeId?: string[]; /** * Self-service maintenance version (e.g. `"20210712_00_00"`). */ maintenanceVersion?: string; }; export type Instance = Resource< "GCP.Memcache.Instance", InstanceProps, { /** Full resource name `projects/{project}/locations/{location}/instances/{instance}`. */ name: string; /** Instance id (last path segment). */ instanceId: string; /** Project id. */ project: string; /** Region id (`us-central1`, …). */ location: string; /** User-facing display name. */ displayName: string | undefined; /** User labels (Alchemy ownership labels stripped). */ labels: Record<string, string>; /** Authorized VPC network. */ authorizedNetwork: string | undefined; /** Zones nodes were provisioned in. */ zones: string[]; /** Number of Memcached nodes. */ nodeCount: number; /** Per-node CPU and memory currently applied. */ nodeConfig: NodeConfig; /** Memcached software version. */ memcacheVersion: string | undefined; /** Full memcached version string (e.g. `memcached-1.5.16`). */ memcacheFullVersion: string | undefined; /** User-defined memcached process parameters currently staged. */ parameters: Record<string, string>; /** Server-assigned parameter-set id. */ parameterId: string | undefined; /** Per-node info. */ memcacheNodes: memcache.Node[]; /** Server-reported state (`READY`, `CREATING`, …). */ state: string | undefined; /** Discovery API endpoint. */ discoveryEndpoint: string | undefined; /** Allocated private-service-access range ids. */ reservedIpRangeId: string[]; /** Self-service maintenance version. */ maintenanceVersion: string | undefined; /** Effective maintenance version. */ effectiveMaintenanceVersion: string | undefined; /** RFC3339 creation timestamp. */ createTime: string | undefined; /** RFC3339 last-update timestamp. */ updateTime: string | undefined; }, never, Providers >; /** * A Memorystore for Memcached instance. * * Changing `instanceId`, `location`, `authorizedNetwork`, `zones`, * `nodeConfig`, or `reservedIpRangeId` replaces the instance. Memcached * version upgrades use `instances.upgrade`; a downgrade replaces the * instance. * * Provisioning typically takes several minutes. * * ### Creating an Instance * **Example:** Generated name, 1 node * ```typescript * const cache = yield* GCP.Memcache.Instance("Cache", { * nodeCount: 1, * nodeConfig: { cpuCount: 1, memorySizeMb: 1024 }, * }); * ``` * * **Example:** Explicit id, labels, and display name * ```typescript * const cache = yield* GCP.Memcache.Instance("Cache", { * instanceId: "app-memcache", * location: "us-central1", * displayName: "app cache", * labels: { env: "prod" }, * nodeCount: 1, * nodeConfig: { cpuCount: 1, memorySizeMb: 1024 }, * }); * ``` * * ### Scaling Nodes * **Example:** Increase node count in place * ```typescript * const cache = yield* GCP.Memcache.Instance("Cache", { * nodeCount: 2, * nodeConfig: { cpuCount: 1, memorySizeMb: 1024 }, * }); * ``` * * @resource * @category Memcache */ export const Instance = Resource<Instance>("GCP.Memcache.Instance"); export class InstanceNotResolved extends Data.TaggedError("GCP.Memcache.InstanceNotResolved")<{ resourceName: string; }> {} export class InstanceNotReady extends Data.TaggedError("GCP.Memcache.InstanceNotReady")<{ resourceName: string; state: string; }> {} export class InstanceStillExists extends Data.TaggedError("GCP.Memcache.InstanceStillExists")<{ resourceName: string; }> {} const lastSegment = (value: string) => { const trimmed = value.replace(/\/+$/, ""); const parts = trimmed.split("/"); return parts[parts.length - 1] || trimmed; }; const normalizeLocation = (location: string | undefined, defaultLocation: string) => lastSegment(location ?? defaultLocation).toLowerCase(); const rfc1035 = (name: string): string => { let next = name .toLowerCase() .replace(/[^a-z0-9-]/g, "-") .replace(/-+/g, "-") .replace(/^-+|-+$/g, ""); if (!/^[a-z]/.test(next)) next = `m${next}`; next = next.slice(0, MAX_NAME_LENGTH).replace(/-+$/g, ""); if (next.length === 0) return "instance"; if (!/[a-z0-9]$/.test(next)) next = `${next.slice(0, MAX_NAME_LENGTH - 1)}0`; return next.slice(0, MAX_NAME_LENGTH); }; const resourceName = (project: string, location: string, instanceId: string) => `projects/${project}/locations/${location}/instances/${instanceId}`; const parseName = (name: string, defaultLocation: string) => { const parts = name.split("/").filter((part) => part.length > 0); const instancesAt = parts.lastIndexOf("instances"); const locationsAt = parts.lastIndexOf("locations"); const projectsAt = parts.lastIndexOf("projects"); return { project: projectsAt >= 0 && parts[projectsAt + 1] ? parts[projectsAt + 1]! : "", location: locationsAt >= 0 && parts[locationsAt + 1] ? parts[locationsAt + 1]! : defaultLocation, instanceId: instancesAt >= 0 && parts[instancesAt + 1] ? parts[instancesAt + 1]! : lastSegment(name), }; }; const userLabels = ( labels: Record<string, string | undefined> | null | undefined, ): Record<string, string> => stripInternalLabels(tagRecord(labels)); const toId = (id: string, instanceId: string | undefined, existing?: string) => Effect.gen(function* () { return ( instanceId ?? existing ?? rfc1035( yield* createPhysicalName({ id, maxLength: MAX_NAME_LENGTH, lowercase: true, }), ) ); }); const paramsOf = ( params: Record<string, string | undefined> | null | undefined, ): Record<string, string> => Object.fromEntries( Object.entries(params ?? {}).filter( (entry): entry is [string, string] => entry[1] !== undefined, ), ); const paramsKey = (params: Record<string, string | undefined> | null | undefined) => JSON.stringify( Object.fromEntries(Object.entries(paramsOf(params)).sort(([a], [b]) => a.localeCompare(b))), ); const listKey = (values: readonly string[] | undefined) => JSON.stringify([...(values ?? [])].map((value) => value.toLowerCase()).sort()); const nodeConfigOf = (config: NodeConfig | undefined): NodeConfig => ({ cpuCount: config?.cpuCount ?? DEFAULT_CPU_COUNT, memorySizeMb: config?.memorySizeMb ?? DEFAULT_MEMORY_SIZE_MB, }); const nodeConfigKey = (config: NodeConfig | undefined) => { const value = nodeConfigOf(config); return JSON.stringify({ cpuCount: value.cpuCount, memorySizeMb: value.memorySizeMb, }); }; const windowKey = (window: WeeklyMaintenanceWindow) => JSON.stringify({ day: (window.day ?? "").toUpperCase(), hours: window.startTime?.hours ?? 0, minutes: window.startTime?.minutes ?? 0, seconds: window.startTime?.seconds ?? 0, nanos: window.startTime?.nanos ?? 0, duration: window.duration ?? "", }); const maintenanceOf = ( policy: memcache.GoogleCloudMemcacheV1MaintenancePolicy | MaintenancePolicy | undefined, ): MaintenancePolicy | undefined => { if (policy === undefined) return undefined; return { description: policy.description, weeklyMaintenanceWindow: policy.weeklyMaintenanceWindow, }; }; const maintenanceKey = (policy: MaintenancePolicy | undefined) => JSON.stringify({ description: policy?.description ?? "", windows: (policy?.weeklyMaintenanceWindow ?? []).map(windowKey), }); const parseMemcacheVersion = (version: string | undefined) => { if (version === undefined) return undefined; const match = version.toUpperCase().match(/^MEMCACHE_(\d+)_(\d+)(?:_(\d+))?$/); if (!match) return undefined; return Number(match[1]) * 10_000 + Number(match[2]) * 100 + Number(match[3] ?? 0); }; const versionDecreasing = (previous: string | undefined, next: string) => { const oldN = parseMemcacheVersion(previous); const newN = parseMemcacheVersion(next); if (oldN === undefined || newN === undefined) return previous !== next; return newN < oldN; }; const toAttrs = (instance: memcache.Instance, project: string, region: string) => { const name = instance.name ?? ""; const parsed = parseName(name, region); return { name, instanceId: parsed.instanceId, project: parsed.project || project, location: parsed.location, displayName: instance.displayName, labels: userLabels(instance.labels), authorizedNetwork: instance.authorizedNetwork, zones: instance.zones ?? [], nodeCount: instance.nodeCount ?? DEFAULT_NODE_COUNT, nodeConfig: nodeConfigOf(instance.nodeConfig), memcacheVersion: instance.memcacheVersion, memcacheFullVersion: instance.memcacheFullVersion, parameters: paramsOf(instance.parameters?.params), parameterId: instance.parameters?.id, memcacheNodes: instance.memcacheNodes ?? [], state: instance.state, discoveryEndpoint: instance.discoveryEndpoint, reservedIpRangeId: instance.reservedIpRangeId ?? [], maintenanceVersion: instance.maintenanceVersion, effectiveMaintenanceVersion: instance.effectiveMaintenanceVersion, createTime: instance.createTime, updateTime: instance.updateTime, }; }; const isPlaceholder = (instance: memcache.Instance) => { const name = instance.name ?? ""; return name.endsWith("/instances/-") || name.endsWith("/instances/"); }; const getByName = (name: string) => memcache .getProjectsLocationsInstances({ name }) .pipe(Effect.catchTag("NotFound", () => Effect.undefined)); /** * Wait for a Memorystore for Memcached operation; instance create, * resize, and upgrade take 10–20 minutes. With `notFoundOk`, NOT_FOUND * (code 5) and an operation that is already gone count as success * (delete race). */ const waitForOperation = (operation: memcache.Operation, options?: { notFoundOk?: boolean }) => waitForGcpOperation(operation, (name) => memcache.getProjectsLocationsOperations({ name }), { budget: "30 minutes", interval: "10 seconds", }).pipe( Effect.catchIf( (error) => options?.notFoundOk === true && (error._tag === "NotFound" || (error._tag === "GCP.OperationFailed" && error.code === 5)), () => Effect.succeed(operation), ), ); const waitUntilExists = (name: string) => getByName(name).pipe( Effect.flatMap((instance) => instance ? Effect.succeed(instance) : Effect.fail(new InstanceNotResolved({ resourceName: name })), ), Effect.retry({ while: (error) => error._tag === "GCP.Memcache.InstanceNotResolved", times: 8, schedule: Schedule.spaced("1 second"), }), ); const waitUntilReady = (name: string) => getByName(name).pipe( Effect.filterOrFail( (instance): instance is memcache.Instance => instance !== undefined, () => new InstanceNotResolved({ resourceName: name }), ), Effect.filterOrFail( (instance) => (instance.state ?? "STATE_UNSPECIFIED") === "READY", (instance) => new InstanceNotReady({ resourceName: name, state: instance.state ?? "STATE_UNSPECIFIED", }), ), Effect.retry({ while: (error) => error._tag === "GCP.Memcache.InstanceNotReady" || error._tag === "GCP.Memcache.InstanceNotResolved", times: 10, schedule: Schedule.spaced("8 seconds"), }), ); const waitUntilGone = (name: string) => getByName(name).pipe( Effect.flatMap((instance) => instance === undefined ? Effect.void : Effect.fail(new InstanceStillExists({ resourceName: name })), ), Effect.retry({ while: (error) => error._tag === "GCP.Memcache.InstanceStillExists", times: 10, schedule: Schedule.spaced("8 seconds"), }), ); const toCreateBody = ( news: InstanceProps, desiredLabels: Record<string, string>, nodeCount: number, nodeConfig: NodeConfig, ): memcache.Instance => ({ displayName: news.displayName, labels: desiredLabels, authorizedNetwork: news.authorizedNetwork, zones: news.zones, nodeCount, nodeConfig, memcacheVersion: news.memcacheVersion, parameters: news.parameters === undefined ? undefined : { params: news.parameters }, maintenancePolicy: news.maintenancePolicy, reservedIpRangeId: news.reservedIpRangeId, }); export const InstanceProvider = () => Provider.succeed(Instance, { stables: ["name", "instanceId", "project", "location", "createTime"], diff: Effect.fn(function* ({ news, olds, output }) { if (!isResolved(news)) return undefined; const env = yield* GcpEnvironment.current; const previousId = olds?.instanceId ?? output?.instanceId; const nextId = news.instanceId ?? previousId; const previousLocation = normalizeLocation(olds?.location ?? output?.location, env.region); const nextLocation = normalizeLocation(news.location ?? output?.location, env.region); const previousNetwork = olds?.authorizedNetwork ?? output?.authorizedNetwork ?? ""; const nextNetwork = news.authorizedNetwork ?? previousNetwork; const previousZones = listKey(olds?.zones ?? output?.zones); const nextZones = news.zones !== undefined ? listKey(news.zones) : previousZones; const previousNodeConfig = nodeConfigKey(olds?.nodeConfig ?? output?.nodeConfig); const nextNodeConfig = nodeConfigKey(news.nodeConfig ?? output?.nodeConfig); const previousRanges = listKey(olds?.reservedIpRangeId ?? output?.reservedIpRangeId); const nextRanges = news.reservedIpRangeId !== undefined ? listKey(news.reservedIpRangeId) : previousRanges; const previousVersion = olds?.memcacheVersion ?? output?.memcacheVersion; const nextVersion = news.memcacheVersion; const downgrade = nextVersion !== undefined && previousVersion !== undefined && versionDecreasing(previousVersion, nextVersion); const replace = (previousId !== undefined && nextId !== undefined && nextId !== previousId) || previousLocation !== nextLocation || previousNetwork !== nextNetwork || previousZones !== nextZones || previousNodeConfig !== nextNodeConfig || previousRanges !== nextRanges || downgrade; if (!replace) return undefined; return { action: "replace" as const, deleteFirst: previousLocation === nextLocation && previousId !== undefined && nextId === previousId, }; }), read: Effect.fn(function* ({ id, olds, output }) { const env = yield* GcpEnvironment.current; const instanceId = yield* toId(id, olds?.instanceId, output?.instanceId); const location = normalizeLocation(olds?.location ?? output?.location, env.region); const name = output?.name ?? resourceName(env.project, location, instanceId); const existing = yield* getByName(name); if (existing === undefined) return undefined; const attrs = toAttrs(existing, env.project, env.region); return (yield* hasAlchemyLabels(id, tagRecord(existing.labels))) ? attrs : Unowned(attrs); }), list: () => Effect.gen(function* () { const env = yield* GcpEnvironment.current; return yield* memcache.listProjectsLocationsInstances .pages({ parent: `projects/${env.project}/locations/-`, pageSize: 1000, }) .pipe( Stream.flatMap((page) => Stream.fromIterable(page.instances ?? [])), Stream.filter( (instance) => !isPlaceholder(instance) && Object.keys(instance.labels ?? {}).some((key) => key.startsWith("alchemy-")), ), Stream.map((instance) => toAttrs(instance, env.project, env.region)), Stream.runCollect, Effect.map((chunk) => Array.from(chunk)), Effect.catchTag("NotFound", () => Effect.succeed([])), ); }), reconcile: Effect.fn(function* ({ id, news, output }) { const env = yield* GcpEnvironment.current; const instanceId = yield* toId(id, news.instanceId, output?.instanceId); const location = normalizeLocation(news.location ?? output?.location, env.region); const name = resourceName(env.project, location, instanceId); const nodeCount = news.nodeCount ?? DEFAULT_NODE_COUNT; const nodeConfig = nodeConfigOf(news.nodeConfig); const desiredLabels = { ...toLabels(news.labels), ...(yield* createInternalLabels(id)), }; let current = yield* getByName(output?.name ?? name); if (current === undefined) { const created = yield* memcache .createProjectsLocationsInstances({ parent: `projects/${env.project}/locations/${location}`, instanceId, body: toCreateBody(news, desiredLabels, nodeCount, nodeConfig), }) .pipe(Effect.catchTag("Conflict", () => Effect.undefined)); if (created !== undefined) { yield* waitForOperation(created); } current = yield* waitUntilExists(name); } if (current === undefined) { return yield* new InstanceNotResolved({ resourceName: name }); } if ((current.state ?? "") !== "READY") { current = yield* waitUntilReady(name); } const desiredVersion = news.memcacheVersion; const currentVersion = current.memcacheVersion; if ( desiredVersion !== undefined && currentVersion !== undefined && desiredVersion !== currentVersion && !versionDecreasing(currentVersion, desiredVersion) ) { const upgraded = yield* memcache.upgradeProjectsLocationsInstances({ name, body: { memcacheVersion: desiredVersion }, }); yield* waitForOperation(upgraded); current = yield* waitUntilReady(name); } const observedLabels = tagRecord(current.labels); const { upsert, removed } = diffLabels(observedLabels, desiredLabels); const labelsChanged = upsert.length > 0 || removed.length > 0; const displayNameChanged = (current.displayName ?? "") !== (news.displayName ?? ""); const desiredNodeCount = news.nodeCount ?? current.nodeCount ?? nodeCount; const nodeCountChanged = (current.nodeCount ?? DEFAULT_NODE_COUNT) !== desiredNodeCount; const maintenanceChanged = news.maintenancePolicy !== undefined && maintenanceKey(maintenanceOf(current.maintenancePolicy)) !== maintenanceKey(news.maintenancePolicy); const maintenanceVersionChanged = news.maintenanceVersion !== undefined && (current.maintenanceVersion ?? "") !== news.maintenanceVersion; if ( labelsChanged || displayNameChanged || nodeCountChanged || maintenanceChanged || maintenanceVersionChanged ) { const updateMask = [ labelsChanged ? "labels" : undefined, displayNameChanged ? "displayName" : undefined, nodeCountChanged ? "nodeCount" : undefined, maintenanceChanged ? "maintenancePolicy" : undefined, maintenanceVersionChanged ? "maintenanceVersion" : undefined, ].filter((field): field is string => field !== undefined); const patched = yield* memcache.patchProjectsLocationsInstances({ name, updateMask: updateMask.join(","), body: { name, labels: desiredLabels, displayName: news.displayName, nodeCount: desiredNodeCount, maintenancePolicy: news.maintenancePolicy, maintenanceVersion: news.maintenanceVersion, }, }); yield* waitForOperation(patched); current = yield* waitUntilReady(name); } const parametersChanged = news.parameters !== undefined && paramsKey(current.parameters?.params) !== paramsKey(news.parameters); if (parametersChanged) { const updated = yield* memcache.updateParametersProjectsLocationsInstances({ name, body: { updateMask: "parameters", parameters: { params: news.parameters }, }, }); yield* waitForOperation(updated); const applied = yield* memcache.applyParametersProjectsLocationsInstances({ name, body: { applyAll: true }, }); yield* waitForOperation(applied); current = yield* waitUntilReady(name); } return toAttrs(current, env.project, env.region); }), delete: Effect.fn(function* ({ output }) { const operation = yield* memcache .deleteProjectsLocationsInstances({ name: output.name }) .pipe( Effect.catchTag("NotFound", () => Effect.undefined), Effect.retry({ while: (error) => error._tag === "Conflict", times: 8, schedule: Schedule.spaced("5 seconds"), }), ); if (operation !== undefined) { yield* waitForOperation(operation, { notFoundOk: true }); } yield* waitUntilGone(output.name); }), });
.repos/alchemy-effect/packages/gcp/src/Memcache/Instance.ts at main · sailfork/t3code-github · Sailfork
(1-40\n * characters). Immutable — changing it replaces the instance.\n */\n instanceId?: string;\n /**\n * Region (`us-central1`, `us-east1`, …). Immutable — changing it\n * replaces the instance. `US-CENTRAL1` is accepted and normalized to\n * `us-central1`.\n * @default the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`)\n */\n location?: string;\n /**\n * User-facing display name. Max 80 characters.\n */\n displayName?: string;\n /**\n * User labels. Alchemy ownership labels are merged in automatically.\n */\n labels?: Record\u003cstring, string>;\n /**\n * VPC network\n * (`projects/{project}/global/networks/{network}`). Immutable. Defaults\n * to the project `default` network.\n */\n authorizedNetwork?: string;\n /**\n * Zones to place nodes in. Nodes are spread evenly. Immutable. If\n * omitted, Memorystore uses every zone in the region.\n */\n zones?: string[];\n /**\n * Number of Memcached nodes.\n * @default 1\n */\n nodeCount?: number;\n /**\n * Per-node CPU and memory. Immutable — changing it replaces the\n * instance.\n */\n nodeConfig?: NodeConfig;\n /**\n * Memcached software version (`MEMCACHE_1_5`, `MEMCACHE_1_6_15`).\n * Upgrading uses `instances.upgrade`; downgrading replaces the instance.\n */\n memcacheVersion?: memcache.InstanceMemcacheVersionEnum | (string & {});\n /**\n * User-defined memcached process parameters (`max_item_size`, …).\n * Staged with `updateParameters` and applied with `applyParameters`.\n */\n parameters?: Record\u003cstring, string>;\n /**\n * Maintenance policy. If omitted, Memorystore may perform maintenance\n * at any time.\n */\n maintenancePolicy?: MaintenancePolicy;\n /**\n * Allocated private-service-access range ids (e.g. `\"default\"`).\n * Immutable.\n */\n reservedIpRangeId?: string[];\n /**\n * Self-service maintenance version (e.g. `\"20210712_00_00\"`).\n */\n maintenanceVersion?: string;\n};\n\nexport type Instance = Resource\u003c\n \"GCP.Memcache.Instance\",\n InstanceProps,\n {\n /** Full resource name `projects/{project}/locations/{location}/instances/{instance}`. */\n name: string;\n /** Instance id (last path segment). */\n instanceId: string;\n /** Project id. */\n project: string;\n /** Region id (`us-central1`, …). */\n location: string;\n /** User-facing display name. */\n displayName: string | undefined;\n /** User labels (Alchemy ownership labels stripped). */\n labels: Record\u003cstring, string>;\n /** Authorized VPC network. */\n authorizedNetwork: string | undefined;\n /** Zones nodes were provisioned in. */\n zones: string[];\n /** Number of Memcached nodes. */\n nodeCount: number;\n /** Per-node CPU and memory currently applied. */\n nodeConfig: NodeConfig;\n /** Memcached software version. */\n memcacheVersion: string | undefined;\n /** Full memcached version string (e.g. `memcached-1.5.16`). */\n memcacheFullVersion: string | undefined;\n /** User-defined memcached process parameters currently staged. */\n parameters: Record\u003cstring, string>;\n /** Server-assigned parameter-set id. */\n parameterId: string | undefined;\n /** Per-node info. */\n memcacheNodes: memcache.Node[];\n /** Server-reported state (`READY`, `CREATING`, …). */\n state: string | undefined;\n /** Discovery API endpoint. */\n discoveryEndpoint: string | undefined;\n /** Allocated private-service-access range ids. */\n reservedIpRangeId: string[];\n /** Self-service maintenance version. */\n maintenanceVersion: string | undefined;\n /** Effective maintenance version. */\n effectiveMaintenanceVersion: string | undefined;\n /** RFC3339 creation timestamp. */\n createTime: string | undefined;\n /** RFC3339 last-update timestamp. */\n updateTime: string | undefined;\n },\n never,\n Providers\n>;\n\n/**\n * A Memorystore for Memcached instance.\n *\n * Changing `instanceId`, `location`, `authorizedNetwork`, `zones`,\n * `nodeConfig`, or `reservedIpRangeId` replaces the instance. Memcached\n * version upgrades use `instances.upgrade`; a downgrade replaces the\n * instance.\n *\n * Provisioning typically takes several minutes.\n *\n * ### Creating an Instance\n * **Example:** Generated name, 1 node\n * ```typescript\n * const cache = yield* GCP.Memcache.Instance(\"Cache\", {\n * nodeCount: 1,\n * nodeConfig: { cpuCount: 1, memorySizeMb: 1024 },\n * });\n * ```\n *\n * **Example:** Explicit id, labels, and display name\n * ```typescript\n * const cache = yield* GCP.Memcache.Instance(\"Cache\", {\n * instanceId: \"app-memcache\",\n * location: \"us-central1\",\n * displayName: \"app cache\",\n * labels: { env: \"prod\" },\n * nodeCount: 1,\n * nodeConfig: { cpuCount: 1, memorySizeMb: 1024 },\n * });\n * ```\n *\n * ### Scaling Nodes\n * **Example:** Increase node count in place\n * ```typescript\n * const cache = yield* GCP.Memcache.Instance(\"Cache\", {\n * nodeCount: 2,\n * nodeConfig: { cpuCount: 1, memorySizeMb: 1024 },\n * });\n * ```\n *\n * @resource\n * @category Memcache\n */\nexport const Instance = Resource\u003cInstance>(\"GCP.Memcache.Instance\");\n\nexport class InstanceNotResolved extends Data.TaggedError(\"GCP.Memcache.InstanceNotResolved\")\u003c{\n resourceName: string;\n}> {}\n\nexport class InstanceNotReady extends Data.TaggedError(\"GCP.Memcache.InstanceNotReady\")\u003c{\n resourceName: string;\n state: string;\n}> {}\n\nexport class InstanceStillExists extends Data.TaggedError(\"GCP.Memcache.InstanceStillExists\")\u003c{\n resourceName: string;\n}> {}\n\nconst lastSegment = (value: string) => {\n const trimmed = value.replace(/\\/+$/, \"\");\n const parts = trimmed.split(\"/\");\n return parts[parts.length - 1] || trimmed;\n};\n\nconst normalizeLocation = (location: string | undefined, defaultLocation: string) =>\n lastSegment(location ?? defaultLocation).toLowerCase();\n\nconst rfc1035 = (name: string): string => {\n let next = name\n .toLowerCase()\n .replace(/[^a-z0-9-]/g, \"-\")\n .replace(/-+/g, \"-\")\n .replace(/^-+|-+$/g, \"\");\n if (!/^[a-z]/.test(next)) next = `m${next}`;\n next = next.slice(0, MAX_NAME_LENGTH).replace(/-+$/g, \"\");\n if (next.length === 0) return \"instance\";\n if (!/[a-z0-9]$/.test(next)) next = `${next.slice(0, MAX_NAME_LENGTH - 1)}0`;\n return next.slice(0, MAX_NAME_LENGTH);\n};\n\nconst resourceName = (project: string, location: string, instanceId: string) =>\n `projects/${project}/locations/${location}/instances/${instanceId}`;\n\nconst parseName = (name: string, defaultLocation: string) => {\n const parts = name.split(\"/\").filter((part) => part.length > 0);\n const instancesAt = parts.lastIndexOf(\"instances\");\n const locationsAt = parts.lastIndexOf(\"locations\");\n const projectsAt = parts.lastIndexOf(\"projects\");\n return {\n project: projectsAt >= 0 && parts[projectsAt + 1] ? parts[projectsAt + 1]! : \"\",\n location:\n locationsAt >= 0 && parts[locationsAt + 1] ? parts[locationsAt + 1]! : defaultLocation,\n instanceId:\n instancesAt >= 0 && parts[instancesAt + 1] ? parts[instancesAt + 1]! : lastSegment(name),\n };\n};\n\nconst userLabels = (\n labels: Record\u003cstring, string | undefined> | null | undefined,\n): Record\u003cstring, string> => stripInternalLabels(tagRecord(labels));\n\nconst toId = (id: string, instanceId: string | undefined, existing?: string) =>\n Effect.gen(function* () {\n return (\n instanceId ??\n existing ??\n rfc1035(\n yield* createPhysicalName({\n id,\n maxLength: MAX_NAME_LENGTH,\n lowercase: true,\n }),\n )\n );\n });\n\nconst paramsOf = (\n params: Record\u003cstring, string | undefined> | null | undefined,\n): Record\u003cstring, string> =>\n Object.fromEntries(\n Object.entries(params ?? {}).filter(\n (entry): entry is [string, string] => entry[1] !== undefined,\n ),\n );\n\nconst paramsKey = (params: Record\u003cstring, string | undefined> | null | undefined) =>\n JSON.stringify(\n Object.fromEntries(Object.entries(paramsOf(params)).sort(([a], [b]) => a.localeCompare(b))),\n );\n\nconst listKey = (values: readonly string[] | undefined) =>\n JSON.stringify([...(values ?? [])].map((value) => value.toLowerCase()).sort());\n\nconst nodeConfigOf = (config: NodeConfig | undefined): NodeConfig => ({\n cpuCount: config?.cpuCount ?? DEFAULT_CPU_COUNT,\n memorySizeMb: config?.memorySizeMb ?? DEFAULT_MEMORY_SIZE_MB,\n});\n\nconst nodeConfigKey = (config: NodeConfig | undefined) => {\n const value = nodeConfigOf(config);\n return JSON.stringify({\n cpuCount: value.cpuCount,\n memorySizeMb: value.memorySizeMb,\n });\n};\n\nconst windowKey = (window: WeeklyMaintenanceWindow) =>\n JSON.stringify({\n day: (window.day ?? \"\").toUpperCase(),\n hours: window.startTime?.hours ?? 0,\n minutes: window.startTime?.minutes ?? 0,\n seconds: window.startTime?.seconds ?? 0,\n nanos: window.startTime?.nanos ?? 0,\n duration: window.duration ?? \"\",\n });\n\nconst maintenanceOf = (\n policy: memcache.GoogleCloudMemcacheV1MaintenancePolicy | MaintenancePolicy | undefined,\n): MaintenancePolicy | undefined => {\n if (policy === undefined) return undefined;\n return {\n description: policy.description,\n weeklyMaintenanceWindow: policy.weeklyMaintenanceWindow,\n };\n};\n\nconst maintenanceKey = (policy: MaintenancePolicy | undefined) =>\n JSON.stringify({\n description: policy?.description ?? \"\",\n windows: (policy?.weeklyMaintenanceWindow ?? []).map(windowKey),\n });\n\nconst parseMemcacheVersion = (version: string | undefined) => {\n if (version === undefined) return undefined;\n const match = version.toUpperCase().match(/^MEMCACHE_(\\d+)_(\\d+)(?:_(\\d+))?$/);\n if (!match) return undefined;\n return Number(match[1]) * 10_000 + Number(match[2]) * 100 + Number(match[3] ?? 0);\n};\n\nconst versionDecreasing = (previous: string | undefined, next: string) => {\n const oldN = parseMemcacheVersion(previous);\n const newN = parseMemcacheVersion(next);\n if (oldN === undefined || newN === undefined) return previous !== next;\n return newN \u003c oldN;\n};\n\nconst toAttrs = (instance: memcache.Instance, project: string, region: string) => {\n const name = instance.name ?? \"\";\n const parsed = parseName(name, region);\n return {\n name,\n instanceId: parsed.instanceId,\n project: parsed.project || project,\n location: parsed.location,\n displayName: instance.displayName,\n labels: userLabels(instance.labels),\n authorizedNetwork: instance.authorizedNetwork,\n zones: instance.zones ?? [],\n nodeCount: instance.nodeCount ?? DEFAULT_NODE_COUNT,\n nodeConfig: nodeConfigOf(instance.nodeConfig),\n memcacheVersion: instance.memcacheVersion,\n memcacheFullVersion: instance.memcacheFullVersion,\n parameters: paramsOf(instance.parameters?.params),\n parameterId: instance.parameters?.id,\n memcacheNodes: instance.memcacheNodes ?? [],\n state: instance.state,\n discoveryEndpoint: instance.discoveryEndpoint,\n reservedIpRangeId: instance.reservedIpRangeId ?? [],\n maintenanceVersion: instance.maintenanceVersion,\n effectiveMaintenanceVersion: instance.effectiveMaintenanceVersion,\n createTime: instance.createTime,\n updateTime: instance.updateTime,\n };\n};\n\nconst isPlaceholder = (instance: memcache.Instance) => {\n const name = instance.name ?? \"\";\n return name.endsWith(\"/instances/-\") || name.endsWith(\"/instances/\");\n};\n\nconst getByName = (name: string) =>\n memcache\n .getProjectsLocationsInstances({ name })\n .pipe(Effect.catchTag(\"NotFound\", () => Effect.undefined));\n\n/**\n * Wait for a Memorystore for Memcached operation; instance create,\n * resize, and upgrade take 10–20 minutes. With `notFoundOk`, NOT_FOUND\n * (code 5) and an operation that is already gone count as success\n * (delete race).\n */\nconst waitForOperation = (operation: memcache.Operation, options?: { notFoundOk?: boolean }) =>\n waitForGcpOperation(operation, (name) => memcache.getProjectsLocationsOperations({ name }), {\n budget: \"30 minutes\",\n interval: \"10 seconds\",\n }).pipe(\n Effect.catchIf(\n (error) =>\n options?.notFoundOk === true &&\n (error._tag === \"NotFound\" || (error._tag === \"GCP.OperationFailed\" && error.code === 5)),\n () => Effect.succeed(operation),\n ),\n );\n\nconst waitUntilExists = (name: string) =>\n getByName(name).pipe(\n Effect.flatMap((instance) =>\n instance\n ? Effect.succeed(instance)\n : Effect.fail(new InstanceNotResolved({ resourceName: name })),\n ),\n Effect.retry({\n while: (error) => error._tag === \"GCP.Memcache.InstanceNotResolved\",\n times: 8,\n schedule: Schedule.spaced(\"1 second\"),\n }),\n );\n\nconst waitUntilReady = (name: string) =>\n getByName(name).pipe(\n Effect.filterOrFail(\n (instance): instance is memcache.Instance => instance !== undefined,\n () => new InstanceNotResolved({ resourceName: name }),\n ),\n Effect.filterOrFail(\n (instance) => (instance.state ?? \"STATE_UNSPECIFIED\") === \"READY\",\n (instance) =>\n new InstanceNotReady({\n resourceName: name,\n state: instance.state ?? \"STATE_UNSPECIFIED\",\n }),\n ),\n Effect.retry({\n while: (error) =>\n error._tag === \"GCP.Memcache.InstanceNotReady\" ||\n error._tag === \"GCP.Memcache.InstanceNotResolved\",\n times: 10,\n schedule: Schedule.spaced(\"8 seconds\"),\n }),\n );\n\nconst waitUntilGone = (name: string) =>\n getByName(name).pipe(\n Effect.flatMap((instance) =>\n instance === undefined\n ? Effect.void\n : Effect.fail(new InstanceStillExists({ resourceName: name })),\n ),\n Effect.retry({\n while: (error) => error._tag === \"GCP.Memcache.InstanceStillExists\",\n times: 10,\n schedule: Schedule.spaced(\"8 seconds\"),\n }),\n );\n\nconst toCreateBody = (\n news: InstanceProps,\n desiredLabels: Record\u003cstring, string>,\n nodeCount: number,\n nodeConfig: NodeConfig,\n): memcache.Instance => ({\n displayName: news.displayName,\n labels: desiredLabels,\n authorizedNetwork: news.authorizedNetwork,\n zones: news.zones,\n nodeCount,\n nodeConfig,\n memcacheVersion: news.memcacheVersion,\n parameters: news.parameters === undefined ? undefined : { params: news.parameters },\n maintenancePolicy: news.maintenancePolicy,\n reservedIpRangeId: news.reservedIpRangeId,\n});\n\nexport const InstanceProvider = () =>\n Provider.succeed(Instance, {\n stables: [\"name\", \"instanceId\", \"project\", \"location\", \"createTime\"],\n\n diff: Effect.fn(function* ({ news, olds, output }) {\n if (!isResolved(news)) return undefined;\n const env = yield* GcpEnvironment.current;\n\n const previousId = olds?.instanceId ?? output?.instanceId;\n const nextId = news.instanceId ?? previousId;\n const previousLocation = normalizeLocation(olds?.location ?? output?.location, env.region);\n const nextLocation = normalizeLocation(news.location ?? output?.location, env.region);\n const previousNetwork = olds?.authorizedNetwork ?? output?.authorizedNetwork ?? \"\";\n const nextNetwork = news.authorizedNetwork ?? previousNetwork;\n const previousZones = listKey(olds?.zones ?? output?.zones);\n const nextZones = news.zones !== undefined ? listKey(news.zones) : previousZones;\n const previousNodeConfig = nodeConfigKey(olds?.nodeConfig ?? output?.nodeConfig);\n const nextNodeConfig = nodeConfigKey(news.nodeConfig ?? output?.nodeConfig);\n const previousRanges = listKey(olds?.reservedIpRangeId ?? output?.reservedIpRangeId);\n const nextRanges =\n news.reservedIpRangeId !== undefined ? listKey(news.reservedIpRangeId) : previousRanges;\n const previousVersion = olds?.memcacheVersion ?? output?.memcacheVersion;\n const nextVersion = news.memcacheVersion;\n const downgrade =\n nextVersion !== undefined &&\n previousVersion !== undefined &&\n versionDecreasing(previousVersion, nextVersion);\n\n const replace =\n (previousId !== undefined && nextId !== undefined && nextId !== previousId) ||\n previousLocation !== nextLocation ||\n previousNetwork !== nextNetwork ||\n previousZones !== nextZones ||\n previousNodeConfig !== nextNodeConfig ||\n previousRanges !== nextRanges ||\n downgrade;\n\n if (!replace) return undefined;\n return {\n action: \"replace\" as const,\n deleteFirst:\n previousLocation === nextLocation && previousId !== undefined && nextId === previousId,\n };\n }),\n\n read: Effect.fn(function* ({ id, olds, output }) {\n const env = yield* GcpEnvironment.current;\n const instanceId = yield* toId(id, olds?.instanceId, output?.instanceId);\n const location = normalizeLocation(olds?.location ?? output?.location, env.region);\n const name = output?.name ?? resourceName(env.project, location, instanceId);\n const existing = yield* getByName(name);\n if (existing === undefined) return undefined;\n const attrs = toAttrs(existing, env.project, env.region);\n return (yield* hasAlchemyLabels(id, tagRecord(existing.labels))) ? attrs : Unowned(attrs);\n }),\n\n list: () =>\n Effect.gen(function* () {\n const env = yield* GcpEnvironment.current;\n return yield* memcache.listProjectsLocationsInstances\n .pages({\n parent: `projects/${env.project}/locations/-`,\n pageSize: 1000,\n })\n .pipe(\n Stream.flatMap((page) => Stream.fromIterable(page.instances ?? [])),\n Stream.filter(\n (instance) =>\n !isPlaceholder(instance) &&\n Object.keys(instance.labels ?? {}).some((key) => key.startsWith(\"alchemy-\")),\n ),\n Stream.map((instance) => toAttrs(instance, env.project, env.region)),\n Stream.runCollect,\n Effect.map((chunk) => Array.from(chunk)),\n Effect.catchTag(\"NotFound\", () => Effect.succeed([])),\n );\n }),\n\n reconcile: Effect.fn(function* ({ id, news, output }) {\n const env = yield* GcpEnvironment.current;\n const instanceId = yield* toId(id, news.instanceId, output?.instanceId);\n const location = normalizeLocation(news.location ?? output?.location, env.region);\n const name = resourceName(env.project, location, instanceId);\n const nodeCount = news.nodeCount ?? DEFAULT_NODE_COUNT;\n const nodeConfig = nodeConfigOf(news.nodeConfig);\n const desiredLabels = {\n ...toLabels(news.labels),\n ...(yield* createInternalLabels(id)),\n };\n\n let current = yield* getByName(output?.name ?? name);\n\n if (current === undefined) {\n const created = yield* memcache\n .createProjectsLocationsInstances({\n parent: `projects/${env.project}/locations/${location}`,\n instanceId,\n body: toCreateBody(news, desiredLabels, nodeCount, nodeConfig),\n })\n .pipe(Effect.catchTag(\"Conflict\", () => Effect.undefined));\n if (created !== undefined) {\n yield* waitForOperation(created);\n }\n current = yield* waitUntilExists(name);\n }\n\n if (current === undefined) {\n return yield* new InstanceNotResolved({ resourceName: name });\n }\n\n if ((current.state ?? \"\") !== \"READY\") {\n current = yield* waitUntilReady(name);\n }\n\n const desiredVersion = news.memcacheVersion;\n const currentVersion = current.memcacheVersion;\n if (\n desiredVersion !== undefined &&\n currentVersion !== undefined &&\n desiredVersion !== currentVersion &&\n !versionDecreasing(currentVersion, desiredVersion)\n ) {\n const upgraded = yield* memcache.upgradeProjectsLocationsInstances({\n name,\n body: { memcacheVersion: desiredVersion },\n });\n yield* waitForOperation(upgraded);\n current = yield* waitUntilReady(name);\n }\n\n const observedLabels = tagRecord(current.labels);\n const { upsert, removed } = diffLabels(observedLabels, desiredLabels);\n const labelsChanged = upsert.length > 0 || removed.length > 0;\n const displayNameChanged = (current.displayName ?? \"\") !== (news.displayName ?? \"\");\n const desiredNodeCount = news.nodeCount ?? current.nodeCount ?? nodeCount;\n const nodeCountChanged = (current.nodeCount ?? DEFAULT_NODE_COUNT) !== desiredNodeCount;\n const maintenanceChanged =\n news.maintenancePolicy !== undefined &&\n maintenanceKey(maintenanceOf(current.maintenancePolicy)) !==\n maintenanceKey(news.maintenancePolicy);\n const maintenanceVersionChanged =\n news.maintenanceVersion !== undefined &&\n (current.maintenanceVersion ?? \"\") !== news.maintenanceVersion;\n\n if (\n labelsChanged ||\n displayNameChanged ||\n nodeCountChanged ||\n maintenanceChanged ||\n maintenanceVersionChanged\n ) {\n const updateMask = [\n labelsChanged ? \"labels\" : undefined,\n displayNameChanged ? \"displayName\" : undefined,\n nodeCountChanged ? \"nodeCount\" : undefined,\n maintenanceChanged ? \"maintenancePolicy\" : undefined,\n maintenanceVersionChanged ? \"maintenanceVersion\" : undefined,\n ].filter((field): field is string => field !== undefined);\n\n const patched = yield* memcache.patchProjectsLocationsInstances({\n name,\n updateMask: updateMask.join(\",\"),\n body: {\n name,\n labels: desiredLabels,\n displayName: news.displayName,\n nodeCount: desiredNodeCount,\n maintenancePolicy: news.maintenancePolicy,\n maintenanceVersion: news.maintenanceVersion,\n },\n });\n yield* waitForOperation(patched);\n current = yield* waitUntilReady(name);\n }\n\n const parametersChanged =\n news.parameters !== undefined &&\n paramsKey(current.parameters?.params) !== paramsKey(news.parameters);\n if (parametersChanged) {\n const updated = yield* memcache.updateParametersProjectsLocationsInstances({\n name,\n body: {\n updateMask: \"parameters\",\n parameters: { params: news.parameters },\n },\n });\n yield* waitForOperation(updated);\n const applied = yield* memcache.applyParametersProjectsLocationsInstances({\n name,\n body: { applyAll: true },\n });\n yield* waitForOperation(applied);\n current = yield* waitUntilReady(name);\n }\n\n return toAttrs(current, env.project, env.region);\n }),\n\n delete: Effect.fn(function* ({ output }) {\n const operation = yield* memcache\n .deleteProjectsLocationsInstances({ name: output.name })\n .pipe(\n Effect.catchTag(\"NotFound\", () => Effect.undefined),\n Effect.retry({\n while: (error) => error._tag === \"Conflict\",\n times: 8,\n schedule: Schedule.spaced(\"5 seconds\"),\n }),\n );\n if (operation !== undefined) {\n yield* waitForOperation(operation, { notFoundOk: true });\n }\n yield* waitUntilGone(output.name);\n }),\n });\n","preview":null,"history":null,"version":"c56bee10dad161d5376ab410df21f57dce3e2bc6"},"/_session?shell=1":null}