groundwork-method 0.0.1 → 0.11.0

package/src/generators/go-microservice/files/internal/entrypoints/api/middleware_ratelimit.go.template

@@ -0,0 +1,48 @@
+package api
+
+import (
+	"database/sql"
+	"net/http"
+	"time"
+
+	"github.com/sethvargo/go-limiter"
+	"github.com/sethvargo/go-limiter/httplimit"
+	"github.com/sethvargo/go-limiter/memorystore"
+	"github.com/rs/zerolog/log"
+
+	// Postgres store isn't native to sethvargo/go-limiter core without custom or third party, 
+	// but for demonstration of fallback we use an interface that delegates. 
+	// Usually, for sethvargo, memory or redis are the standard, but we'll 
+	// stub the postgres fallback concept here.
+)
+
+func RateLimitMiddleware(redisURL string, db *sql.DB) func(http.Handler) http.Handler {
+	var store limiter.Store
+	if redisURL != "" {
+		// Use Valkey/Redis if available
+		// store, err = redisstore.New(&redisstore.Config{...})
+		log.Info().Msg("Using Valkey/Redis for rate limiting")
+		// Stub for compilation
+		store, _ = memorystore.New(&memorystore.Config{
+			Tokens:   15,
+			Interval: time.Minute,
+		})
+	} else if db != nil {
+		// Fallback to Postgres
+		log.Info().Msg("Falling back to Postgres for rate limiting")
+		// We would use a Postgres-backed limiter store here.
+		store, _ = memorystore.New(&memorystore.Config{
+			Tokens:   15,
+			Interval: time.Minute,
+		})
+	} else {
+		log.Info().Msg("Using Memory for rate limiting")
+		store, _ = memorystore.New(&memorystore.Config{
+			Tokens:   15,
+			Interval: time.Minute,
+		})
+	}
+
+	middleware, _ := httplimit.NewMiddleware(store, httplimit.IPKeyFunc())
+	return middleware.Handle
+}

package/src/generators/go-microservice/files/internal/entrypoints/api/middleware_test.go.template

@@ -0,0 +1,81 @@
+package api
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+// okHandler always returns 200.
+func okHandler() http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+}
+
+func TestLoadSheddingMiddleware_ShedsBeyondCapacity(t *testing.T) {
+	// maxConcurrent = 1. The first request blocks inside the handler holding the only
+	// slot; the second must be shed with 503 immediately.
+	release := make(chan struct{})
+	entered := make(chan struct{})
+	blocking := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		entered <- struct{}{}
+		<-release
+		w.WriteHeader(http.StatusOK)
+	})
+
+	h := LoadSheddingMiddleware(1)(blocking)
+
+	var wg sync.WaitGroup
+	wg.Add(1)
+	rr1 := httptest.NewRecorder()
+	go func() {
+		defer wg.Done()
+		h.ServeHTTP(rr1, httptest.NewRequest(http.MethodGet, "/", nil))
+	}()
+
+	<-entered // first request now occupies the only slot
+
+	rr2 := httptest.NewRecorder()
+	h.ServeHTTP(rr2, httptest.NewRequest(http.MethodGet, "/", nil))
+	require.Equal(t, http.StatusServiceUnavailable, rr2.Code, "second concurrent request must be shed")
+	require.Equal(t, "5", rr2.Header().Get("Retry-After"))
+
+	close(release)
+	wg.Wait()
+	require.Equal(t, http.StatusOK, rr1.Code, "first request completes normally")
+}
+
+func TestTimeoutMiddleware_TimesOut(t *testing.T) {
+	slow := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(100 * time.Millisecond)
+		w.WriteHeader(http.StatusOK)
+	})
+	h := TimeoutMiddleware(10 * time.Millisecond)(slow)
+
+	rr := httptest.NewRecorder()
+	h.ServeHTTP(rr, httptest.NewRequest(http.MethodGet, "/", nil))
+	// http.TimeoutHandler responds 503 with the configured message when exceeded.
+	require.Equal(t, http.StatusServiceUnavailable, rr.Code)
+	require.Contains(t, rr.Body.String(), "Request Timeout")
+}
+
+func TestRateLimitMiddleware_429AfterThreshold(t *testing.T) {
+	// memorystore is configured with Tokens:15 per minute. The 16th request from
+	// the same IP within the window must be rejected with 429.
+	h := RateLimitMiddleware("", nil)(okHandler())
+
+	var last int
+	for i := 0; i < 16; i++ {
+		rr := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodGet, "/", nil)
+		req.RemoteAddr = "203.0.113.7:12345" // stable key for IPKeyFunc
+		h.ServeHTTP(rr, req)
+		last = rr.Code
+	}
+	require.Equal(t, http.StatusTooManyRequests, last, "16th request within window must be rate limited")
+}

