encore.dev 0.0.0-devel.202311141645

package/dist/pubsub/acker.js

@@ -0,0 +1,73 @@
+/**
+ * Acker is used to ack or nack a message.
+ */
+export class Acker {
+    #acked;
+    #nacked;
+    #succesfulResult = false;
+    #ack;
+    #nack;
+    constructor(ack, nack) {
+        this.#ack = ack;
+        this.#nack = nack;
+    }
+    /**
+     * Acknowledges the message.
+     *
+     * If the message has been nacked, an error is thrown.
+     *
+     * Multiple calls to ack() will return the same promise, unless the
+     * promise has been rejected, in which case a new promise will be returned.
+     */
+    async ack() {
+        if (this.#nacked) {
+            throw new Error("message already nacked and cannot be acked");
+        }
+        if (this.#acked) {
+            return this.#acked;
+        }
+        this.#acked = this.#ack();
+        this.#acked
+            .then(() => {
+            this.#succesfulResult = true;
+        })
+            .catch((e) => {
+            this.#acked = undefined;
+            throw e;
+        });
+    }
+    /**
+     * Negatively acknowledges the message.
+     *
+     * If the message has been acked, an error is thrown.
+     *
+     * Multiple calls to nack() will return the same promise, unless the
+     * promise has been rejected, in which case a new promise will be returned.
+     */
+    async nack() {
+        if (this.#acked) {
+            throw new Error("message already acked and cannot be nacked");
+        }
+        if (this.#nacked) {
+            return this.#nacked;
+        }
+        this.#nacked = this.#nack();
+        this.#nacked
+            .then(() => {
+            this.#succesfulResult = true;
+        })
+            .catch((e) => {
+            this.#nacked = undefined;
+            throw e;
+        });
+    }
+    currentResult() {
+        if (this.#succesfulResult) {
+            return Promise.resolve(true);
+        }
+        return (this.#acked ?? this.#nacked ?? Promise.reject())
+            .then(() => true)
+            .catch(() => false);
+    }
+}
+//# sourceMappingURL=acker.js.map

package/dist/pubsub/acker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acker.js","sourceRoot":"","sources":["../../pubsub/acker.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,KAAK;IAChB,MAAM,CAAiB;IACvB,OAAO,CAAiB;IACxB,gBAAgB,GAAG,KAAK,CAAC;IAChB,IAAI,CAAsB;IAC1B,KAAK,CAAsB;IAEpC,YAAY,GAAwB,EAAE,IAAyB;QAC7D,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAChB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG;QACP,IAAI,IAAI,CAAC,OAAO,EAAE;YAChB,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;SAC/D;QACD,IAAI,IAAI,CAAC,MAAM,EAAE;YACf,OAAO,IAAI,CAAC,MAAM,CAAC;SACpB;QAED,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC1B,IAAI,CAAC,MAAM;aACR,IAAI,CAAC,GAAG,EAAE;YACT,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;QAC/B,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE;YACpB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;YACxB,MAAM,CAAC,CAAC;QACV,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,MAAM,EAAE;YACf,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;SAC/D;QACD,IAAI,IAAI,CAAC,OAAO,EAAE;YAChB,OAAO,IAAI,CAAC,OAAO,CAAC;SACrB;QAED,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC5B,IAAI,CAAC,OAAO;aACT,IAAI,CAAC,GAAG,EAAE;YACT,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;QAC/B,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE;YACpB,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;YACzB,MAAM,CAAC,CAAC;QACV,CAAC,CAAC,CAAC;IACP,CAAC;IAED,aAAa;QACX,IAAI,IAAI,CAAC,gBAAgB,EAAE;YACzB,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;SAC9B;QAED,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;aACrD,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;aAChB,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;IACxB,CAAC;CACF"}

package/dist/pubsub/attributes.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Attribute represents a field on a message that should be sent
+ * as an attribute in a PubSub message, rather than in the message
+ * body.
+ *
+ * This is useful for ordering messages, or for filtering messages
+ * on a subscription - otherwise you should not use this.
+ *
+ * To create attributes on a message, use the `Attribute` type:
+ *   type Message = {
+ *     user_id: Attribute<number>;
+ *     name: string;
+ *   };
+ *
+ *   const msg: Message = {
+ *     user_id: 123,
+ *     name:    "John Doe",
+ *   };
+ *
+ * The union of brandedAttribute is simply used to help the TypeScript compiler
+ * understand that the type is an attribute and allow the AttributesOf type
+ * to extract the keys of said type.
+ */
+export type Attribute<T extends string | number | boolean> = T | brandedAttribute<T>;
+/**
+ * AttributesOf is a helper type to extract all keys from an object
+ * who's type is an Attribute type.
+ *
+ * For example:
+ *    type Message = {
+ *        user_id: Attribute<number>;
+ *        name: string;
+ *        age: Attribute<number>;
+ *    };
+ *
+ *    type MessageAttributes = AttributesOf<Message>; // "user_id" | "age"
+ */
+export type AttributesOf<T extends object> = keyof {
+    [Key in keyof T as Extract<T[Key], allBrandedTypes> extends never ? never : Key]: never;
+};
+/**
+ * supportedAttributeTypes is a union of all primitive types that are supported as attributes
+ */
+type supportedAttributeTypes = string | number | boolean;
+/**
+ * brandedAttribute is a helper type to brand a type as an attribute
+ * which is distinct from the base type. It is a compile time only
+ * type and has no runtime representation.
+ */
+type brandedAttribute<T> = T & {
+    readonly __attributeBrand: unique symbol;
+};
+/**
+ * allBrandedTypes is a helper type to create a union of all branded supported attribute types
+ *
+ * The result of this is: brandedAttribute<string> | brandedAttribute<number> | brandedAttribute<boolean>
+ */
+type allBrandedTypes<Union = supportedAttributeTypes> = Union extends supportedAttributeTypes ? brandedAttribute<Union> : never;
+export {};

package/dist/pubsub/attributes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=attributes.js.map

package/dist/pubsub/attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attributes.js","sourceRoot":"","sources":["../../pubsub/attributes.ts"],"names":[],"mappings":""}

package/dist/pubsub/mod.d.ts

@@ -0,0 +1,5 @@
+export { Topic } from "./topic.js";
+export type { TopicConfig, DeliveryGuarantee } from "./topic.js";
+export { Subscription } from "./subscription.js";
+export type { SubscriptionConfig } from "./subscription.js";
+export type { Attribute } from "./attributes.js";

package/dist/pubsub/mod.js

@@ -0,0 +1,3 @@
+export { Topic } from "./topic.js";
+export { Subscription } from "./subscription.js";
+//# sourceMappingURL=mod.js.map

package/dist/pubsub/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../pubsub/mod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGhC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/pubsub/subscription.d.ts

@@ -0,0 +1,100 @@
+import { DurationString } from "../internal/types/mod.js";
+import { Topic } from "./topic.js";
+export declare class Subscription<Msg extends object> {
+    #private;
+    private readonly client_id;
+    private readonly topic;
+    private readonly name;
+    private readonly handler;
+    private readonly config;
+    private readonly logger;
+    private failedState;
+    private activeDeliveries;
+    constructor(topic: Topic<Msg>, name: string, cfg: SubscriptionConfig<Msg>);
+}
+/**
+ * SubscriptionConfig is used when creating a subscription
+ *
+ * The values given here may be clamped to the supported values by
+ * the target cloud. (i.e. ack deadline may be brought within the supported range
+ * by the target cloud pubsub implementation).
+ */
+export interface SubscriptionConfig<Msg> {
+    /**
+     * Handler is the function which will be called to process a message
+     * sent on the topic.
+     *
+     * When this function returns an error the message will be
+     * negatively acknowledged (nacked), which will cause a redelivery
+     * attempt to be made (unless the retry policy's MaxRetries has been reached).
+     */
+    handler: (msg: Msg) => Promise<unknown>;
+    /**
+     * MaxConcurrency is the maximum number of messages which will be processed
+     * simultaneously per instance of the service for this subscription.
+     *
+     * Note that this is per instance of the service, so if your service has
+     * scaled to 10 instances and this is set to 10, then 100 messages could be
+     * processed simultaneously.
+     *
+     * If the value is negative, then there will be no limit on the number
+     * of messages processed simultaneously.
+     *
+     * Note: This is not supported by all cloud providers; specifically on GCP
+     * when using Cloud Run instances on an unordered topic the subscription will
+     * be configured as a Push Subscription and will have an adaptive concurrency
+     * See [GCP Push Delivery Rate](https://cloud.google.com/pubsub/docs/push#push_delivery_rate).
+     *
+     * This setting also has no effect on Encore Cloud environments.
+     * If not set, it uses a reasonable default based on the cloud provider.
+     */
+    maxConcurrency?: number;
+    /**
+     * AckDeadline is the time a consumer has to process a message
+     * before it's returned to the subscription
+     *
+     * Default is 30 seconds, however the ack deadline must be at least
+     * 1 second.
+     */
+    ackDeadline?: DurationString;
+    /**
+     * MessageRetention is how long an undelivered message is kept
+     * on the topic before it's purged.
+     *
+     * Default is 7 days.
+     */
+    messageRetention?: DurationString;
+    /**
+     * RetryPolicy defines how a message should be retried when
+     * the subscriber returns an error
+     */
+    retryPolicy?: RetryPolicy;
+}
+/**
+ * RetryPolicy defines how a subscription should handle retries
+ * after errors either delivering the message or processing the message.
+ *
+ * The values given to this structure are parsed at compile time, such that
+ * the correct Cloud resources can be provisioned to support the queue.
+ *
+ * As such the values given here may be clamped to the supported values by
+ * the target cloud. (i.e. min/max values brought within the supported range
+ * by the target cloud).
+ */
+export interface RetryPolicy {
+    /**
+     * The minimum time to wait between retries. Defaults to 10 seconds.
+     */
+    minBackoff?: DurationString;
+    /**
+     * The maximum time to wait between retries. Defaults to 10 minutes.
+     */
+    maxBackoff?: DurationString;
+    /**
+     * MaxRetries is used to control deadletter queuing logic, when:
+     *   n == 0: A default value of 100 retries will be used
+     *   n > 0:  Encore will forward a message to a dead letter queue after n retries
+     *   n == pubsub.InfiniteRetries: Messages will not be forwarded to the dead letter queue by the Encore framework
+     */
+    maxRetries?: number;
+}

package/dist/pubsub/subscription.js

@@ -0,0 +1,164 @@
+import { api } from "@encore.dev/internal-runtime";
+import reqtrack from "@encore.dev/internal-runtime/reqtrack/index";
+import { newSpanID, newTraceID, } from "@encore.dev/internal-runtime/reqtrack/tracecontext";
+import { withLogCtx, } from "@encore.dev/internal-runtime/reqtrack/logging";
+import { durationToProto, now, parseDuration, since, toDurationStr, } from "@encore.dev/internal-runtime/utils/timers";
+import { runtime } from "@encore.dev/internal-runtime/jsruntime";
+import log from "../log/mod.js";
+import { PubSub } from "@encore.dev/sidecar-api";
+import { Acker } from "./acker.js";
+export class Subscription {
+    client_id;
+    topic;
+    name;
+    handler;
+    config;
+    logger;
+    failedState = false;
+    activeDeliveries = [];
+    constructor(topic, name, cfg) {
+        // Generate a unique client ID for this instance
+        const id = new Uint8Array(16);
+        runtime().getRandomValues(id);
+        this.client_id = Buffer.from(id).toString("hex");
+        this.topic = topic;
+        this.name = name;
+        this.handler = cfg.handler;
+        this.logger = log.with({ topic: topic.name, subscription: name });
+        const ackDeadline = parseDuration(cfg.ackDeadline ?? "30s");
+        const minBackoff = parseDuration(cfg.retryPolicy?.minBackoff ?? "10s");
+        const maxBackoff = parseDuration(cfg.retryPolicy?.maxBackoff ?? "10m");
+        this.config = new PubSub.SubscriptionConfig({
+            maxConcurrency: cfg.maxConcurrency ?? -1,
+            ackDeadline: durationToProto(ackDeadline),
+            retryPolicy: new PubSub.RetryPolicy({
+                minBackoff: durationToProto(minBackoff),
+                maxBackoff: durationToProto(maxBackoff),
+                maxRetries: cfg.retryPolicy?.maxRetries ?? 100,
+            }),
+        });
+        let backoff = 250; // Start at 250ms for exponential backoff
+        const start = () => {
+            this.logger.trace("starting subscription");
+            this.#startSubscription()
+                .then(() => this.logger.warn("subscription ended"))
+                .catch((e) => {
+                this.failedState = true;
+                backoff *= 2;
+                if (backoff > 60 * 1000) {
+                    // cap the backoff at 1 minute
+                    backoff = 60 * 1000;
+                }
+                this.logger.error(e, "subscription failed with error");
+                setTimeout(start, backoff);
+            });
+        };
+        this.logger.info("registered subscription");
+        // Start the subscription
+        process.nextTick(start);
+    }
+    async #startSubscription() {
+        const resp = api().pubsub.subscribe(new PubSub.SubscribeRequest({
+            clientId: this.client_id,
+            topic: this.topic.name,
+            subscription: this.name,
+            config: this.config,
+        }));
+        // Now we have an active subscription, we touch messages if we have active messages
+        const interval = setInterval(() => {
+            this.#touchActiveMessages();
+        }, 30 * 1000);
+        try {
+            for await (const msg of resp) {
+                if (this.failedState) {
+                    this.logger.info("subscription recovered");
+                    this.failedState = false;
+                }
+                process.nextTick(() => this.#handleMessage(msg));
+            }
+        }
+        finally {
+            clearInterval(interval);
+        }
+    }
+    #touchActiveMessages() {
+        if (this.activeDeliveries.length === 0) {
+            return;
+        }
+        const acks = this.activeDeliveries;
+        api()
+            .pubsub.touch({
+            clientId: this.client_id,
+            ackIds: acks,
+        })
+            .then(() => {
+            this.logger.trace("touched active messages", { ack_ids: acks });
+        })
+            .catch((e) => {
+            this.logger.error(e, "failed to touch messages", { ack_ids: acks });
+        });
+    }
+    async #handleMessage(event) {
+        if (event.event.case !== "messageDelivery") {
+            // If it's a keep alive or some other unknown message
+            return;
+        }
+        const msg = event.event.value;
+        const logCtx = {
+            topic: this.topic.name,
+            subscription: this.name,
+            msg_id: msg.msgId,
+            delivery_attempt: msg.deliveryAttempt,
+        };
+        const traceID = newTraceID();
+        const spanID = newSpanID();
+        const ctx = {
+            traceID: traceID,
+            spanID: spanID,
+        };
+        // Record this ack ID as being active
+        this.activeDeliveries.push(msg.ackId);
+        return reqtrack.run(ctx, async () => {
+            return withLogCtx(logCtx, async () => {
+                const acker = new Acker(() => this.#acknowledge(msg.ackId), () => this.#negativeAcknowledge(msg.ackId));
+                try {
+                    this.logger.info("starting request");
+                    const data = Buffer.from(msg.message?.data ?? Uint8Array.of()).toString();
+                    const start = now();
+                    await this.handler(JSON.parse(data), acker);
+                    this.logger.info("request completed", {
+                        duration: toDurationStr(since(start)),
+                    });
+                    const hasAcked = await acker.currentResult();
+                    if (!hasAcked) {
+                        await acker.ack();
+                    }
+                }
+                catch (e) {
+                    this.logger.error(e, "request failed");
+                    const hasAcked = await acker.currentResult();
+                    if (!hasAcked) {
+                        await acker.nack();
+                    }
+                }
+            });
+        });
+    }
+    async #acknowledge(ackID) {
+        await api().pubsub.acknowledge({
+            clientId: this.client_id,
+            ackId: ackID,
+        });
+        this.activeDeliveries = this.activeDeliveries.filter((id) => id !== ackID);
+        this.logger.trace("acknowledged message", { ack_id: ackID });
+    }
+    async #negativeAcknowledge(ackID) {
+        await api().pubsub.negativeAcknowledge({
+            clientId: this.client_id,
+            ackId: ackID,
+        });
+        this.activeDeliveries = this.activeDeliveries.filter((id) => id !== ackID);
+        this.logger.trace("negatively acknowledged message", { ack_id: ackID });
+    }
+}
+//# sourceMappingURL=subscription.js.map

