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

main
ts 390 lines 13.8 KB
Raw
1 import * as TSW from "@distilled.cloud/aws/timestream-write";
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 { toWireDays, toWireHours } from "alchemy/Util/Duration";
9 import * as Data from "effect/Data";
10 import type * as Duration from "effect/Duration";
11 import * as Effect from "effect/Effect";
12 import * as EffectStream from "effect/Stream";
13 import { AWSEnvironment, type AccountID } from "../Environment.ts";
14 import type { Providers } from "../Providers.ts";
15 import type { RegionID } from "../Region.ts";
16 import { withWriteEndpoint } from "./internal.ts";
17
18 export class TimestreamTableInvalidProps extends Data.TaggedError("TimestreamTableInvalidProps")<{
19 readonly message: string;
20 readonly cause?: unknown;
21 }> {}
22
23 export class TimestreamTableUnexpectedResponse extends Data.TaggedError(
24 "TimestreamTableUnexpectedResponse",
25 )<{
26 readonly message: string;
27 readonly cause?: unknown;
28 }> {}
29
30 export type TableArn =
31 `arn:aws:timestream:${RegionID}:${AccountID}:database/${string}/table/${string}`;
32
33 export type TableStatus = "ACTIVE" | "DELETING" | "RESTORING";
34
35 export interface TableRetentionProperties {
36 /**
37 * How long data stays in the memory store before moving to the magnetic
38 * store. Rounded to whole hours on the wire
39 * (`MemoryStoreRetentionPeriodInHours`).
40 */
41 memoryStoreRetention: Duration.Input;
42 /**
43 * How long data stays in the magnetic store before deletion. Rounded to
44 * whole days on the wire (`MagneticStoreRetentionPeriodInDays`).
45 */
46 magneticStoreRetention: Duration.Input;
47 }
48
49 export interface TableProps {
50 /**
51 * Name of the database that owns this table. Pass the `databaseName` of a
52 * {@link Database} resource.
53 */
54 databaseName: string;
55 /**
56 * Name of the table. Must be unique within the database and between 3 and
57 * 256 characters.
58 * @default ${app}-${stage}-${id}
59 */
60 tableName?: string;
61 /**
62 * Retention configuration for the table's memory and magnetic stores.
63 * @default { memoryStoreRetention: "6 hours", magneticStoreRetention: "73000 days" }
64 */
65 retentionProperties?: TableRetentionProperties;
66 /**
67 * Magnetic store write configuration, including whether late-arriving data
68 * is written to the magnetic store and where rejected records are logged.
69 */
70 magneticStoreWriteProperties?: TSW.MagneticStoreWriteProperties;
71 /**
72 * Partitioning schema for the table.
73 */
74 schema?: TSW.Schema;
75 /**
76 * Tags to associate with the table.
77 */
78 tags?: Record<string, string>;
79 }
80
81 export interface Table extends Resource<
82 "AWS.Timestream.Table",
83 TableProps,
84 {
85 /**
86 * The table's physical name.
87 */
88 tableName: string;
89 /**
90 * Name of the database that owns the table.
91 */
92 databaseName: string;
93 /**
94 * ARN of the table.
95 */
96 tableArn: TableArn;
97 /**
98 * Current lifecycle status of the table.
99 */
100 tableStatus: TableStatus;
101 /**
102 * Effective retention configuration for the table.
103 */
104 retentionProperties: TSW.RetentionProperties | undefined;
105 /**
106 * Effective magnetic store write configuration.
107 */
108 magneticStoreWriteProperties: TSW.MagneticStoreWriteProperties | undefined;
109 /**
110 * Current tags reported for the table.
111 */
112 tags: Record<string, string>;
113 },
114 never,
115 Providers
116 > {}
117
118 /**
119 * An Amazon Timestream for LiveAnalytics table — a time-series store inside a
120 * {@link Database}.
121 *
122 * `Table` owns the table's lifecycle and its mutable configuration: memory and
123 * magnetic store retention, magnetic store write behavior, and tags. A table
124 * name is auto-generated from the app, stage, and logical ID unless you provide
125 * one.
126 *
127 * :::note
128 * Timestream for LiveAnalytics is closed to new AWS customers. Accounts that
129 * were not already onboarded receive `TimestreamNotOnboarded` on every
130 * operation.
131 * :::
132 * ### Creating Tables
133 * **Example:** Basic Table
134 * ```typescript
135 * import * as Timestream from "@alchemy.run/aws/Timestream";
136 *
137 * const database = yield* Timestream.Database("Metrics");
138 * const table = yield* Timestream.Table("Cpu", {
139 * databaseName: database.databaseName,
140 * });
141 * ```
142 *
143 * **Example:** Table with Retention Tuning
144 * ```typescript
145 * const table = yield* Timestream.Table("Cpu", {
146 * databaseName: database.databaseName,
147 * retentionProperties: {
148 * memoryStoreRetention: "24 hours",
149 * magneticStoreRetention: "365 days",
150 * },
151 * });
152 * ```
153 *
154 * ### Writing Points
155 * **Example:** Write records from a handler
156 * ```typescript
157 * // init
158 * const writeRecords = yield* Timestream.WriteRecords(table);
159 *
160 * return {
161 * fetch: Effect.gen(function* () {
162 * // runtime
163 * yield* writeRecords({
164 * Records: [
165 * {
166 * Dimensions: [{ Name: "host", Value: "web-1" }],
167 * MeasureName: "cpu",
168 * MeasureValue: "42.0",
169 * MeasureValueType: "DOUBLE",
170 * Time: `${Date.now()}`,
171 * TimeUnit: "MILLISECONDS",
172 * },
173 * ],
174 * });
175 * return HttpServerResponse.text("ok");
176 * }),
177 * };
178 * ```
179 *
180 * @resource
181 */
182 export const Table = Resource<Table>("AWS.Timestream.Table");
183
184 const createTableName = (id: string, props: { tableName?: string | undefined }) =>
185 Effect.gen(function* () {
186 if (props.tableName) {
187 return props.tableName;
188 }
189 return yield* createPhysicalName({ id, maxLength: 256 });
190 });
191
192 const toTagRecord = (
193 tags: Array<{ Key: string; Value: string }> | undefined,
194 ): Record<string, string> => Object.fromEntries((tags ?? []).map((tag) => [tag.Key, tag.Value]));
195
196 /**
197 * Convert the alchemy-shaped {@link TableRetentionProperties} (Duration
198 * inputs) to Timestream's wire shape (whole hours / whole days).
199 */
200 const toWireRetention = (
201 retention: TableRetentionProperties | undefined,
202 ): TSW.RetentionProperties | undefined =>
203 retention === undefined
204 ? undefined
205 : {
206 MemoryStoreRetentionPeriodInHours: toWireHours(retention.memoryStoreRetention)!,
207 MagneticStoreRetentionPeriodInDays: toWireDays(retention.magneticStoreRetention)!,
208 };
209
210 const readTable = Effect.fn(function* (databaseName: string, tableName: string) {
211 const response = yield* withWriteEndpoint(
212 TSW.describeTable({ DatabaseName: databaseName, TableName: tableName }),
213 ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
214 if (!response?.Table) {
215 return undefined;
216 }
217 const table = response.Table;
218 const tagsResponse = yield* withWriteEndpoint(
219 TSW.listTagsForResource({ ResourceARN: table.Arn! }),
220 ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
221 if (!tagsResponse) {
222 return undefined;
223 }
224 return {
225 tableName: table.TableName!,
226 databaseName: table.DatabaseName!,
227 tableArn: table.Arn as TableArn,
228 tableStatus: (table.TableStatus ?? "ACTIVE") as TableStatus,
229 retentionProperties: table.RetentionProperties,
230 magneticStoreWriteProperties: table.MagneticStoreWriteProperties,
231 tags: toTagRecord(tagsResponse.Tags),
232 } satisfies Table["Attributes"];
233 });
234
235 export const TableProvider = () =>
236 Provider.effect(
237 Table,
238 Effect.gen(function* () {
239 return {
240 stables: ["tableName", "databaseName", "tableArn"],
241 // Enumerate every Timestream table in the ambient account/region.
242 // `listTables` with no `DatabaseName` lists across all databases; it is
243 // paginated, so collect every page and hydrate each into the `read`
244 // Attributes shape.
245 list: () =>
246 Effect.gen(function* () {
247 const refs = yield* withWriteEndpoint(
248 TSW.listTables.pages({}).pipe(EffectStream.runCollect),
249 ).pipe(
250 Effect.map((chunk) =>
251 Array.from(chunk).flatMap((page) =>
252 (page.Tables ?? []).flatMap((table) =>
253 table.DatabaseName && table.TableName
254 ? [
255 {
256 databaseName: table.DatabaseName,
257 tableName: table.TableName,
258 },
259 ]
260 : [],
261 ),
262 ),
263 ),
264 );
265 const hydrated = yield* Effect.forEach(
266 refs,
267 (ref) => readTable(ref.databaseName, ref.tableName),
268 { concurrency: 10 },
269 );
270 return hydrated.filter((attrs): attrs is Table["Attributes"] => attrs !== undefined);
271 }),
272 read: Effect.fn(function* ({ id, olds, output }) {
273 const databaseName = output?.databaseName ?? olds?.databaseName;
274 if (!databaseName) return undefined;
275 const tableName = output?.tableName ?? (yield* createTableName(id, olds ?? {}));
276 const state = yield* readTable(databaseName, tableName);
277 if (!state) return undefined;
278 return (yield* hasAlchemyTags(id, state.tags as Tags)) ? state : Unowned(state);
279 }),
280 diff: Effect.fn(function* ({ id, news, olds = {} }) {
281 if (!isResolved(news)) return;
282 const oldName = yield* createTableName(id, olds);
283 const newName = yield* createTableName(id, news);
284 // Table name or its owning database is immutable — either requires a
285 // replacement.
286 if (oldName !== newName || olds.databaseName !== news.databaseName) {
287 return { action: "replace" } as const;
288 }
289 }),
290 reconcile: Effect.fn(function* ({ id, news, output, session }) {
291 if (!news?.databaseName) {
292 return yield* new TimestreamTableInvalidProps({
293 message: "Timestream Table requires a databaseName",
294 });
295 }
296 const { accountId, region } = yield* AWSEnvironment.current;
297 const databaseName = news.databaseName;
298 const tableName = output?.tableName ?? (yield* createTableName(id, news));
299 const tableArn =
300 `arn:aws:timestream:${region}:${accountId}:database/${databaseName}/table/${tableName}` as TableArn;
301 const internalTags = yield* createInternalTags(id);
302 const desiredTags = { ...internalTags, ...news.tags };
303 const desiredRetention = toWireRetention(news.retentionProperties);
304
305 // Observe.
306 let state = yield* readTable(databaseName, tableName);
307
308 // Ensure — create if missing; tolerate a ConflictException race.
309 if (state === undefined) {
310 yield* withWriteEndpoint(
311 TSW.createTable({
312 DatabaseName: databaseName,
313 TableName: tableName,
314 RetentionProperties: desiredRetention,
315 MagneticStoreWriteProperties: news.magneticStoreWriteProperties,
316 Schema: news.schema,
317 Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
318 Key,
319 Value,
320 })),
321 }),
322 ).pipe(Effect.catchTag("ConflictException", () => Effect.void));
323 yield* session.note(`Creating table ${tableName}...`);
324 state = yield* readTable(databaseName, tableName);
325 if (state === undefined) {
326 return yield* new TimestreamTableUnexpectedResponse({
327 message: `failed to read created table ${tableName}`,
328 });
329 }
330 }
331
332 // Sync retention / magnetic-store-write config — diff the desired
333 // wire values against observed cloud state and skip the API call
334 // entirely on a no-op.
335 const retentionDrifted =
336 desiredRetention !== undefined &&
337 (state.retentionProperties?.MemoryStoreRetentionPeriodInHours !==
338 desiredRetention.MemoryStoreRetentionPeriodInHours ||
339 state.retentionProperties?.MagneticStoreRetentionPeriodInDays !==
340 desiredRetention.MagneticStoreRetentionPeriodInDays);
341 if (retentionDrifted || news.magneticStoreWriteProperties !== undefined) {
342 yield* withWriteEndpoint(
343 TSW.updateTable({
344 DatabaseName: databaseName,
345 TableName: tableName,
346 RetentionProperties: desiredRetention,
347 MagneticStoreWriteProperties: news.magneticStoreWriteProperties,
348 Schema: news.schema,
349 }),
350 );
351 yield* session.note(`Updated table ${tableName} configuration`);
352 }
353
354 // Sync tags — diff against observed cloud tags.
355 const { removed, upsert } = diffTags(state.tags, desiredTags);
356 if (removed.length > 0) {
357 yield* withWriteEndpoint(
358 TSW.untagResource({ ResourceARN: tableArn, TagKeys: removed }),
359 );
360 }
361 if (upsert.length > 0) {
362 yield* withWriteEndpoint(
363 TSW.tagResource({
364 ResourceARN: tableArn,
365 Tags: upsert.map(({ Key, Value }) => ({ Key, Value })),
366 }),
367 );
368 }
369
370 yield* session.note(tableArn);
371
372 const final = yield* readTable(databaseName, tableName);
373 if (!final) {
374 return yield* new TimestreamTableUnexpectedResponse({
375 message: `failed to read reconciled table ${tableName}`,
376 });
377 }
378 return final;
379 }),
380 delete: Effect.fn(function* ({ output }) {
381 yield* withWriteEndpoint(
382 TSW.deleteTable({
383 DatabaseName: output.databaseName,
384 TableName: output.tableName,
385 }),
386 ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
387 }),
388 };
389 }),
390 );