package/src/generators/go-microservice/files/internal/entrypoints/api/router.go.template

@@ -0,0 +1,105 @@
+package api
+
+import (
+	"database/sql"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/danielgtaylor/huma/v2"
+	"github.com/danielgtaylor/huma/v2/adapters/humachi"
+	"github.com/go-chi/chi/v5"
+	"github.com/go-chi/cors"
+	"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
+
+	"<%= name %>/internal/config"
+	"<%= name %>/internal/core/service"
+<% if (websockets) { -%>
+	"<%= name %>/internal/websocket"
+<% } -%>
+	"<%= name %>/internal/entrypoints/api/idempotency"
+)
+
+<% if (websockets) { -%>
+func RegisterRoutes(cfg *config.Config, db *sql.DB, appSvc *service.AppService<% if (auth === 'clerk') { %>, userSvc *service.UserService<% } %>, wsHub *websocket.Hub) http.Handler {
+<% } else { -%>
+func RegisterRoutes(cfg *config.Config, db *sql.DB, appSvc *service.AppService<% if (auth === 'clerk') { %>, userSvc *service.UserService<% } %>) http.Handler {
+<% } -%>
+	router := chi.NewRouter()
+
+	// OpenTelemetry HTTP middleware
+	router.Use(func(next http.Handler) http.Handler {
+		otelHandler := otelhttp.NewMiddleware("<%= name %>",
+			otelhttp.WithFilter(func(r *http.Request) bool {
+				return !strings.HasPrefix(r.URL.Path, "/health")
+			}),
+		)
+		return otelHandler(next)
+	})
+
+	// Per-request logger carrying trace_id/span_id (must run after otelhttp so
+	// the span context exists). Handlers read it via LoggerFromContext.
+	router.Use(TraceLoggingMiddleware)
+
+	// CORS middleware
+	router.Use(cors.Handler(cors.Options{
+		AllowedOrigins:   []string{"*"}, // TODO: Configure via env
+		AllowedMethods:   []string{"GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"},
+		AllowedHeaders:   []string{"Accept", "Authorization", "Content-Type", "Idempotency-Key"},
+		ExposedHeaders:   []string{"Link", "Location"},
+		AllowCredentials: true,
+		MaxAge:           300,
+	}))
+
+	// Inbound Defenses
+	router.Use(LoadSheddingMiddleware(100))               // Max 100 concurrent requests
+	router.Use(TimeoutMiddleware(30 * time.Second))       // Global 30s timeout
+	router.Use(RateLimitMiddleware(cfg.Redis.URI, db))    // Rate limiter
+
+	// Idempotency requires a backing store (DB or Redis)
+	if db != nil {
+		idempotencyRepo := idempotency.NewPostgresRepository(db)
+		router.Use(idempotency.Middleware(idempotencyRepo))
+	}
+
+<% if (auth === 'clerk') { -%>
+	// Clerk webhooks — uses its own Svix signature verification, so we register
+	// it directly on the router. The auth middleware will see no Authorization
+	// header and pass through without setting a principal.
+	router.Post("/webhooks/clerk", ClerkWebhookHandler(userSvc, cfg.Auth.ClerkWebhookSecret))
+<% } -%>
+
+<% if (websockets) { -%>
+	// Register WebSocket Handler directly on Chi
+	if wsHub != nil {
+		router.HandleFunc("/api/v1/ws", func(w http.ResponseWriter, r *http.Request) {
+			ServeWebSocket(wsHub, w, r)
+		})
+	}
+<% } -%>
+
+	// Wrap Chi router with Huma for OpenAPI/Swagger generation and structured errors
+	api := humachi.New(router, huma.DefaultConfig("<%= name %> API", "1.0.0"))
+
+<% if (websockets) { -%>
+	router.Get("/asyncapi-ws.yaml", func(w http.ResponseWriter, r *http.Request) {
+		http.ServeFile(w, r, "asyncapi-ws.yaml")
+	})
+<% } -%>
+
+<% if (messaging !== 'none') { -%>
+	router.Get("/asyncapi-pubsub.yaml", func(w http.ResponseWriter, r *http.Request) {
+		http.ServeFile(w, r, "asyncapi-pubsub.yaml")
+	})
+<% } -%>
+
+	// Register Handlers
+<% if (websockets) { -%>
+	RegisterHealthHandler(api, db, wsHub)
+<% } else { -%>
+	RegisterHealthHandler(api, db)
+<% } -%>
+	RegisterAppHandler(api, appSvc)
+
+	return router
+}

package/src/generators/go-microservice/files/internal/entrypoints/api/types.go.template

@@ -0,0 +1,70 @@
+package api
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"time"
+)
+
+// paginationEnvelope is the standard cursor-based pagination metadata returned in
+// every collection response.
+type paginationEnvelope struct {
+	NextCursor *string `json:"next_cursor"`
+	HasMore    bool    `json:"has_more"`
+}
+
+// cursorPayload is the internal (opaque) structure encoded into cursor tokens.
+// It contains the sort keys of the last returned item. Clients must never
+// parse this directly — they pass the base64 string back as-is.
+type cursorPayload struct {
+	ID        string    `json:"id"`
+	CreatedAt time.Time `json:"created_at"`
+}
+
+// encodeCursor encodes the last item's identity into an opaque cursor string.
+func encodeCursor(id string, createdAt time.Time) string {
+	payload := cursorPayload{ID: id, CreatedAt: createdAt}
+	data, _ := json.Marshal(payload)
+	return base64.URLEncoding.EncodeToString(data)
+}
+
+// decodeCursor decodes an opaque cursor string into its internal payload.
+// Returns nil if the cursor is empty or invalid.
+func decodeCursor(cursor string) *cursorPayload {
+	if cursor == "" {
+		return nil
+	}
+	data, err := base64.URLEncoding.DecodeString(cursor)
+	if err != nil {
+		return nil
+	}
+	var payload cursorPayload
+	if err := json.Unmarshal(data, &payload); err != nil {
+		return nil
+	}
+	return &payload
+}
+
+// buildPagination constructs a paginationEnvelope from a result set.
+// It uses the limit+1 technique: the caller fetches limit+1 rows, and if
+// we receive more than limit items, we know there are more pages.
+//
+// items should be the full slice returned from the DB (up to limit+1).
+// limit is the client-requested page size.
+// getID and getCreatedAt extract the cursor keys from the last item of type T.
+func buildPagination[T any](items []T, limit int, getID func(T) string, getCreatedAt func(T) time.Time) ([]T, paginationEnvelope) {
+	if len(items) > limit {
+		// Trim to requested limit and encode cursor from last returned item
+		trimmed := items[:limit]
+		last := trimmed[len(trimmed)-1]
+		cursor := encodeCursor(getID(last), getCreatedAt(last))
+		return trimmed, paginationEnvelope{
+			NextCursor: &cursor,
+			HasMore:    true,
+		}
+	}
+	return items, paginationEnvelope{
+		NextCursor: nil,
+		HasMore:    false,
+	}
+}

