Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@ make demo
| Send event | `POST /v1/events` (header `X-Signature`, optional `X-Key-Id`) |
| Rotate HMAC | `POST /v1/hmac/rotate` (header `X-API-Key`; overlap for that brand only) |
| Read player | `GET /v1/players/{id}` (header `X-API-Key`) |
| List dead letters | `GET /v1/dlq` (header `X-API-Key`) |
| Tool call | `POST /v1/tools/{name}` (header `X-API-Key`; `ingest` also `X-Signature`) |
| Read player (gRPC) | `GetPlayer` (metadata `x-api-key`) |
| Health | `GET /healthz` |
Expand Down
8 changes: 6 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,9 @@ Code: `internal/store/outbox.go`, `internal/outbox/publisher.go`.

Local demos can turn on `FAIL_INJECT=true`. Then an event id that starts with `poison-` fails after mark, retries three times, and lands on `player.events.dlq`. Default ingest is unchanged. Leave this off on the public API.

Code: `internal/kafka/consumer.go`, `internal/kafka/dlq.go`.
`GET /v1/dlq` (API key) lists the last N dead letters for that brand. Redrive is a new signed `POST /v1/events` of the same `event_id` — not an admin credit. Arena’s Architecture page shows the list; a human has to click Redrive. The ledger unique key still blocks a second bonus.

Code: `internal/kafka/consumer.go`, `internal/kafka/dlq.go`, `internal/kafka/inspect.go`.

## Why bonus credits use a unique event id

Expand Down Expand Up @@ -143,6 +145,7 @@ Details: [concepts.md](./concepts.md). Code: `internal/rules`.
| `POST /v1/hmac/rotate` | Header `X-API-Key`. Overlap window for that brand only. Response has key ids, not secrets. |
| `POST /v1/tools/{name}` | Header `X-API-Key`; `ingest` also `X-Signature` of the event body |
| `GET /v1/players/{id}` | Header `X-API-Key` |
| `GET /v1/dlq` | Header `X-API-Key`; last N dead letters for that brand |
| gRPC `GetPlayer` | metadata `x-api-key` |

Unknown brand and bad signature both return **401** (same answer on purpose).
Expand All @@ -160,11 +163,12 @@ Useful coverage for this path:

- worker rollback if processing fails after the mark (`internal/worker`)
- bad HMAC / unknown tenant → 401, cross-tenant player read → 404 (`internal/api/httpapi`)
- last N DLQ inspect + signed redrive credit-once (`internal/kafka`, `internal/api/httpapi`)
- ledger credit-once under concurrent delivery (`internal/ledger`)

## Not in this project

- Game UI / website for players
- Real money payments
- Full fraud team tools for DLQ messages
- Auto-redrive of DLQ messages (inspect is read; redrive is a human click through HMAC ingest)
- Machine-learning “personal offers”
53 changes: 53 additions & 0 deletions internal/api/httpapi/dlq.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
package httpapi

import (
"context"
"encoding/json"
"net/http"
"strconv"
"time"

"github.com/o-mid/engagepulse/internal/kafka"
)

func (s *Server) handleListDLQ(w http.ResponseWriter, r *http.Request) {
tenant, ok := TenantFromContext(r.Context())
if !ok {
http.Error(w, "unauthorized", http.StatusUnauthorized)
return
}
n := 20
if q := r.URL.Query().Get("n"); q != "" {
parsed, err := strconv.Atoi(q)
if err == nil && parsed > 0 {
n = parsed
}
}
if n > 100 {
n = 100
}

items := []kafka.DeadLetter{}
if s.dlq != nil {
ctx, cancel := context.WithTimeout(r.Context(), 8*time.Second)
defer cancel()
all, err := s.dlq.Recent(ctx, 100)
if err != nil {
s.logger.Error("list dlq", "err", err)
writeError(w, http.StatusBadGateway, "dlq unavailable")
return
}
for _, dl := range all {
if dl.Event.TenantID != tenant.ID {
continue
}
items = append(items, dl)
if len(items) >= n {
break
}
}
}

w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(map[string]any{"items": items})
}
221 changes: 221 additions & 0 deletions internal/api/httpapi/dlq_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,221 @@
package httpapi_test

import (
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"log/slog"
"net/http"
"net/http/httptest"
"os"
"testing"
"time"

"github.com/o-mid/engagepulse/internal/api/httpapi"
"github.com/o-mid/engagepulse/internal/domain"
"github.com/o-mid/engagepulse/internal/ingest"
"github.com/o-mid/engagepulse/internal/kafka"
"github.com/o-mid/engagepulse/internal/store"
"github.com/o-mid/engagepulse/internal/worker"
)

