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

main
ts 275 lines 9.55 KB
Raw
1 import * as iotfleetwise from "@distilled.cloud/aws/iotfleetwise";
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, hasAlchemyTags } from "alchemy/Tags";
8 import * as Data from "effect/Data";
9 import * as Effect from "effect/Effect";
10 import * as Stream from "effect/Stream";
11 import type { Providers } from "../Providers.ts";
12 import {
13 inFleetWiseRegion,
14 readFleetWiseTags,
15 retryObservation,
16 retryWhileConflict,
17 stableEquals,
18 syncFleetWiseTags,
19 toFleetWiseTagList,
20 } from "./internal.ts";
21
22 export class SignalCatalogUnexpectedResponse extends Data.TaggedError(
23 "SignalCatalogUnexpectedResponse",
24 )<{
25 readonly message: string;
26 readonly cause?: unknown;
27 }> {}
28
29 export interface SignalCatalogProps {
30 /**
31 * Name of the signal catalog. Must be 1-100 characters of
32 * `[a-zA-Z0-9:_-]`. If omitted, a deterministic physical name is
33 * generated. Changing the name replaces the catalog.
34 */
35 signalCatalogName?: string;
36 /**
37 * Human-readable description of the signal catalog.
38 */
39 description?: string;
40 /**
41 * Signal nodes forming the catalog's tree — branches, sensors,
42 * actuators, attributes, structs and properties. Each node is one of the
43 * union variants (`{ branch }`, `{ sensor }`, ...) keyed by
44 * `fullyQualifiedName`. Updated in place via
45 * `nodesToAdd`/`nodesToUpdate`/`nodesToRemove` deltas.
46 */
47 nodes?: iotfleetwise.Node[];
48 /**
49 * User-defined tags for the signal catalog.
50 */
51 tags?: Record<string, string>;
52 }
53
54 export interface SignalCatalog extends Resource<
55 "AWS.IoTFleetWise.SignalCatalog",
56 SignalCatalogProps,
57 {
58 /** The name of the signal catalog. */
59 signalCatalogName: string;
60 /** The ARN of the signal catalog. */
61 signalCatalogArn: string;
62 },
63 never,
64 Providers
65 > {}
66
67 /**
68 * An AWS IoT FleetWise signal catalog — the account-wide collection of
69 * standardized vehicle signals (branches, sensors, actuators, attributes)
70 * that model manifests draw from.
71 *
72 * AWS IoT FleetWise is offered in `us-east-1` and `eu-central-1` only; the
73 * provider follows the ambient region when supported and pins `us-east-1`
74 * otherwise. Access to the service is allowlist-gated by AWS — accounts
75 * without access receive `AccessDeniedException` on every operation.
76 * ### Creating a Signal Catalog
77 * **Example:** Catalog with a Branch and a Sensor
78 * ```typescript
79 * const catalog = yield* SignalCatalog("Signals", {
80 * nodes: [
81 * { branch: { fullyQualifiedName: "Vehicle" } },
82 * {
83 * sensor: {
84 * fullyQualifiedName: "Vehicle.Speed",
85 * dataType: "DOUBLE",
86 * unit: "km/h",
87 * },
88 * },
89 * ],
90 * });
91 * ```
92 *
93 * **Example:** Catalog with Attributes
94 * ```typescript
95 * const catalog = yield* SignalCatalog("Signals", {
96 * description: "vehicle signals",
97 * nodes: [
98 * { branch: { fullyQualifiedName: "Vehicle" } },
99 * {
100 * attribute: {
101 * fullyQualifiedName: "Vehicle.VIN",
102 * dataType: "STRING",
103 * },
104 * },
105 * ],
106 * tags: { team: "telemetry" },
107 * });
108 * ```
109 *
110 * @resource
111 */
112 export const SignalCatalog = Resource<SignalCatalog>("AWS.IoTFleetWise.SignalCatalog");
113
114 const nodeFqn = (node: iotfleetwise.Node): string =>
115 node.branch?.fullyQualifiedName ??
116 node.sensor?.fullyQualifiedName ??
117 node.actuator?.fullyQualifiedName ??
118 node.attribute?.fullyQualifiedName ??
119 node.struct?.fullyQualifiedName ??
120 node.property?.fullyQualifiedName ??
121 "";
122
123 export const SignalCatalogProvider = () =>
124 Provider.effect(
125 SignalCatalog,
126 Effect.gen(function* () {
127 const toName = (id: string, props: { signalCatalogName?: string }) =>
128 props.signalCatalogName
129 ? Effect.succeed(props.signalCatalogName)
130 : createPhysicalName({ id, maxLength: 100 });
131
132 const readCatalog = Effect.fn(function* (name: string) {
133 return yield* iotfleetwise.getSignalCatalog({ name }).pipe(
134 inFleetWiseRegion,
135 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
136 );
137 });
138
139 const readNodes = Effect.fn(function* (name: string) {
140 return yield* iotfleetwise.listSignalCatalogNodes.items({ name }).pipe(
141 Stream.runCollect,
142 Effect.map((chunk) => Array.from(chunk)),
143 inFleetWiseRegion,
144 );
145 });
146
147 return {
148 stables: ["signalCatalogName", "signalCatalogArn"],
149
150 diff: Effect.fn(function* ({ id, olds, news }) {
151 if (!isResolved(news)) return undefined;
152 if ((yield* toName(id, olds)) !== (yield* toName(id, news))) {
153 return { action: "replace" } as const;
154 }
155 }),
156
157 read: Effect.fn(function* ({ id, olds, output }) {
158 const name = output?.signalCatalogName ?? (yield* toName(id, olds ?? {}));
159 const found = yield* readCatalog(name);
160 if (found === undefined) return undefined;
161 const attrs = {
162 signalCatalogName: found.name,
163 signalCatalogArn: found.arn,
164 };
165 const tags = yield* readFleetWiseTags(found.arn);
166 return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
167 }),
168
169 reconcile: Effect.fn(function* ({ id, news, output, session }) {
170 const name = output?.signalCatalogName ?? (yield* toName(id, news));
171 const internalTags = yield* createInternalTags(id);
172 const desiredTags = { ...internalTags, ...news.tags };
173 const desiredNodes = news.nodes ?? [];
174
175 // 1. Observe — cloud state is authoritative.
176 let observed = yield* readCatalog(name);
177
178 // 2. Ensure — create if missing; tolerate the AlreadyExists race.
179 if (observed === undefined) {
180 yield* iotfleetwise
181 .createSignalCatalog({
182 name,
183 description: news.description,
184 nodes: desiredNodes,
185 tags: toFleetWiseTagList(desiredTags),
186 })
187 .pipe(
188 inFleetWiseRegion,
189 Effect.catchTag("ConflictException", () => Effect.void),
190 );
191 observed = yield* readCatalog(name).pipe(
192 Effect.flatMap((catalog) =>
193 catalog === undefined
194 ? Effect.fail(
195 new SignalCatalogUnexpectedResponse({
196 message: `Signal catalog '${name}' not found`,
197 }),
198 )
199 : Effect.succeed(catalog),
200 ),
201 retryObservation,
202 );
203 }
204
205 // 3. Sync nodes + description — diff OBSERVED nodes against the
206 // desired tree keyed by fullyQualifiedName.
207 const observedNodes = yield* readNodes(name);
208 const observedByFqn = new Map(observedNodes.map((node) => [nodeFqn(node), node]));
209 const desiredByFqn = new Map(desiredNodes.map((node) => [nodeFqn(node), node]));
210 const nodesToAdd = desiredNodes.filter((node) => !observedByFqn.has(nodeFqn(node)));
211 const nodesToUpdate = desiredNodes.filter((node) => {
212 const current = observedByFqn.get(nodeFqn(node));
213 return current !== undefined && !stableEquals(current, node);
214 });
215 const nodesToRemove = observedNodes.map(nodeFqn).filter((fqn) => !desiredByFqn.has(fqn));
216 const descriptionChanged =
217 news.description !== undefined && news.description !== observed.description;
218 if (
219 nodesToAdd.length > 0 ||
220 nodesToUpdate.length > 0 ||
221 nodesToRemove.length > 0 ||
222 descriptionChanged
223 ) {
224 yield* iotfleetwise
225 .updateSignalCatalog({
226 name,
227 description: descriptionChanged ? news.description : undefined,
228 nodesToAdd: nodesToAdd.length > 0 ? nodesToAdd : undefined,
229 nodesToUpdate: nodesToUpdate.length > 0 ? nodesToUpdate : undefined,
230 nodesToRemove: nodesToRemove.length > 0 ? nodesToRemove : undefined,
231 })
232 .pipe(inFleetWiseRegion);
233 }
234
235 // 3b. Sync tags against OBSERVED cloud tags.
236 yield* syncFleetWiseTags(observed.arn, desiredTags);
237
238 yield* session.note(name);
239 return {
240 signalCatalogName: observed.name,
241 signalCatalogArn: observed.arn,
242 };
243 }),
244
245 delete: Effect.fn(function* ({ output }) {
246 // Idempotent: FleetWise deletes return success for missing
247 // resources. Model manifests still detaching surface as
248 // ConflictException — retry through the window (bounded).
249 yield* iotfleetwise.deleteSignalCatalog({ name: output.signalCatalogName }).pipe(
250 inFleetWiseRegion,
251 retryWhileConflict,
252 Effect.catchTag("ConflictException", () => Effect.void),
253 );
254 }),
255
256 list: () =>
257 iotfleetwise.listSignalCatalogs.items({}).pipe(
258 Stream.runCollect,
259 Effect.map((chunk) =>
260 Array.from(chunk).flatMap((summary) =>
261 summary.name !== undefined && summary.arn !== undefined
262 ? [
263 {
264 signalCatalogName: summary.name,
265 signalCatalogArn: summary.arn,
266 },
267 ]
268 : [],
269 ),
270 ),
271 inFleetWiseRegion,
272 ),
273 };
274 }),
275 );