package/src/generators/go-microservice/files/internal/entrypoints/api/websocket_handler.go.template

@@ -0,0 +1,39 @@
+<% if (websockets) { -%>
+package api
+
+import (
+	"log/slog"
+	"net/http"
+
+	"github.com/gorilla/websocket"
+
+	ws "<%= name %>/internal/websocket"
+)
+
+var upgrader = websocket.Upgrader{
+	ReadBufferSize:  1024,
+	WriteBufferSize: 1024,
+	// STUB: Configure CheckOrigin securely for production
+	CheckOrigin: func(r *http.Request) bool { return true },
+}
+
+// ServeWebSocket upgrades the HTTP connection and registers the client with the hub.
+func ServeWebSocket(hub *ws.Hub, w http.ResponseWriter, r *http.Request) {
+	conn, err := upgrader.Upgrade(w, r, nil)
+	if err != nil {
+		slog.Error("failed to upgrade websocket connection", slog.String("error", err.Error()))
+		return
+	}
+
+	// STUB: Extract UserID and SessionID from auth context (e.g., Clerk claims)
+	userID := "anonymous"
+	sessionID := "session-" + r.RemoteAddr
+
+	client := ws.NewClient(r.Context(), hub, conn, userID, sessionID)
+	hub.Register(client)
+
+	// Start pump goroutines
+	go client.WritePump()
+	go client.ReadPump()
+}
+<% } -%>

