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

main
ts 260 lines 9 KB
Raw
1 import * as osis from "@distilled.cloud/aws/osis";
2 import { isResolved } from "alchemy/Diff";
3 import * as Provider from "alchemy/Provider";
4 import { Resource } from "alchemy/Resource";
5 import * as Data from "effect/Data";
6 import * as Effect from "effect/Effect";
7 import * as Schedule from "effect/Schedule";
8 import * as Stream from "effect/Stream";
9 import type { Providers } from "../Providers.ts";
10 import { jsonEquals } from "./internal.ts";
11
12 export class PipelineEndpointUnexpectedResponse extends Data.TaggedError(
13 "PipelineEndpointUnexpectedResponse",
14 )<{
15 readonly message: string;
16 readonly cause?: unknown;
17 }> {}
18
19 export interface PipelineEndpointVpcOptions {
20 /**
21 * Subnet IDs the endpoint's network interfaces are placed into. Changing
22 * subnets replaces the endpoint.
23 */
24 subnetIds: string[];
25 /**
26 * Security group IDs applied to the endpoint's network interfaces.
27 * Changing security groups replaces the endpoint.
28 */
29 securityGroupIds?: string[];
30 }
31
32 export interface PipelineEndpointProps {
33 /**
34 * ARN of the OSIS pipeline the endpoint ingests into. Changing the
35 * pipeline replaces the endpoint.
36 */
37 pipelineArn: string;
38 /**
39 * VPC placement for the endpoint. All fields are create-only — any change
40 * replaces the endpoint.
41 */
42 vpcOptions: PipelineEndpointVpcOptions;
43 }
44
45 export interface PipelineEndpoint extends Resource<
46 "AWS.OSIS.PipelineEndpoint",
47 PipelineEndpointProps,
48 {
49 /**
50 * Opaque id of the pipeline endpoint, assigned by OSIS on create.
51 */
52 endpointId: string;
53 /**
54 * ARN of the pipeline the endpoint ingests into.
55 */
56 pipelineArn: string;
57 /**
58 * Endpoint status (e.g. `ACTIVE`, `CREATING`, `REVOKED`).
59 */
60 status: string;
61 /**
62 * Id of the VPC the endpoint lives in.
63 */
64 vpcId: string | undefined;
65 /**
66 * The VPC-private ingest URL for the endpoint.
67 */
68 ingestEndpointUrl: string | undefined;
69 },
70 never,
71 Providers
72 > {}
73
74 /**
75 * A VPC endpoint for an Amazon OpenSearch Ingestion (OSIS) pipeline — lets
76 * clients inside a VPC ingest data into a pipeline privately, without
77 * traversing the public ingest endpoint.
78 *
79 * The target pipeline must itself be a VPC pipeline (`vpcOptions` set), and
80 * the endpoint must live in a different VPC than the pipeline — within the
81 * pipeline's own VPC, use its ingest URL instead. Every VPC involved needs
82 * `enableDnsSupport` and `enableDnsHostnames`. Cross-account endpoints also
83 * need an {@link ResourcePolicy} granting `osis:CreatePipelineEndpoint`.
84 *
85 * All properties are create-only; any change replaces the endpoint. The
86 * endpoint id is assigned by OSIS on create.
87 * ### Creating a Pipeline Endpoint
88 * **Example:** Private Ingest From a VPC
89 * ```typescript
90 * const endpoint = yield* OSIS.PipelineEndpoint("Private", {
91 * pipelineArn: pipeline.pipelineArn,
92 * vpcOptions: {
93 * subnetIds: [subnet.subnetId],
94 * securityGroupIds: [securityGroup.securityGroupId],
95 * },
96 * });
97 * // endpoint.ingestEndpointUrl — the VPC-private ingest URL
98 * ```
99 *
100 * @resource
101 */
102 export const PipelineEndpoint = Resource<PipelineEndpoint>("AWS.OSIS.PipelineEndpoint");
103
104 /**
105 * A pipeline endpoint whose asynchronous create converged to a failed
106 * status.
107 */
108 export class PipelineEndpointCreateFailed extends Data.TaggedError(
109 "OsisPipelineEndpointCreateFailed",
110 )<{
111 readonly endpointId: string;
112 readonly status: string;
113 }> {}
114
115 export const PipelineEndpointProvider = () =>
116 Provider.effect(
117 PipelineEndpoint,
118 Effect.gen(function* () {
119 /**
120 * There is no `getPipelineEndpoint` — observe by enumerating the
121 * account's endpoints and matching the id.
122 */
123 const findEndpoint = Effect.fn(function* (endpointId: string) {
124 return yield* osis.listPipelineEndpoints.pages({}).pipe(
125 Stream.runCollect,
126 Effect.map((chunk) =>
127 Array.from(chunk)
128 .flatMap((page) => page.PipelineEndpoints ?? [])
129 .find((endpoint) => endpoint.EndpointId === endpointId),
130 ),
131 );
132 });
133
134 const toAttrs = Effect.fn(function* (endpoint: osis.PipelineEndpoint) {
135 if (!endpoint.EndpointId || !endpoint.PipelineArn) {
136 return yield* new PipelineEndpointUnexpectedResponse({
137 message: `OSIS pipeline endpoint '${endpoint.EndpointId}' is missing its id or pipeline ARN`,
138 });
139 }
140 return {
141 endpointId: endpoint.EndpointId,
142 pipelineArn: endpoint.PipelineArn,
143 status: endpoint.Status ?? "ACTIVE",
144 vpcId: endpoint.VpcId,
145 ingestEndpointUrl: endpoint.IngestEndpointUrl,
146 };
147 });
148
149 /**
150 * Endpoint creation provisions VPC network interfaces and typically
151 * takes a few minutes. Bounded: 15s x 40 (~10 minutes). The explicit
152 * return annotation is load-bearing — see `waitForPipelineSettled` in
153 * `internal.ts`.
154 */
155 const waitForSettled = <E, R>(
156 read: Effect.Effect<osis.PipelineEndpoint | undefined, E, R>,
157 ): Effect.Effect<osis.PipelineEndpoint | undefined, E, R> =>
158 Effect.repeat(read, {
159 schedule: Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(40)]),
160 until: (endpoint): boolean => endpoint === undefined || endpoint.Status !== "CREATING",
161 });
162
163 return {
164 stables: ["endpointId", "pipelineArn"],
165
166 diff: Effect.fn(function* ({ olds, news }) {
167 if (!isResolved(news)) return undefined;
168 // Every property is create-only.
169 if (
170 olds?.pipelineArn !== news.pipelineArn ||
171 !jsonEquals(olds?.vpcOptions, news.vpcOptions)
172 ) {
173 return { action: "replace" } as const;
174 }
175 }),
176
177 read: Effect.fn(function* ({ output }) {
178 // The endpoint id is assigned by OSIS on create; without a
179 // persisted id there is nothing deterministic to look up.
180 if (output?.endpointId === undefined) return undefined;
181 const endpoint = yield* findEndpoint(output.endpointId);
182 if (endpoint === undefined) return undefined;
183 // Endpoints are not taggable — ownership is implied by the
184 // persisted create-assigned id.
185 return yield* toAttrs(endpoint);
186 }),
187
188 reconcile: Effect.fn(function* ({ news, output, session }) {
189 const props = news!;
190
191 // 1. Observe — the persisted id is a cache, not a guarantee.
192 let observed =
193 output?.endpointId !== undefined ? yield* findEndpoint(output.endpointId) : undefined;
194
195 // 2. Ensure — create if missing (ids are server-assigned, so
196 // there is no AlreadyExists race to tolerate).
197 if (observed === undefined) {
198 const created = yield* osis.createPipelineEndpoint({
199 PipelineArn: props.pipelineArn,
200 VpcOptions: {
201 SubnetIds: props.vpcOptions.subnetIds,
202 SecurityGroupIds: props.vpcOptions.securityGroupIds,
203 },
204 });
205 if (created.EndpointId === undefined) {
206 return yield* new PipelineEndpointUnexpectedResponse({
207 message: "OSIS createPipelineEndpoint returned no EndpointId",
208 });
209 }
210 observed = yield* findEndpoint(created.EndpointId);
211 }
212
213 // Wait (bounded) for the asynchronous create to settle; there is
214 // no mutable aspect to sync — every property is create-only.
215 if (observed?.Status === "CREATING" && observed.EndpointId) {
216 observed = yield* waitForSettled(findEndpoint(observed.EndpointId));
217 }
218 if (observed === undefined) {
219 return yield* new PipelineEndpointUnexpectedResponse({
220 message: "OSIS pipeline endpoint disappeared while waiting for create",
221 });
222 }
223 if (observed.Status === "CREATE_FAILED") {
224 return yield* new PipelineEndpointCreateFailed({
225 endpointId: observed.EndpointId ?? "",
226 status: observed.Status,
227 });
228 }
229
230 yield* session.note(observed.EndpointId ?? "");
231 return yield* toAttrs(observed);
232 }),
233
234 delete: Effect.fn(function* ({ output }) {
235 // Observe first for idempotency — the delete error union carries
236 // no typed not-found tag.
237 const observed = yield* findEndpoint(output.endpointId);
238 if (observed === undefined || observed.Status === "DELETING") {
239 return;
240 }
241 yield* osis.deletePipelineEndpoint({
242 EndpointId: output.endpointId,
243 });
244 }),
245
246 list: () =>
247 osis.listPipelineEndpoints.pages({}).pipe(
248 Stream.runCollect,
249 Effect.map((chunk) =>
250 Array.from(chunk).flatMap((page) => page.PipelineEndpoints ?? []),
251 ),
252 Effect.flatMap(
253 Effect.forEach((endpoint) => toAttrs(endpoint), {
254 concurrency: 4,
255 }),
256 ),
257 ),
258 };
259 }),
260 );