go-pubsub

Encore Go 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 as package-level variables — never inside functions.

Topics

package events

import "encore.dev/pubsub"

type OrderCreatedEvent struct {
    OrderID string `json:"order_id"`
    UserID  string `json:"user_id"`
    Total   int    `json:"total"`
}

// Package level declaration
var OrderCreated = pubsub.NewTopic[*OrderCreatedEvent]("order-created", pubsub.TopicConfig{
    DeliveryGuarantee: pubsub.AtLeastOnce,
})

Publishing

msgID, err := events.OrderCreated.Publish(ctx, &events.OrderCreatedEvent{
    OrderID: "123",
    UserID:  "user-456",
    Total:   9999,
})

Subscriptions

package notifications

import (
    "context"
    "myapp/events"
    "encore.dev/pubsub"
)

var _ = pubsub.NewSubscription(events.OrderCreated, "send-confirmation-email",
    pubsub.SubscriptionConfig[*events.OrderCreatedEvent]{
        Handler: sendConfirmationEmail,
    },
)

func sendConfirmationEmail(ctx context.Context, event *events.OrderCreatedEvent) error {
    // Send email...
    return nil
}

Topic References

Pass topic access to library code while maintaining static analysis. The snippet below is a sketch: create the reference inside a function within an Encore service so static analysis still applies, and pass the context of the caller into the helper as a parameter instead of relying on an undeclared one:

// Create a reference with publish permission
ref := pubsub.TopicRef[pubsub.Publisher[*OrderCreatedEvent]](OrderCreated)

// Use the reference in library code
func publishEvent(ref pubsub.Publisher[*OrderCreatedEvent], event *OrderCreatedEvent) error {
    _, err := ref.Publish(ctx, event)
    return err
}

Delivery Guarantees

• pubsub.AtLeastOnce (default): may deliver duplicates → handlers must be idempotent.
• pubsub.ExactlyOnce: stricter, capped throughput (AWS 300 msg/s/topic, GCP 3000+ msg/s/region). Does not deduplicate on the publish side. Even with exactly once delivery, duplicate Publish calls produce distinct messages, so keep handlers idempotent. Throughput limits depend on the cloud provider; check them against current Encore and cloud documentation.

Guidelines

• Topics and subscriptions must be declared as package-level variables.
• Subscription handlers must be idempotent (at-least-once delivery is the default).
• To make a handler idempotent, record a processed key, such as the order ID plus the subscription name, in a database table with a unique constraint before the side effect, and skip the work when the key already exists. Returning an error after a partial side effect causes a retry, so that side effect may repeat.
• Validate required event fields, such as a non-empty order ID and user ID, before any side effect, and load authoritative state from the owning service when the handler depends on it. For permanently invalid messages, log them and return nil so they are not retried forever.
• Keep event payloads minimal and prefer IDs over personal data. Keep secrets and tokens out of events, since every subscriber receives them and the broker may store them; subscribers can fetch sensitive details from the owning service.
• Subscription handlers receive a context.Context and the event pointer; return an error to retry per the retry policy of the subscription. The retry policy is configured on the subscription, and messages that exceed the maximum retries go to a dead letter.
• Publish returns once the message is queued and does not wait for subscribers. Move slow work into subscription handlers, and always check the error that Publish returns.