Publish an order-placed event from a standard library ServeMux handler and process it in idempotent subscribers, using Encore on SNS and SQS or GCP Pub/Sub, or the AWS SDK by hand.

The Go standard library http.ServeMux is enough to accept a POST /orders and write a JSON response, and Go 1.22 patterns such as POST /orders need no extra router.
The work starts after the insert: a warehouse needs a reserved-stock event, a packing desk needs a slip, and those must not be lost if the handler process restarts, which means a topic, a queue per consumer, retries, a dead-letter queue, and IAM for the publisher and each worker.
This guide adds Pub/Sub to a net/http order API starting with Encore, which declares the topic and subscribers in Go next to the ServeMux and runs them locally and in your own AWS or GCP account, then shows the same flow with SNS, SQS and aws-sdk-go-v2.
Encore works alongside a plain net/http app: the ServeMux and its handlers stay standard library code, and the topic they publish to is a Go declaration next to them. A raw endpoint is an ordinary http.HandlerFunc, so the mux is mounted in one fallback route that receives every request no Encore endpoint matches. The Pub/Sub API publishes from the handler and runs each subscriber as its own function.
A coding agent working in this repository adds the topic type, the publish call and the subscribers in the same change, then uses encore run to publish an order and watch both subscribers run on the laptop.
Run in your terminal to get started locally.
The schema stores the order and a claims table so a redelivered event cannot reserve stock or send a slip twice:
-- orders/migrations/1_create_orders.up.sql
CREATE TABLE orders (
id TEXT PRIMARY KEY,
sku TEXT NOT NULL,
qty INT NOT NULL CHECK (qty > 0),
status TEXT NOT NULL DEFAULT 'placed' CHECK (status IN ('placed', 'reserved', 'packed')),
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE processed_events (
event_id TEXT PRIMARY KEY,
consumer TEXT NOT NULL,
processed_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- Events to publish, written in the same transaction as the order.
CREATE TABLE order_outbox (
order_id TEXT PRIMARY KEY REFERENCES orders (id),
sku TEXT NOT NULL,
qty INT NOT NULL,
placed_at TIMESTAMPTZ NOT NULL
);
The service declares the topic, mounts the ServeMux, and writes an outbox row in the same transaction as the order. After the commit, flushOutbox publishes that row and deletes it, so a failed publish is retried on the next request instead of being lost. Two subscriptions each claim the event id in processed_events before they do their work:
// orders/orders.go
package orders
import (
"context"
"encoding/json"
"errors"
"net/http"
"strings"
"time"
"encore.dev/pubsub"
"encore.dev/rlog"
"encore.dev/storage/sqldb"
"encore.dev/storage/sqldb/sqlerr"
)
var db = sqldb.NewDatabase("orders", sqldb.DatabaseConfig{
Migrations: "./migrations",
})
type OrderPlaced struct {
OrderID string `json:"order_id"`
SKU string `json:"sku"`
Qty int `json:"qty"`
PlacedAt time.Time `json:"placed_at"`
}
// Every subscription gets its own copy of each event.
var Orders = pubsub.NewTopic[*OrderPlaced]("order-placed", pubsub.TopicConfig{
DeliveryGuarantee: pubsub.AtLeastOnce,
})
//encore:service
type Service struct {
mux *http.ServeMux
}
func initService() (*Service, error) {
mux := http.NewServeMux()
mux.HandleFunc("POST /orders", placeOrder)
return &Service{mux: mux}, nil
}
// Fallback hands every request that no Encore endpoint matches to the ServeMux.
//
//encore:api public raw path=/!fallback
func (s *Service) Fallback(w http.ResponseWriter, req *http.Request) {
s.mux.ServeHTTP(w, req)
}
func placeOrder(w http.ResponseWriter, r *http.Request) {
var in struct {
OrderID string `json:"order_id"`
SKU string `json:"sku"`
Qty int `json:"qty"`
}
if err := json.NewDecoder(r.Body).Decode(&in); err != nil || strings.TrimSpace(in.OrderID) == "" || in.Qty < 1 {
http.Error(w, "order_id and a positive qty are required", http.StatusBadRequest)
return
}
placedAt := time.Now().UTC()
tx, err := db.Begin(r.Context())
if err != nil {
http.Error(w, "could not create order", http.StatusInternalServerError)
return
}
defer tx.Rollback()
_, err = tx.Exec(r.Context(), `
INSERT INTO orders (id, sku, qty) VALUES ($1, $2, $3)`, in.OrderID, in.SKU, in.Qty)
exists := sqldb.ErrCode(err) == sqlerr.UniqueViolation
if err != nil && !exists {
http.Error(w, "could not create order", http.StatusInternalServerError)
return
}
if !exists {
if _, err := tx.Exec(r.Context(), `
INSERT INTO order_outbox (order_id, sku, qty, placed_at)
VALUES ($1, $2, $3, $4)`, in.OrderID, in.SKU, in.Qty, placedAt); err != nil {
http.Error(w, "could not create order", http.StatusInternalServerError)
return
}
if err := tx.Commit(); err != nil {
http.Error(w, "could not create order", http.StatusInternalServerError)
return
}
} else {
_ = tx.Rollback()
}
msgID, err := flushOutbox(r.Context(), in.OrderID)
if err != nil {
http.Error(w, "order saved, event not published", http.StatusInternalServerError)
return
}
if exists && msgID == "" {
http.Error(w, "order already exists", http.StatusConflict)
return
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusAccepted)
_ = json.NewEncoder(w).Encode(map[string]string{"status": "placed", "message_id": msgID})
}
// Publish any committed order events that have not yet been sent. A failed
// publish leaves the row in place so the next request retries it.
func flushOutbox(ctx context.Context, orderID string) (string, error) {
var sku string
var qty int
var placedAt time.Time
err := db.QueryRow(ctx, `
SELECT sku, qty, placed_at FROM order_outbox WHERE order_id = $1`, orderID).Scan(&sku, &qty, &placedAt)
if errors.Is(err, sqldb.ErrNoRows) {
return "", nil
} else if err != nil {
return "", err
}
msgID, err := Orders.Publish(ctx, &OrderPlaced{
OrderID: orderID,
SKU: sku,
Qty: qty,
PlacedAt: placedAt,
})
if err != nil {
return "", err
}
_, err = db.Exec(ctx, `DELETE FROM order_outbox WHERE order_id = $1`, orderID)
return msgID, err
}
func claim(ctx context.Context, consumer, eventID string) (bool, error) {
_, err := db.Exec(ctx, `
INSERT INTO processed_events (event_id, consumer) VALUES ($1, $2)`, eventID+":"+consumer, consumer)
if sqldb.ErrCode(err) == sqlerr.UniqueViolation {
return false, nil
}
return err == nil, err
}
func release(ctx context.Context, consumer, eventID string) {
_, _ = db.Exec(ctx, `DELETE FROM processed_events WHERE event_id = $1`, eventID+":"+consumer)
}
var _ = pubsub.NewSubscription(Orders, "reserve-stock",
pubsub.SubscriptionConfig[*OrderPlaced]{
Handler: reserveStock,
RetryPolicy: &pubsub.RetryPolicy{
MinBackoff: 10 * time.Second,
MaxBackoff: 5 * time.Minute,
MaxRetries: 8,
},
},
)
func reserveStock(ctx context.Context, ev *OrderPlaced) error {
ok, err := claim(ctx, "reserve-stock", ev.OrderID)
if err != nil || !ok {
return err
}
// Call your inventory service here. On failure, release so a retry can claim again.
if err := reserveSKU(ctx, ev.SKU, ev.Qty); err != nil {
release(ctx, "reserve-stock", ev.OrderID)
rlog.Warn("reserve failed, will retry", "order", ev.OrderID, "err", err)
return err
}
_, err = db.Exec(ctx, `UPDATE orders SET status = 'reserved' WHERE id = $1 AND status = 'placed'`, ev.OrderID)
return err
}
var _ = pubsub.NewSubscription(Orders, "print-packing-slip",
pubsub.SubscriptionConfig[*OrderPlaced]{
Handler: printPackingSlip,
AckDeadline: time.Minute,
RetryPolicy: &pubsub.RetryPolicy{
MinBackoff: 30 * time.Second,
MaxBackoff: 10 * time.Minute,
MaxRetries: 10,
},
},
)
func printPackingSlip(ctx context.Context, ev *OrderPlaced) error {
ok, err := claim(ctx, "print-packing-slip", ev.OrderID)
if err != nil || !ok {
return err
}
if err := sendSlip(ctx, ev.OrderID, ev.SKU, ev.Qty); err != nil {
release(ctx, "print-packing-slip", ev.OrderID)
return err
}
rlog.Info("packing slip sent", "order", ev.OrderID)
return nil
}
func reserveSKU(ctx context.Context, sku string, qty int) error {
// Stand-in for your inventory reservation call.
return nil
}
func sendSlip(ctx context.Context, orderID, sku string, qty int) error {
// Stand-in for your packing-slip printer or email API.
return nil
}
encore run starts Postgres locally, applies the migration, and delivers published messages to both subscribers on your laptop. On deploy to your own AWS account, Encore provisions SNS and SQS for the topic and subscriptions, and Encore provisions an IAM role for the service; on GCP that is a Pub/Sub topic with subscriptions and a service account. Failed deliveries follow the RetryPolicy and then go to a dead-letter queue.
AtLeastOnce means a subscriber can run more than once for the same event, which is why the unique claim comes before the side effect. Exactly-once delivery tightens the broker guarantees, with a 300 messages per second limit on AWS, and still asks for an idempotent handler because an acknowledgement can be lost.
Best fit: a net/http API that wants the topic declared next to the handlers, with SNS and SQS or GCP Pub/Sub in your own account.
The same API can publish to an SNS topic and let each consumer long-poll its own SQS queue subscribed to that topic. You provision the topic, the queues, the subscriptions, a redrive policy, and an IAM role that can publish and consume.
// cmd/api/main.go
package main
import (
"context"
"database/sql"
"encoding/json"
"errors"
"log"
"net/http"
"os"
"strings"
"time"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/sns"
"github.com/jackc/pgx/v5/pgconn"
_ "github.com/jackc/pgx/v5/stdlib"
)
type OrderPlaced struct {
OrderID string `json:"order_id"`
SKU string `json:"sku"`
Qty int `json:"qty"`
PlacedAt time.Time `json:"placed_at"`
}
type api struct {
sns *sns.Client
db *sql.DB
topicARN string
}
func main() {
cfg, err := config.LoadDefaultConfig(context.Background())
if err != nil {
log.Fatal(err)
}
db, err := sql.Open("pgx", os.Getenv("DATABASE_URL"))
if err != nil {
log.Fatal(err)
}
a := &api{sns: sns.NewFromConfig(cfg), db: db, topicARN: os.Getenv("ORDERS_TOPIC_ARN")}
mux := http.NewServeMux()
mux.HandleFunc("POST /orders", a.placeOrder)
srv := &http.Server{Addr: ":8080", Handler: mux, ReadHeaderTimeout: 5 * time.Second}
log.Fatal(srv.ListenAndServe())
}
func (a *api) placeOrder(w http.ResponseWriter, r *http.Request) {
var in OrderPlaced
if err := json.NewDecoder(r.Body).Decode(&in); err != nil || strings.TrimSpace(in.OrderID) == "" || in.Qty < 1 {
http.Error(w, "order_id and a positive qty are required", http.StatusBadRequest)
return
}
placedAt := time.Now().UTC()
tx, err := a.db.BeginTx(r.Context(), nil)
if err != nil {
http.Error(w, "could not create order", http.StatusInternalServerError)
return
}
defer tx.Rollback()
_, err = tx.ExecContext(r.Context(), `INSERT INTO orders (id, sku, qty) VALUES ($1, $2, $3)`, in.OrderID, in.SKU, in.Qty)
exists := isUniqueViolation(err)
if err != nil && !exists {
http.Error(w, "could not create order", http.StatusInternalServerError)
return
}
if !exists {
if _, err := tx.ExecContext(r.Context(), `
INSERT INTO order_outbox (order_id, sku, qty, placed_at)
VALUES ($1, $2, $3, $4)`, in.OrderID, in.SKU, in.Qty, placedAt); err != nil {
http.Error(w, "could not create order", http.StatusInternalServerError)
return
}
if err := tx.Commit(); err != nil {
http.Error(w, "could not create order", http.StatusInternalServerError)
return
}
} else {
_ = tx.Rollback()
}
published, err := a.flushOutbox(r.Context(), in.OrderID)
if err != nil {
http.Error(w, "order saved, event not published", http.StatusInternalServerError)
return
}
if exists && !published {
http.Error(w, "order already exists", http.StatusConflict)
return
}
w.WriteHeader(http.StatusAccepted)
}
func (a *api) flushOutbox(ctx context.Context, orderID string) (bool, error) {
var sku string
var qty int
var placedAt time.Time
err := a.db.QueryRowContext(ctx, `
SELECT sku, qty, placed_at FROM order_outbox WHERE order_id = $1`, orderID).Scan(&sku, &qty, &placedAt)
if errors.Is(err, sql.ErrNoRows) {
return false, nil
} else if err != nil {
return false, err
}
body, err := json.Marshal(OrderPlaced{OrderID: orderID, SKU: sku, Qty: qty, PlacedAt: placedAt})
if err != nil {
return false, err
}
if _, err := a.sns.Publish(ctx, &sns.PublishInput{TopicArn: &a.topicARN, Message: awsString(string(body))}); err != nil {
return false, err
}
_, err = a.db.ExecContext(ctx, `DELETE FROM order_outbox WHERE order_id = $1`, orderID)
return true, err
}
func isUniqueViolation(err error) bool {
var pgErr *pgconn.PgError
return errors.As(err, &pgErr) && pgErr.Code == "23505"
}
func awsString(s string) *string { return &s }
A second process long-polls the inventory queue, unmarshals the SNS wrapper around the event, claims the order id, and deletes the SQS message only after the work succeeds. Set ReceiveMessageWaitTimeSeconds to 20, give the queue a redrive policy after a bounded number of receives, and use the queue URL from configuration rather than hard-coding an account id.
Best fit: teams that already have SNS and SQS in Terraform and want the net/http process to stay a plain binary.
Publishing to a channel and starting a goroutine in placeOrder is the smallest change, and it disappears if the process exits before the work finishes. There is no retry, no dead-letter queue, and no second consumer on another machine. Use it only for work you can afford to lose, such as an in-memory metric, not for reserving stock.
Best fit: throwaway local experiments, not an order pipeline.
Pick Encore when you want the topic and subscribers declared next to the ServeMux, delivered locally with encore run, and provisioned as SNS and SQS or GCP Pub/Sub in your own account. Pick SNS and SQS by hand when those resources already live in Terraform and you want to keep the API a plain net/http binary. A goroutine in the handler is not a substitute for a broker once a missed event would leave an order unreserved.
The idempotency pattern itself does not depend on the choice: claim the event in a unique table before the side effect, and release the claim if the side effect fails, as described in the Pub/Sub delivery guarantees.
Write an outbox row in the same transaction as the order, commit, then publish and delete the outbox row, and return 202. Process the event in a separate consumer that is safe to run twice. On AWS that is usually an SNS topic with one SQS queue per consumer, published with the aws-sdk-go-v2 SNS client and read by a long-polling SQS loop.
Declare a topic with pubsub.NewTopic and one pubsub.NewSubscription per consumer, mount the ServeMux in a raw endpoint with path=/!fallback, and publish from the handler after the database write. encore run delivers messages to subscribers on your laptop, and on deploy Encore provisions SNS and SQS on AWS, or GCP Pub/Sub, in your own account.
Record the message or order id in a table with a unique constraint before doing the side effect, and treat a unique-violation as already done. If the side effect fails, delete the claim row (or leave it uncommitted) so a retry can try again.
Publishing inside the transaction can leave a message for a rolled-back order if the broker commit happens first. Write an outbox row in the same transaction as the order, commit, then publish. A failed publish leaves the outbox row in place so a later request or worker can retry it. Do not rely on the client retrying a request that already inserted the order.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.