type memDLQList struct {
items []kafka.DeadLetter
}

func (m memDLQList) Recent(_ context.Context, n int) ([]kafka.DeadLetter, error) {
if n > len(m.items) {
n = len(m.items)
}
return m.items[:n], nil
}

func TestListDLQRequiresAPIKey(t *testing.T) {
st, srv := newSecurityTestServer(t)
defer st.Close()
defer srv.Close()

resp, err := http.Get(srv.URL + "/v1/dlq")
if err != nil {
t.Fatalf("get: %v", err)
}
defer func() { _ = resp.Body.Close() }()
if resp.StatusCode != http.StatusUnauthorized {
t.Fatalf("status=%d want 401", resp.StatusCode)
}
}

func TestListDLQHidesOtherTenant(t *testing.T) {
st, api, srv := newDLQTestServer(t)
defer st.Close()
defer srv.Close()

suffix := fmt.Sprintf("%d", time.Now().UnixNano())
api.SetDLQ(memDLQList{items: []kafka.DeadLetter{
{
FailedAt: time.Now().UTC(),
Error: "injected",
Attempts: 3,
Event: domain.Event{
EventID: "acme-dlq-" + suffix,
TenantID: "acme-casino",
PlayerID: "p-acme",
Type: domain.EventDeposit,
Amount: 50,
},
},
{
FailedAt: time.Now().UTC(),
Error: "injected",
Attempts: 3,
Event: domain.Event{
EventID: "nova-dlq-" + suffix,
TenantID: "nova-sports",
PlayerID: "p-nova",
Type: domain.EventDeposit,
Amount: 50,
},
},
}})

req, err := http.NewRequest(http.MethodGet, srv.URL+"/v1/dlq?n=20", nil)
if err != nil {
t.Fatalf("request: %v", err)
}
req.Header.Set("X-API-Key", "ak_acme_dev_001")
resp, err := http.DefaultClient.Do(req)
if err != nil {
t.Fatalf("do: %v", err)
}
defer func() { _ = resp.Body.Close() }()
if resp.StatusCode != http.StatusOK {
body, _ := io.ReadAll(resp.Body)
t.Fatalf("status=%d body=%s", resp.StatusCode, body)
}
var out struct {
Items []kafka.DeadLetter `json:"items"`
}
if err = json.NewDecoder(resp.Body).Decode(&out); err != nil {
t.Fatalf("decode: %v", err)
}
if len(out.Items) != 1 || out.Items[0].Event.EventID != "acme-dlq-"+suffix {
t.Fatalf("items=%+v", out.Items)
}
}

func TestRedriveSignedIngestIsCreditOnce(t *testing.T) {
st, api, srv := newDLQTestServer(t)
defer st.Close()
defer srv.Close()

ctx := context.Background()
suffix := fmt.Sprintf("%d", time.Now().UnixNano())
playerID := "redrive-" + suffix
eventID := "redrive-evt-" + suffix
evt := domain.Event{
EventID: eventID,
TenantID: "acme-casino",
PlayerID: playerID,
Type: domain.EventDeposit,
Amount: 50,
OccurredAt: time.Now().UTC(),
}
api.SetDLQ(memDLQList{items: []kafka.DeadLetter{{
FailedAt: time.Now().UTC(),
Error: "injected",
Attempts: 3,
Event: evt,
}}})

req, err := http.NewRequest(http.MethodGet, srv.URL+"/v1/dlq", nil)
if err != nil {
t.Fatalf("request: %v", err)
}
req.Header.Set("X-API-Key", "ak_acme_dev_001")
resp, err := http.DefaultClient.Do(req)
if err != nil {
t.Fatalf("list: %v", err)
}
_ = resp.Body.Close()
if resp.StatusCode != http.StatusOK {
t.Fatalf("list status=%d", resp.StatusCode)
}

tenant, err := st.GetTenant(ctx, "acme-casino")
if err != nil {
t.Fatalf("tenant: %v", err)
}
w := worker.New(st, slog.New(slog.NewTextHandler(io.Discard, nil)))

status := postSignedEvent(t, srv.URL, tenant.HMACSecret, evt)
if status != http.StatusAccepted {
t.Fatalf("redrive status=%d", status)
}
if err = w.Handle(ctx, evt); err != nil {
t.Fatalf("handle: %v", err)
}
snap, err := st.GetPlayerSnapshot(ctx, "acme-casino", playerID)
if err != nil {
t.Fatalf("snapshot: %v", err)
}
if snap.Balance <= 0 {
t.Fatalf("first redrive balance=%d", snap.Balance)
}
first := snap.Balance

status = postSignedEvent(t, srv.URL, tenant.HMACSecret, evt)
if status != http.StatusAccepted {
t.Fatalf("second ingest status=%d", status)
}
if err = w.Handle(ctx, evt); err != nil {
t.Fatalf("handle again: %v", err)
}
snap, err = st.GetPlayerSnapshot(ctx, "acme-casino", playerID)
if err != nil {
t.Fatalf("snapshot: %v", err)
}
if snap.Balance != first {
t.Fatalf("second redrive balance=%d want %d", snap.Balance, first)
}
}

