Encore Go Pub/Sub

Instructions

Pub/Sub est destiné à la messagerie asynchrone entre services. Les producteurs publient des événements sur un Topic ; les consommateurs attachent des Subscriptions pour réagir. Les ressources doivent être déclarées comme variables de niveau package — jamais à l'intérieur de fonctions.

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

Passez l'accès au topic au code library tout en maintenant l'analyse statique :

// 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 (par défaut) : peut livrer des doublons → les handlers doivent être idempotents.
pubsub.ExactlyOnce : plus strict, débit plafonné (AWS 300 msg/s/topic, GCP 3000+ msg/s/région). Ne déduplique pas côté publication.

Guidelines

Les topics et subscriptions doivent être déclarés comme variables de niveau package.
Les handlers de subscription doivent être idempotents (la livraison at-least-once est le défaut).
Les handlers de subscription reçoivent un context.Context et le pointeur d'événement ; retournez une error pour réessayer selon la politique de retry du topic.
Ne faites pas de travail synchrone lourd dans les appelants de Publish — Publish retourne une fois que le message est mis en file d'attente.

encore-go-pubsub