package/dist/pubsub/subscription.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.js","sourceRoot":"","sources":["../../pubsub/subscription.ts"],"names":[],"mappings":"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"}

package/dist/pubsub/topic.d.ts

@@ -0,0 +1,105 @@
+import { AttributesOf } from "./attributes.js";
+/**
+ * A topic is a resource to which you can publish messages
+ * to be delivered to subscribers of that topic.
+ */
+export declare class Topic<Msg extends object> {
+    readonly name: string;
+    readonly cfg: TopicConfig<Msg>;
+    constructor(name: string, cfg: TopicConfig<Msg>);
+    publish(msg: Msg): Promise<string>;
+}
+/**
+ * DeliveryGuarantee is used to configure the delivery contract for a topic.
+ */
+export type DeliveryGuarantee = "at-least-once" | "exactly-once";
+/**
+ * At Least Once delivery guarantees that a message for a subscription is delivered to
+ * a consumer at least once.
+ *
+ * On AWS and GCP there is no limit to the throughput for a topic.
+ */
+export declare const atLeastOnce: DeliveryGuarantee;
+/**
+ * ExactlyOnce guarantees that a message for a subscription is delivered to
+ * a consumer exactly once, to the best of the system's ability.
+ *
+ * However, there are edge cases when a message might be redelivered.
+ * For example, if a networking issue causes the acknowledgement of success
+ * processing the message to be lost before the cloud provider receives it.
+ *
+ * It is also important to note that the ExactlyOnce delivery guarantee only
+ * applies to the delivery of the message to the consumer, and not to the
+ * original publishing of the message, such that if a message is published twice,
+ * such as due to an retry within the application logic, it will be delivered twice.
+ * (i.e. ExactlyOnce delivery does not imply message deduplication on publish)
+ *
+ * As such it's recommended that the subscription handler function is idempotent
+ * and is able to handle duplicate messages.
+ *
+ * Subscriptions attached to ExactlyOnce topics have higher message delivery latency compared to AtLeastOnce.
+ *
+ * By using ExactlyOnce semantics on a topic, the throughput will be limited depending on the cloud provider:
+ * - AWS: 300 messages per second for the topic (see [AWS SQS Quotas]).
+ * - GCP: At least 3,000 messages per second across all topics in the region
+ *      (can be higher on the region see [GCP PubSub Quotas]).
+ *
+ * [AWS SQS Quotas]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/quotas-messages.html
+ * [GCP PubSub Quotas]: https://cloud.google.com/pubsub/quotas#quotas
+ */
+export declare const exactlyOnce: DeliveryGuarantee;
+/**
+ * TopicConfig is used when creating a Topic
+ */
+export interface TopicConfig<Msg extends object> {
+    /**
+     * DeliveryGuarantee is used to configure the delivery guarantee of a Topic
+     */
+    deliveryGuarantee: DeliveryGuarantee;
+    /**
+     * OrderingAttribute is the message attribute to use as a ordering key for
+     * messages and delivery will ensure that messages with the same value will
+     * be delivered in the order they where published.
+     *
+     * If OrderingAttribute is not set, messages can be delivered in any order.
+     *
+     * It is important to note, that in the case of an error being returned by a
+     * subscription handler, the message will be retried before any subsequent
+     * messages for that ordering key are delivered. This means depending on the
+     * retry configuration, a large backlog of messages for a given ordering key
+     * may build up. When using OrderingAttribute, it is recommended to use reason
+     * about your failure modes and set the retry configuration appropriately.
+     *
+     * Once the maximum number of retries has been reached, the message will be
+     * forwarded to the dead letter queue, and the next message for that ordering
+     * key will be delivered.
+     *
+     * To create attributes on a message, use the `Attribute` type:
+     *
+     *  type UserEvent = {
+     *    user_id Attribute<string>;
+     *    action  string;
+     *  }
+     *
+     *  const topic = new Topic<UserEvent>("user-events", {
+     *    deliveryGuarantee: DeliveryGuarantee.AtLeastOnce,
+     *    orderingAttribute: "user_id", // Messages with the same user-id will be delivered in the order they where
+     * published
+     *  })
+     *
+     *  topic.publish(ctx, {user_id: "1", action: "login"})  // This message will be delivered before the logout
+     *  topic.publish(ctx, {user_id: "2", action: "login"})  // This could be delivered at any time because it has a different user id
+     *  topic.publish(ctx, {user_id: "1", action: "logout"}) // This message will be delivered after the first message
+     *
+     * By using OrderingAttribute, the throughput will be limited depending on the cloud provider:
+     *
+     * - AWS: 300 messages per second for the topic (see [AWS SQS Quotas]).
+     * - GCP: 1MB/s for each ordering key (see [GCP PubSub Quotas]).
+     *
+     * Note: OrderingAttribute currently has no effect during local development.
+     *
+     * [AWS SQS Quotas]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/quotas-messages.html
+     * [GCP PubSub Quotas]: https://cloud.google.com/pubsub/quotas#resource_limits
+     */
+    orderingAttribute?: AttributesOf<Msg>;
+}

