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

main
ts 259 lines 8.26 KB
Raw
1 import * as s3tables from "@distilled.cloud/aws/s3tables";
2 import { isResolved } from "alchemy/Diff";
3 import { createPhysicalName } from "alchemy/PhysicalName";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import * as Effect from "effect/Effect";
7 import * as Schedule from "effect/Schedule";
8 import type { Providers } from "../Providers.ts";
9
10 /**
11 * A field in an Apache Iceberg table schema.
12 */
13 export interface IcebergSchemaField {
14 /**
15 * Name of the field.
16 */
17 name: string;
18 /**
19 * Iceberg field type, e.g. `int`, `long`, `string`, `boolean`,
20 * `timestamp`, `date`, `decimal(10,2)`.
21 */
22 type: string;
23 /**
24 * Whether the field is required (non-nullable).
25 * @default false
26 */
27 required?: boolean;
28 }
29
30 export interface TableProps {
31 /**
32 * ARN of the table bucket that owns the table. Changing it replaces the
33 * table.
34 */
35 tableBucket: string;
36 /**
37 * Name of the namespace that owns the table. Changing it replaces the
38 * table.
39 */
40 namespace: string;
41 /**
42 * Name of the table. Must be 1-255 characters of lowercase letters,
43 * numbers, and underscores, beginning with a letter or number. Changing
44 * the name replaces the table.
45 * @default a deterministic name derived from the app, stage, and logical ID
46 */
47 name?: string;
48 /**
49 * Open table format. Only `ICEBERG` is supported.
50 * @default "ICEBERG"
51 */
52 format?: "ICEBERG";
53 /**
54 * Iceberg schema for the table, applied at create time. Schema evolution
55 * after creation is a data-plane concern; changing this replaces the
56 * table.
57 */
58 schema?: {
59 /**
60 * Ordered list of schema fields.
61 */
62 fields: IcebergSchemaField[];
63 };
64 }
65
66 export interface Table extends Resource<
67 "AWS.S3Tables.Table",
68 TableProps,
69 {
70 tableArn: string;
71 name: string;
72 namespace: string;
73 tableBucketArn: string;
74 versionToken: string;
75 metadataLocation: string | undefined;
76 warehouseLocation: string;
77 format: string;
78 type: string;
79 createdAt: Date;
80 },
81 never,
82 Providers
83 > {}
84
85 /**
86 * A fully-managed Apache Iceberg table within an S3 Tables {@link Namespace}.
87 *
88 * S3 Tables manages the table's storage, metadata, and maintenance
89 * (compaction, snapshot expiration). Query it through engines like Amazon
90 * Athena, Amazon EMR, or Apache Spark via the S3 Tables Iceberg catalog.
91 * ### Creating Tables
92 * **Example:** Table with an Iceberg schema
93 * ```typescript
94 * import * as S3Tables from "@alchemy.run/aws/S3Tables";
95 *
96 * const bucket = yield* S3Tables.TableBucket("Analytics");
97 * const ns = yield* S3Tables.Namespace("Events", {
98 * tableBucket: bucket.tableBucketArn,
99 * });
100 * const table = yield* S3Tables.Table("PageViews", {
101 * tableBucket: bucket.tableBucketArn,
102 * namespace: ns.namespace,
103 * schema: {
104 * fields: [
105 * { name: "id", type: "long", required: true },
106 * { name: "url", type: "string" },
107 * { name: "ts", type: "timestamp" },
108 * ],
109 * },
110 * });
111 * ```
112 *
113 * @resource
114 */
115 export const Table = Resource<Table>("AWS.S3Tables.Table");
116
117 const createTableName = (id: string, props: { name?: string | undefined }) =>
118 Effect.gen(function* () {
119 if (props.name) {
120 return props.name;
121 }
122 // Table names allow lowercase letters, numbers, and underscores only.
123 const base = yield* createPhysicalName({
124 id,
125 maxLength: 60,
126 lowercase: true,
127 });
128 return base.replaceAll("-", "_");
129 });
130
131 const buildMetadata = (props: TableProps): s3tables.TableMetadata | undefined =>
132 props.schema
133 ? {
134 iceberg: {
135 schema: {
136 fields: props.schema.fields.map((f) => ({
137 name: f.name,
138 type: f.type,
139 required: f.required,
140 })),
141 },
142 },
143 }
144 : undefined;
145
146 export const TableProvider = () =>
147 Provider.succeed(Table, {
148 stables: ["tableArn", "name", "namespace", "tableBucketArn"],
149 // Tables are scoped to a parent namespace; the engine drives lifecycle
150 // from state rather than ambient enumeration.
151 list: () => Effect.succeed([]),
152 read: Effect.fn(function* ({ id, olds, output }) {
153 const tableBucketArn = output?.tableBucketArn ?? olds?.tableBucket;
154 const namespace = output?.namespace ?? olds?.namespace;
155 if (typeof tableBucketArn !== "string" || typeof namespace !== "string") {
156 return undefined;
157 }
158 const name = output?.name ?? (yield* createTableName(id, olds ?? {}));
159 return yield* s3tables.getTable({ tableBucketARN: tableBucketArn, namespace, name }).pipe(
160 Effect.map((t): Table["Attributes"] => ({
161 tableArn: t.tableARN,
162 name: t.name,
163 namespace: t.namespace[0] ?? namespace,
164 tableBucketArn,
165 versionToken: t.versionToken,
166 metadataLocation: t.metadataLocation,
167 warehouseLocation: t.warehouseLocation,
168 format: t.format,
169 type: t.type,
170 createdAt: t.createdAt,
171 })),
172 Effect.catchTag("NotFoundException", () => Effect.undefined),
173 );
174 }),
175 diff: Effect.fn(function* ({ id, news, olds }) {
176 if (!isResolved(news)) return;
177 if (news.tableBucket !== olds?.tableBucket || news.namespace !== olds?.namespace) {
178 return { action: "replace" } as const;
179 }
180 const oldName = yield* createTableName(id, olds ?? {});
181 const newName = yield* createTableName(id, news);
182 if (oldName !== newName) {
183 return { action: "replace" } as const;
184 }
185 if ((news.format ?? "ICEBERG") !== (olds?.format ?? "ICEBERG")) {
186 return { action: "replace" } as const;
187 }
188 // Schema is fixed at create time; schema evolution is out of band.
189 const oldSchema = JSON.stringify(olds?.schema ?? null);
190 const newSchema = JSON.stringify(news.schema ?? null);
191 if (oldSchema !== newSchema) {
192 return { action: "replace" } as const;
193 }
194 }),
195 reconcile: Effect.fn(function* ({ id, news, output, session }) {
196 const tableBucketArn = news.tableBucket as string;
197 const namespace = news.namespace as string;
198 const name = output?.name ?? (yield* createTableName(id, news));
199
200 // Observe — read live state; the table may have been deleted
201 // out-of-band even if `output` cached its ARN.
202 let table = yield* s3tables
203 .getTable({ tableBucketARN: tableBucketArn, namespace, name })
204 .pipe(
205 Effect.map((t) => t),
206 Effect.catchTag("NotFoundException", () => Effect.undefined),
207 );
208
209 // Ensure — create if missing, tolerating a concurrent create.
210 if (table === undefined) {
211 yield* s3tables
212 .createTable({
213 tableBucketARN: tableBucketArn,
214 namespace,
215 name,
216 format: news.format ?? "ICEBERG",
217 metadata: buildMetadata(news),
218 })
219 .pipe(
220 Effect.asVoid,
221 Effect.catchTag("ConflictException", () => Effect.void),
222 );
223 // Eventual consistency: getTable can briefly 404 a table that
224 // createTable just returned.
225 table = yield* s3tables.getTable({ tableBucketARN: tableBucketArn, namespace, name }).pipe(
226 Effect.retry({
227 while: (e) => e._tag === "NotFoundException",
228 schedule: Schedule.max([Schedule.exponential(500), Schedule.recurs(8)]),
229 }),
230 );
231 }
232
233 yield* session.note(table.tableARN);
234 return {
235 tableArn: table.tableARN,
236 name: table.name,
237 namespace: table.namespace[0] ?? namespace,
238 tableBucketArn,
239 versionToken: table.versionToken,
240 metadataLocation: table.metadataLocation,
241 warehouseLocation: table.warehouseLocation,
242 format: table.format,
243 type: table.type,
244 createdAt: table.createdAt,
245 };
246 }),
247 delete: Effect.fn(function* ({ output }) {
248 // Deliberately NO versionToken: destroy is unconditional. Runtime
249 // commits (UpdateTableMetadataLocation) rotate the token, so the
250 // persisted one may be stale and would fail with ConflictException.
251 yield* s3tables
252 .deleteTable({
253 tableBucketARN: output.tableBucketArn,
254 namespace: output.namespace,
255 name: output.name,
256 })
257 .pipe(Effect.catchTag("NotFoundException", () => Effect.void));
258 }),
259 });