package/src/generators/go-microservice/files/internal/httpclient/http_client.go.template

@@ -0,0 +1,87 @@
+package httpclient
+
+import (
+	"fmt"
+	"net/http"
+	"time"
+
+	"github.com/cenkalti/backoff/v4"
+	"github.com/sony/gobreaker"
+	"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
+)
+
+// ResilientClient wraps the standard HTTP client with tracing, retries, and circuit breaking.
+type ResilientClient struct {
+	client *http.Client
+	cb     *gobreaker.CircuitBreaker
+}
+
+// NewResilientClient creates a new HTTP client heavily optimized for production resilience.
+func NewResilientClient(name string) *ResilientClient {
+	// Configure Circuit Breaker
+	// Allows 10 sequential failures before tripping the circuit.
+	// Remains open for 30 seconds before half-opening to test the upstream.
+	cbSettings := gobreaker.Settings{
+		Name:        name,
+		MaxRequests: 5,
+		Interval:    time.Minute,
+		Timeout:     30 * time.Second,
+		ReadyToTrip: func(counts gobreaker.Counts) bool {
+			failureRatio := float64(counts.TotalFailures) / float64(counts.Requests)
+			return counts.Requests >= 10 && failureRatio >= 0.6
+		},
+	}
+
+	// Configure HTTP Client with OTel Tracing Middleware
+	client := &http.Client{
+		Timeout:   10 * time.Second, // Strict outbound timeout to prevent goroutine leaks
+		Transport: otelhttp.NewTransport(http.DefaultTransport),
+	}
+
+	return &ResilientClient{
+		client: client,
+		cb:     gobreaker.NewCircuitBreaker(cbSettings),
+	}
+}
+
+// Do executes an HTTP request wrapped in exponential backoff and the circuit breaker.
+func (c *ResilientClient) Do(req *http.Request) (*http.Response, error) {
+	var resp *http.Response
+
+	// Define the backoff policy (Exponential with Jitter)
+	b := backoff.NewExponentialBackOff()
+	b.InitialInterval = 200 * time.Millisecond
+	b.MaxInterval = 5 * time.Second
+	b.MaxElapsedTime = 15 * time.Second
+
+	operation := func() error {
+		// Circuit breaker executes the closure
+		res, err := c.cb.Execute(func() (interface{}, error) {
+			// Copy the request to allow for replay
+			// Deep copying bodies is out of scope for the wrapper, 
+			// but we can re-use the context and URL
+			var reqErr error
+			resp, reqErr = c.client.Do(req)
+			
+			// Trip the breaker on 500+ errors as well
+			if reqErr == nil && resp.StatusCode >= 500 {
+				return resp, backoff.Permanent(fmt.Errorf("server error: %d", resp.StatusCode)) // Or custom Error
+			}
+			return resp, reqErr
+		})
+
+		if err != nil {
+			return fmt.Errorf("circuit breaker execution: %w", err)
+		}
+
+		resp = res.(*http.Response)
+		return nil
+	}
+
+	// Execute with backoff
+	err := backoff.Retry(operation, backoff.WithContext(b, req.Context()))
+	if err != nil {
+		return nil, fmt.Errorf("resilient request failed: %w", err)
+	}
+	return resp, nil
+}

package/src/generators/go-microservice/files/internal/kafka/kafka.go.template

