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

main
ts 386 lines 14.3 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 ClusterSchedulerConfigInvalidProps extends Data.TaggedError(
15 "ClusterSchedulerConfigInvalidProps",
16 )<{
17 readonly message: string;
18 readonly cause?: unknown;
19 }> {}
20
21 export class ClusterSchedulerConfigUnexpectedResponse extends Data.TaggedError(
22 "ClusterSchedulerConfigUnexpectedResponse",
23 )<{
24 readonly message: string;
25 readonly cause?: unknown;
26 }> {}
27
28 export type SchedulerResourceStatus = sagemaker.SchedulerResourceStatus;
29
30 export interface ClusterSchedulerConfigProps {
31 /**
32 * Name of the cluster policy. Maximum 63 characters, alphanumeric and
33 * hyphens.
34 * @default ${app}-${stage}-${id}
35 */
36 name?: string;
37 /**
38 * ARN of the EKS-orchestrated HyperPod cluster the policy applies to.
39 * Changing the cluster replaces the policy. AWS allows ONE cluster
40 * policy per cluster — creating a second fails with the typed
41 * `ClusterSchedulerConfigAlreadyExists` error.
42 */
43 clusterArn: string;
44 /**
45 * The policy itself: task priority classes, fair-share allocation, and
46 * idle-resource sharing.
47 */
48 schedulerConfig?: sagemaker.SchedulerConfig;
49 /**
50 * A description of the cluster policy.
51 */
52 description?: string;
53 /**
54 * Tags to associate with the cluster policy. Merged with internal Alchemy
55 * tags.
56 */
57 tags?: Record<string, string>;
58 }
59
60 export interface ClusterSchedulerConfig extends Resource<
61 "AWS.SageMaker.ClusterSchedulerConfig",
62 ClusterSchedulerConfigProps,
63 {
64 /**
65 * The cluster policy's ID.
66 */
67 clusterSchedulerConfigId: string;
68 /**
69 * ARN of the cluster policy.
70 */
71 clusterSchedulerConfigArn: string;
72 /**
73 * The cluster policy's name.
74 */
75 name: string;
76 /**
77 * ARN of the HyperPod cluster the policy applies to.
78 */
79 clusterArn: string;
80 /**
81 * The policy's current version (incremented on every update).
82 */
83 clusterSchedulerConfigVersion: number;
84 },
85 never,
86 Providers
87 > {}
88
89 /**
90 * A SageMaker HyperPod cluster policy (task governance) — configures how an
91 * EKS-orchestrated HyperPod cluster prioritizes tasks and allocates idle
92 * compute across teams via priority classes and fair-share weights.
93 * ### Creating Cluster Policies
94 * **Example:** Priority Classes with Fair-Share
95 * ```typescript
96 * import * as AWS from "@alchemy.run/aws";
97 *
98 * const policy = yield* AWS.SageMaker.ClusterSchedulerConfig("Scheduler", {
99 * clusterArn: hyperpod.clusterArn,
100 * schedulerConfig: {
101 * PriorityClasses: [
102 * { Name: "inference", Weight: 100 },
103 * { Name: "training", Weight: 75 },
104 * ],
105 * FairShare: "Enabled",
106 * },
107 * description: "Prioritize inference over training",
108 * });
109 * ```
110 *
111 * @resource
112 */
113 export const ClusterSchedulerConfig = Resource<ClusterSchedulerConfig>(
114 "AWS.SageMaker.ClusterSchedulerConfig",
115 );
116
117 const createConfigName = (id: string, props: { name?: string | undefined }) =>
118 props.name ? Effect.succeed(props.name) : createPhysicalName({ id, maxLength: 63 });
119
120 const describeConfigOrUndefined = (configId: string) =>
121 sagemaker
122 .describeClusterSchedulerConfig({ ClusterSchedulerConfigId: configId })
123 .pipe(Effect.catchTag("ResourceNotFound", () => Effect.undefined));
124
125 /**
126 * Look a cluster policy up by exact name — used when state was lost (read
127 * without output) or a create raced.
128 */
129 const findConfigByName = Effect.fn(function* (name: string) {
130 const summaries = yield* sagemaker.listClusterSchedulerConfigs.pages({ NameContains: name }).pipe(
131 EffectStream.runCollect,
132 Effect.map((chunk) =>
133 Array.from(chunk).flatMap((page) => page.ClusterSchedulerConfigSummaries ?? []),
134 ),
135 );
136 return summaries.find((s) => s.Name === name && s.Status !== "Deleted");
137 });
138
139 const fetchConfigTags = Effect.fn(function* (arn: string) {
140 const response = yield* sagemaker
141 .listTags({ ResourceArn: arn })
142 .pipe(Effect.catchTag("AccessDeniedException", () => Effect.undefined));
143 return Object.fromEntries(
144 (response?.Tags ?? []).flatMap((tag) =>
145 tag.Key !== undefined ? [[tag.Key, tag.Value ?? ""]] : [],
146 ),
147 );
148 });
149
150 const toAttrs = (
151 described: sagemaker.DescribeClusterSchedulerConfigResponse,
152 ): ClusterSchedulerConfig["Attributes"] => ({
153 clusterSchedulerConfigId: described.ClusterSchedulerConfigId,
154 clusterSchedulerConfigArn: described.ClusterSchedulerConfigArn,
155 name: described.Name,
156 clusterArn: described.ClusterArn ?? "",
157 clusterSchedulerConfigVersion: described.ClusterSchedulerConfigVersion,
158 });
159
160 /**
161 * The cluster policy is still transitioning toward the awaited state —
162 * retried by the bounded wait schedule.
163 */
164 class SchedulerConfigNotReady extends Data.TaggedError("SchedulerConfigNotReady")<{
165 readonly configId: string;
166 readonly status: string | undefined;
167 }> {}
168
169 /**
170 * The cluster policy converged to a terminal failed status.
171 */
172 export class SchedulerConfigFailed extends Data.TaggedError("SchedulerConfigFailed")<{
173 readonly configId: string;
174 readonly status: string | undefined;
175 readonly message: string | undefined;
176 }> {}
177
178 const FAILED_STATUSES: string[] = [
179 "CreateFailed",
180 "CreateRollbackFailed",
181 "UpdateFailed",
182 "UpdateRollbackFailed",
183 "DeleteFailed",
184 "DeleteRollbackFailed",
185 ];
186
187 // Explicitly-typed retry wrapper — an inline `Effect.retry` in provider
188 // lifecycle code leaks `Retry.Return`'s conditional type into declaration
189 // emit and widens the provider layer to `unknown` for every consumer of
190 // `AWS.providers()`.
191 const retryWhileNotReady = <A, E extends { readonly _tag: string }, R>(
192 self: Effect.Effect<A, E, R>,
193 ): Effect.Effect<A, E, R> =>
194 Effect.retry(self, {
195 while: (e) => e._tag === "SchedulerConfigNotReady",
196 schedule: Schedule.max([Schedule.spaced("5 seconds"), Schedule.recurs(60)]),
197 });
198
199 const waitForConfig = (configId: string, target: "Ready" | "Gone") =>
200 retryWhileNotReady(
201 Effect.gen(function* () {
202 const described = yield* describeConfigOrUndefined(configId);
203 if (target === "Gone") {
204 if (described === undefined || described.Status === "Deleted") return;
205 if (FAILED_STATUSES.includes(described.Status)) {
206 return yield* new SchedulerConfigFailed({
207 configId,
208 status: described.Status,
209 message: described.FailureReason,
210 });
211 }
212 return yield* new SchedulerConfigNotReady({ configId, status: described.Status });
213 }
214 if (described?.Status === "Created" || described?.Status === "Updated") {
215 return;
216 }
217 if (described !== undefined && FAILED_STATUSES.includes(described.Status)) {
218 return yield* new SchedulerConfigFailed({
219 configId,
220 status: described.Status,
221 message: described.FailureReason,
222 });
223 }
224 return yield* new SchedulerConfigNotReady({ configId, status: described?.Status });
225 }),
226 );
227
228 export const ClusterSchedulerConfigProvider = () =>
229 Provider.effect(
230 ClusterSchedulerConfig,
231 Effect.gen(function* () {
232 return {
233 stables: ["clusterSchedulerConfigId", "clusterSchedulerConfigArn", "name", "clusterArn"],
234 list: () =>
235 Effect.gen(function* () {
236 const summaries = yield* sagemaker.listClusterSchedulerConfigs.pages({}).pipe(
237 EffectStream.runCollect,
238 Effect.map((chunk) =>
239 Array.from(chunk).flatMap((page) => page.ClusterSchedulerConfigSummaries ?? []),
240 ),
241 );
242 return summaries.flatMap((s) =>
243 s.ClusterSchedulerConfigId !== undefined && s.Status !== "Deleted"
244 ? [
245 {
246 clusterSchedulerConfigId: s.ClusterSchedulerConfigId,
247 clusterSchedulerConfigArn: s.ClusterSchedulerConfigArn ?? "",
248 name: s.Name ?? "",
249 clusterArn: s.ClusterArn ?? "",
250 clusterSchedulerConfigVersion: s.ClusterSchedulerConfigVersion ?? 1,
251 },
252 ]
253 : [],
254 );
255 }),
256 read: Effect.fn(function* ({ id, olds, output }) {
257 const configId =
258 output?.clusterSchedulerConfigId ??
259 (yield* findConfigByName(yield* createConfigName(id, olds ?? {})))
260 ?.ClusterSchedulerConfigId;
261 if (configId === undefined) return undefined;
262 const described = yield* describeConfigOrUndefined(configId);
263 if (!described || described.Status === "Deleting" || described.Status === "Deleted") {
264 return undefined;
265 }
266 const attrs = toAttrs(described);
267 const tags = yield* fetchConfigTags(attrs.clusterSchedulerConfigArn);
268 return (yield* hasAlchemyTags(id, tags as Tags)) ? attrs : Unowned(attrs);
269 }),
270 diff: Effect.fn(function* ({ id, news, olds }) {
271 if (!isResolved(news)) return;
272 if (olds === undefined) return;
273 const oldName = yield* createConfigName(id, olds);
274 const newName = yield* createConfigName(id, news);
275 // The name and target cluster are fixed at creation.
276 if (oldName !== newName || olds.clusterArn !== news.clusterArn) {
277 return { action: "replace" } as const;
278 }
279 }),
280 reconcile: Effect.fn(function* ({ id, news, output, session }) {
281 if (!news) {
282 return yield* new ClusterSchedulerConfigInvalidProps({
283 message: "SageMaker ClusterSchedulerConfig requires props",
284 });
285 }
286 const name = yield* createConfigName(id, news);
287 const internalTags = yield* createInternalTags(id);
288 const desiredTags = { ...internalTags, ...news.tags };
289
290 // Observe — by cached id first, then by name (lost state or race).
291 let configId = output?.clusterSchedulerConfigId;
292 let described =
293 configId !== undefined ? yield* describeConfigOrUndefined(configId) : undefined;
294 if (described === undefined) {
295 const found = yield* findConfigByName(name);
296 described =
297 found?.ClusterSchedulerConfigId !== undefined
298 ? yield* describeConfigOrUndefined(found.ClusterSchedulerConfigId)
299 : undefined;
300 }
301
302 // Ensure — create if missing; a Conflict means a concurrent
303 // create won the race, so re-observe by name.
304 if (described === undefined) {
305 const created = yield* sagemaker
306 .createClusterSchedulerConfig({
307 Name: name,
308 ClusterArn: news.clusterArn,
309 SchedulerConfig: news.schedulerConfig,
310 Description: news.description,
311 Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
312 Key,
313 Value,
314 })),
315 })
316 .pipe(Effect.catchTag("ConflictException", () => Effect.undefined));
317 configId =
318 created?.ClusterSchedulerConfigId ??
319 (yield* findConfigByName(name))?.ClusterSchedulerConfigId;
320 if (configId === undefined) {
321 return yield* new ClusterSchedulerConfigUnexpectedResponse({
322 message: `failed to create cluster scheduler config ${name}`,
323 });
324 }
325 yield* session.note(`Creating cluster policy ${name}...`);
326 yield* waitForConfig(configId, "Ready");
327 } else {
328 configId = described.ClusterSchedulerConfigId;
329 // Wait out any in-flight transition before diffing.
330 yield* waitForConfig(configId, "Ready");
331 described = yield* describeConfigOrUndefined(configId);
332 // Sync — diff observed policy against desired.
333 if (
334 described !== undefined &&
335 (JSON.stringify(described.SchedulerConfig) !== JSON.stringify(news.schedulerConfig) ||
336 (described.Description ?? undefined) !== (news.description ?? undefined))
337 ) {
338 yield* sagemaker.updateClusterSchedulerConfig({
339 ClusterSchedulerConfigId: configId,
340 TargetVersion: described.ClusterSchedulerConfigVersion,
341 SchedulerConfig: news.schedulerConfig,
342 Description: news.description,
343 });
344 yield* session.note(`Updating cluster policy ${name}...`);
345 yield* waitForConfig(configId, "Ready");
346 }
347 }
348
349 described = yield* describeConfigOrUndefined(configId);
350 if (described === undefined) {
351 return yield* new ClusterSchedulerConfigUnexpectedResponse({
352 message: `failed to read reconciled cluster scheduler config ${name}`,
353 });
354 }
355 const attrs = toAttrs(described);
356
357 // Sync tags — diff against OBSERVED cloud tags.
358 const currentTags = yield* fetchConfigTags(attrs.clusterSchedulerConfigArn);
359 const { removed, upsert } = diffTags(currentTags, desiredTags);
360 if (removed.length > 0) {
361 yield* sagemaker.deleteTags({
362 ResourceArn: attrs.clusterSchedulerConfigArn,
363 TagKeys: removed,
364 });
365 }
366 if (upsert.length > 0) {
367 yield* sagemaker.addTags({
368 ResourceArn: attrs.clusterSchedulerConfigArn,
369 Tags: upsert.map(({ Key, Value }) => ({ Key, Value })),
370 });
371 }
372
373 yield* session.note(attrs.clusterSchedulerConfigArn);
374 return attrs;
375 }),
376 delete: Effect.fn(function* ({ output }) {
377 yield* sagemaker
378 .deleteClusterSchedulerConfig({
379 ClusterSchedulerConfigId: output.clusterSchedulerConfigId,
380 })
381 .pipe(Effect.catchTag("ResourceNotFound", () => Effect.void));
382 yield* waitForConfig(output.clusterSchedulerConfigId, "Gone");
383 }),
384 };
385 }),
386 );