encore-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;
}
 

Publishing

Subscriptions

Message Attributes

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

Topic References

Pass topic access to other code while maintaining static analysis:

Delivery Guarantees

• at-least-once (default): 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 (at-least-once delivery is the default).
• Use Attribute<T> for fields meant for filtering/ordering, not for arbitrary metadata.
• Don't do heavy synchronous work in publish callers — publish returns once the message is queued.