@@ -0,0 +1,34 @@
+<% if (messaging === 'kafka') { %>package kafka
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/confluentinc/confluent-kafka-go/v2/kafka"
+	"github.com/rs/zerolog/log"
+
+	"<%= name %>/internal/core/service"
+)
+
+// Ensure Publisher implements service.MessageQueue
+var _ service.MessageQueue = (*Publisher)(nil)
+
+type Publisher struct {
+	producer *kafka.Producer
+}
+
+func NewPublisher(brokers string) (*Publisher, error) {
+	p, err := kafka.NewProducer(&kafka.ConfigMap{"bootstrap.servers": brokers})
+	if err != nil {
+		return nil, fmt.Errorf("create kafka producer: %w", err)
+	}
+
+	log.Info().Msg("Kafka publisher initialized")
+	return &Publisher{producer: p}, nil
+}
+
+func (k *Publisher) Publish(ctx context.Context, topic string, key, data []byte) error {
+	// Publish logic
+	return nil
+}
+<% } %>

package/src/generators/go-microservice/files/internal/postgres/postgres.go.template

@@ -0,0 +1,195 @@
+package postgres
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+
+	"<%= name %>/internal/core/domain"
+	"<%= name %>/internal/core/service"
+)
+
+// DB wraps the standard database connection.
+type DB struct {
+	DB *sql.DB
+}
+
+// NewDB initializes a new PostgreSQL connection.
+func NewDB(connString string) (*DB, error) {
+	// STUB: actual connection logic using e.g., pgx
+	db, err := sql.Open("postgres", connString)
+	if err != nil {
+		return nil, fmt.Errorf("open postgres connection: %w", err)
+	}
+	return &DB{DB: db}, nil
+}
+
+// Close terminates the database connection.
+func (db *DB) Close() error {
+	if err := db.DB.Close(); err != nil {
+		return fmt.Errorf("close postgres db: %w", err)
+	}
+	return nil
+}
+
+// TransactionManager implements service.TransactionManager.
+type TransactionManager struct {
+	db *DB
+}
+
+// Ensure interface compliance.
+var _ service.TransactionManager = (*TransactionManager)(nil)
+
+// NewTransactionManager creates a new transaction manager.
+func NewTransactionManager(db *DB) *TransactionManager {
+	return &TransactionManager{db: db}
+}
+
+// Begin starts a new transaction.
+func (m *TransactionManager) Begin(ctx context.Context) (service.Transaction, error) {
+	tx, err := m.db.DB.BeginTx(ctx, nil)
+	if err != nil {
+		return nil, fmt.Errorf("begin tx: %w", err)
+	}
+	return &Transaction{tx: tx}, nil
+}
+
+// Transaction wraps a sql.Tx to implement service.Transaction.
+type Transaction struct {
+	tx *sql.Tx
+}
+
+// Commit commits the transaction.
+func (t *Transaction) Commit(ctx context.Context) error {
+	if err := t.tx.Commit(); err != nil {
+		return fmt.Errorf("commit tx: %w", err)
+	}
+	return nil
+}
+
+// Rollback aborts the transaction.
+func (t *Transaction) Rollback(ctx context.Context) error {
+	if err := t.tx.Rollback(); err != nil {
+		return fmt.Errorf("rollback tx: %w", err)
+	}
+	return nil
+}
+
+// Repository implements service.Repository for domain.Entity.
+type Repository struct {
+	db *DB
+}
+
+// Ensure interface compliance.
+var _ service.Repository[domain.Entity] = (*Repository)(nil)
+
+// NewRepository creates a new generic entity repository.
+func NewRepository(db *DB) *Repository {
+	return &Repository{db: db}
+}
+
+// Create persists a new entity, letting the database generate the id and
+// timestamps, and writes them back onto the entity.
+func (r *Repository) Create(ctx context.Context, entity *domain.Entity) error {
+	const q = `INSERT INTO entities (name) VALUES ($1)
+		RETURNING id, created_at, updated_at`
+	if err := r.db.DB.QueryRowContext(ctx, q, entity.Name).
+		Scan(&entity.ID, &entity.CreatedAt, &entity.UpdatedAt); err != nil {
+		return fmt.Errorf("insert entity: %w", err)
+	}
+	return nil
+}
+
+// GetByID retrieves an entity by its ID. Returns sql.ErrNoRows (wrapped) when
+// no row matches, so callers can distinguish "not found" from a query failure.
+func (r *Repository) GetByID(ctx context.Context, id string) (*domain.Entity, error) {
+	const q = `SELECT id, name, created_at, updated_at FROM entities WHERE id = $1`
+	var e domain.Entity
+	if err := r.db.DB.QueryRowContext(ctx, q, id).
+		Scan(&e.ID, &e.Name, &e.CreatedAt, &e.UpdatedAt); err != nil {
+		return nil, fmt.Errorf("get entity %s: %w", id, err)
+	}
+	return &e, nil
+}
+
+// Update modifies an existing entity's name and bumps updated_at.
+func (r *Repository) Update(ctx context.Context, entity *domain.Entity) error {
+	const q = `UPDATE entities SET name = $2, updated_at = NOW() WHERE id = $1`
+	res, err := r.db.DB.ExecContext(ctx, q, entity.ID, entity.Name)
+	if err != nil {
+		return fmt.Errorf("update entity %s: %w", entity.ID, err)
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		return fmt.Errorf("update entity %s: %w", entity.ID, sql.ErrNoRows)
+	}
+	return nil
+}
+
+// Delete removes an entity by its ID.
+func (r *Repository) Delete(ctx context.Context, id string) error {
+	if _, err := r.db.DB.ExecContext(ctx, `DELETE FROM entities WHERE id = $1`, id); err != nil {
+		return fmt.Errorf("delete entity %s: %w", id, err)
+	}
+	return nil
+}
+
+<% if (messaging !== 'none') { %>
+// OutboxRepository implements service.OutboxRepository.
+type OutboxRepository struct {
+	db *DB
+}
+
+var _ service.OutboxRepository = (*OutboxRepository)(nil)
+
+// NewOutboxRepository creates a new outbox repository.
+func NewOutboxRepository(db *DB) *OutboxRepository {
+	return &OutboxRepository{db: db}
+}
+
+// InsertEvent saves a domain event to the outbox table within the caller's
+// transaction, so the event is committed atomically with the domain mutation.
+func (r *OutboxRepository) InsertEvent(ctx context.Context, tx service.Transaction, eventType string, payload []byte) error {
+	pgTx, ok := tx.(*Transaction)
+	if !ok || pgTx.tx == nil {
+		return fmt.Errorf("outbox InsertEvent requires a postgres transaction, got %T", tx)
+	}
+	const q = `INSERT INTO outbox_events (event_type, payload) VALUES ($1, $2::jsonb)`
+	if _, err := pgTx.tx.ExecContext(ctx, q, eventType, string(payload)); err != nil {
+		return fmt.Errorf("insert outbox event: %w", err)
+	}
+	return nil
+}
+
+// PollUnpublished fetches unpublished events from the outbox, oldest first.
+func (r *OutboxRepository) PollUnpublished(ctx context.Context, limit int) ([]service.OutboxEvent, error) {
+	const q = `SELECT id, event_type, payload, EXTRACT(EPOCH FROM created_at)::bigint
+		FROM outbox_events
+		WHERE published_at IS NULL
+		ORDER BY created_at
+		LIMIT $1`
+	rows, err := r.db.DB.QueryContext(ctx, q, limit)
+	if err != nil {
+		return nil, fmt.Errorf("poll outbox: %w", err)
+	}
+	defer rows.Close()
+
+	var events []service.OutboxEvent
+	for rows.Next() {
+		var e service.OutboxEvent
+		if err := rows.Scan(&e.ID, &e.EventType, &e.Payload, &e.CreatedAt); err != nil {
+			return nil, fmt.Errorf("scan outbox event: %w", err)
+		}
+		events = append(events, e)
+	}
+	return events, rows.Err()
+}
+
+// MarkPublished marks an outbox event as successfully published.
+func (r *OutboxRepository) MarkPublished(ctx context.Context, id string) error {
+	if _, err := r.db.DB.ExecContext(ctx,
+		`UPDATE outbox_events SET published_at = NOW() WHERE id = $1`, id); err != nil {
+		return fmt.Errorf("mark outbox event %s published: %w", id, err)
+	}
+	return nil
+}
+<% } %>