sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ PubSub/ ReadSubscription.ts

import type * as pubsub from "@distilled.cloud/gcp/pubsub_v1";
import * as Binding from "alchemy/Binding";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import type * as Effect from "effect/Effect";
import type { Subscription } from "./Subscription.ts";

export interface PullSubscriptionOptions {
  /**
   * Maximum messages to return.
   * @default 10
   */
  maxMessages?: number;
  /**
   * Return immediately when no messages are available instead of waiting
   * briefly for some to arrive.
   * @default false
   */
  returnImmediately?: boolean;
}

/** A pulled message with its payload decoded. */
export interface PulledMessage extends pubsub.ReceivedMessage {
  /** Ack id for `acknowledge` / `modifyAckDeadline`. */
  ackId: string;
  /** Server-assigned message id. */
  messageId: string;
  /** Decoded message body. */
  data: Uint8Array;
  /** `data` decoded as UTF-8. */
  text: string;
  /** Message attributes (empty when none were set). */
  attributes: Record<string, string>;
}

/** Consumer client for one Pub/Sub subscription. */
export interface ReadSubscriptionClient {
  /** Pull up to `maxMessages` messages; an empty array when none arrived. */
  pull(
    options?: PullSubscriptionOptions,
  ): Effect.Effect<PulledMessage[], pubsub.PullProjectsSubscriptionsError, RuntimeContext>;
  /** Acknowledge messages by ack id. An empty list is a no-op. */
  acknowledge(
    ackIds: ReadonlyArray<string>,
  ): Effect.Effect<void, pubsub.AcknowledgeProjectsSubscriptionsError, RuntimeContext>;
  /**
   * Extend (or, with `0`, release for redelivery) the ack deadline of
   * messages. An empty list is a no-op.
   */
  modifyAckDeadline(
    ackIds: ReadonlyArray<string>,
    seconds: number,
  ): Effect.Effect<void, pubsub.ModifyAckDeadlineProjectsSubscriptionsError, RuntimeContext>;
}

/**
 * Consume access to a Pub/Sub {@link Subscription}: `pull`, `acknowledge`,
 * `modifyAckDeadline`. Grants `roles/pubsub.subscriber` on the subscription
 * only.
 *
 * ### Consuming messages
 * **Example:** Pull and acknowledge
 * ```typescript
 * const inbox = yield* GCP.PubSub.ReadSubscription(subscription);
 * const messages = yield* inbox.pull({ maxMessages: 10 });
 * for (const message of messages) {
 *   yield* Effect.log(message.text, message.attributes);
 * }
 * yield* inbox.acknowledge(messages.map((m) => m.ackId));
 * // …provided with Effect.provide(GCP.PubSub.ReadSubscriptionHttp)
 * ```
 *
 * **Example:** Release a message for redelivery
 * ```typescript
 * yield* inbox.modifyAckDeadline([message.ackId], 0);
 * ```
 *
 * @binding
 * @category PubSub
 */
export interface ReadSubscription extends Binding.Service<
  ReadSubscription,
  "GCP.PubSub.ReadSubscription",
  (subscription: Subscription) => Effect.Effect<ReadSubscriptionClient>
> {}

export const ReadSubscription = Binding.Service<ReadSubscription>("GCP.PubSub.ReadSubscription");