pubsub

Encore Pub/Sub

Instructions

Pub/Sub is for asynchronous messaging between services. Producers publish events to a Topic; consumers attach Subscriptions to react. Resources must be declared at package level — never inside functions.

Topics

import { Topic } from "encore.dev/pubsub";

interface OrderCreatedEvent {
  orderId: string;
  userId: string;
  total: number;
}

// Package level declaration
export const orderCreated = new Topic<OrderCreatedEvent>("order-created", {
  deliveryGuarantee: "at-least-once",
});

Publishing

await orderCreated.publish({
  orderId: "123",
  userId: "user-456",
  total: 99.99,
});

Subscriptions

import { Subscription } from "encore.dev/pubsub";

const _ = new Subscription(orderCreated, "send-confirmation-email", {
  handler: async (event) => {
    await sendEmail(event.userId, event.orderId);
  },
});

This handler is a minimal sketch. In real code, treat the event fields as untrusted input: check that the referenced order exists and belongs to the user, look up the email address from your own records, and make the handler idempotent by recording that this order was already handled by this subscription, so a repeated delivery still sends only one email.

Message Attributes

Use Attribute<T> for fields that should be treated as message attributes (for filtering/ordering):

import { Topic, Attribute } from "encore.dev/pubsub";

interface CartEvent {
  cartId: Attribute<string>;  // Used for ordering
  userId: string;
  action: "add" | "remove";
  productId: string;
}

// Ordered topic: events with same cartId delivered in order
export const cartEvents = new Topic<CartEvent>("cart-events", {
  deliveryGuarantee: "at-least-once",
  orderingAttribute: "cartId",
});

Topic References

Pass topic access to other code while maintaining static analysis:

import { Publisher } from "encore.dev/pubsub";

const publisherRef = orderCreated.ref<Publisher>();

async function notifyOrder(ref: typeof publisherRef, orderId: string) {
  await ref.publish({ orderId, userId: "123", total: 99.99 });
}

The user and total values above are placeholders. In real code, pass them in, taking the user from the authenticated caller or the order record.

Delivery Guarantees

• at-least-once (the usual choice; always set the delivery guarantee explicitly in the topic config): may deliver duplicates → handlers must be idempotent.
• exactly-once: stricter, capped throughput (AWS 300 msg/s/topic, GCP 3000+ msg/s/region). Does not deduplicate on the publish side.

Guidelines

• Topics and subscriptions must be declared at package level.
• Subscription handlers must be idempotent (duplicates are possible under either guarantee).
• Treat event payloads as untrusted input; validate fields in the handler and look up authorization relevant data from your own stores.
• Plan for handler failures: a handler that throws may be delivered again, so make sure a bad message cannot fail forever or block ordered delivery, and review the retry settings available on subscriptions.
• Use Attribute<T> for fields meant for filtering/ordering, not for arbitrary metadata. Attribute values are visible to the broker, so use opaque identifiers there that reveal nothing sensitive.
• Keep event payloads minimal: publish identifiers and let subscribers fetch personal or payment details from the owning service.
• publish returns once the message is queued, so put slow or heavy work in subscription handlers rather than in the code that publishes.