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

main
ts 278 lines 10.4 KB
Raw
1 import * as iotw from "@distilled.cloud/aws/iot-wireless";
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, createTagsList, 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 { readIotWirelessTags, sameShape, syncIotWirelessTags } from "./internal.ts";
13
14 export class WirelessGatewayUnexpectedResponse extends Data.TaggedError(
15 "WirelessGatewayUnexpectedResponse",
16 )<{
17 readonly message: string;
18 readonly cause?: unknown;
19 }> {}
20
21 export interface WirelessGatewayProps {
22 /**
23 * Name of the wireless gateway. If omitted, a deterministic physical name
24 * is generated from the app, stage, and logical ID. Can be changed in
25 * place.
26 */
27 name?: string;
28 /**
29 * Human-readable description of the gateway.
30 */
31 description?: string;
32 /**
33 * LoRaWAN gateway configuration. `GatewayEui` (the gateway's unique
34 * 64-bit radio identifier) and `RfRegion` are the gateway's identity —
35 * changing either replaces the gateway. `JoinEuiFilters`, `NetIdFilters`,
36 * and `MaxEirp` update in place.
37 */
38 loRaWAN: iotw.LoRaWANGateway;
39 /**
40 * Tags applied to the gateway. Alchemy ownership tags are merged in
41 * automatically.
42 */
43 tags?: Record<string, string>;
44 }
45
46 export interface WirelessGateway extends Resource<
47 "AWS.IoTWireless.WirelessGateway",
48 WirelessGatewayProps,
49 {
50 /** Server-assigned ID of the wireless gateway. */
51 wirelessGatewayId: string;
52 /** ARN of the wireless gateway. */
53 wirelessGatewayArn: string;
54 /** Name of the wireless gateway. */
55 wirelessGatewayName: string;
56 /** The gateway's unique 64-bit radio identifier. */
57 gatewayEui: string | undefined;
58 },
59 never,
60 Providers
61 > {}
62
63 /**
64 * An AWS IoT Core for LoRaWAN wireless gateway — the cloud registration of
65 * a physical LoRaWAN gateway (packet forwarder), keyed by its unique
66 * 64-bit `GatewayEui`.
67 *
68 * The gateway's radio identity (`GatewayEui`, `RfRegion`, sub-bands,
69 * beaconing) is immutable — changing it replaces the gateway. The name,
70 * description, EUI/NetID filters, `MaxEirp`, and tags update in place.
71 * ### Creating Gateways
72 * **Example:** US915 Gateway
73 * ```typescript
74 * import * as IoTWireless from "@alchemy.run/aws/IoTWireless";
75 *
76 * const gateway = yield* IoTWireless.WirelessGateway("RooftopGw", {
77 * loRaWAN: {
78 * GatewayEui: "aa555a0000000001",
79 * RfRegion: "US915",
80 * },
81 * tags: { site: "hq" },
82 * });
83 * ```
84 *
85 * **Example:** Gateway with join filters
86 * ```typescript
87 * const gateway = yield* IoTWireless.WirelessGateway("RooftopGw", {
88 * loRaWAN: {
89 * GatewayEui: "aa555a0000000001",
90 * RfRegion: "US915",
91 * JoinEuiFilters: [["0000000000000001", "00000000000000ff"]],
92 * MaxEirp: 30,
93 * },
94 * });
95 * ```
96 *
97 * @resource
98 */
99 export const WirelessGateway = Resource<WirelessGateway>("AWS.IoTWireless.WirelessGateway");
100
101 /** The parts of a LoRaWAN gateway spec that form its immutable identity. */
102 const gatewayIdentity = (loRaWAN: iotw.LoRaWANGateway | undefined) => ({
103 GatewayEui: loRaWAN?.GatewayEui,
104 RfRegion: loRaWAN?.RfRegion,
105 SubBands: loRaWAN?.SubBands,
106 Beaconing: loRaWAN?.Beaconing,
107 });
108
109 export const WirelessGatewayProvider = () =>
110 Provider.effect(
111 WirelessGateway,
112 Effect.gen(function* () {
113 const createName = Effect.fn(function* (id: string, props: { name?: string }) {
114 return props.name ?? (yield* createPhysicalName({ id, maxLength: 256 }));
115 });
116
117 const getBy = (identifier: string, type: iotw.WirelessGatewayIdType) =>
118 iotw
119 .getWirelessGateway({ Identifier: identifier, IdentifierType: type })
120 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
121
122 const observe = Effect.fn(function* (
123 output: WirelessGateway["Attributes"] | undefined,
124 props: WirelessGatewayProps,
125 ) {
126 if (output?.wirelessGatewayId !== undefined) {
127 const found = yield* getBy(output.wirelessGatewayId, "WirelessGatewayId");
128 if (found !== undefined) return found;
129 }
130 // Recover identity by the gateway's unique EUI when state was lost.
131 if (props.loRaWAN?.GatewayEui !== undefined) {
132 return yield* getBy(props.loRaWAN.GatewayEui, "GatewayEui");
133 }
134 return undefined;
135 });
136
137 const toAttrs = Effect.fn(function* (gateway: iotw.GetWirelessGatewayResponse, name: string) {
138 if (gateway.Id === undefined || gateway.Arn === undefined) {
139 return yield* new WirelessGatewayUnexpectedResponse({
140 message: `IoT Wireless gateway '${name}' returned without Id/Arn`,
141 });
142 }
143 return {
144 wirelessGatewayId: gateway.Id,
145 wirelessGatewayArn: gateway.Arn,
146 wirelessGatewayName: gateway.Name ?? name,
147 gatewayEui: gateway.LoRaWAN?.GatewayEui,
148 };
149 });
150
151 return WirelessGateway.Provider.of({
152 stables: ["wirelessGatewayId", "wirelessGatewayArn", "gatewayEui"],
153
154 list: () =>
155 iotw.listWirelessGateways.pages({}).pipe(
156 Stream.runCollect,
157 Effect.map((chunk) =>
158 Array.from(chunk)
159 .flatMap((page) => page.WirelessGatewayList ?? [])
160 .flatMap((g) =>
161 g.Id !== undefined && g.Arn !== undefined
162 ? [
163 {
164 wirelessGatewayId: g.Id,
165 wirelessGatewayArn: g.Arn,
166 wirelessGatewayName: g.Name ?? g.Id,
167 gatewayEui: g.LoRaWAN?.GatewayEui,
168 },
169 ]
170 : [],
171 ),
172 ),
173 ),
174
175 read: Effect.fn(function* ({ id, olds, output }) {
176 const props = olds ?? { loRaWAN: {} };
177 const name = output?.wirelessGatewayName ?? (yield* createName(id, props));
178 const gateway = yield* observe(output, props);
179 if (gateway === undefined) return undefined;
180 const attrs = yield* toAttrs(gateway, name);
181 const tags = yield* readIotWirelessTags(attrs.wirelessGatewayArn);
182 return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
183 }),
184
185 // The radio identity (GatewayEui, RfRegion, sub-bands, beaconing) is
186 // create-only. Name, description, filters, and MaxEirp update in
187 // place via UpdateWirelessGateway.
188 diff: Effect.fn(function* ({ news, olds }) {
189 if (!isResolved(news)) return undefined;
190 if (!sameShape(gatewayIdentity(olds?.loRaWAN), gatewayIdentity(news.loRaWAN))) {
191 return { action: "replace" } as const;
192 }
193 }),
194
195 reconcile: Effect.fn(function* ({ id, news, output, session }) {
196 const name = output?.wirelessGatewayName ?? (yield* createName(id, news));
197 const internalTags = yield* createInternalTags(id);
198 const desiredTags = { ...news.tags, ...internalTags };
199
200 // 1. OBSERVE — cloud state is authoritative; output is an id cache.
201 let gateway = yield* observe(output, news);
202
203 // 2. ENSURE — create if missing; a Conflict means the EUI is
204 // already registered, so re-observe by it.
205 if (gateway === undefined) {
206 yield* session.note(`creating wireless gateway ${name}`);
207 const created = yield* iotw
208 .createWirelessGateway({
209 Name: name,
210 Description: news.description,
211 LoRaWAN: news.loRaWAN,
212 Tags: createTagsList(desiredTags),
213 })
214 .pipe(Effect.catchTag("ConflictException", () => Effect.undefined));
215 gateway =
216 created?.Id !== undefined
217 ? yield* getBy(created.Id, "WirelessGatewayId")
218 : yield* observe(undefined, news);
219 }
220 if (gateway === undefined) {
221 return yield* new WirelessGatewayUnexpectedResponse({
222 message: `IoT Wireless gateway '${name}' not found after create`,
223 });
224 }
225 const attrs = yield* toAttrs(gateway, name);
226
227 // 3. SYNC — apply the mutable-aspect delta from OBSERVED state.
228 const nameDelta = gateway.Name !== name;
229 const descriptionDelta =
230 news.description !== undefined && gateway.Description !== news.description;
231 const joinFiltersDelta =
232 news.loRaWAN.JoinEuiFilters !== undefined &&
233 !sameShape(gateway.LoRaWAN?.JoinEuiFilters, news.loRaWAN.JoinEuiFilters);
234 const netIdFiltersDelta =
235 news.loRaWAN.NetIdFilters !== undefined &&
236 !sameShape(gateway.LoRaWAN?.NetIdFilters, news.loRaWAN.NetIdFilters);
237 const maxEirpDelta =
238 news.loRaWAN.MaxEirp !== undefined && gateway.LoRaWAN?.MaxEirp !== news.loRaWAN.MaxEirp;
239 if (
240 nameDelta ||
241 descriptionDelta ||
242 joinFiltersDelta ||
243 netIdFiltersDelta ||
244 maxEirpDelta
245 ) {
246 yield* iotw.updateWirelessGateway({
247 Id: attrs.wirelessGatewayId,
248 Name: name,
249 Description: news.description,
250 JoinEuiFilters: news.loRaWAN.JoinEuiFilters,
251 NetIdFilters: news.loRaWAN.NetIdFilters,
252 MaxEirp: news.loRaWAN.MaxEirp,
253 });
254 }
255
256 // 3b. SYNC tags — diff against OBSERVED cloud tags.
257 yield* syncIotWirelessTags(attrs.wirelessGatewayArn, desiredTags);
258
259 // 4. RETURN fresh attributes.
260 const final = yield* getBy(attrs.wirelessGatewayId, "WirelessGatewayId");
261 if (final === undefined) {
262 return yield* new WirelessGatewayUnexpectedResponse({
263 message: `IoT Wireless gateway '${name}' vanished during update`,
264 });
265 }
266 yield* session.note(attrs.wirelessGatewayId);
267 return yield* toAttrs(final, name);
268 }),
269
270 delete: Effect.fn(function* ({ output }) {
271 yield* iotw.deleteWirelessGateway({ Id: output.wirelessGatewayId }).pipe(
272 Effect.asVoid,
273 Effect.catchTag("ResourceNotFoundException", () => Effect.void),
274 );
275 }),
276 });
277 }),
278 );