func newDLQTestServer(t *testing.T) (*store.Store, *httpapi.Server, *httptest.Server) {
t.Helper()
dsn := os.Getenv("DATABASE_URL")
if dsn == "" {
t.Skip("DATABASE_URL not set")
}
ctx := context.Background()
st, err := store.Open(ctx, dsn)
if err != nil {
t.Fatalf("open: %v", err)
}
if err = st.Migrate(ctx); err != nil {
st.Close()
t.Fatalf("migrate: %v", err)
}
api := httpapi.New(st, st, slog.New(slog.NewTextHandler(io.Discard, nil)))
return st, api, httptest.NewServer(api.Handler())
}

func postSignedEvent(t *testing.T, base, secret string, evt domain.Event) int {
t.Helper()
body, err := json.Marshal(evt)
if err != nil {
t.Fatalf("marshal: %v", err)
}
req, err := http.NewRequest(http.MethodPost, base+"/v1/events", bytes.NewReader(body))
if err != nil {
t.Fatalf("request: %v", err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Signature", ingest.Sign(secret, body))
resp, err := http.DefaultClient.Do(req)
if err != nil {
t.Fatalf("do: %v", err)
}
defer func() { _ = resp.Body.Close() }()
return resp.StatusCode
}
15 changes: 13 additions & 2 deletions internal/api/httpapi/server.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import (

"github.com/o-mid/engagepulse/internal/domain"
"github.com/o-mid/engagepulse/internal/ingest"
"github.com/o-mid/engagepulse/internal/kafka"
"github.com/o-mid/engagepulse/internal/metrics"
"github.com/o-mid/engagepulse/internal/store"
)
Expand All @@ -19,24 +20,34 @@ type EventAccepter interface {
EnqueueEvent(ctx context.Context, evt domain.Event) error
}

type DLQLister interface {
Recent(ctx context.Context, n int) ([]kafka.DeadLetter, error)
}

type Server struct {
store *store.Store
accept EventAccepter
dlq DLQLister
store *store.Store
logger *slog.Logger
mux *http.ServeMux
}

func New(st *store.Store, accept EventAccepter, logger *slog.Logger) *Server {
s := &Server{store: st, accept: accept, logger: logger, mux: http.NewServeMux()}
s := &Server{accept: accept, store: st, logger: logger, mux: http.NewServeMux()}
s.mux.HandleFunc("GET /healthz", s.handleHealth)
s.mux.Handle("GET /metrics", metrics.Handler())
s.mux.HandleFunc("POST /v1/events", s.handleIngest)
s.mux.HandleFunc("POST /v1/hmac/rotate", s.requireAPIKey(s.handleRotateHMAC))
s.mux.HandleFunc("POST /v1/tools/{name}", s.requireAPIKey(s.handleTool))
s.mux.HandleFunc("GET /v1/players/{id}", s.requireAPIKey(s.handleGetPlayer))
s.mux.HandleFunc("GET /v1/dlq", s.requireAPIKey(s.handleListDLQ))
return s
}

func (s *Server) SetDLQ(l DLQLister) {
s.dlq = l
}

func (s *Server) Handler() http.Handler {
return s.mux
}
Expand Down
1 change: 1 addition & 0 deletions internal/app/app.go
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@ func (a *App) Run(ctx context.Context) error {
defer func() { _ = consumer.Close() }()

api := httpapi.New(a.store, a.store, a.logger)
api.SetDLQ(kafka.NewInspector(a.cfg.KafkaBrokers, a.cfg.KafkaDLQTopic))
srv := &http.Server{
Addr: a.cfg.HTTPAddr,
Handler: api.Handler(),
Expand Down
Loading
Loading