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

main
ts 431 lines 15.9 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 ComputeQuotaInvalidProps extends Data.TaggedError("ComputeQuotaInvalidProps")<{
15 readonly message: string;
16 readonly cause?: unknown;
17 }> {}
18
19 export class ComputeQuotaUnexpectedResponse extends Data.TaggedError(
20 "ComputeQuotaUnexpectedResponse",
21 )<{
22 readonly message: string;
23 readonly cause?: unknown;
24 }> {}
25
26 export interface ComputeQuotaProps {
27 /**
28 * Name of the compute allocation. Maximum 63 characters, alphanumeric and
29 * hyphens.
30 * @default ${app}-${stage}-${id}
31 */
32 name?: string;
33 /**
34 * ARN of the EKS-orchestrated HyperPod cluster the allocation applies to.
35 * Changing the cluster replaces the allocation.
36 */
37 clusterArn: string;
38 /**
39 * The team the quota is allocated to (its name maps to a Kubernetes
40 * namespace `hyperpod-ns-<team-name>`) and its fair-share weight.
41 */
42 computeQuotaTarget: sagemaker.ComputeQuotaTarget;
43 /**
44 * The allocation itself: instance-type quotas, the resource-sharing
45 * strategy for idle compute, and whether the team's own tasks can preempt
46 * each other.
47 */
48 computeQuotaConfig?: sagemaker.ComputeQuotaConfig;
49 /**
50 * Whether the quota is enforced.
51 * @default "Enabled"
52 */
53 activationState?: sagemaker.ActivationState;
54 /**
55 * A description of the compute allocation.
56 */
57 description?: string;
58 /**
59 * Tags to associate with the compute allocation. Merged with internal
60 * Alchemy tags.
61 */
62 tags?: Record<string, string>;
63 }
64
65 /**
66 * Kueue label selecting the task-governance queue. Set it on a
67 * `Kubernetes.Job` / `Kubernetes.Deployment`'s `labels` with the quota's
68 * `queueName` attribute to submit the workload through HyperPod task
69 * governance.
70 */
71 export const KUEUE_QUEUE_NAME_LABEL = "kueue.x-k8s.io/queue-name";
72
73 /**
74 * Kueue label selecting the task-governance priority class. Its value is
75 * `<PriorityClass name>-priority` for a class declared on the cluster's
76 * `AWS.SageMaker.ClusterSchedulerConfig`.
77 */
78 export const KUEUE_PRIORITY_CLASS_LABEL = "kueue.x-k8s.io/priority-class";
79
80 export interface ComputeQuota extends Resource<
81 "AWS.SageMaker.ComputeQuota",
82 ComputeQuotaProps,
83 {
84 /**
85 * The compute allocation's ID.
86 */
87 computeQuotaId: string;
88 /**
89 * ARN of the compute allocation.
90 */
91 computeQuotaArn: string;
92 /**
93 * The compute allocation's name.
94 */
95 name: string;
96 /**
97 * ARN of the HyperPod cluster the allocation applies to.
98 */
99 clusterArn: string;
100 /**
101 * The allocation's current version (incremented on every update).
102 */
103 computeQuotaVersion: number;
104 /**
105 * The team the quota is allocated to. Task governance materializes the
106 * `hyperpod-ns-<teamName>` namespace and its Kueue LocalQueue from it.
107 */
108 teamName: string;
109 /**
110 * The Kubernetes namespace task governance materializes for the team
111 * (`hyperpod-ns-<teamName>`). Pass it as a governed
112 * `Kubernetes.Job` / `Kubernetes.Deployment`'s `namespace`.
113 */
114 namespace: string;
115 /**
116 * The team's Kueue LocalQueue name
117 * (`hyperpod-ns-<teamName>-localqueue`). Set it on a governed
118 * workload's `labels` under {@link KUEUE_QUEUE_NAME_LABEL}.
119 */
120 queueName: string;
121 },
122 never,
123 Providers
124 > {}
125
126 /**
127 * A SageMaker HyperPod compute allocation (task governance) — reserves
128 * instance capacity on an EKS-orchestrated HyperPod cluster for a team,
129 * with fair-share weights and borrow/lend rules for idle compute.
130 * ### Creating Compute Allocations
131 * **Example:** Team Quota with Borrowing
132 * ```typescript
133 * import * as AWS from "@alchemy.run/aws";
134 *
135 * const quota = yield* AWS.SageMaker.ComputeQuota("ResearchQuota", {
136 * clusterArn: hyperpod.clusterArn,
137 * computeQuotaTarget: { TeamName: "research", FairShareWeight: 10 },
138 * computeQuotaConfig: {
139 * ComputeQuotaResources: [{ InstanceType: "ml.g5.xlarge", Count: 2 }],
140 * ResourceSharingConfig: { Strategy: "Lend", BorrowLimit: 50 },
141 * },
142 * });
143 * ```
144 *
145 * @resource
146 */
147 export const ComputeQuota = Resource<ComputeQuota>("AWS.SageMaker.ComputeQuota");
148
149 const createQuotaName = (id: string, props: { name?: string | undefined }) =>
150 props.name ? Effect.succeed(props.name) : createPhysicalName({ id, maxLength: 63 });
151
152 const describeQuotaOrUndefined = (quotaId: string) =>
153 sagemaker
154 .describeComputeQuota({ ComputeQuotaId: quotaId })
155 .pipe(Effect.catchTag("ResourceNotFound", () => Effect.undefined));
156
157 /**
158 * Look a compute allocation up by exact name — used when state was lost
159 * (read without output) or a create raced.
160 */
161 const findQuotaByName = Effect.fn(function* (name: string) {
162 const summaries = yield* sagemaker.listComputeQuotas.pages({ NameContains: name }).pipe(
163 EffectStream.runCollect,
164 Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.ComputeQuotaSummaries ?? [])),
165 );
166 return summaries.find((s) => s.Name === name && s.Status !== "Deleted");
167 });
168
169 const fetchQuotaTags = Effect.fn(function* (arn: string) {
170 const response = yield* sagemaker
171 .listTags({ ResourceArn: arn })
172 .pipe(Effect.catchTag("AccessDeniedException", () => Effect.undefined));
173 return Object.fromEntries(
174 (response?.Tags ?? []).flatMap((tag) =>
175 tag.Key !== undefined ? [[tag.Key, tag.Value ?? ""]] : [],
176 ),
177 );
178 });
179
180 const toAttrs = (described: sagemaker.DescribeComputeQuotaResponse): ComputeQuota["Attributes"] => {
181 const teamName = described.ComputeQuotaTarget?.TeamName ?? "";
182 return {
183 computeQuotaId: described.ComputeQuotaId,
184 computeQuotaArn: described.ComputeQuotaArn,
185 name: described.Name,
186 clusterArn: described.ClusterArn ?? "",
187 computeQuotaVersion: described.ComputeQuotaVersion,
188 teamName,
189 // Task-governance conventions: the quota materializes the team's
190 // namespace and Kueue LocalQueue under these derived names.
191 namespace: `hyperpod-ns-${teamName}`,
192 queueName: `hyperpod-ns-${teamName}-localqueue`,
193 };
194 };
195
196 /**
197 * The compute allocation is still transitioning toward the awaited state —
198 * retried by the bounded wait schedule.
199 */
200 class ComputeQuotaNotReady extends Data.TaggedError("ComputeQuotaNotReady")<{
201 readonly quotaId: string;
202 readonly status: string | undefined;
203 }> {}
204
205 /**
206 * The compute allocation converged to a terminal failed status.
207 */
208 export class ComputeQuotaFailed extends Data.TaggedError("ComputeQuotaFailed")<{
209 readonly quotaId: string;
210 readonly status: string | undefined;
211 readonly message: string | undefined;
212 }> {}
213
214 const FAILED_STATUSES: string[] = [
215 "CreateFailed",
216 "CreateRollbackFailed",
217 "UpdateFailed",
218 "UpdateRollbackFailed",
219 "DeleteFailed",
220 "DeleteRollbackFailed",
221 ];
222
223 // Explicitly-typed retry wrapper — an inline `Effect.retry` in provider
224 // lifecycle code leaks `Retry.Return`'s conditional type into declaration
225 // emit and widens the provider layer to `unknown` for every consumer of
226 // `AWS.providers()`.
227 const retryWhileNotReady = <A, E extends { readonly _tag: string }, R>(
228 self: Effect.Effect<A, E, R>,
229 ): Effect.Effect<A, E, R> =>
230 Effect.retry(self, {
231 while: (e) => e._tag === "ComputeQuotaNotReady",
232 schedule: Schedule.max([Schedule.spaced("5 seconds"), Schedule.recurs(60)]),
233 });
234
235 const waitForQuota = (quotaId: string, target: "Ready" | "Gone") =>
236 retryWhileNotReady(
237 Effect.gen(function* () {
238 const described = yield* describeQuotaOrUndefined(quotaId);
239 if (target === "Gone") {
240 if (described === undefined || described.Status === "Deleted") return;
241 if (FAILED_STATUSES.includes(described.Status)) {
242 return yield* new ComputeQuotaFailed({
243 quotaId,
244 status: described.Status,
245 message: described.FailureReason,
246 });
247 }
248 return yield* new ComputeQuotaNotReady({ quotaId, status: described.Status });
249 }
250 if (described?.Status === "Created" || described?.Status === "Updated") {
251 return;
252 }
253 if (described !== undefined && FAILED_STATUSES.includes(described.Status)) {
254 return yield* new ComputeQuotaFailed({
255 quotaId,
256 status: described.Status,
257 message: described.FailureReason,
258 });
259 }
260 return yield* new ComputeQuotaNotReady({ quotaId, status: described?.Status });
261 }),
262 );
263
264 export const ComputeQuotaProvider = () =>
265 Provider.effect(
266 ComputeQuota,
267 Effect.gen(function* () {
268 return {
269 stables: ["computeQuotaId", "computeQuotaArn", "name", "clusterArn"],
270 list: () =>
271 Effect.gen(function* () {
272 const summaries = yield* sagemaker.listComputeQuotas.pages({}).pipe(
273 EffectStream.runCollect,
274 Effect.map((chunk) =>
275 Array.from(chunk).flatMap((page) => page.ComputeQuotaSummaries ?? []),
276 ),
277 );
278 return summaries.flatMap((s) => {
279 if (s.ComputeQuotaId === undefined || s.Status === "Deleted") {
280 return [];
281 }
282 const teamName = s.ComputeQuotaTarget?.TeamName ?? "";
283 return [
284 {
285 computeQuotaId: s.ComputeQuotaId,
286 computeQuotaArn: s.ComputeQuotaArn ?? "",
287 name: s.Name ?? "",
288 clusterArn: s.ClusterArn ?? "",
289 computeQuotaVersion: s.ComputeQuotaVersion ?? 1,
290 teamName,
291 namespace: `hyperpod-ns-${teamName}`,
292 queueName: `hyperpod-ns-${teamName}-localqueue`,
293 },
294 ];
295 });
296 }),
297 read: Effect.fn(function* ({ id, olds, output }) {
298 const quotaId =
299 output?.computeQuotaId ??
300 (yield* findQuotaByName(yield* createQuotaName(id, olds ?? {})))?.ComputeQuotaId;
301 if (quotaId === undefined) return undefined;
302 const described = yield* describeQuotaOrUndefined(quotaId);
303 if (!described || described.Status === "Deleting" || described.Status === "Deleted") {
304 return undefined;
305 }
306 const attrs = toAttrs(described);
307 const tags = yield* fetchQuotaTags(attrs.computeQuotaArn);
308 return (yield* hasAlchemyTags(id, tags as Tags)) ? attrs : Unowned(attrs);
309 }),
310 diff: Effect.fn(function* ({ id, news, olds }) {
311 if (!isResolved(news)) return;
312 if (olds === undefined) return;
313 const oldName = yield* createQuotaName(id, olds);
314 const newName = yield* createQuotaName(id, news);
315 // The name and target cluster are fixed at creation.
316 if (oldName !== newName || olds.clusterArn !== news.clusterArn) {
317 return { action: "replace" } as const;
318 }
319 }),
320 reconcile: Effect.fn(function* ({ id, news, output, session }) {
321 if (!news) {
322 return yield* new ComputeQuotaInvalidProps({
323 message: "SageMaker ComputeQuota requires props",
324 });
325 }
326 const name = yield* createQuotaName(id, news);
327 const internalTags = yield* createInternalTags(id);
328 const desiredTags = { ...internalTags, ...news.tags };
329
330 // Observe — by cached id first, then by name (lost state or race).
331 let quotaId = output?.computeQuotaId;
332 let described =
333 quotaId !== undefined ? yield* describeQuotaOrUndefined(quotaId) : undefined;
334 if (described === undefined) {
335 const found = yield* findQuotaByName(name);
336 described =
337 found?.ComputeQuotaId !== undefined
338 ? yield* describeQuotaOrUndefined(found.ComputeQuotaId)
339 : undefined;
340 }
341
342 // Ensure — create if missing; a Conflict means a concurrent
343 // create won the race, so re-observe by name.
344 if (described === undefined) {
345 const created = yield* sagemaker
346 .createComputeQuota({
347 Name: name,
348 ClusterArn: news.clusterArn,
349 ComputeQuotaConfig: news.computeQuotaConfig,
350 ComputeQuotaTarget: news.computeQuotaTarget,
351 ActivationState: news.activationState,
352 Description: news.description,
353 Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
354 Key,
355 Value,
356 })),
357 })
358 .pipe(Effect.catchTag("ConflictException", () => Effect.undefined));
359 quotaId = created?.ComputeQuotaId ?? (yield* findQuotaByName(name))?.ComputeQuotaId;
360 if (quotaId === undefined) {
361 return yield* new ComputeQuotaUnexpectedResponse({
362 message: `failed to create compute quota ${name}`,
363 });
364 }
365 yield* session.note(`Creating compute quota ${name}...`);
366 yield* waitForQuota(quotaId, "Ready");
367 } else {
368 quotaId = described.ComputeQuotaId;
369 // Wait out any in-flight transition before diffing.
370 yield* waitForQuota(quotaId, "Ready");
371 described = yield* describeQuotaOrUndefined(quotaId);
372 // Sync — diff observed allocation against desired.
373 if (
374 described !== undefined &&
375 (JSON.stringify(described.ComputeQuotaConfig) !==
376 JSON.stringify(news.computeQuotaConfig) ||
377 JSON.stringify(described.ComputeQuotaTarget) !==
378 JSON.stringify(news.computeQuotaTarget) ||
379 (news.activationState !== undefined &&
380 described.ActivationState !== news.activationState) ||
381 (described.Description ?? undefined) !== (news.description ?? undefined))
382 ) {
383 yield* sagemaker.updateComputeQuota({
384 ComputeQuotaId: quotaId,
385 TargetVersion: described.ComputeQuotaVersion,
386 ComputeQuotaConfig: news.computeQuotaConfig,
387 ComputeQuotaTarget: news.computeQuotaTarget,
388 ActivationState: news.activationState,
389 Description: news.description,
390 });
391 yield* session.note(`Updating compute quota ${name}...`);
392 yield* waitForQuota(quotaId, "Ready");
393 }
394 }
395
396 described = yield* describeQuotaOrUndefined(quotaId);
397 if (described === undefined) {
398 return yield* new ComputeQuotaUnexpectedResponse({
399 message: `failed to read reconciled compute quota ${name}`,
400 });
401 }
402 const attrs = toAttrs(described);
403
404 // Sync tags — diff against OBSERVED cloud tags.
405 const currentTags = yield* fetchQuotaTags(attrs.computeQuotaArn);
406 const { removed, upsert } = diffTags(currentTags, desiredTags);
407 if (removed.length > 0) {
408 yield* sagemaker.deleteTags({
409 ResourceArn: attrs.computeQuotaArn,
410 TagKeys: removed,
411 });
412 }
413 if (upsert.length > 0) {
414 yield* sagemaker.addTags({
415 ResourceArn: attrs.computeQuotaArn,
416 Tags: upsert.map(({ Key, Value }) => ({ Key, Value })),
417 });
418 }
419
420 yield* session.note(attrs.computeQuotaArn);
421 return attrs;
422 }),
423 delete: Effect.fn(function* ({ output }) {
424 yield* sagemaker
425 .deleteComputeQuota({ ComputeQuotaId: output.computeQuotaId })
426 .pipe(Effect.catchTag("ResourceNotFound", () => Effect.void));
427 yield* waitForQuota(output.computeQuotaId, "Gone");
428 }),
429 };
430 }),
431 );