package/dist/pubsub/topic.js

@@ -0,0 +1,62 @@
+import { api } from "@encore.dev/internal-runtime";
+import reqtrack from "@encore.dev/internal-runtime/reqtrack/index";
+import { PubSub } from "@encore.dev/sidecar-api";
+/**
+ * A topic is a resource to which you can publish messages
+ * to be delivered to subscribers of that topic.
+ */
+export class Topic {
+    name;
+    cfg;
+    constructor(name, cfg) {
+        this.name = name;
+        this.cfg = cfg;
+    }
+    async publish(msg) {
+        const res = await api().pubsub.publish(new PubSub.PublishRequest({
+            topic: this.name,
+            message: new PubSub.Message({
+                data: Buffer.from(JSON.stringify(msg)),
+                attributes: {},
+                traceParent: reqtrack.currentTraceParent(),
+            }),
+        }));
+        return res.id;
+    }
+}
+/**
+ * At Least Once delivery guarantees that a message for a subscription is delivered to
+ * a consumer at least once.
+ *
+ * On AWS and GCP there is no limit to the throughput for a topic.
+ */
+export const atLeastOnce = "at-least-once";
+/**
+ * ExactlyOnce guarantees that a message for a subscription is delivered to
+ * a consumer exactly once, to the best of the system's ability.
+ *
+ * However, there are edge cases when a message might be redelivered.
+ * For example, if a networking issue causes the acknowledgement of success
+ * processing the message to be lost before the cloud provider receives it.
+ *
+ * It is also important to note that the ExactlyOnce delivery guarantee only
+ * applies to the delivery of the message to the consumer, and not to the
+ * original publishing of the message, such that if a message is published twice,
+ * such as due to an retry within the application logic, it will be delivered twice.
+ * (i.e. ExactlyOnce delivery does not imply message deduplication on publish)
+ *
+ * As such it's recommended that the subscription handler function is idempotent
+ * and is able to handle duplicate messages.
+ *
+ * Subscriptions attached to ExactlyOnce topics have higher message delivery latency compared to AtLeastOnce.
+ *
+ * By using ExactlyOnce semantics on a topic, the throughput will be limited depending on the cloud provider:
+ * - AWS: 300 messages per second for the topic (see [AWS SQS Quotas]).
+ * - GCP: At least 3,000 messages per second across all topics in the region
+ *      (can be higher on the region see [GCP PubSub Quotas]).
+ *
+ * [AWS SQS Quotas]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/quotas-messages.html
+ * [GCP PubSub Quotas]: https://cloud.google.com/pubsub/quotas#quotas
+ */
+export const exactlyOnce = "exactly-once";
+//# sourceMappingURL=topic.js.map

