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

main
ts 333 lines 11.8 KB
Raw
1 import * as sagemaker from "@distilled.cloud/aws/sagemaker";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import { createPhysicalName } from "alchemy/PhysicalName";
5 import * as Provider from "alchemy/Provider";
6 import { Resource } from "alchemy/Resource";
7 import { createInternalTags, diffTags, hasAlchemyTags, type Tags } from "alchemy/Tags";
8 import * as Data from "effect/Data";
9 import * as Effect from "effect/Effect";
10 import * as Schedule from "effect/Schedule";
11 import * as EffectStream from "effect/Stream";
12 import type { Providers } from "../Providers.ts";
13
14 export class SageMakerEndpointInvalidProps extends Data.TaggedError(
15 "SageMakerEndpointInvalidProps",
16 )<{
17 readonly message: string;
18 readonly cause?: unknown;
19 }> {}
20
21 export class SageMakerEndpointUnexpectedResponse extends Data.TaggedError(
22 "SageMakerEndpointUnexpectedResponse",
23 )<{
24 readonly message: string;
25 readonly cause?: unknown;
26 }> {}
27
28 export type EndpointStatus = sagemaker.EndpointStatus;
29
30 export interface EndpointProps {
31 /**
32 * Name of the endpoint. Maximum 63 characters.
33 * @default ${app}-${stage}-${id}
34 */
35 endpointName?: string;
36 /**
37 * Name of the `EndpointConfig` that describes the models and hosting
38 * resources to deploy. Changing it updates the live endpoint in place
39 * (blue/green by default on the SageMaker side).
40 */
41 endpointConfigName: string;
42 /**
43 * Deployment (blue/green or rolling) configuration applied when the
44 * endpoint is updated to a new configuration.
45 */
46 deploymentConfig?: sagemaker.DeploymentConfig;
47 /**
48 * Tags to associate with the endpoint. Merged with internal Alchemy tags.
49 */
50 tags?: Record<string, string>;
51 }
52
53 export interface Endpoint extends Resource<
54 "AWS.SageMaker.Endpoint",
55 EndpointProps,
56 {
57 /**
58 * The endpoint's name.
59 */
60 endpointName: string;
61 /**
62 * ARN of the endpoint.
63 */
64 endpointArn: string;
65 /**
66 * Lifecycle status of the endpoint after reconcile (`InService`).
67 */
68 endpointStatus: EndpointStatus | undefined;
69 },
70 never,
71 Providers
72 > {}
73
74 /**
75 * An Amazon SageMaker Endpoint — the live, invocable deployment of an
76 * `EndpointConfig`. Provisioning takes minutes and **bills while the
77 * endpoint exists** (serverless variants bill per request; instance variants
78 * bill per instance-hour). Destroy endpoints promptly.
79 *
80 * Invoke a deployed endpoint from a function with
81 * `AWS.SageMakerRuntime.InvokeEndpoint`.
82 * ### Creating Endpoints
83 * **Example:** Deploy an EndpointConfig
84 * ```typescript
85 * import * as AWS from "@alchemy.run/aws";
86 *
87 * const endpoint = yield* AWS.SageMaker.Endpoint("MyEndpoint", {
88 * endpointConfigName: config.endpointConfigName,
89 * });
90 * ```
91 *
92 * ### Invoking
93 * **Example:** Invoke from a Lambda function
94 * ```typescript
95 * // init
96 * const invoke = yield* AWS.SageMakerRuntime.InvokeEndpoint(
97 * endpoint.endpointName,
98 * );
99 *
100 * // runtime
101 * const result = yield* invoke({
102 * ContentType: "application/json",
103 * Body: JSON.stringify({ instances: [[1, 2, 3, 4]] }),
104 * });
105 * ```
106 *
107 * @resource
108 */
109 export const Endpoint = Resource<Endpoint>("AWS.SageMaker.Endpoint");
110
111 const createEndpointName = (id: string, props: { endpointName?: string | undefined }) =>
112 props.endpointName
113 ? Effect.succeed(props.endpointName)
114 : createPhysicalName({ id, maxLength: 63 });
115
116 const fetchEndpointTags = Effect.fn(function* (arn: string) {
117 const response = yield* sagemaker
118 .listTags({ ResourceArn: arn })
119 .pipe(Effect.catchTag("AccessDeniedException", () => Effect.undefined));
120 return Object.fromEntries(
121 (response?.Tags ?? []).flatMap((tag) =>
122 tag.Key !== undefined ? [[tag.Key, tag.Value ?? ""]] : [],
123 ),
124 );
125 });
126
127 const describeEndpointOrUndefined = (name: string) =>
128 sagemaker
129 .describeEndpoint({ EndpointName: name })
130 .pipe(Effect.catchTag("EndpointNotFound", () => Effect.undefined));
131
132 /**
133 * The endpoint is still transitioning toward the awaited state — retried by
134 * the bounded wait schedule.
135 */
136 class EndpointNotReady extends Data.TaggedError("EndpointNotReady")<{
137 readonly endpointName: string;
138 readonly status: string | undefined;
139 }> {}
140
141 /**
142 * The endpoint's asynchronous provisioning converged to the terminal
143 * `Failed` status (e.g. the container image could not be pulled or the model
144 * server failed its health checks).
145 */
146 export class EndpointProvisioningFailed extends Data.TaggedError("EndpointProvisioningFailed")<{
147 readonly endpointName: string;
148 readonly message: string | undefined;
149 }> {}
150
151 // Explicitly-typed retry wrapper — an inline `Effect.retry` in provider
152 // lifecycle code leaks `Retry.Return`'s conditional type into declaration
153 // emit and widens the provider layer to `unknown` for every consumer of
154 // `AWS.providers()`.
155 const retryWhileNotReady = <A, E extends { readonly _tag: string }, R>(
156 self: Effect.Effect<A, E, R>,
157 ): Effect.Effect<A, E, R> =>
158 Effect.retry(self, {
159 while: (e) => e._tag === "EndpointNotReady",
160 // Endpoint provisioning takes ~3-10 min; poll every 15s up to ~20 min.
161 schedule: Schedule.max([Schedule.spaced("15 seconds"), Schedule.recurs(80)]),
162 });
163
164 const waitForEndpoint = (name: string, target: "InService" | "Gone") =>
165 retryWhileNotReady(
166 Effect.gen(function* () {
167 const described = yield* describeEndpointOrUndefined(name);
168 if (target === "Gone") {
169 if (described === undefined) return;
170 return yield* new EndpointNotReady({
171 endpointName: name,
172 status: described.EndpointStatus,
173 });
174 }
175 if (described?.EndpointStatus === "InService") return;
176 if (described?.EndpointStatus === "Failed") {
177 return yield* new EndpointProvisioningFailed({
178 endpointName: name,
179 message: described.FailureReason,
180 });
181 }
182 return yield* new EndpointNotReady({
183 endpointName: name,
184 status: described?.EndpointStatus,
185 });
186 }),
187 );
188
189 export const EndpointProvider = () =>
190 Provider.effect(
191 Endpoint,
192 Effect.gen(function* () {
193 return {
194 stables: ["endpointName", "endpointArn"],
195 list: () =>
196 Effect.gen(function* () {
197 const summaries = yield* sagemaker.listEndpoints.pages({}).pipe(
198 EffectStream.runCollect,
199 Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.Endpoints ?? [])),
200 );
201 return summaries.flatMap((s) =>
202 s.EndpointName !== undefined && s.EndpointArn !== undefined
203 ? [
204 {
205 endpointName: s.EndpointName,
206 endpointArn: s.EndpointArn,
207 endpointStatus: s.EndpointStatus,
208 },
209 ]
210 : [],
211 );
212 }),
213 read: Effect.fn(function* ({ id, olds, output }) {
214 const name = output?.endpointName ?? (yield* createEndpointName(id, olds ?? {}));
215 const described = yield* describeEndpointOrUndefined(name);
216 if (!described || described.EndpointStatus === "Deleting") {
217 return undefined;
218 }
219 const attrs = {
220 endpointName: described.EndpointName,
221 endpointArn: described.EndpointArn,
222 endpointStatus: described.EndpointStatus,
223 };
224 const tags = yield* fetchEndpointTags(described.EndpointArn);
225 return (yield* hasAlchemyTags(id, tags as Tags)) ? attrs : Unowned(attrs);
226 }),
227 diff: Effect.fn(function* ({ id, news, olds }) {
228 if (!isResolved(news)) return;
229 if (olds === undefined) return;
230 const oldName = yield* createEndpointName(id, olds);
231 const newName = yield* createEndpointName(id, news);
232 if (oldName !== newName) {
233 return { action: "replace" } as const;
234 }
235 // endpointConfigName changes update the live endpoint in place.
236 }),
237 reconcile: Effect.fn(function* ({ id, news, output, session }) {
238 if (!news) {
239 return yield* new SageMakerEndpointInvalidProps({
240 message: "SageMaker Endpoint requires props",
241 });
242 }
243 const name = output?.endpointName ?? (yield* createEndpointName(id, news));
244 const internalTags = yield* createInternalTags(id);
245 const desiredTags = { ...internalTags, ...news.tags };
246
247 // Observe.
248 let described = yield* describeEndpointOrUndefined(name);
249
250 // A terminally-failed endpoint cannot be updated — delete it and
251 // fall through to a fresh create so the reconciler converges.
252 if (described?.EndpointStatus === "Failed") {
253 yield* session.note(
254 `Endpoint ${name} is Failed (${described.FailureReason ?? "unknown"}) — recreating`,
255 );
256 yield* sagemaker
257 .deleteEndpoint({ EndpointName: name })
258 .pipe(Effect.catchTag("EndpointNotFound", () => Effect.void));
259 yield* waitForEndpoint(name, "Gone");
260 described = undefined;
261 }
262
263 // Ensure — create if missing; tolerate the already-exists race.
264 if (described === undefined) {
265 yield* sagemaker
266 .createEndpoint({
267 EndpointName: name,
268 EndpointConfigName: news.endpointConfigName,
269 DeploymentConfig: news.deploymentConfig,
270 Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
271 Key,
272 Value,
273 })),
274 })
275 .pipe(Effect.catchTag("EndpointAlreadyExists", () => Effect.void));
276 yield* session.note(`Creating endpoint ${name}...`);
277 } else if (
278 described.EndpointConfigName !== news.endpointConfigName &&
279 described.EndpointStatus === "InService"
280 ) {
281 // Sync — roll the live endpoint onto the desired configuration.
282 yield* sagemaker.updateEndpoint({
283 EndpointName: name,
284 EndpointConfigName: news.endpointConfigName,
285 DeploymentConfig: news.deploymentConfig,
286 });
287 yield* session.note(
288 `Updating endpoint ${name} to config ${news.endpointConfigName}...`,
289 );
290 }
291
292 // Converge to InService (also settles Creating/Updating states we
293 // observed mid-flight, e.g. after a crashed reconcile).
294 yield* waitForEndpoint(name, "InService");
295 const final = yield* describeEndpointOrUndefined(name);
296 if (final === undefined) {
297 return yield* new SageMakerEndpointUnexpectedResponse({
298 message: `failed to read reconciled endpoint ${name}`,
299 });
300 }
301
302 // Sync tags — diff against OBSERVED cloud tags.
303 const currentTags = yield* fetchEndpointTags(final.EndpointArn);
304 const { removed, upsert } = diffTags(currentTags, desiredTags);
305 if (removed.length > 0) {
306 yield* sagemaker.deleteTags({
307 ResourceArn: final.EndpointArn,
308 TagKeys: removed,
309 });
310 }
311 if (upsert.length > 0) {
312 yield* sagemaker.addTags({
313 ResourceArn: final.EndpointArn,
314 Tags: upsert.map(({ Key, Value }) => ({ Key, Value })),
315 });
316 }
317
318 yield* session.note(final.EndpointArn);
319 return {
320 endpointName: final.EndpointName,
321 endpointArn: final.EndpointArn,
322 endpointStatus: final.EndpointStatus,
323 };
324 }),
325 delete: Effect.fn(function* ({ output }) {
326 yield* sagemaker
327 .deleteEndpoint({ EndpointName: output.endpointName })
328 .pipe(Effect.catchTag("EndpointNotFound", () => Effect.void));
329 yield* waitForEndpoint(output.endpointName, "Gone");
330 }),
331 };
332 }),
333 );