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

main
ts 259 lines 9.67 KB
Raw
1 import * as Neon from "@distilled.cloud/neon";
2 import { OwnedBySomeoneElse, unownedUnlessPrevious } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import * as Data from "effect/Data";
7 import * as Effect from "effect/Effect";
8 import type { Providers } from "./Providers.ts";
9
10 export interface OrganizationVPCEndpointProps {
11 /** Existing Neon organization ID. Changing it replaces the registration, cleaning up the old scope first. */
12 orgId: string;
13 /** Neon AWS region ID, such as aws-us-east-2. Azure is not supported. Changes replace the registration. */
14 regionId: string;
15 /** Existing AWS VPC endpoint ID, not a VPC ID. Changes replace the registration. */
16 vpcEndpointId: string;
17 /** Descriptive label on the Neon registration. */
18 label: string;
19 }
20
21 export interface OrganizationVPCEndpointAttributes {
22 /** Organization containing the registration. */
23 orgId: string;
24 /** Neon AWS region containing the registration. */
25 regionId: string;
26 /** Referenced AWS VPC endpoint; never created, modified, or deleted by this resource. */
27 vpcEndpointId: string;
28 /** Observed label, or null when the registration is absent. */
29 label: string | null;
30 /** Original adopted label; null denotes a registration created by Alchemy. */
31 initialLabel: string | null;
32 /** Last managed label, retained across refreshes for drift-safe cleanup. */
33 managedLabel: string;
34 /** Observed Neon registration state (for example new or accepted); null when absent. */
35 state: string | null;
36 }
37
38 export interface OrganizationVPCEndpoint extends Resource<
39 "Neon.OrganizationVPCEndpoint",
40 OrganizationVPCEndpointProps,
41 OrganizationVPCEndpointAttributes,
42 never,
43 Providers
44 > {}
45
46 /**
47 * Register an EXISTING AWS PrivateLink endpoint with a Neon organization.
48 * Requires an entitled organization admin and a supported AWS region matching
49 * the endpoint and client. Azure is unsupported. Neon allows at most ten
50 * private networking configurations per AWS region. This neither provisions
51 * the AWS endpoint nor configures its DNS, and does not block public connections.
52 *
53 * Existing registrations require explicit resource-scoped adoption. Their label
54 * is durably captured before mutation and restored on destroy, without revoking
55 * the registration. New registrations are unregistered on destroy only if their
56 * label is still managed and no projects restrict access through them.
57 * IMPORTANT: Neon permanently prevents re-registering a removed endpoint in the
58 * same organization. Replacement cleans up the old scope first; use a fresh AWS
59 * endpoint when necessary. External drift blocks cleanup. Preserve the state
60 * store and serialize writers: Neon exposes no conditional association writes.
61 *
62 * ### Register private networking
63 * **Example:** Bind an existing AWS endpoint
64 * ```typescript
65 * const network = yield* Neon.OrganizationVPCEndpoint("PrivateNetwork", {
66 * orgId: "org-example-12345678",
67 * regionId: "aws-us-east-2",
68 * vpcEndpointId: "vpce-0123456789abcdef0",
69 * label: "Application network",
70 * });
71 * ```
72 *
73 * @resource
74 * @product Organization
75 */
76 export const OrganizationVPCEndpoint = Resource<OrganizationVPCEndpoint>(
77 "Neon.OrganizationVPCEndpoint",
78 );
79
80 export class InvalidOrganizationVPCEndpoint extends Data.TaggedError(
81 "InvalidOrganizationVPCEndpoint",
82 )<{
83 /** Invalid scope or unsafe mutation condition. */
84 message: string;
85 }> {}
86
87 /** @internal */
88 export const validateOrganizationVPCEndpoint = (props: OrganizationVPCEndpointProps) =>
89 /^[a-z0-9-]{1,60}$/.test(props.orgId) &&
90 /^aws-[a-z0-9-]+$/.test(props.regionId) &&
91 /^vpce-[a-f0-9]+$/.test(props.vpcEndpointId) &&
92 props.label.trim().length > 0
93 ? Effect.void
94 : Effect.fail(
95 new InvalidOrganizationVPCEndpoint({
96 message:
97 "An organization ID, AWS Neon region, existing vpce- endpoint ID, and nonempty label are required",
98 }),
99 );
100
101 const request = (scope: { orgId: string; regionId: string; vpcEndpointId: string }) => ({
102 org_id: scope.orgId,
103 region_id: scope.regionId,
104 vpc_endpoint_id: scope.vpcEndpointId,
105 });
106
107 const observe = (scope: { orgId: string; regionId: string; vpcEndpointId: string }) =>
108 Neon.getOrganizationVPCEndpointDetails(request(scope)).pipe(
109 Effect.catchTag("NotFound", () => Effect.undefined),
110 );
111
112 export const OrganizationVPCEndpointProvider = () =>
113 Provider.succeed(OrganizationVPCEndpoint, {
114 stables: ["orgId", "regionId", "vpcEndpointId", "initialLabel"],
115 diff: Effect.fn(function* ({ olds, news, output }) {
116 const previous = output ?? olds;
117 if (!("orgId" in news) || !("regionId" in news) || !("vpcEndpointId" in news)) {
118 return { action: "replace", deleteFirst: true } as const;
119 }
120 for (const key of ["orgId", "regionId", "vpcEndpointId"] as const) {
121 if (!isResolved(news[key]) || news[key] !== previous[key]) {
122 return { action: "replace", deleteFirst: true } as const;
123 }
124 }
125 if (!isResolved<OrganizationVPCEndpointProps>(news)) return;
126 yield* validateOrganizationVPCEndpoint(news);
127 if ((yield* observe(news))?.label !== news.label) {
128 return { action: "update" } as const;
129 }
130 }),
131 read: Effect.fn(function* ({ olds, output, previous }) {
132 const scope = output ?? olds;
133 if (!scope?.orgId || !scope.regionId || !scope.vpcEndpointId) return;
134 const observed = yield* observe(scope);
135 if (output)
136 return {
137 ...output,
138 label: observed?.label ?? null,
139 state: observed?.state ?? null,
140 };
141 if (!observed) return;
142 return unownedUnlessPrevious(
143 {
144 orgId: scope.orgId,
145 regionId: scope.regionId,
146 vpcEndpointId: scope.vpcEndpointId,
147 label: observed.label,
148 initialLabel: observed.label,
149 managedLabel: observed.label,
150 state: observed.state,
151 },
152 previous,
153 "vpcEndpointId",
154 );
155 }),
156 reconcile: Effect.fn(function* ({ news, output, olds }) {
157 yield* validateOrganizationVPCEndpoint(news);
158 if (
159 output &&
160 (output.orgId !== news.orgId ||
161 output.regionId !== news.regionId ||
162 output.vpcEndpointId !== news.vpcEndpointId)
163 ) {
164 return yield* new InvalidOrganizationVPCEndpoint({
165 message: "Registration identity changed without replacement",
166 });
167 }
168 const observed = yield* observe(news);
169 if (observed && !output) {
170 return yield* new OwnedBySomeoneElse({
171 message:
172 "Existing VPC registration requires scoped adoption; an equal endpoint ID is not ownership",
173 resourceType: "Neon.OrganizationVPCEndpoint",
174 });
175 }
176 if (
177 output &&
178 !olds &&
179 observed?.label !== output.managedLabel &&
180 observed?.label !== news.label
181 ) {
182 return yield* new InvalidOrganizationVPCEndpoint({
183 message: "VPC registration changed since its adoption baseline was captured",
184 });
185 }
186 if (!observed && output) {
187 return yield* new InvalidOrganizationVPCEndpoint({
188 message:
189 "The registration was removed externally; Neon forbids re-registering it in this organization",
190 });
191 }
192 if (observed?.label !== news.label) {
193 yield* Neon.assignOrganizationVPCEndpoint({
194 ...request(news),
195 label: news.label,
196 }).pipe(
197 Effect.catchTag(
198 "Conflict",
199 Effect.fn(function* (error) {
200 const raced = yield* observe(news);
201 if (!raced || raced.label !== news.label) return yield* error;
202 if (!output)
203 return yield* new OwnedBySomeoneElse({
204 message: "A registration appeared during creation; explicit adoption is required",
205 resourceType: "Neon.OrganizationVPCEndpoint",
206 });
207 }),
208 ),
209 );
210 }
211 const current = yield* observe(news);
212 if (!current || current.label !== news.label) {
213 return yield* new InvalidOrganizationVPCEndpoint({
214 message: "VPC registration changed during reconciliation",
215 });
216 }
217 return {
218 orgId: news.orgId,
219 regionId: news.regionId,
220 vpcEndpointId: news.vpcEndpointId,
221 label: current.label,
222 initialLabel: output?.initialLabel ?? null,
223 managedLabel: news.label,
224 state: current.state,
225 };
226 }),
227 delete: Effect.fn(function* ({ output, olds }) {
228 const observed = yield* observe(output);
229 if (!observed) return;
230 if (output.initialLabel !== null && observed.label === output.initialLabel) return;
231 if (observed.label !== output.managedLabel && observed.label !== olds.label) {
232 return yield* new InvalidOrganizationVPCEndpoint({
233 message: "Refusing cleanup of an externally relabeled VPC registration",
234 });
235 }
236 if (output.initialLabel !== null) {
237 yield* Neon.assignOrganizationVPCEndpoint({
238 ...request(output),
239 label: output.initialLabel,
240 }).pipe(
241 Effect.catchTag(
242 "NotFound",
243 Effect.fn(function* (error) {
244 if (yield* observe(output)) return yield* error;
245 }),
246 ),
247 );
248 } else {
249 if (observed.num_restricted_projects !== 0) {
250 return yield* new InvalidOrganizationVPCEndpoint({
251 message: "Remove project VPC restrictions before unregistering this endpoint",
252 });
253 }
254 yield* Neon.deleteOrganizationVPCEndpoint(request(output)).pipe(
255 Effect.catchTag("NotFound", () => Effect.void),
256 );
257 }
258 }),
259 });