package/dist/pubsub/topic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic.js","sourceRoot":"","sources":["../../pubsub/topic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,8BAA8B,CAAC;AACnD,OAAO,QAAQ,MAAM,6CAA6C,CAAC;AACnE,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGjD;;;GAGG;AACH,MAAM,OAAO,KAAK;IACA,IAAI,CAAS;IACb,GAAG,CAAmB;IAEtC,YAAY,IAAY,EAAE,GAAqB;QAC7C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAEM,KAAK,CAAC,OAAO,CAAC,GAAQ;QAC3B,MAAM,GAAG,GAAG,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CACpC,IAAI,MAAM,CAAC,cAAc,CAAC;YACxB,KAAK,EAAE,IAAI,CAAC,IAAI;YAChB,OAAO,EAAE,IAAI,MAAM,CAAC,OAAO,CAAC;gBAC1B,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;gBACtC,UAAU,EAAE,EAAE;gBACd,WAAW,EAAE,QAAQ,CAAC,kBAAkB,EAAE;aAC3C,CAAC;SACH,CAAC,CACH,CAAC;QAEF,OAAO,GAAG,CAAC,EAAE,CAAC;IAChB,CAAC;CACF;AAOD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAsB,eAAe,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,WAAW,GAAsB,cAAc,CAAC"}

