sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ IoTWireless/ DestinationEventSource.ts

import * as Binding from "alchemy/Binding";
import type * as Effect from "effect/Effect";
import type * as Stream from "effect/Stream";
import type { Destination } from "./Destination.ts";

/**
 * The JSON envelope AWS IoT Core for LoRaWAN delivers to a `RuleName`
 * destination's IoT rule for every uplink — the raw payload (base64) plus
 * the radio metadata.
 */
export interface WirelessUplinkMessage {
  /** ID of the wireless device that sent the uplink. */
  WirelessDeviceId: string;
  /** The uplink payload, base64-encoded. */
  PayloadData: string;
  /** Radio metadata (DevEui, FPort, data rate, gateway RSSI/SNR, ...). */
  WirelessMetadata?: {
    /** LoRaWAN uplink metadata. */
    LoRaWAN?: {
      /** The DevEui of the sending device. */
      DevEui?: string;
      /** The FPort the payload was sent on. */
      FPort?: number;
      /** ISO-8601 server-side receive timestamp. */
      Timestamp?: string;
      [key: string]: unknown;
    };
    /** Amazon Sidewalk uplink metadata. */
    Sidewalk?: { [key: string]: unknown };
  };
  [key: string]: unknown;
}

/**
 * The handler invoked with a stream of uplink messages routed through the
 * bound destination.
 */
export type WirelessUplinkHandlerFn<Req = never> = (
  stream: Stream.Stream<WirelessUplinkMessage>,
) => Effect.Effect<void, never, Req>;

export type DestinationEventSourceService = <Req = never>(
  destination: Destination,
  process: WirelessUplinkHandlerFn<Req>,
) => Effect.Effect<void, never, never>;

/**
 * Event source connecting an IoT Wireless {@link Destination} to the
 * hosting compute — every uplink a wireless device sends through the
 * destination invokes the handler.
 *
 * The destination must use `expressionType: "RuleName"`. At deploy time the
 * Lambda implementation (`Lambda.WirelessDestinationEventSource`) creates
 * the IoT topic rule the destination's `expression` names, with a Lambda
 * action targeting the current function, and grants `iot.amazonaws.com`
 * permission to invoke it; at runtime it dispatches uplink invocations to
 * the handler.
 *
 * Use the {@link consumeUplinks} helper rather than the service directly,
 * and provide `Lambda.WirelessDestinationEventSource` on the hosting
 * function.
 * ### Consuming Uplinks
 * **Example:** Consume LoRaWAN Uplinks in a Lambda
 * ```typescript
 * export default IngestFunction.make(
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const destination = yield* IoTWireless.Destination("Uplinks", {
 *       expressionType: "RuleName",
 *       expression: "sensor_uplinks",
 *       roleArn: deliveryRole.roleArn,
 *     });
 *
 *     // deploy: creates the `sensor_uplinks` IoT rule targeting this Lambda
 *     // runtime: handles every uplink routed through the destination
 *     yield* IoTWireless.consumeUplinks(destination, (uplinks) =>
 *       uplinks.pipe(
 *         Stream.runForEach((uplink) =>
 *           Effect.log(uplink.WirelessDeviceId, uplink.PayloadData),
 *         ),
 *         Effect.orDie,
 *       ),
 *     );
 *
 *     return {};
 *   }).pipe(Effect.provide(Lambda.WirelessDestinationEventSource)),
 * );
 * ```
 *
 * @binding
 */
export interface DestinationEventSource extends Binding.Service<
  DestinationEventSource,
  "AWS.IoTWireless.DestinationEventSource",
  DestinationEventSourceService
> {}

export const DestinationEventSource = Binding.Service<DestinationEventSource>(
  "AWS.IoTWireless.DestinationEventSource",
);

/**
 * Invoke an Effect handler for every uplink message routed through the
 * destination, by creating the IoT rule the destination's `expression`
 * names with a Lambda action targeting the current function.
 *
 * Provide `Lambda.WirelessDestinationEventSource` on the hosting function
 * to satisfy the requirement.
 *
 * @param destination The `RuleName` destination whose uplinks to consume.
 * @param process The handler invoked with a stream of uplink messages.
 *
 * @example Store uplinks in DynamoDB
 * ```typescript
 * yield* IoTWireless.consumeUplinks(destination, (uplinks) =>
 *   uplinks.pipe(
 *     Stream.runForEach((uplink) =>
 *       putItem({ Item: { pk: { S: uplink.WirelessDeviceId } } }),
 *     ),
 *     Effect.orDie,
 *   ),
 * );
 * ```
 */
export function consumeUplinks<Req = never>(
  destination: Destination,
  process: WirelessUplinkHandlerFn<Req>,
): Effect.Effect<void, never, DestinationEventSource> {
  return DestinationEventSource.use((source) => source(destination, process));
}