package/dist/storage/sqldb/database.d.ts

@@ -0,0 +1,51 @@
+import type { StringLiteral } from "@encore.dev/internal-runtime/utils/constraints";
+export interface SQLDatabaseConfig {
+    migrations?: string;
+}
+/**
+ * Represents a single row from a query result
+ */
+export type Row = Record<string, any>;
+/** Represents a type that can be used in query template literals */
+export type Primitive = string | number | boolean | null;
+/**
+ * Constructing a new database object will result in Encore provisioning a database with
+ * that name and returning this object to represent it.
+ *
+ * If you want to reference an existing database, use `Database.Named(name)` as it is a
+ * compile error to create duplicate databases.
+ */
+export declare class SQLDatabase {
+    private readonly runtimeCfg;
+    private readonly pool;
+    /**
+     * Creates a new database with the given name and configuration
+     */
+    constructor(name: string, cfg?: SQLDatabaseConfig);
+    /**
+     * Reference an existing database by name, if the database doesn't
+     * exist yet, use `new Database(name)` instead.
+     */
+    static named<name extends string>(name: StringLiteral<name>): SQLDatabase;
+    /**
+     * Returns the connection string for the database
+     */
+    get connectionString(): string;
+    /**
+     * q allows you to query the database using a template string, replacing your placeholders in the template
+     * with parametrised values. It returns an async generator that you can iterate over to get the results, in a
+     * streaming fashion.
+     *
+     * @example
+     *
+     * const email = "foo@example.com";
+     * const result = database.q`SELECT id FROM users WHERE email=${email}` // produces a prepared query of
+     *                                                                      // "SELECT id FROM users WHERE email=$1"
+     *                                                                      // with an arg array of [email]
+     *
+     * for await (const row of result) {
+     *    console.log(row.id);
+     * }
+     */
+    q<T extends Row = Record<string, any>>(strings: TemplateStringsArray, ...expr: Primitive[]): AsyncGenerator<T>;
+}