From 8551782ffa26060b525af4dceea0d7b42373a4a4 Mon Sep 17 00:00:00 2001 From: Naheem Adisa Date: Sat, 17 Oct 2026 14:38:41 +0100 Subject: [PATCH 1/3] feat(broadcasts): add cancellation and rescheduling controls --- internal/api/analytics_handler.go | 3 +- internal/api/broadcast_control.go | 67 ++++ internal/api/broadcast_control_test.go | 152 ++++++++ internal/api/broadcast_handler.go | 2 +- internal/api/openapi.go | 151 +++++++- internal/api/openapi_test.go | 6 +- internal/api/routes.go | 2 + internal/broadcast/control_test.go | 112 ++++++ internal/broadcast/expander.go | 22 ++ internal/database/analytics.go | 17 +- internal/database/analytics_timezone_test.go | 46 +++ internal/database/broadcast_control.go | 114 ++++++ internal/database/broadcast_control_test.go | 333 ++++++++++++++++++ internal/database/broadcast_expansion.go | 52 ++- internal/database/broadcasts.go | 23 +- internal/database/messages.go | 18 +- .../000035_broadcast_control.down.sql | 5 + .../000035_broadcast_control.up.sql | 3 + 18 files changed, 1091 insertions(+), 37 deletions(-) create mode 100644 internal/api/broadcast_control.go create mode 100644 internal/api/broadcast_control_test.go create mode 100644 internal/broadcast/control_test.go create mode 100644 internal/database/analytics_timezone_test.go create mode 100644 internal/database/broadcast_control.go create mode 100644 internal/database/broadcast_control_test.go create mode 100644 internal/database/migrations/000035_broadcast_control.down.sql create mode 100644 internal/database/migrations/000035_broadcast_control.up.sql diff --git a/internal/api/analytics_handler.go b/internal/api/analytics_handler.go index 494b3d7..72f28de 100644 --- a/internal/api/analytics_handler.go +++ b/internal/api/analytics_handler.go @@ -162,6 +162,7 @@ type broadcastAnalyticsResponse struct { BroadcastID string `json:"broadcast_id"` Intended int `json:"intended"` Pending int `json:"pending"` + Cancelled int `json:"cancelled"` Suppressed int `json:"suppressed"` Materialized int `json:"materialized"` RecipientFailed int `json:"recipient_failed"` @@ -184,7 +185,7 @@ func (h *analyticsHandler) handleBroadcast(w http.ResponseWriter, r *http.Reques return } writeJSON(w, http.StatusOK, broadcastAnalyticsResponse{ - BroadcastID: a.BroadcastID, Intended: a.Intended, Pending: a.Pending, Suppressed: a.Suppressed, + BroadcastID: a.BroadcastID, Intended: a.Intended, Pending: a.Pending, Cancelled: a.Cancelled, Suppressed: a.Suppressed, Materialized: a.Materialized, RecipientFailed: a.RecipientFailed, Delivered: a.Delivered, Bounced: a.Bounced, Complained: a.Complained, Failed: a.Failed, }) diff --git a/internal/api/broadcast_control.go b/internal/api/broadcast_control.go new file mode 100644 index 0000000..b213c39 --- /dev/null +++ b/internal/api/broadcast_control.go @@ -0,0 +1,67 @@ +package api + +import ( + "encoding/json" + "errors" + "io" + "net/http" + + "github.com/Ferousco-dev/mailx/internal/database" +) + +func (h *broadcastHandler) handleCancel(w http.ResponseWriter, r *http.Request) { + b, err := h.db.CancelBroadcast(r.Context(), tenantFromContext(r.Context()), r.PathValue("id")) + if err != nil { + writeError(w, r, broadcastControlError(err)) + return + } + writeJSON(w, http.StatusOK, broadcastFromRow(b)) +} + +func (h *broadcastHandler) handleReschedule(w http.ResponseWriter, r *http.Request) { + if !acceptsJSONContentType(r.Header.Get("Content-Type")) { + writeError(w, r, newError(ErrUnsupportedMediaType, "unsupported_media_type", "Content-Type must be application/json")) + return + } + var req struct { + SendAt *string `json:"send_at"` + } + dec := json.NewDecoder(r.Body) + dec.DisallowUnknownFields() + if err := dec.Decode(&req); err != nil { + writeError(w, r, newError(ErrInvalidRequest, "malformed_json", "request body is not valid JSON")) + return + } + if err := dec.Decode(new(any)); err != io.EOF { + writeError(w, r, newError(ErrInvalidRequest, "malformed_json", "request body must contain one JSON object")) + return + } + if req.SendAt == nil { + writeError(w, r, newError(ErrValidation, "missing_send_at", "send_at is required")) + return + } + sendAt, aerr := parseSendAt(req.SendAt, h.now()) + if aerr != nil { + writeError(w, r, aerr) + return + } + b, err := h.db.RescheduleBroadcast(r.Context(), tenantFromContext(r.Context()), r.PathValue("id"), *sendAt) + if err != nil { + writeError(w, r, broadcastControlError(err)) + return + } + writeJSON(w, http.StatusOK, broadcastFromRow(b)) +} + +func broadcastControlError(err error) *apiError { + switch { + case errors.Is(err, database.ErrNotFound): + return newError(ErrNotFoundType, "broadcast_not_found", "no broadcast found with that id") + case errors.Is(err, database.ErrBroadcastStateConflict): + return newError(ErrConflictType, "broadcast_state_conflict", "the broadcast cannot be changed in its current state") + case errors.Is(err, database.ErrInvalidBroadcastSchedule): + return newError(ErrValidation, "invalid_send_at", "send_at must be in the future") + default: + return newError(ErrInternal, "internal_error", "failed to update broadcast") + } +} diff --git a/internal/api/broadcast_control_test.go b/internal/api/broadcast_control_test.go new file mode 100644 index 0000000..dbcc8dd --- /dev/null +++ b/internal/api/broadcast_control_test.go @@ -0,0 +1,152 @@ +package api + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + "testing" + "time" + + "github.com/Ferousco-dev/mailx/internal/auth" +) + +func TestBroadcastControlHTTPWorkflow(t *testing.T) { + a := newDKIMAPI(t) + f := setupBroadcastReady(t, a, "controls") + first := time.Now().UTC().Add(time.Hour).Format(time.RFC3339) + rec := doJSON(t, f.h, "POST", "/v1/broadcasts", f.body(map[string]any{"send_at": first})) + if rec.Code != http.StatusAccepted { + t.Fatalf("create: %d %s", rec.Code, rec.Body.String()) + } + b := decodeBroadcast(t, rec) + second := time.Now().UTC().Add(2 * time.Hour).Format(time.RFC3339) + rec = doJSON(t, f.h, "POST", "/v1/broadcasts/"+b.ID+"/reschedule", map[string]any{"send_at": second}) + if rec.Code != http.StatusOK { + t.Fatalf("reschedule: %d %s", rec.Code, rec.Body.String()) + } + changed := decodeBroadcast(t, rec) + if changed.Status != "accepted" || changed.SendAt == nil || changed.SendAt.UTC().Format(time.RFC3339) != second { + t.Fatalf("rescheduled resource: %+v", changed) + } + for i := 0; i < 2; i++ { + rec = doJSON(t, f.h, "POST", "/v1/broadcasts/"+b.ID+"/cancel", nil) + if rec.Code != http.StatusOK || decodeBroadcast(t, rec).Status != "cancelled" { + t.Fatalf("cancel: %d %s", rec.Code, rec.Body.String()) + } + } + rec = doJSON(t, f.h, "GET", "/v1/broadcasts/"+b.ID, nil) + if rec.Code != http.StatusOK || decodeBroadcast(t, rec).Status != "cancelled" { + t.Fatalf("persisted cancellation: %d %s", rec.Code, rec.Body.String()) + } + rec = doJSON(t, f.h, "POST", "/v1/broadcasts/"+b.ID+"/reschedule", map[string]any{"send_at": second}) + if rec.Code != http.StatusConflict || !strings.Contains(rec.Body.String(), "broadcast_state_conflict") { + t.Fatalf("rescheduled cancellation: %d %s", rec.Code, rec.Body.String()) + } +} + +func TestBroadcastControlHTTPAuthenticationAndIsolation(t *testing.T) { + a := newDKIMAPI(t) + f := setupBroadcastReady(t, a, "owner") + b := decodeBroadcast(t, doJSON(t, f.h, "POST", "/v1/broadcasts", f.body(nil))) + foreign, _ := a.scopedActor("foreign", auth.ScopeBroadcastsWrite) + readOnly, _ := a.scopedActor("reader", auth.ScopeBroadcastsRead) + for _, action := range []string{"cancel", "reschedule"} { + path := "/v1/broadcasts/" + b.ID + "/" + action + body := map[string]any{"send_at": time.Now().UTC().Add(time.Hour).Format(time.RFC3339)} + for _, c := range []struct { + h http.Handler + want int + }{{a.mux, http.StatusUnauthorized}, {foreign.h, http.StatusNotFound}, {readOnly.h, http.StatusForbidden}} { + rec := doJSON(t, c.h, "POST", path, body) + if rec.Code != c.want { + t.Fatalf("%s: want %d, got %d %s", action, c.want, rec.Code, rec.Body.String()) + } + } + } + if got := decodeBroadcast(t, doJSON(t, f.h, "GET", "/v1/broadcasts/"+b.ID, nil)); got.Status != "accepted" { + t.Fatalf("foreign request changed broadcast: %+v", got) + } +} + +func TestBroadcastRescheduleHTTPRejectsInvalidBodies(t *testing.T) { + a := newDKIMAPI(t) + f := setupBroadcastReady(t, a, "validation") + b := decodeBroadcast(t, doJSON(t, f.h, "POST", "/v1/broadcasts", f.body(nil))) + path := "/v1/broadcasts/" + b.ID + "/reschedule" + future := time.Now().UTC().Add(time.Hour).Format(time.RFC3339) + for _, c := range []struct { + body string + want int + }{ + {`{}`, 422}, {`null`, 422}, {`{"send_at":null}`, 422}, + {`{"send_at":"yesterday"}`, 422}, {`{"send_at":"2000-01-01T00:00:00Z"}`, 422}, + {`{"send_at":5}`, 400}, {`{"unknown":true}`, 400}, {`{`, 400}, + {`{"send_at":"` + future + `"} {}`, 400}, + } { + r := httptest.NewRequest("POST", path, strings.NewReader(c.body)) + r.Header.Set("Content-Type", "application/json") + rec := httptest.NewRecorder() + f.h.ServeHTTP(rec, r) + if rec.Code != c.want { + t.Fatalf("%s: want %d, got %d %s", c.body, c.want, rec.Code, rec.Body.String()) + } + } + r := httptest.NewRequest("POST", path, strings.NewReader(`{}`)) + r.Header.Set("Content-Type", "text/plain") + rec := httptest.NewRecorder() + f.h.ServeHTTP(rec, r) + if rec.Code != http.StatusUnsupportedMediaType { + t.Fatalf("content type: %d %s", rec.Code, rec.Body.String()) + } +} + +func TestBroadcastRescheduleHTTPConflictsOnceExpanding(t *testing.T) { + a := newDKIMAPI(t) + f := setupBroadcastReady(t, a, "active") + b := decodeBroadcast(t, doJSON(t, f.h, "POST", "/v1/broadcasts", f.body(nil))) + if err := a.db.MarkBroadcastExpanding(context.Background(), b.ID); err != nil { + t.Fatal(err) + } + rec := doJSON(t, f.h, "POST", "/v1/broadcasts/"+b.ID+"/reschedule", map[string]any{"send_at": time.Now().UTC().Add(time.Hour).Format(time.RFC3339)}) + if rec.Code != http.StatusConflict { + t.Fatalf("active reschedule: %d %s", rec.Code, rec.Body.String()) + } + rec = doJSON(t, f.h, "POST", "/v1/broadcasts/"+b.ID+"/cancel", nil) + if rec.Code != http.StatusOK || decodeBroadcast(t, rec).Status != "cancelled" { + t.Fatalf("active cancel: %d %s", rec.Code, rec.Body.String()) + } +} + +func TestBroadcastControlOpenAPIContract(t *testing.T) { + var doc map[string]any + if err := json.Unmarshal([]byte(openAPISpec), &doc); err != nil { + t.Fatal(err) + } + paths := doc["paths"].(map[string]any) + for _, action := range []string{"cancel", "reschedule"} { + path := "/broadcasts/{id}/" + action + item, ok := paths[path].(map[string]any) + if !ok { + t.Fatalf("missing path %s", path) + } + op := item["post"].(map[string]any) + for _, status := range []string{"200", "401", "403", "404", "409", "429", "500"} { + if _, ok := op["responses"].(map[string]any)[status]; !ok { + t.Errorf("%s missing response %s", path, status) + } + } + } + schemas := doc["components"].(map[string]any)["schemas"].(map[string]any) + for _, name := range []string{"Broadcast", "BroadcastRecipient"} { + status := schemas[name].(map[string]any)["properties"].(map[string]any)["status"].(map[string]any) + found := false + for _, v := range status["enum"].([]any) { + found = found || v == "cancelled" + } + if !found { + t.Errorf("%s missing cancelled status", name) + } + } +} diff --git a/internal/api/broadcast_handler.go b/internal/api/broadcast_handler.go index 5214185..6d79e09 100644 --- a/internal/api/broadcast_handler.go +++ b/internal/api/broadcast_handler.go @@ -42,7 +42,7 @@ type createBroadcastRequest struct { } // broadcastResource never claims delivery: status values are orchestration -// states (accepted/expanding/completed/failed), and "completed" means every +// states (accepted/expanding/completed/failed/cancelled), and "completed" means every // recipient was handed to the existing send pipeline or suppressed — never // that mail reached an inbox. type broadcastResource struct { diff --git a/internal/api/openapi.go b/internal/api/openapi.go index 7ea8d39..e7a31a3 100644 --- a/internal/api/openapi.go +++ b/internal/api/openapi.go @@ -847,7 +847,7 @@ const openAPISpec = `{ "/broadcasts/{id}": { "get": { "summary": "Get a broadcast", - "description": "Requires broadcasts:read. status is an orchestration state (accepted|expanding|completed|failed): 'completed' means every recipient was either suppressed or handed to the normal send pipeline - it does NOT mean delivered, and never means inbox placement. Another account's broadcast is indistinguishable from a missing one (404).", + "description": "Requires broadcasts:read. status is an orchestration state (accepted|expanding|completed|failed|cancelled): 'completed' means every recipient was either suppressed or handed to the normal send pipeline - it does NOT mean delivered, and never means inbox placement. Another account's broadcast is indistinguishable from a missing one (404).", "parameters": [ { "name": "id", @@ -885,10 +885,129 @@ const openAPISpec = `{ "operationId": "getBroadcastsId" } }, + "/broadcasts/{id}/cancel": { + "post": { + "summary": "Cancel a broadcast", + "description": "Requires broadcasts:write. Stops new recipient snapshots and message handoffs for an accepted or expanding broadcast. Already queued messages continue through the delivery pipeline and cannot be recalled. Cancellation waits for any database handoff already in progress. Repeating a successful cancellation returns the same cancelled broadcast. Completed or failed broadcasts return 409. Another account's broadcast returns 404.", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The updated broadcast", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Broadcast" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Error" + }, + "403": { + "$ref": "#/components/responses/Error" + }, + "404": { + "$ref": "#/components/responses/Error" + }, + "409": { + "$ref": "#/components/responses/Error" + }, + "429": { + "$ref": "#/components/responses/Error" + }, + "500": { + "$ref": "#/components/responses/Error" + } + }, + "tags": [ + "Broadcasts" + ], + "operationId": "cancelBroadcast" + } + }, + "/broadcasts/{id}/reschedule": { + "post": { + "summary": "Reschedule a broadcast", + "description": "Requires broadcasts:write. Changes send_at only while the broadcast is accepted and expansion has not started. The new timestamp must be in the future according to the database clock. Preserves the original audience and template snapshot boundaries. Expansion and rescheduling serialize on the broadcast row, so a stale poller cannot activate the old schedule. Expanding or terminal broadcasts return 409. Another account's broadcast returns 404.", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The updated broadcast", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Broadcast" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Error" + }, + "403": { + "$ref": "#/components/responses/Error" + }, + "404": { + "$ref": "#/components/responses/Error" + }, + "409": { + "$ref": "#/components/responses/Error" + }, + "429": { + "$ref": "#/components/responses/Error" + }, + "500": { + "$ref": "#/components/responses/Error" + }, + "400": { + "$ref": "#/components/responses/Error" + }, + "415": { + "$ref": "#/components/responses/Error" + }, + "422": { + "$ref": "#/components/responses/Error" + } + }, + "tags": [ + "Broadcasts" + ], + "operationId": "rescheduleBroadcast", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RescheduleBroadcastRequest" + } + } + } + } + } + }, "/broadcasts/{id}/recipients": { "get": { "summary": "List a broadcast's recipients", - "description": "Requires broadcasts:read. Keyset pagination (limit, cursor); the entire recipient set is never returned in one response, however large the audience was. message_id, once present, is a normal /v1/emails id - GET /v1/emails/{message_id} carries that recipient's actual delivery status.", + "description": "Requires broadcasts:read. Keyset pagination (limit, cursor); the entire recipient set is never returned in one response, however large the audience was. Recipients awaiting handoff in a cancelled broadcast report cancelled. Recipients already handed off still report materialized. A cancelled broadcast may have a partial snapshot; members not snapshotted have no recipient row. message_id, once present, is a normal /v1/emails id - GET /v1/emails/{message_id} carries that recipient's actual delivery status.", "parameters": [ { "name": "id", @@ -1063,7 +1182,7 @@ const openAPISpec = `{ "/analytics/broadcasts/{id}": { "get": { "summary": "Broadcast analytics", - "description": "Requires analytics:read. Recipient/orchestration counts come from the Broadcast's OWN durable snapshot (broadcast_recipients, frozen at acceptance - see v0.36) - never live Audience membership, which may have changed since. intended is the full snapshotted recipient count and is NOT a delivery guarantee: some may still be pending/suppressed/recipient_failed. delivered/bounced/complained/failed are the events-table breakdown for recipients that reached materialization, with the same semantics as the overview endpoint's fields. Another account's broadcast is indistinguishable from a missing one (404).", + "description": "Requires analytics:read. Recipient/orchestration counts come from the Broadcast's OWN durable snapshot (broadcast_recipients, frozen at acceptance - see v0.36) - never live Audience membership, which may have changed since. intended is the full snapshotted recipient count and is NOT a delivery guarantee: some may still be pending/suppressed/recipient_failed/cancelled. Cancellation counts only snapshotted recipients without a message handoff; unsnapshotted audience members are not included. delivered/bounced/complained/failed are the events-table breakdown for recipients that reached materialization, with the same semantics as the overview endpoint's fields. Another account's broadcast is indistinguishable from a missing one (404).", "parameters": [ { "name": "id", @@ -3484,7 +3603,8 @@ const openAPISpec = `{ "accepted", "expanding", "completed", - "failed" + "failed", + "cancelled" ] }, "send_at": { @@ -3503,6 +3623,20 @@ const openAPISpec = `{ } } }, + "RescheduleBroadcastRequest": { + "type": "object", + "required": [ + "send_at" + ], + "properties": { + "send_at": { + "type": "string", + "format": "date-time", + "description": "Required RFC 3339 absolute timestamp in the future. Null and missing values are rejected." + } + }, + "additionalProperties": false + }, "CreateBroadcastRequest": { "type": "object", "required": [ @@ -3540,7 +3674,7 @@ const openAPISpec = `{ "type": "string", "format": "date-time", "nullable": true, - "description": "v0.37: RFC 3339 absolute instant. Omit to expand immediately (unchanged v0.36 behavior). The Audience snapshot boundary is always acceptance time regardless of send_at - scheduling only delays WHEN expansion may begin, never which recipients are eligible. Suppression is still re-checked at expansion time, not frozen at creation. Part of the idempotency fingerprint: a retry with the same key but a different send_at is a 409 conflict, not a reschedule. Immutable after acceptance - there is no reschedule/cancel endpoint in v0.37." + "description": "v0.37: RFC 3339 absolute instant. Omit to expand immediately (unchanged v0.36 behavior). The Audience snapshot boundary is always acceptance time regardless of send_at - scheduling only delays WHEN expansion may begin, never which recipients are eligible. Suppression is still re-checked at expansion time, not frozen at creation. Part of the idempotency fingerprint: a retry with the same key but a different send_at is a 409 conflict, not a reschedule. Use POST /broadcasts/{id}/reschedule before expansion starts, or POST /broadcasts/{id}/cancel to stop further handoffs." } }, "additionalProperties": false @@ -3578,7 +3712,8 @@ const openAPISpec = `{ "pending", "suppressed", "materialized", - "failed" + "failed", + "cancelled" ] }, "message_id": { @@ -3740,6 +3875,10 @@ const openAPISpec = `{ "pending": { "type": "integer" }, + "cancelled": { + "type": "integer", + "description": "Snapshotted recipients stopped before message handoff. Already queued messages and unsnapshotted audience members are excluded." + }, "suppressed": { "type": "integer", "description": "Suppressed at broadcast-materialization time (recipient-level historical fact)." diff --git a/internal/api/openapi_test.go b/internal/api/openapi_test.go index b182a61..ac7aff5 100644 --- a/internal/api/openapi_test.go +++ b/internal/api/openapi_test.go @@ -22,7 +22,7 @@ func TestOpenAPISpecParses(t *testing.T) { "/events", "/webhooks", "/webhooks/{id}", "/webhooks/{id}/rotate-secret", "/webhooks/{id}/deliveries", "/templates", "/templates/{id}", "/contacts", "/contacts/{id}", "/audiences", "/audiences/{id}", "/audiences/{id}/contacts", "/audiences/{id}/contacts/{contact_id}", - "/broadcasts", "/broadcasts/{id}", "/broadcasts/{id}/recipients", + "/broadcasts", "/broadcasts/{id}", "/broadcasts/{id}/recipients", "/broadcasts/{id}/cancel", "/broadcasts/{id}/reschedule", } { if _, ok := paths[want]; !ok { t.Errorf("documented spec is missing path %q", want) @@ -36,7 +36,7 @@ func TestOpenAPISpecParses(t *testing.T) { "Template", "CreateTemplateRequest", "UpdateTemplateRequest", "TemplateList", "Contact", "CreateContactRequest", "UpdateContactRequest", "ContactList", "Audience", "CreateAudienceRequest", "UpdateAudienceRequest", "AudienceList", "AddMemberRequest", - "Broadcast", "CreateBroadcastRequest", "BroadcastList", "BroadcastRecipient", "BroadcastRecipientList", + "Broadcast", "CreateBroadcastRequest", "RescheduleBroadcastRequest", "BroadcastList", "BroadcastRecipient", "BroadcastRecipientList", } { if _, ok := schemas[want]; !ok { t.Errorf("documented spec is missing schema %q", want) @@ -93,6 +93,8 @@ func TestOpenAPIRoutesMatchRuntime(t *testing.T) { {"GET", "/v1/broadcasts"}, {"GET", "/v1/broadcasts/some-id"}, {"GET", "/v1/broadcasts/some-id/recipients"}, + {"POST", "/v1/broadcasts/some-id/cancel"}, + {"POST", "/v1/broadcasts/some-id/reschedule"}, {"POST", "/v1/audiences"}, {"GET", "/v1/audiences"}, {"GET", "/v1/audiences/some-id"}, diff --git a/internal/api/routes.go b/internal/api/routes.go index 91ac30b..ad99d38 100644 --- a/internal/api/routes.go +++ b/internal/api/routes.go @@ -95,6 +95,8 @@ func newMux(h *emailHandler, authSvc authService, readiness func() error, extras v1.HandleFunc("GET /v1/broadcasts", requireScope(auth.ScopeBroadcastsRead)(broadcasts.handleList)) v1.HandleFunc("GET /v1/broadcasts/{id}", requireScope(auth.ScopeBroadcastsRead)(broadcasts.handleGet)) v1.HandleFunc("GET /v1/broadcasts/{id}/recipients", requireScope(auth.ScopeBroadcastsRead)(broadcasts.handleListRecipients)) + v1.HandleFunc("POST /v1/broadcasts/{id}/cancel", requireScope(auth.ScopeBroadcastsWrite)(broadcasts.handleCancel)) + v1.HandleFunc("POST /v1/broadcasts/{id}/reschedule", requireScope(auth.ScopeBroadcastsWrite)(broadcasts.handleReschedule)) analytics := &analyticsHandler{db: h.db, now: func() time.Time { return time.Now().UTC() }} v1.HandleFunc("GET /v1/analytics/overview", requireScope(auth.ScopeAnalyticsRead)(analytics.handleOverview)) diff --git a/internal/broadcast/control_test.go b/internal/broadcast/control_test.go new file mode 100644 index 0000000..80ad0b9 --- /dev/null +++ b/internal/broadcast/control_test.go @@ -0,0 +1,112 @@ +package broadcast + +import ( + "context" + "errors" + "os" + "testing" + "time" + + "github.com/Ferousco-dev/mailx/internal/database" +) + +func TestCancelledBroadcastStalePollerDoesNotSnapshotOrQueue(t *testing.T) { + db := newTestDB(t) + e := newTestExpander(t, db) + ctx := context.Background() + tn, b := setupBroadcastReady(t, db, 3) + claimed, err := db.ClaimActiveBroadcasts(ctx, 10) + if err != nil || len(claimed) != 1 { + t.Fatalf("claim: %+v %v", claimed, err) + } + if _, err := db.CancelBroadcast(ctx, tn.ID, b.ID); err != nil { + t.Fatal(err) + } + e.process(ctx, claimed[0]) + runTicks(e, ctx, 3) + got, err := db.GetBroadcast(ctx, tn.ID, b.ID) + if err != nil || got.Status != "cancelled" { + t.Fatalf("stale poller resumed: %+v %v", got, err) + } + if rows, err := db.ListBroadcastRecipients(ctx, tn.ID, b.ID, 10, nil); err != nil || len(rows) != 0 { + t.Fatalf("cancelled audience was snapshotted: %+v %v", rows, err) + } +} + +func TestRescheduledBroadcastStalePollerDoesNotStartEarly(t *testing.T) { + db := newTestDB(t) + e := newTestExpander(t, db) + ctx := context.Background() + tn, b := setupBroadcastReady(t, db, 1) + if _, err := db.RescheduleBroadcast(ctx, tn.ID, b.ID, time.Now().Add(time.Hour)); err != nil { + t.Fatal(err) + } + e.process(ctx, b) + runTicks(e, ctx, 3) + got, err := db.GetBroadcast(ctx, tn.ID, b.ID) + if err != nil || got.Status != "accepted" || got.SnapshotComplete { + t.Fatalf("old schedule activated: %+v %v", got, err) + } +} + +func TestCancelledBroadcastClaimedRecipientsDoNotMaterialize(t *testing.T) { + db := newTestDB(t) + e := newTestExpander(t, db) + ctx := context.Background() + tn, b := setupBroadcastReady(t, db, 3) + if err := db.MarkBroadcastExpanding(ctx, b.ID); err != nil { + t.Fatal(err) + } + if _, _, err := db.SnapshotBroadcastBatch(ctx, b, 10); err != nil { + t.Fatal(err) + } + pending, err := db.ClaimPendingBroadcastRecipients(ctx, b.ID, 10) + if err != nil || len(pending) != 3 { + t.Fatalf("pending: %+v %v", pending, err) + } + if err := e.materializeOne(ctx, b, "example.com", pending[0]); err != nil { + t.Fatal(err) + } + if _, err := db.CancelBroadcast(ctx, tn.ID, b.ID); err != nil { + t.Fatal(err) + } + e.materializeBatch(ctx, b, "example.com", pending[1:]) + for _, r := range pending[1:] { + if _, err := db.GetMessage(ctx, tn.ID, r.ID); !errors.Is(err, database.ErrNotFound) { + t.Fatalf("cancelled message exists: %v", err) + } + if _, err := e.store.Load(r.ID); !errors.Is(err, os.ErrNotExist) { + t.Fatalf("cancelled raw file remains: %v", err) + } + } + if err := e.materializeOne(ctx, b, "example.com", pending[0]); err != nil { + t.Fatalf("replaying accepted recipient: %v", err) + } + if _, err := e.store.Load(pending[0].ID); err != nil { + t.Fatalf("cancellation removed already queued raw mail: %v", err) + } + stats, err := db.BroadcastAnalytics(ctx, tn.ID, b.ID) + if err != nil || stats.Materialized != 1 || stats.Cancelled != 2 || stats.Pending != 0 { + t.Fatalf("counts: %+v %v", stats, err) + } +} + +func TestCancelledBroadcastKeepsPartialSnapshotAndStopsNextBatch(t *testing.T) { + db := newTestDB(t) + e := newTestExpander(t, db) + ctx := context.Background() + tn, b := setupBroadcastReady(t, db, defaultSnapshotBatch+30) + e.tick(ctx) + before, err := db.BroadcastAnalytics(ctx, tn.ID, b.ID) + if err != nil || before.Intended != defaultSnapshotBatch || before.Materialized != defaultMaterializeBatch { + t.Fatalf("initial bounded tick: %+v %v", before, err) + } + if _, err := db.CancelBroadcast(ctx, tn.ID, b.ID); err != nil { + t.Fatal(err) + } + runTicks(e, ctx, 3) + stats, err := db.BroadcastAnalytics(ctx, tn.ID, b.ID) + if err != nil || stats.Intended != before.Intended || stats.Materialized != before.Materialized || stats.Pending != 0 || stats.Cancelled != defaultSnapshotBatch-defaultMaterializeBatch { + t.Fatalf("cancellation expanded the unsnapshotted audience or handed off more messages: %+v %v", stats, err) + } +} diff --git a/internal/broadcast/expander.go b/internal/broadcast/expander.go index 2c0a8a4..a12aca9 100644 --- a/internal/broadcast/expander.go +++ b/internal/broadcast/expander.go @@ -146,6 +146,9 @@ func (e *Expander) tick(ctx context.Context) { // audience — see docs/design-v0.36.md "no giant transaction". func (e *Expander) process(ctx context.Context, b database.Broadcast) { if err := e.db.MarkBroadcastExpanding(ctx, b.ID); err != nil { + if errors.Is(err, database.ErrBroadcastStateConflict) { + return + } e.onError(fmt.Errorf("broadcast %s: mark expanding: %w", b.ID, err)) return } @@ -153,6 +156,9 @@ func (e *Expander) process(ctx context.Context, b database.Broadcast) { if !b.SnapshotComplete { n, _, err := e.db.SnapshotBroadcastBatch(ctx, b, defaultSnapshotBatch) if err != nil { + if errors.Is(err, database.ErrBroadcastStateConflict) { + return + } e.onError(fmt.Errorf("broadcast %s: snapshot batch: %w", b.ID, err)) return } @@ -241,6 +247,9 @@ func (e *Expander) materializeBatch(ctx context.Context, b database.Broadcast, f } if err := e.materializeOne(ctx, b, fromDomain, r); err != nil { + if errors.Is(err, database.ErrBroadcastStateConflict) { + return + } e.onError(fmt.Errorf("broadcast recipient %s: materialize: %w", r.ID, err)) e.metrics.BroadcastExpansionBatch("materialize", "error") // Bounded retry, but ONLY for errDeterministic failures (render/ @@ -363,6 +372,19 @@ func (e *Expander) materializeOne(ctx context.Context, b database.Broadcast, fro SenderDomain: fromDomain, RequireBroadcastRecipientID: r.ID, }) + if errors.Is(err, database.ErrBroadcastStateConflict) { + var delErr error + for attempt := 0; attempt < 3; attempt++ { + if delErr = e.store.Delete(r.ID); delErr == nil { + break + } + time.Sleep(erasedCleanupRetryDelay) + } + if delErr != nil { + return fmt.Errorf("cancelled recipient disk cleanup: %w", delErr) + } + return err + } if errors.Is(err, database.ErrRecipientErased) { // The recipient was erased (GDPR gdpr-delete) between being claimed // above and this insert — the file just saved above is now for a diff --git a/internal/database/analytics.go b/internal/database/analytics.go index ce5c60f..258fd88 100644 --- a/internal/database/analytics.go +++ b/internal/database/analytics.go @@ -177,7 +177,7 @@ func (db *DB) AnalyticsTimeseries(ctx context.Context, tenantID string, from, to return nil, ErrTooManyBuckets } rows, err := db.pool.Query(ctx, ` - SELECT date_trunc($4, occurred_at) AS bucket,`+eventTypeCountColumns+` + SELECT date_trunc($4, occurred_at, 'UTC') AS bucket,`+eventTypeCountColumns+` FROM events WHERE tenant_id = $1 AND occurred_at >= $2 AND occurred_at < $3 GROUP BY bucket @@ -219,6 +219,7 @@ type BroadcastAnalytics struct { BroadcastID string Intended int // total snapshotted broadcast_recipients rows Pending int + Cancelled int Suppressed int // suppressed at broadcast-materialization time (recipient-level historical fact) Materialized int RecipientFailed int // broadcast_recipients.status = 'failed' (bounded-retry terminal, see migration 000021) @@ -245,13 +246,19 @@ func (db *DB) BroadcastAnalytics(ctx context.Context, tenantID, broadcastID stri err := db.pool.QueryRow(ctx, ` SELECT count(*) FILTER (WHERE status = 'pending'), + count(*) FILTER (WHERE status = 'cancelled'), count(*) FILTER (WHERE status = 'suppressed'), count(*) FILTER (WHERE status = 'materialized'), count(*) FILTER (WHERE status = 'failed'), count(*) - FROM broadcast_recipients WHERE broadcast_id = $1`, - broadcastID, - ).Scan(&out.Pending, &out.Suppressed, &out.Materialized, &out.RecipientFailed, &out.Intended) + FROM ( + SELECT `+broadcastRecipientEffectiveStatus+` AS status + FROM broadcast_recipients r JOIN broadcasts b ON b.id = r.broadcast_id AND b.tenant_id = r.tenant_id + LEFT JOIN messages m ON m.id = coalesce(r.message_id, r.id) AND m.tenant_id = r.tenant_id + WHERE r.broadcast_id = $1 AND r.tenant_id = $2 + ) recipients`, + broadcastID, tenantID, + ).Scan(&out.Pending, &out.Cancelled, &out.Suppressed, &out.Materialized, &out.RecipientFailed, &out.Intended) if err != nil { return BroadcastAnalytics{}, fmt.Errorf("database: broadcast recipient counts: %w", normalizeErr(err)) } @@ -263,7 +270,7 @@ func (db *DB) BroadcastAnalytics(ctx context.Context, tenantID, broadcastID stri count(*) FILTER (WHERE e.event_type = 'failed') FROM events e WHERE e.tenant_id = $1 AND e.message_id IN ( - SELECT message_id FROM broadcast_recipients WHERE broadcast_id = $2 AND message_id IS NOT NULL + SELECT coalesce(message_id, id) FROM broadcast_recipients WHERE broadcast_id = $2 AND tenant_id = $1 )`, tenantID, broadcastID, ).Scan(&out.Delivered, &out.Bounced, &out.Complained, &out.Failed) diff --git a/internal/database/analytics_timezone_test.go b/internal/database/analytics_timezone_test.go new file mode 100644 index 0000000..ccd2fad --- /dev/null +++ b/internal/database/analytics_timezone_test.go @@ -0,0 +1,46 @@ +package database + +import ( + "context" + "net/url" + "testing" + "time" +) + +func TestAnalyticsTimeseriesUsesUTCRegardlessOfDatabaseTimezone(t *testing.T) { + dsn, err := url.Parse(baseTestDSN(t)) + if err != nil { + t.Fatal(err) + } + query := dsn.Query() + query.Set("timezone", "Asia/Kathmandu") + dsn.RawQuery = query.Encode() + t.Setenv("MAILX_TEST_DATABASE_URL", dsn.String()) + db := newTestDB(t) + ctx := context.Background() + var timezone string + if err := db.pool.QueryRow(ctx, `SHOW timezone`).Scan(&timezone); err != nil || timezone != "Asia/Kathmandu" { + t.Fatalf("test timezone: %s %v", timezone, err) + } + tn := newTestTenant(t, db) + msg, err := db.InsertMessage(ctx, sampleNewMessage(t, tn.ID)) + if err != nil { + t.Fatal(err) + } + day := time.Date(2026, 6, 1, 0, 0, 0, 0, time.UTC) + insertEvent(t, db, tn.ID, msg.ID, EventQueued, day.Add(15*time.Minute)) + insertEvent(t, db, tn.ID, msg.ID, EventQueued, day.Add(20*time.Hour)) + for _, interval := range []string{"day", "hour"} { + buckets, err := db.AnalyticsTimeseries(ctx, tn.ID, day, day.Add(24*time.Hour), interval) + if err != nil { + t.Fatal(err) + } + if interval == "day" { + if len(buckets) != 1 || !buckets[0].Timestamp.Equal(day) || buckets[0].Counts.Queued != 2 { + t.Fatalf("day buckets follow local timezone: %+v", buckets) + } + } else if len(buckets) != 2 || !buckets[0].Timestamp.Equal(day) || !buckets[1].Timestamp.Equal(day.Add(20*time.Hour)) { + t.Fatalf("hour buckets follow local timezone: %+v", buckets) + } + } +} diff --git a/internal/database/broadcast_control.go b/internal/database/broadcast_control.go new file mode 100644 index 0000000..5b28dff --- /dev/null +++ b/internal/database/broadcast_control.go @@ -0,0 +1,114 @@ +package database + +import ( + "context" + "errors" + "fmt" + "time" + + "github.com/jackc/pgx/v5" +) + +var ErrBroadcastStateConflict = errors.New("database: broadcast cannot be changed in its current state") +var ErrInvalidBroadcastSchedule = errors.New("database: broadcast send_at must be in the future") + +func (db *DB) CancelBroadcast(ctx context.Context, tenantID, id string) (Broadcast, error) { + tx, b, err := db.lockBroadcast(ctx, tenantID, id) + if err != nil { + return Broadcast{}, err + } + defer func() { _ = tx.Rollback(ctx) }() + if b.Status == "cancelled" { + return b, nil + } + if b.Status != "accepted" && b.Status != "expanding" { + return Broadcast{}, ErrBroadcastStateConflict + } + b, err = scanBroadcast(tx.QueryRow(ctx, ` + UPDATE broadcasts SET status = 'cancelled', completed_at = clock_timestamp(), updated_at = clock_timestamp() + WHERE tenant_id = $1 AND id = $2 RETURNING `+broadcastColumns, tenantID, id)) + if err != nil { + return Broadcast{}, fmt.Errorf("database: cancel broadcast: %w", err) + } + if err := tx.Commit(ctx); err != nil { + return Broadcast{}, fmt.Errorf("database: commit broadcast cancellation: %w", normalizeErr(err)) + } + return b, nil +} + +func (db *DB) RescheduleBroadcast(ctx context.Context, tenantID, id string, sendAt time.Time) (Broadcast, error) { + tx, b, err := db.lockBroadcast(ctx, tenantID, id) + if err != nil { + return Broadcast{}, err + } + defer func() { _ = tx.Rollback(ctx) }() + if b.Status != "accepted" { + return Broadcast{}, ErrBroadcastStateConflict + } + b, err = scanBroadcast(tx.QueryRow(ctx, ` + UPDATE broadcasts SET send_at = $3, updated_at = clock_timestamp() + WHERE tenant_id = $1 AND id = $2 AND $3::timestamptz > clock_timestamp() + RETURNING `+broadcastColumns, tenantID, id, sendAt)) + if errors.Is(err, ErrNotFound) { + return Broadcast{}, ErrInvalidBroadcastSchedule + } + if err != nil { + return Broadcast{}, fmt.Errorf("database: reschedule broadcast: %w", err) + } + if err := tx.Commit(ctx); err != nil { + return Broadcast{}, fmt.Errorf("database: commit broadcast reschedule: %w", normalizeErr(err)) + } + return b, nil +} + +func (db *DB) lockBroadcast(ctx context.Context, tenantID, id string) (pgx.Tx, Broadcast, error) { + tx, err := db.pool.Begin(ctx) + if err != nil { + return nil, Broadcast{}, fmt.Errorf("database: begin broadcast change: %w", normalizeErr(err)) + } + b, err := scanBroadcast(tx.QueryRow(ctx, `SELECT `+broadcastColumns+` + FROM broadcasts WHERE tenant_id = $1 AND id = $2 FOR UPDATE`, tenantID, id)) + if err != nil { + _ = tx.Rollback(ctx) + return nil, Broadcast{}, fmt.Errorf("database: lock broadcast: %w", err) + } + return tx, b, nil +} + +func lockBroadcastRecipient(ctx context.Context, tx pgx.Tx, in NewMessage) error { + var broadcastID, broadcastStatus, recipientStatus string + var due bool + err := tx.QueryRow(ctx, `SELECT broadcast_id FROM broadcast_recipients + WHERE tenant_id = $1 AND id = $2`, in.TenantID, in.RequireBroadcastRecipientID).Scan(&broadcastID) + if errors.Is(normalizeErr(err), ErrNotFound) { + return ErrRecipientErased + } + if err != nil { + return fmt.Errorf("database: find broadcast recipient: %w", normalizeErr(err)) + } + err = tx.QueryRow(ctx, `SELECT status, send_at IS NULL OR send_at <= clock_timestamp() FROM broadcasts + WHERE tenant_id = $1 AND id = $2 FOR SHARE`, in.TenantID, broadcastID).Scan(&broadcastStatus, &due) + if err != nil { + return fmt.Errorf("database: lock recipient broadcast: %w", normalizeErr(err)) + } + err = tx.QueryRow(ctx, `SELECT status FROM broadcast_recipients + WHERE tenant_id = $1 AND id = $2 FOR UPDATE`, in.TenantID, in.RequireBroadcastRecipientID).Scan(&recipientStatus) + if errors.Is(normalizeErr(err), ErrNotFound) { + return ErrRecipientErased + } + if err != nil { + return fmt.Errorf("database: lock broadcast recipient: %w", normalizeErr(err)) + } + var materialized bool + if err := tx.QueryRow(ctx, `SELECT EXISTS (SELECT 1 FROM messages WHERE tenant_id = $1 AND id = $2)`, + in.TenantID, in.ID).Scan(&materialized); err != nil { + return fmt.Errorf("database: check materialized recipient: %w", normalizeErr(err)) + } + if materialized { + return ErrConflict + } + if (broadcastStatus != "accepted" && broadcastStatus != "expanding") || !due || recipientStatus != "pending" { + return ErrBroadcastStateConflict + } + return nil +} diff --git a/internal/database/broadcast_control_test.go b/internal/database/broadcast_control_test.go new file mode 100644 index 0000000..a0da399 --- /dev/null +++ b/internal/database/broadcast_control_test.go @@ -0,0 +1,333 @@ +package database + +import ( + "context" + "errors" + "fmt" + "testing" + "time" +) + +func controlBroadcast(t *testing.T, db *DB, count int) (Tenant, Broadcast, []BroadcastRecipient) { + t.Helper() + ctx := context.Background() + tn, aud, tmpl := setupAudienceFixture(t, db) + for i := 0; i < count; i++ { + c := mustContact(t, db, tn.ID, fmt.Sprintf("control%d@example.com", i)) + if err := db.AddAudienceMember(ctx, tn.ID, aud.ID, c.ID); err != nil { + t.Fatal(err) + } + } + b := createBroadcast(t, db, tn, aud, tmpl) + if err := db.MarkBroadcastExpanding(ctx, b.ID); err != nil { + t.Fatal(err) + } + if _, _, err := db.SnapshotBroadcastBatch(ctx, b, count+1); err != nil { + t.Fatal(err) + } + recipients, err := db.ListBroadcastRecipients(ctx, tn.ID, b.ID, count+1, nil) + if err != nil || len(recipients) != count { + t.Fatalf("recipients: %+v %v", recipients, err) + } + return tn, b, recipients +} + +func controlMessage(t *testing.T, tn Tenant, r BroadcastRecipient) NewMessage { + t.Helper() + in := sampleNewMessage(t, tn.ID) + in.ID = r.ID + in.RequireBroadcastRecipientID = r.ID + in.Recipients = []RecipientInput{{Address: "<" + r.Email + ">", HeaderKind: strPtr("to")}} + return in +} + +func TestBroadcastCancelStopsHandoffsAndPreservesQueuedMessages(t *testing.T) { + db := newTestDB(t) + ctx := context.Background() + tn, b, recipients := controlBroadcast(t, db, 3) + if _, err := db.InsertMessage(ctx, controlMessage(t, tn, recipients[0])); err != nil { + t.Fatal(err) + } + cancelled, err := db.CancelBroadcast(ctx, tn.ID, b.ID) + if err != nil || cancelled.Status != "cancelled" { + t.Fatalf("cancel: %+v %v", cancelled, err) + } + replay, err := db.CancelBroadcast(ctx, tn.ID, b.ID) + if err != nil || !replay.UpdatedAt.Equal(cancelled.UpdatedAt) { + t.Fatalf("repeat cancellation changed the result: %+v %v", replay, err) + } + for _, r := range recipients[1:] { + if _, err := db.InsertMessage(ctx, controlMessage(t, tn, r)); !errors.Is(err, ErrBroadcastStateConflict) { + t.Fatalf("late handoff: %v", err) + } + } + if _, err := db.InsertMessage(ctx, controlMessage(t, tn, recipients[0])); !errors.Is(err, ErrConflict) { + t.Fatalf("already queued message must remain an idempotent conflict: %v", err) + } + if _, _, err := db.SnapshotBroadcastBatch(ctx, b, 10); !errors.Is(err, ErrBroadcastStateConflict) { + t.Fatalf("stale snapshot: %v", err) + } + if claimed, err := db.ClaimPendingBroadcastRecipients(ctx, b.ID, 10); err != nil || len(claimed) != 0 { + t.Fatalf("cancelled broadcast claimed: %+v %v", claimed, err) + } + if done, err := db.TryCompleteBroadcast(ctx, b.ID); err != nil || done { + t.Fatalf("cancelled broadcast completed: %v %v", done, err) + } + listed, err := db.ListBroadcastRecipients(ctx, tn.ID, b.ID, 10, nil) + if err != nil { + t.Fatal(err) + } + if listed[0].Status != "materialized" || listed[0].MessageID == nil { + t.Fatalf("queued recipient lost: %+v", listed[0]) + } + for _, r := range listed[1:] { + if r.Status != "cancelled" || r.MessageID != nil { + t.Fatalf("unqueued recipient: %+v", r) + } + } + stats, err := db.BroadcastAnalytics(ctx, tn.ID, b.ID) + if err != nil || stats.Intended != 3 || stats.Materialized != 1 || stats.Cancelled != 2 || stats.Pending != 0 { + t.Fatalf("analytics: %+v %v", stats, err) + } + for _, table := range []string{"messages", "outbox", "events"} { + var count int + if err := db.pool.QueryRow(ctx, "SELECT count(*) FROM "+table+" WHERE tenant_id = $1", tn.ID).Scan(&count); err != nil || count != 1 { + t.Fatalf("%s: %d %v", table, count, err) + } + } +} + +func TestBroadcastControlTenantIsolationAndTerminalStates(t *testing.T) { + db := newTestDB(t) + ctx := context.Background() + tn, _, b := setupBroadcastFixture(t, db) + other := newTestTenant(t, db) + for _, id := range []string{b.ID, "missing"} { + if _, err := db.CancelBroadcast(ctx, other.ID, id); !errors.Is(err, ErrNotFound) { + t.Fatalf("foreign cancel: %v", err) + } + if _, err := db.RescheduleBroadcast(ctx, other.ID, id, time.Now().Add(time.Hour)); !errors.Is(err, ErrNotFound) { + t.Fatalf("foreign reschedule: %v", err) + } + } + for _, state := range []string{"completed", "failed"} { + if _, err := db.pool.Exec(ctx, `UPDATE broadcasts SET status = $2 WHERE id = $1`, b.ID, state); err != nil { + t.Fatal(err) + } + if _, err := db.CancelBroadcast(ctx, tn.ID, b.ID); !errors.Is(err, ErrBroadcastStateConflict) { + t.Fatalf("cancel %s: %v", state, err) + } + if _, err := db.RescheduleBroadcast(ctx, tn.ID, b.ID, time.Now().Add(time.Hour)); !errors.Is(err, ErrBroadcastStateConflict) { + t.Fatalf("reschedule %s: %v", state, err) + } + } +} + +func TestBroadcastRescheduleFencesStaleActivationAndKeepsSnapshots(t *testing.T) { + db := newTestDB(t) + ctx := context.Background() + tn, _, b := setupBroadcastFixture(t, db) + claimed, err := db.ClaimActiveBroadcasts(ctx, 10) + if err != nil || len(claimed) != 1 { + t.Fatalf("initial claim: %+v %v", claimed, err) + } + future := time.Now().UTC().Add(time.Hour).Truncate(time.Microsecond) + rescheduled, err := db.RescheduleBroadcast(ctx, tn.ID, b.ID, future) + if err != nil || rescheduled.SendAt == nil || !rescheduled.SendAt.Equal(future) { + t.Fatalf("reschedule: %+v %v", rescheduled, err) + } + if !rescheduled.AudienceSnapshotAt.Equal(b.AudienceSnapshotAt) || rescheduled.SubjectTemplate != b.SubjectTemplate { + t.Fatal("rescheduling changed the acceptance snapshots") + } + if err := db.MarkBroadcastExpanding(ctx, claimed[0].ID); !errors.Is(err, ErrBroadcastStateConflict) { + t.Fatalf("stale activation: %v", err) + } + if _, _, err := db.SnapshotBroadcastBatch(ctx, claimed[0], 10); !errors.Is(err, ErrBroadcastStateConflict) { + t.Fatalf("early snapshot: %v", err) + } + if due, err := db.ClaimActiveBroadcasts(ctx, 10); err != nil || len(due) != 0 { + t.Fatalf("future broadcast claimed: %+v %v", due, err) + } + if _, err := db.RescheduleBroadcast(ctx, tn.ID, b.ID, time.Now().Add(-time.Hour)); !errors.Is(err, ErrInvalidBroadcastSchedule) { + t.Fatalf("past schedule: %v", err) + } + if _, err := db.pool.Exec(ctx, `UPDATE broadcasts SET send_at = now() - interval '1 second' WHERE id = $1`, b.ID); err != nil { + t.Fatal(err) + } + if err := db.MarkBroadcastExpanding(ctx, b.ID); err != nil { + t.Fatal(err) + } + if _, err := db.RescheduleBroadcast(ctx, tn.ID, b.ID, future); !errors.Is(err, ErrBroadcastStateConflict) { + t.Fatalf("rescheduled after activation: %v", err) + } +} + +func waitForBlockedQuery(t *testing.T, db *DB, blocker int, query string) int { + t.Helper() + ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) + defer cancel() + for ctx.Err() == nil { + var pid int + err := db.pool.QueryRow(ctx, `SELECT pid FROM pg_stat_activity + WHERE $1 = ANY(pg_blocking_pids(pid)) AND strpos(query, $2) > 0 LIMIT 1`, blocker, query).Scan(&pid) + if err == nil { + return pid + } + if !errors.Is(normalizeErr(err), ErrNotFound) { + t.Fatal(err) + } + time.Sleep(5 * time.Millisecond) + } + t.Fatalf("query %q did not wait on transaction %d", query, blocker) + return 0 +} + +func TestBroadcastCancelWaitsForMessageHandoffCommit(t *testing.T) { + db := newTestDB(t) + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + tn, b, recipients := controlBroadcast(t, db, 2) + blocker, err := db.pool.Begin(ctx) + if err != nil { + t.Fatal(err) + } + defer func() { _ = blocker.Rollback(ctx) }() + var blockerPID int + if err := blocker.QueryRow(ctx, `SELECT pg_backend_pid()`).Scan(&blockerPID); err != nil { + t.Fatal(err) + } + if _, err := blocker.Exec(ctx, `SELECT 1 FROM broadcast_recipients WHERE id = $1 FOR UPDATE`, recipients[0].ID); err != nil { + t.Fatal(err) + } + in := controlMessage(t, tn, recipients[0]) + inserted := make(chan error, 1) + go func() { _, err := db.InsertMessage(ctx, in); inserted <- err }() + insertPID := waitForBlockedQuery(t, db, blockerPID, "SELECT status FROM broadcast_recipients") + cancelled := make(chan error, 1) + go func() { _, err := db.CancelBroadcast(ctx, tn.ID, b.ID); cancelled <- err }() + waitForBlockedQuery(t, db, insertPID, "FROM broadcasts") + if err := blocker.Commit(ctx); err != nil { + t.Fatal(err) + } + if err := <-inserted; err != nil { + t.Fatal(err) + } + if err := <-cancelled; err != nil { + t.Fatal(err) + } + if _, err := db.InsertMessage(ctx, controlMessage(t, tn, recipients[1])); !errors.Is(err, ErrBroadcastStateConflict) { + t.Fatalf("handoff after cancellation returned: %v", err) + } + stats, err := db.BroadcastAnalytics(ctx, tn.ID, b.ID) + if err != nil || stats.Materialized != 1 || stats.Cancelled != 1 { + t.Fatalf("post-race counts: %+v %v", stats, err) + } +} + +func TestBroadcastCancellationWinsBeforeBlockedMessageInsert(t *testing.T) { + db := newTestDB(t) + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + tn, b, recipients := controlBroadcast(t, db, 1) + tx, err := db.pool.Begin(ctx) + if err != nil { + t.Fatal(err) + } + defer func() { _ = tx.Rollback(ctx) }() + var pid int + if err := tx.QueryRow(ctx, `SELECT pg_backend_pid()`).Scan(&pid); err != nil { + t.Fatal(err) + } + if _, err := tx.Exec(ctx, `UPDATE broadcasts SET status = 'cancelled' WHERE id = $1`, b.ID); err != nil { + t.Fatal(err) + } + in := controlMessage(t, tn, recipients[0]) + done := make(chan error, 1) + go func() { _, err := db.InsertMessage(ctx, in); done <- err }() + waitForBlockedQuery(t, db, pid, "send_at IS NULL OR send_at <= clock_timestamp() FROM broadcasts") + if err := tx.Commit(ctx); err != nil { + t.Fatal(err) + } + if err := <-done; !errors.Is(err, ErrBroadcastStateConflict) { + t.Fatalf("insert ignored concurrent cancellation: %v", err) + } + if _, err := db.GetMessage(ctx, tn.ID, in.ID); !errors.Is(err, ErrNotFound) { + t.Fatalf("cancelled message exists: %v", err) + } +} + +func TestBroadcastCancelledLegacyHandoffIsReportedAsMaterialized(t *testing.T) { + db := newTestDB(t) + ctx := context.Background() + tn, b, recipients := controlBroadcast(t, db, 1) + in := controlMessage(t, tn, recipients[0]) + in.RequireBroadcastRecipientID = "" + if _, err := db.InsertMessage(ctx, in); err != nil { + t.Fatal(err) + } + if _, err := db.CancelBroadcast(ctx, tn.ID, b.ID); err != nil { + t.Fatal(err) + } + listed, err := db.ListBroadcastRecipients(ctx, tn.ID, b.ID, 10, nil) + if err != nil || len(listed) != 1 || listed[0].Status != "materialized" || listed[0].MessageID == nil { + t.Fatalf("legacy pending row with a committed message: %+v %v", listed, err) + } + stats, err := db.BroadcastAnalytics(ctx, tn.ID, b.ID) + if err != nil || stats.Materialized != 1 || stats.Cancelled != 0 { + t.Fatalf("legacy counts: %+v %v", stats, err) + } +} + +func TestBroadcastControlMigrationRollbackDoesNotReactivate(t *testing.T) { + db := newTestDB(t) + ctx := context.Background() + tn, _, b := setupBroadcastFixture(t, db) + if _, err := db.CancelBroadcast(ctx, tn.ID, b.ID); err != nil { + t.Fatal(err) + } + if err := db.MigrateDownOne(ctx); err != nil { + t.Fatal(err) + } + got, err := db.GetBroadcast(ctx, tn.ID, b.ID) + if err != nil || got.Status != "failed" || got.FailureReason != "cancelled" { + t.Fatalf("rollback lost cancellation: %+v %v", got, err) + } + if err := db.Migrate(ctx); err != nil { + t.Fatal(err) + } + if active, err := db.ClaimActiveBroadcasts(ctx, 10); err != nil || len(active) != 0 { + t.Fatalf("rollback reactivated broadcast: %+v %v", active, err) + } +} + +func TestBroadcastRescheduleWinsAgainstBlockedActivation(t *testing.T) { + db := newTestDB(t) + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + tn, _, b := setupBroadcastFixture(t, db) + tx, err := db.pool.Begin(ctx) + if err != nil { + t.Fatal(err) + } + defer func() { _ = tx.Rollback(ctx) }() + var pid int + if err := tx.QueryRow(ctx, `SELECT pg_backend_pid()`).Scan(&pid); err != nil { + t.Fatal(err) + } + if _, err := tx.Exec(ctx, `UPDATE broadcasts SET send_at = now() + interval '1 hour' WHERE id = $1 AND tenant_id = $2`, b.ID, tn.ID); err != nil { + t.Fatal(err) + } + done := make(chan error, 1) + go func() { done <- db.MarkBroadcastExpanding(ctx, b.ID) }() + waitForBlockedQuery(t, db, pid, "UPDATE broadcasts SET status = 'expanding'") + if err := tx.Commit(ctx); err != nil { + t.Fatal(err) + } + if err := <-done; !errors.Is(err, ErrBroadcastStateConflict) { + t.Fatalf("activation ignored concurrently changed schedule: %v", err) + } + got, err := db.GetBroadcast(ctx, tn.ID, b.ID) + if err != nil || got.Status != "accepted" { + t.Fatalf("rescheduled broadcast started: %+v %v", got, err) + } +} diff --git a/internal/database/broadcast_expansion.go b/internal/database/broadcast_expansion.go index c8fc98f..2b44412 100644 --- a/internal/database/broadcast_expansion.go +++ b/internal/database/broadcast_expansion.go @@ -43,12 +43,21 @@ func (db *DB) ClaimActiveBroadcasts(ctx context.Context, limit int) ([]Broadcast // MarkBroadcastExpanding transitions accepted -> expanding (idempotent: a // no-op if already expanding) and stamps started_at once. func (db *DB) MarkBroadcastExpanding(ctx context.Context, id string) error { - _, err := db.pool.Exec(ctx, ` + tag, err := db.pool.Exec(ctx, ` UPDATE broadcasts SET status = 'expanding', started_at = COALESCE(started_at, now()), updated_at = now() - WHERE id = $1 AND status = 'accepted'`, id) + WHERE id = $1 AND status = 'accepted' AND (send_at IS NULL OR send_at <= clock_timestamp())`, id) if err != nil { return fmt.Errorf("database: mark broadcast expanding: %w", normalizeErr(err)) } + if tag.RowsAffected() == 0 { + var status string + if err := db.pool.QueryRow(ctx, `SELECT status FROM broadcasts WHERE id = $1`, id).Scan(&status); err != nil { + return fmt.Errorf("database: check broadcast activation: %w", normalizeErr(err)) + } + if status != "expanding" { + return ErrBroadcastStateConflict + } + } return nil } @@ -91,11 +100,22 @@ func (db *DB) SnapshotBroadcastBatch(ctx context.Context, b Broadcast, batchSize var cursorAt *time.Time var cursorID *string + var status string + var snapshotComplete bool + var due bool if err := tx.QueryRow(ctx, ` - SELECT expansion_cursor_created_at, expansion_cursor_contact_id FROM broadcasts WHERE id = $1 FOR UPDATE`, - b.ID).Scan(&cursorAt, &cursorID); err != nil { + SELECT expansion_cursor_created_at, expansion_cursor_contact_id, status, snapshot_complete, + send_at IS NULL OR send_at <= clock_timestamp() + FROM broadcasts WHERE id = $1 AND tenant_id = $2 FOR UPDATE`, + b.ID, b.TenantID).Scan(&cursorAt, &cursorID, &status, &snapshotComplete, &due); err != nil { return 0, false, fmt.Errorf("database: lock broadcast: %w", normalizeErr(err)) } + if (status != "accepted" && status != "expanding") || !due { + return 0, false, ErrBroadcastStateConflict + } + if snapshotComplete { + return 0, true, nil + } rows, err := tx.Query(ctx, ` SELECT m.contact_id, m.created_at, c.email, c.name, c.attributes @@ -188,7 +208,21 @@ const recipientClaimLease = 5 * time.Minute // unavailable to other claimants for the lease duration even after the SQL // statement's own lock releases, covering the actual processing window. func (db *DB) ClaimPendingBroadcastRecipients(ctx context.Context, broadcastID string, limit int) ([]BroadcastRecipient, error) { - rows, err := db.pool.Query(ctx, ` + tx, err := db.pool.Begin(ctx) + if err != nil { + return nil, fmt.Errorf("database: begin recipient claim: %w", normalizeErr(err)) + } + defer func() { _ = tx.Rollback(ctx) }() + var status string + var due bool + if err := tx.QueryRow(ctx, `SELECT status, send_at IS NULL OR send_at <= clock_timestamp() + FROM broadcasts WHERE id = $1 FOR SHARE`, broadcastID).Scan(&status, &due); err != nil { + return nil, fmt.Errorf("database: lock claimed broadcast: %w", normalizeErr(err)) + } + if (status != "accepted" && status != "expanding") || !due { + return nil, nil + } + rows, err := tx.Query(ctx, ` UPDATE broadcast_recipients SET claimed_at = now() WHERE id IN ( SELECT id FROM broadcast_recipients @@ -211,7 +245,13 @@ func (db *DB) ClaimPendingBroadcastRecipients(ctx context.Context, broadcastID s } out = append(out, r) } - return out, rows.Err() + if err := rows.Err(); err != nil { + return nil, err + } + if err := tx.Commit(ctx); err != nil { + return nil, fmt.Errorf("database: commit recipient claim: %w", normalizeErr(err)) + } + return out, nil } // maxRecipientAttempts bounds retries of a deterministically-failing diff --git a/internal/database/broadcasts.go b/internal/database/broadcasts.go index f0bd4da..d1496c9 100644 --- a/internal/database/broadcasts.go +++ b/internal/database/broadcasts.go @@ -22,7 +22,7 @@ type Broadcast struct { TextTemplate string HTMLTemplate string Variables map[string]string - Status string // accepted | expanding | completed | failed + Status string // accepted | expanding | completed | failed | cancelled FailureReason string // SendAt is nil for immediate (unchanged v0.36 behavior) or the instant // below which expansion must never start (v0.37). It never affects @@ -67,7 +67,7 @@ type BroadcastRecipient struct { Email string Name string Attributes map[string]string - Status string // pending | suppressed | materialized | failed + Status string // pending | suppressed | materialized | failed | cancelled MessageID *string Attempts int CreatedAt time.Time @@ -214,6 +214,11 @@ func scanBroadcastRecipient(row rowScanner) (BroadcastRecipient, error) { const broadcastRecipientColumns = `id, broadcast_id, contact_id, email, name, attributes, status, message_id, attempts, created_at` +const broadcastRecipientEffectiveStatus = `CASE + WHEN r.status = 'pending' AND m.id IS NOT NULL THEN 'materialized' + WHEN r.status = 'pending' AND b.status = 'cancelled' THEN 'cancelled' + ELSE r.status END` + // ListBroadcastRecipients is tenant-scoped via the broadcast row itself // (confirmed first, so an unknown/foreign broadcast id is ErrNotFound, not a // silently empty page) and keyset-paginated — never returns the whole set. @@ -230,12 +235,14 @@ func (db *DB) ListBroadcastRecipients(ctx context.Context, tenantID, broadcastID if after != nil { afterTime, afterID = &after.CreatedAt, &after.ID } - rows, err := db.pool.Query(ctx, `SELECT `+broadcastRecipientColumns+` - FROM broadcast_recipients - WHERE broadcast_id = $1 - AND ($2::timestamptz IS NULL OR (created_at, id) > ($2, $3)) - ORDER BY created_at, id - LIMIT $4`, broadcastID, afterTime, afterID, limit) + rows, err := db.pool.Query(ctx, `SELECT r.id, r.broadcast_id, r.contact_id, r.email, r.name, r.attributes, + `+broadcastRecipientEffectiveStatus+`, coalesce(r.message_id, m.id), r.attempts, r.created_at + FROM broadcast_recipients r JOIN broadcasts b ON b.id = r.broadcast_id AND b.tenant_id = r.tenant_id + LEFT JOIN messages m ON m.id = coalesce(r.message_id, r.id) AND m.tenant_id = r.tenant_id + WHERE r.broadcast_id = $1 AND r.tenant_id = $5 + AND ($2::timestamptz IS NULL OR (r.created_at, r.id) > ($2, $3)) + ORDER BY r.created_at, r.id + LIMIT $4`, broadcastID, afterTime, afterID, limit, tenantID) if err != nil { return nil, fmt.Errorf("database: list broadcast recipients: %w", normalizeErr(err)) } diff --git a/internal/database/messages.go b/internal/database/messages.go index 633fc78..53fabae 100644 --- a/internal/database/messages.go +++ b/internal/database/messages.go @@ -173,14 +173,8 @@ func (db *DB) InsertMessage(ctx context.Context, in NewMessage) (Message, error) defer func() { _ = tx.Rollback(ctx) }() if in.RequireBroadcastRecipientID != "" { - var exists int - err := tx.QueryRow(ctx, `SELECT 1 FROM broadcast_recipients WHERE id = $1 FOR UPDATE`, - in.RequireBroadcastRecipientID).Scan(&exists) - if errors.Is(normalizeErr(err), ErrNotFound) { - return Message{}, ErrRecipientErased - } - if err != nil { - return Message{}, fmt.Errorf("database: check broadcast recipient still exists: %w", normalizeErr(err)) + if err := lockBroadcastRecipient(ctx, tx, in); err != nil { + return Message{}, err } } @@ -289,6 +283,14 @@ func (db *DB) InsertMessage(ctx context.Context, in NewMessage) (Message, error) return Message{}, fmt.Errorf("database: insert outbox row: %w", normalizeErr(err)) } + if in.RequireBroadcastRecipientID != "" { + if _, err := tx.Exec(ctx, `UPDATE broadcast_recipients + SET status = 'materialized', message_id = $2, updated_at = now() + WHERE tenant_id = $1 AND id = $3`, in.TenantID, msg.ID, in.RequireBroadcastRecipientID); err != nil { + return Message{}, fmt.Errorf("database: mark inserted broadcast recipient: %w", normalizeErr(err)) + } + } + if in.IdempotencyCompletion != nil { ic := in.IdempotencyCompletion tag, err := tx.Exec(ctx, ` diff --git a/internal/database/migrations/000035_broadcast_control.down.sql b/internal/database/migrations/000035_broadcast_control.down.sql new file mode 100644 index 0000000..a49d5f3 --- /dev/null +++ b/internal/database/migrations/000035_broadcast_control.down.sql @@ -0,0 +1,5 @@ +UPDATE broadcasts SET status = 'failed', failure_reason = 'cancelled' + WHERE status = 'cancelled'; +ALTER TABLE broadcasts DROP CONSTRAINT broadcasts_status_check; +ALTER TABLE broadcasts ADD CONSTRAINT broadcasts_status_check + CHECK (status IN ('accepted','expanding','completed','failed')); diff --git a/internal/database/migrations/000035_broadcast_control.up.sql b/internal/database/migrations/000035_broadcast_control.up.sql new file mode 100644 index 0000000..23644d8 --- /dev/null +++ b/internal/database/migrations/000035_broadcast_control.up.sql @@ -0,0 +1,3 @@ +ALTER TABLE broadcasts DROP CONSTRAINT broadcasts_status_check; +ALTER TABLE broadcasts ADD CONSTRAINT broadcasts_status_check + CHECK (status IN ('accepted','expanding','completed','failed','cancelled')); From ddd8fb6145c540185c3525f8894c400638b048da Mon Sep 17 00:00:00 2001 From: Naheem Adisa Date: Sat, 17 Oct 2026 14:38:51 +0100 Subject: [PATCH 2/3] docs: rewrite README with architecture and setup guidance --- README.md | 399 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 237 insertions(+), 162 deletions(-) diff --git a/README.md b/README.md index faece2e..389d774 100644 --- a/README.md +++ b/README.md @@ -1,263 +1,338 @@
- MailX - developer-first email infrastructure built in Go + MailX -
- - Go CI status - Security workflow status - Go version - MIT license - Active development +

+ Go CI + Security checks + Go version + MIT license +

- Overview · Quick start · - API · + Send an email · Architecture · + Broadcasts · Development

-## Overview +MailX is open-source email infrastructure written in Go. Submit mail through a tenant-scoped REST API or authenticated SMTP submission, send directly to recipient mail servers or through a trusted relay, and follow each message through signed webhooks. -MailX is open-source, developer-first email infrastructure built from the protocol up in Go. It accepts mail over SMTP or a tenant-scoped REST API, stores the source message, processes delivery through a durable PostgreSQL and Redis pipeline, and exposes lifecycle events through signed webhooks. - -The project is intentionally built as understandable infrastructure rather than a wrapper around a third-party email provider. Its design keeps durable lifecycle state in PostgreSQL, raw message data in local storage, and transient delivery scheduling in Redis. +PostgreSQL records delivery history. Redis schedules work, and local storage keeps the MIME message. The protocol, queue and delivery code live in this repository. > [!WARNING] -> MailX is under active development and is not production-ready. +> MailX is under active development and is not production-ready. The supplied stack is for local development. Keep the unauthenticated SMTP receiver and operator endpoints off untrusted networks. ## Capabilities -| | Capability | What MailX provides | -| --- | --- | --- | -| | SMTP engine | Bounded command and message handling, CRLF validation, dot-stuffing, recipient and connection limits, enhanced status codes, and graceful shutdown. | -| | MIME and storage | Plain text, HTML, nested multipart parsing, transfer decoding, attachment extraction, raw `.eml` preservation, and local message inspection. | -| | Developer API | Tenant-scoped email, domain, event, and webhook resources with API-key scopes, pagination, request IDs, OpenAPI documentation, and HTTP idempotency. | -| | Durable processing | PostgreSQL outbox state, a Redis-backed leased queue, bounded workers, persistent delivery attempts, retries, and crash recovery. | -| | Mail delivery | DNS MX resolution, direct SMTP transfer, retry classification and scheduling, terminal outcomes, and safe bounce/DSN generation. | -| | Events and webhooks | Immutable lifecycle events, durable fan-out, HMAC-SHA256 signatures, retries, secret rotation, tenant isolation, and delivery inspection. | +| Area | Included | +| --- | --- | +| Sending | Plain text and HTML, templates, scheduled emails, batch submission, direct MX delivery and authenticated relay delivery | +| Campaigns | Contacts, audiences, personalized broadcasts, scheduling, rescheduling before expansion and cancellation of further message handoffs | +| Delivery safety | Verified sender domains, DKIM signing, recipient suppression, tenant limits, bounded workers and durable retry history | +| Transport | Verified outbound STARTTLS and optional SMTP submission over implicit TLS with API-key authentication | +| Events | Immutable email events, signed webhooks, retry history and webhook secret rotation | +| Visibility | Delivery analytics, optional open/click tracking, structured logs, Prometheus metrics and health checks | +| Accounts | Human accounts, organizations, invitations, scoped API keys, optional OAuth and TOTP MFA, and optional Paystack billing | +| Operations | Sending pools, DNS readiness checks for SPF/DMARC/BIMI, retention controls and operator GDPR export/delete tools | ## Quick start -### Requirements - -- Docker Engine with Docker Compose v2 -- `curl` for the API example -- Go 1.27.1 only when building or testing outside Docker - -### Run the complete local stack - -1. Clone the repository and enter it. - - ```bash - git clone https://github.com/Ferousco-dev/Mailx.git - cd Mailx - ``` +You need Docker Engine with Compose v2 and `curl`. Building outside Docker requires Go 1.27.1 or newer. -2. Create a local environment file. +### Start the local stack - ```bash - cp .env.example .env - ``` - - The checked-in defaults are for local development only. Never reuse them in a real deployment. - -3. Build and start MailX, PostgreSQL, Redis, and the database migration job. - - ```bash - docker compose up --build -d - docker compose ps - ``` - -4. Confirm the API is available. - - ```bash - curl --fail http://localhost:8080/health/live - curl --fail http://localhost:8080/health/ready - ``` +```bash +git clone https://github.com/Ferousco-dev/Mailx.git +cd Mailx +cp .env.example .env +docker compose up --build -d +docker compose ps +``` -The local services are available at: +Compose starts PostgreSQL, Redis, a migration job and MailX. It publishes the following ports on loopback only: -| Service | Address | +| Service | Local address | | --- | --- | | REST API | `http://localhost:8080` | -| Interactive API documentation | `http://localhost:8080/docs` | +| Interactive API docs | `http://localhost:8080/docs` | | OpenAPI contract | `http://localhost:8080/openapi.json` | -| SMTP receiver | `localhost:2525` | +| SMTP capture receiver | `localhost:2525` | +| Operator metrics and health | `http://localhost:9090` | | PostgreSQL | `localhost:5432` | | Redis | `localhost:6379` | -View logs or stop the stack with: +Check that MailX can reach its dependencies: + +```bash +curl --fail http://localhost:8080/health/live +curl --fail http://localhost:8080/health/ready +``` + +Liveness reports whether the process is running. Readiness requires PostgreSQL and Redis; an unavailable dependency returns `503` with its name. + +
+Logs, shutdown and smaller hosts ```bash docker compose logs -f mailx docker compose down ``` -Use `docker compose down -v` only when you intentionally want to delete all local MailX, PostgreSQL, and Redis data. +`docker compose down` preserves the named volumes. Adding `-v` deletes the stored messages, database and queue data. -### Small hosts (about 1 GB RAM) - -An opt-in low-memory PostgreSQL profile is available for small deployments. It is not the default and it keeps PostgreSQL's durability settings on: +For hosts with about 1 GB RAM, use the optional PostgreSQL profile: ```bash docker compose -f compose.yaml -f compose.low-memory.yaml up -d ``` -See `docs/low-memory-deployment.md` for what it changes, the measured effect and the trade-offs. +The profile keeps durability enabled. See the [deployment guide](./docs/low-memory-deployment.md) for its settings and trade-offs. A separate [DNS override](./compose.dns-workaround.yaml) is available for environments that need it. -## Client libraries +
-Official SDKs live in their own repos under the [UseMailx](https://github.com/UseMailx) organization, not in this one — a self-hosted server checkout doesn't need client-side code in five languages sitting in it. Each SDK defaults to the hosted API's base URL but takes an override, so the same client code works against a self-hosted deployment. +## Send your first email -| Language | Repo | -| --- | --- | -| Node.js / TypeScript | [UseMailx/mailx-node](https://github.com/UseMailx/mailx-node) | -| Python | [UseMailx/mailx-python](https://github.com/UseMailx/mailx-python) | -| Go | [UseMailx/mailx-go](https://github.com/UseMailx/mailx-go) | -| PHP | [UseMailx/mailx-php](https://github.com/UseMailx/mailx-php) | -| Ruby | [UseMailx/mailx-ruby](https://github.com/UseMailx/mailx-ruby) | +The sender's domain must belong to your tenant and pass DNS ownership verification. Create the tenant and API key first, then verify the domain before submitting mail. -## API example +### 1. Create a tenant and API key -Every `/v1` endpoint requires a scoped MailX API key. Tenant and key management are deliberately operator-only CLI operations. +```bash +docker compose exec mailx /app/mailx create-tenant -name local-development +``` -1. Create a tenant. +Use the printed `tenant_id` in the next command: - ```bash - docker compose exec mailx /app/mailx create-tenant -name local-development - ``` +```bash +docker compose exec mailx /app/mailx create-api-key \ + -tenant TENANT-ID \ + -name local-client \ + -scopes emails:send,emails:read,domains:read,domains:write,webhooks:read +``` -2. Create a key using the `tenant_id` printed by the previous command. +Save the printed `key`. MailX displays the raw key once. - ```bash - docker compose exec mailx /app/mailx create-api-key \ - -tenant TENANT-ID \ - -name local-client \ - -scopes emails:send,emails:read,domains:read,domains:write,webhooks:read,webhooks:write - ``` +```bash +export MAILX_API_KEY='PASTE-THE-KEY-HERE' +export MAILX_DOMAIN='your-domain.example' +``` - Save the printed `key` immediately. MailX displays the raw key only once. +Replace `your-domain.example` with a public domain you own. The values above are placeholders. -3. Submit an email using that key. +### 2. Verify your sending domain - ```bash - export MAILX_API_KEY='PASTE-THE-KEY-HERE' +```bash +curl --fail-with-body --request POST http://localhost:8080/v1/domains \ + --header "Authorization: Bearer ${MAILX_API_KEY}" \ + --header 'Content-Type: application/json' \ + --data "{\"name\":\"${MAILX_DOMAIN}\"}" +``` - curl --request POST http://localhost:8080/v1/emails \ - --header "Authorization: Bearer ${MAILX_API_KEY}" \ - --header 'Content-Type: application/json' \ - --header 'Idempotency-Key: local-example-001' \ - --data '{ - "from": "sender@example.com", - "to": ["recipient@example.net"], - "subject": "Hello from MailX", - "text": "MailX accepted this message for asynchronous delivery." - }' - ``` +Publish the TXT record returned in `records` at your DNS provider. Set `MAILX_DOMAIN_ID` to the response's `id`, then verify it after DNS has propagated: -An HTTP `202 Accepted` response means MailX durably recorded responsibility for the message. It does not mean that a remote SMTP server accepted the message or that it reached an inbox. Use `GET /v1/emails/{id}` and `GET /v1/events` to inspect durable lifecycle state. +```bash +export MAILX_DOMAIN_ID='DOMAIN-ID' -For the complete API, including domains, webhooks, pagination, scopes, and error schemas, open the [interactive documentation](http://localhost:8080/docs) after starting MailX. +curl --fail-with-body --request POST \ + "http://localhost:8080/v1/domains/${MAILX_DOMAIN_ID}/verify" \ + --header "Authorization: Bearer ${MAILX_API_KEY}" +``` -## Architecture +Continue once `ownership_state` is `verified`. Sending before verification returns `403 from_domain_not_authorized`. Ownership verification is separate from publishing DKIM, SPF and DMARC records. -
- MailX architecture: SMTP and HTTP inputs flow through durable PostgreSQL state, local message storage, Redis scheduling, delivery workers, SMTP transfer, lifecycle events, and signed webhooks -
+### 3. Submit the message -MailX separates durable truth from scheduling: +Set `MAILX_RECIPIENT` to an address you control: -- **PostgreSQL** owns tenants, API keys, email lifecycle state, delivery attempts, domains, idempotency records, immutable events, and webhook deliveries. -- **Local file storage** preserves raw messages and extracted attachment data. -- **Redis** coordinates available and leased jobs; it is not the authoritative delivery-history store. -- **Workers** persist delivery outcomes before acknowledging or releasing queue jobs. -- **Webhooks** observe immutable events and never change email delivery state. +```bash +export MAILX_RECIPIENT='recipient@example.net' -This architecture provides at-least-once processing. MailX does not claim exactly-once SMTP delivery: a crash after remote acceptance but before local outcome persistence is inherently ambiguous. +curl --fail-with-body --request POST http://localhost:8080/v1/emails \ + --header "Authorization: Bearer ${MAILX_API_KEY}" \ + --header 'Content-Type: application/json' \ + --header 'Idempotency-Key: local-example-001' \ + --data "{\"from\":\"sender@${MAILX_DOMAIN}\",\"to\":[\"${MAILX_RECIPIENT}\"],\"subject\":\"Hello from MailX\",\"text\":\"This message was submitted through MailX.\"}" +``` -## Configuration +`202 Accepted` means MailX committed the message and its delivery work to PostgreSQL. The worker sends it asynchronously. Use the returned email `id` to check progress: -The complete development configuration is documented in [`.env.example`](./.env.example). The main runtime settings are: +```bash +curl --fail-with-body "http://localhost:8080/v1/emails/EMAIL-ID" \ + --header "Authorization: Bearer ${MAILX_API_KEY}" -| Variable | Purpose | Local default | -| --- | --- | --- | -| `DATABASE_URL` | PostgreSQL connection string; enables the full API, queue, worker, and webhook runtime | Set by Compose | -| `REDIS_ADDR` | Redis queue address | `localhost:6379` outside Compose | -| `MAILX_HTTP_ADDR` | HTTP API listener | `:8080` | -| `MAILX_SMTP_ADDR` | SMTP listener | `:2525` | -| `MAILX_STORAGE_ROOT` | Raw message and attachment storage directory | MailX storage default | -| `MAILX_API_KEY_PEPPER` | Optional HMAC pepper for stored API-key verifiers | Development-only value in Compose | -| `MAILX_WEBHOOK_MASTER_KEY` | Base64-encoded 32-byte key used to protect webhook secrets | Development-only value in Compose | -| `MAILX_WEBHOOK_ALLOW_INSECURE` | Allows HTTP/private webhook targets for local development | `true` in Compose | -| `MAILX_WEBHOOK_WORKERS` | Number of webhook delivery workers | `4` | +curl --fail-with-body http://localhost:8080/v1/events \ + --header "Authorization: Bearer ${MAILX_API_KEY}" +``` -Do not commit a real `.env` file. Use distinct random secrets and restricted network bindings outside local development. +`delivered` means the remote SMTP server accepted the message. Inbox placement depends on the receiver. -### SMTP-only mode +Each email's To, Cc and Bcc recipients must share one destination domain. Use separate messages or a broadcast to reach recipients across domains. -When `DATABASE_URL` is unset, running MailX starts the original SMTP receiver and local file store without the REST API, PostgreSQL pipeline, Redis queue, or webhooks: +## Architecture -```bash -go run ./cmd/mailx +All outbound entry points share the same message, outbox and delivery pipeline. Broadcasts hand off one message per recipient in bounded batches. + +```mermaid +flowchart TD + API["Tenant REST API"] --> Accept["Validate sender and limits
Build MIME and sign DKIM"] + Submission["Authenticated SMTP submission
Implicit TLS, optional"] --> Accept + Campaign["Scheduled broadcast"] --> Expand["Snapshot and personalize
Bounded expansion"] + Expand --> Accept + Accept --> Files[("Local message storage
Raw MIME and attachments")] + Accept --> DB[("PostgreSQL
Messages, recipients, outbox and events")] + DB --> Dispatch["Dispatch due outbox work"] + Dispatch --> Redis[("Redis
Available jobs and leased claims")] + Redis --> Worker["Bounded delivery workers"] + Worker --> Transport["MX lookup or trusted relay
SMTP and STARTTLS policy"] + Transport --> Remote["Recipient mail server"] + Worker -->|"Persist outcome before ack or retry"| DB + DB --> Fanout["Durable event fan-out"] + Fanout --> Hooks["Webhook workers
Sign, deliver and retry"] + Hooks --> Target["Subscriber HTTPS endpoint"] + Capture["Local SMTP capture receiver
Storage only"] --> Files + + classDef store fill:#eef2f6,stroke:#64748b,color:#0f172a + class Files,DB,Redis store ``` -This mode is useful for parser and receiver development; it is not equivalent to the complete stack. +### State and recovery + +| Component | Responsibility | +| --- | --- | +| PostgreSQL | Authoritative message state, attempts, tenant data, campaign snapshots and webhook history | +| Local files | Stored message bytes and extracted attachments | +| Redis | Job scheduling and temporary claim ownership | +| Workers | Delivery attempts; commit outcomes before acknowledging jobs or scheduling retries | + +Acceptance writes the message, recipients, queued event and outbox row in one database transaction. The dispatcher retries the handoff to Redis. Workers load durable state when reclaiming a job, so they can resume after a crash. -## Local message inspection +Delivery is at least once. A crash after a remote server accepts mail but before MailX records that outcome can lead to a repeat attempt. SMTP has no transaction that spans both servers. -Messages accepted by the SMTP receiver can be listed and inspected from the local file store: +### SMTP modes + +| Mode | Behavior | +| --- | --- | +| Capture receiver | The default `:2525` listener parses and stores mail locally. It creates no delivery jobs and requires no authentication. | +| Authenticated submission | Optional listener configured with `MAILX_SUBMISSION_ADDR` and certificate/key files. Uses implicit TLS and an API key with `emails:send` as the password, then enters the outbound pipeline. | +| Outbound delivery | Direct MX connections by default, or one configured trusted relay. STARTTLS verifies certificates; a TLS attempt that fails never falls back to plaintext. | + +Without `DATABASE_URL`, MailX runs the capture receiver and operator listener without the API or delivery pipeline. To inspect locally captured messages: ```bash go run ./cmd/mailx list go run ./cmd/mailx inspect MAILX-ID ``` -Set `MAILX_STORAGE_ROOT` when the messages are not stored in the default location. The inspection command reports metadata and attachment information without rendering HTML or executing remote content. +Set `MAILX_STORAGE_ROOT` to inspect a different store. Inspection reports metadata and attachments without rendering HTML. + +## Broadcast controls + +Create a broadcast with an audience, template and optional RFC 3339 `send_at`. Its template content is copied at acceptance. Audience members added afterward are excluded; members removed before their snapshot batch is scanned may be excluded too. + +```mermaid +stateDiagram-v2 + [*] --> accepted: Create + accepted --> accepted: Reschedule + accepted --> expanding: Schedule is due + accepted --> cancelled: Cancel + expanding --> cancelled: Cancel + expanding --> completed: Expansion finishes + expanding --> failed: Broadcast-wide failure + completed --> [*] + failed --> [*] + cancelled --> [*] +``` + +Both control endpoints require `broadcasts:write`. Replace `BROADCAST-ID` with your broadcast's `id`. + +| Action | Endpoint | Allowed states | +| --- | --- | --- | +| Change the schedule | `POST /v1/broadcasts/{id}/reschedule` | `accepted` | +| Stop further handoffs | `POST /v1/broadcasts/{id}/cancel` | `accepted`, `expanding`; repeats on `cancelled` succeed | + +```bash +curl --fail-with-body --request POST \ + http://localhost:8080/v1/broadcasts/BROADCAST-ID/reschedule \ + --header "Authorization: Bearer ${MAILX_API_KEY}" \ + --header 'Content-Type: application/json' \ + --data '{"send_at":"2027-01-15T09:00:00Z"}' + +curl --fail-with-body --request POST \ + http://localhost:8080/v1/broadcasts/BROADCAST-ID/cancel \ + --header "Authorization: Bearer ${MAILX_API_KEY}" +``` + +Choose a future timestamp. Rescheduling preserves the original audience and template snapshots. Once expansion starts, rescheduling returns `409 broadcast_state_conflict`. + +Cancellation waits for any database handoff already in progress, then prevents new snapshots and message inserts. Messages already queued continue through delivery and cannot be recalled. A completed or failed broadcast returns `409`; another tenant's broadcast returns `404`. + +Recipient lists and broadcast analytics distinguish `cancelled` recipients from `materialized` recipients already handed off. Counts cover the stored snapshot, which can be partial when cancellation interrupts expansion. Audience members never snapshotted have no recipient row and are excluded from those counts. `completed` means expansion finished, regardless of the messages' delivery outcomes. + +Apply migrations and upgrade all MailX processes before using these controls. Older expander binaries do not enforce the cancellation boundary. Rolling migration 000035 back preserves cancelled broadcasts as failed records so they stay inactive. + +## Configuration + +The [environment example](./.env.example) covers the core local stack. Optional features also read the settings below; Compose must explicitly pass any additional variables or mount certificate files you configure. + +| Settings | Purpose | +| --- | --- | +| `DATABASE_URL`, `REDIS_ADDR` | Database and queue connections | +| `MAILX_HTTP_ADDR`, `MAILX_SMTP_ADDR`, `MAILX_STORAGE_ROOT` | API, capture listener and local storage | +| `MAILX_API_KEY_PEPPER` | API-key verifier protection | +| `MAILX_WEBHOOK_MASTER_KEY`, `MAILX_DKIM_MASTER_KEY` | Distinct base64-encoded 32-byte encryption keys for webhook secrets and DKIM keys | +| `MAILX_SMTP_TLS_POLICY`, `MAILX_SMTP_TLS_CA_FILE` | Outbound `opportunistic` or `required` TLS and optional additional trusted CA roots | +| `MAILX_RELAY_HOST`, `MAILX_RELAY_PORT`, `MAILX_RELAY_USERNAME`, `MAILX_RELAY_PASSWORD` | Optional trusted relay; authenticated relay delivery requires verified STARTTLS | +| `MAILX_SMTP_HOSTNAME`, `MAILX_SENDING_IPS`, `MAILX_SPF_RELAY_INCLUDE` | Public sending identity and DNS readiness guidance | +| `MAILX_LOG_LEVEL`, `MAILX_LOG_FORMAT`, `MAILX_OBSERVABILITY_ADDR` | Logging and the separate operator listener | +| `MAILX_SUBMISSION_ADDR`, `MAILX_SUBMISSION_TLS_CERT`, `MAILX_SUBMISSION_TLS_KEY` | Optional authenticated SMTP submission listener | +| `MAILX_JWT_SECRET`, `MAILX_SYSTEM_TENANT_ID`, `MAILX_SYSTEM_FROM_ADDRESS` | Persistent human sessions and system email delivery from a verified sender | + +Use fresh secrets outside local development, set `MAILX_WEBHOOK_ALLOW_INSECURE=false`, and put the HTTP API behind HTTPS. Without a configured system mailer, account verification and password-reset emails cannot be sent. Optional OAuth, MFA, tracking and billing configuration lives in the corresponding [runtime modules](./cmd/mailx). ## Development -Start the infrastructure dependencies, then run the full validation suite: +Start PostgreSQL and Redis before running integration tests. If you already have them running locally, use an isolated test database and set its connection string instead of starting duplicate services. ```bash docker compose up -d postgres redis export MAILX_TEST_DATABASE_URL='postgres://mailx:mailx-dev-only@127.0.0.1:5432/mailx?sslmode=disable' export REDIS_ADDR='127.0.0.1:6379' +export GOMAXPROCS=2 go fmt ./... -go vet ./... -go test -count=1 ./... -go test -race -count=1 ./... -go build ./... +go vet -p 1 ./... +go test -p 1 -parallel 2 -count=1 ./... +go test -race -p 1 -parallel 2 -count=1 ./... +go build -p 1 ./... git diff --check ``` -The test suite includes unit, integration, concurrency, protocol-boundary, persistence, tenant-isolation, retry, and security regression coverage. PostgreSQL and Redis integration tests require those services to be reachable. +Tests use isolated PostgreSQL schemas and Redis namespaces. Set `MAILX_TEST_DATABASE_URL` explicitly: database tests can skip if PostgreSQL is unavailable, while Redis integration tests fail if Redis is unreachable. -Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a change. Pull requests should be focused, tested, and use Conventional Commit messages. +### Repository map -## Project status - -MailX is an educational and engineering project under active development. The current codebase implements milestones through durable webhook delivery; operational observability and transport security remain ongoing roadmap work. - -read [Ilana](.ilana) for the current progress of mailx +| Path | Contains | +| --- | --- | +| [`cmd/mailx`](./cmd/mailx) | Runtime wiring, configuration and operator commands | +| [`internal/api`](./internal/api) | HTTP handlers, middleware and the OpenAPI contract | +| [`internal/database`](./internal/database) | PostgreSQL repositories and versioned migrations | +| [`internal/smtp`](./internal/smtp) | SMTP protocol server and outbound client | +| [`internal/broadcast`](./internal/broadcast) | Campaign snapshots and bounded message handoffs | +| [`internal/worker`](./internal/worker), [`internal/queue`](./internal/queue), [`internal/dispatch`](./internal/dispatch) | Delivery processing, claims and outbox dispatch | +| [`internal/webhook`](./internal/webhook) | Signing, fan-out and delivery retries | -## Security +## Project status -MailX handles private message data and security-sensitive credentials. Do not include real API keys, webhook secrets, SMTP credentials, message bodies, or connection strings in issues or logs. +MailX implements the sending pipeline and account backend, with features through the v0.47 account and organization work. Some features require optional configuration. The repository remains a project under active development. Its [progress record](./.ilana/milestones.md) tracks the completed milestones and remaining scope. -Report vulnerabilities privately according to [SECURITY.md](./SECURITY.md). Do not open a public issue containing exploit details. +DNS readiness checks describe sender configuration; they cannot guarantee inbox placement. General inbound mailbox hosting is outside the current scope. Generated bounce/DSN reports are recorded locally rather than automatically sent. -## Community +## Contributing -- MailX is maintained by Feranmi Oresajo with contributions welcomed from the community. -- Read the [contribution guide](./CONTRIBUTING.md) before submitting code. -- Follow the [Code of Conduct](./CODE_OF_CONDUCT.md) in all project spaces. -- Use [GitHub Issues](https://github.com/Ferousco-dev/Mailx/issues) for reproducible bugs and scoped feature proposals. -- Use the generated [OpenAPI contract](http://localhost:8080/openapi.json) as the source of truth for the current HTTP surface. +Read the [contribution guide](./CONTRIBUTING.md) and [Code of Conduct](./CODE_OF_CONDUCT.md). Keep changes focused, test the affected behavior and use Conventional Commit messages. For a large feature, discuss the scope with the maintainer before submitting it. -## License +Report bugs and feature proposals through [GitHub Issues](https://github.com/Ferousco-dev/Mailx/issues). Report security vulnerabilities privately using [SECURITY.md](./SECURITY.md); keep credentials and private message content out of reports and logs. -MailX is available under the [MIT License](./LICENSE). +MailX is maintained by Feranmi Oresajo and released under the [MIT License](./LICENSE). From c0b065dcf1638320d9e2b0f757ea5ec0651f4a72 Mon Sep 17 00:00:00 2001 From: Naheem Adisa Date: Sat, 17 Oct 2026 17:26:37 +0100 Subject: [PATCH 3/3] docs: record broadcast lifecycle controls in Ilana --- .ilana/architecture.md | 8 ++++---- .ilana/decisions.md | 2 ++ .ilana/ledger.md | 3 +++ .ilana/milestones.md | 5 +++++ .ilana/risks.md | 2 +- .ilana/state.json | 16 ++++++++++++++-- 6 files changed, 29 insertions(+), 7 deletions(-) diff --git a/.ilana/architecture.md b/.ilana/architecture.md index f14ea8a..b16b0fb 100644 --- a/.ilana/architecture.md +++ b/.ilana/architecture.md @@ -345,7 +345,7 @@ Redis queue polling (200ms..2s), not blocking primitives (multi-condition wake-u ## Broadcasts / bulk sending (v0.36) - Orchestration ONLY over the EXISTING send pipeline (MIME/DKIM/outbox/queue/worker/SMTP unchanged): a broadcast never becomes one giant SMTP transaction — each recipient becomes its own normal `messages` row via the SAME `database.InsertMessage` POST /v1/emails uses. -- State machine (`broadcasts.status`): accepted -> expanding -> completed | failed. "completed" means every recipient was either suppressed or handed to the existing pipeline — NEVER delivered/inbox placement. "failed" is used only for a whole-broadcast condition (From domain no longer verified), never for one bad recipient. +- State machine (`broadcasts.status`): accepted -> expanding -> completed | failed, with accepted/expanding -> cancelled. "completed" means every recipient was either suppressed or handed to the existing pipeline — NEVER delivered/inbox placement. "failed" is used for a whole-broadcast failure; migration 000035 rollback also maps cancelled broadcasts to failed while preserving the cancellation reason. - Two durable phases per (broadcast, contact): SNAPSHOT (`broadcast_recipients` row: contact_id/email/name/attributes copied once) then MATERIALIZE (render -> MIME -> DKIM -> `InsertMessage`, status pending->suppressed|materialized). `internal/broadcast.Expander` (mirrors `internal/dispatch`'s outbox-polling pattern) advances both phases in bounded per-tick batches (200 audience rows / 25 recipients), never the whole audience in memory or one transaction. - Audience snapshot semantics: `broadcasts.audience_snapshot_at` is stamped by PostgreSQL's `now()` at acceptance (not Go's clock — avoids Go/DB clock skew, found and fixed during testing). Expansion only ever reads `audience_members` rows with `created_at <= audience_snapshot_at`, so a contact added afterward is NEVER included, however long expansion takes (tested). A member removed from the audience before its batch is scanned is a documented narrow race (RSK-038), not a correctness bug. - Template snapshot: `broadcasts.subject_template/text_template/html_template` copy the Template's CURRENT source at acceptance; the live `templates` table is NEVER re-read during expansion (tested: edited-then-deleted template still produces the original frozen content for every recipient, mutation-checked). @@ -355,8 +355,8 @@ Redis queue polling (200ms..2s), not blocking primitives (multi-condition wake-u - Suppression: reused authority (`suppression.Normalize` + `SuppressedForTenant`), checked LATE — immediately before materialization, not just at acceptance — so a suppression created while a broadcast is still expanding still stops any not-yet-materialized recipient (tested). Suppressed recipients consume zero quota and zero SMTP attempts. - Abuse controls: materialization charges the SAME tenant recipient bucket as `/v1/emails` (`ratelimit.TenantRecipientKey`) and respects the same `CountTenantQueued`/`CountPendingOutbox` backpressure before each batch; a refusal leaves recipients `pending` for a later tick (this IS the broadcast's backpressure/fairness mechanism — it never bypasses v0.31, it proceeds more slowly). API keys cannot multiply broadcast throughput (same tenant-scoped accounting). - Tenant isolation: every DB query tenant-scoped; audience/template ownership validated authoritatively in `handleCreate`, not merely because auth passed; cross-tenant references are 404, never disclosing which resource was missing/foreign (tested both directions). -- Cancellation: DEFERRED (not implemented) — explicitly documented rather than faked; a partial/fake cancel that still lets workers send would be worse than none. -- API: `POST/GET /v1/broadcasts`, `GET /v1/broadcasts/{id}/recipients` (keyset). No PATCH, no DELETE (deliberately omitted — see limitations). Scopes `broadcasts:read`/`broadcasts:write`. +- Cancellation: accepted/expanding broadcasts can stop further snapshots and message handoffs (DEC-250). Repeating cancellation returns the cancelled broadcast. Already queued messages continue through the ordinary delivery pipeline; cancellation does not recall them. +- API: `POST/GET /v1/broadcasts`, `GET /v1/broadcasts/{id}/recipients` (keyset), `POST /v1/broadcasts/{id}/cancel` and `POST /v1/broadcasts/{id}/reschedule`. Both control endpoints are tenant-scoped and require `broadcasts:write`; reads require `broadcasts:read`. No PATCH or DELETE. - Feedback/events: no `broadcast.*` events or bounce truth store added — materialized recipients are normal messages, so v0.32 feedback and existing `email.*` events already apply via the message's own id; `BroadcastRecipient.message_id` is the correlation handle. - Metrics: `mailx_broadcast_expansion_batches_total{phase,outcome}` (bounded: 3x5 series). No broadcast/tenant/contact id ever labeled. - Retention: `broadcasts`/`broadcast_recipients` are durable historical/operational records (like `delivery_attempts`), not auto-expired; deleting a broadcast is not implemented, so no cascade-into-history risk exists yet. @@ -376,7 +376,7 @@ Redis queue polling (200ms..2s), not blocking primitives (multi-condition wake-u - Restart/downtime: no additional recovery path needed — a scheduled row is ordinary durable Postgres state (`outbox`/`broadcasts`), found by the SAME polling queries dispatch/expansion already run every tick; a crashed or restarted process simply resumes polling and any now-due row becomes eligible, exactly like the pre-existing v0.15/v0.36 crash-recovery model. No new crash window was introduced. - Concurrency: unaffected — outbox dispatch was already duplicate-safe (JobID + idempotent `MarkOutboxDispatched`), and `ClaimActiveBroadcasts`'s `FOR UPDATE SKIP LOCKED` (unchanged) still prevents two expander instances claiming the same broadcast. - Idempotency: `send_at`/`scheduled_at` are ordinary fields in the fingerprinted request struct (`idempotency.Fingerprint` hashes the whole validated request) — a retry with the same Idempotency-Key but a different scheduled time is a 409 conflict, not a silent reschedule (tested both paths). -- Reschedule/cancel: NOT implemented (DEC-130). `send_at` is immutable after acceptance, same posture as v0.36's broadcast-configuration immutability (DEC-123). Deferred rather than adding unsafe/racy cancel semantics (RSK-039 unchanged). +- Broadcast controls (DEC-250): `POST /v1/broadcasts/{id}/reschedule` accepts a future RFC3339 `send_at` only while status is accepted. `POST /v1/broadcasts/{id}/cancel` changes accepted/expanding to cancelled and repeats idempotently. PostgreSQL row locks fence stale activation, snapshots, claims and message handoffs; recipient progress commits with the message and outbox. Cancelled pending recipients are projected at read time; existing messages remain materialized, and analytics counts only the durable snapshot. Migration `000035_broadcast_control.up.sql` adds cancelled to the status constraint. Its down migration changes cancelled broadcasts to failed with `failure_reason = 'cancelled'` before restoring the previous constraint, so rollback does not reactivate them. Upgrade every expander and message-handoff process before enabling controls. - Fairness/backpressure: unaffected — a large overdue backlog is still bounded by the SAME per-tick batch sizes (outbox's fair round-robin batch, expander's 200/25 batches); scheduling introduces no new unbounded-selection path. - Indexes: `idx_broadcasts_active_due (send_at, created_at) WHERE status IN ('accepted','expanding')`. EXPLAIN at 2003 active broadcasts (2000 future-scheduled, 3 due): bitmap index scan, 8 buffer hits, 0.018ms — no sequential scan (`TestClaimActiveBroadcastsDueScanAtScale`, MET-072). - API: no new scopes — reuses `emails:send`/`broadcasts:write`. OpenAPI documents `scheduled_at`/`send_at` on both request and response schemas, including the "eligibility boundary, not exact delivery time" semantics. diff --git a/.ilana/decisions.md b/.ilana/decisions.md index 7ac21b2..8e405fb 100644 --- a/.ilana/decisions.md +++ b/.ilana/decisions.md @@ -254,3 +254,5 @@ Process decisions above (DEC-001..DEC-007) belong to the v0.23 FLEET run and sta - DEC-247 [v0.47 dashboard API keys] (renumbered from DEC-243): (a) create/rotate pass a per-human `apiKeyMintLimitMiddleware` (`Policy.APIKeyMintRate`/`APIKeyMintBurst`, default 1/30 rps burst 10, env `MAILX_LIMIT_APIKEY_MINT_RPS`/`_BURST`), same shape as `orgInviteLimitMiddleware`; list/revoke are unlimited beyond humanAuth. (b) HTTP rotate uses grace 0 (old key invalid immediately); rotating a revoked/expired key -> 409 `api_key_not_active`. (c) Revoke matches the CLI exactly: an already-revoked key yields 404 `api_key_not_found` and no change (NOT idempotent-204 like invite revoke) - deliberate consistency with `database.RevokeAPIKey`. - DEC-248 [org API keys, merge review]: independently verified the API-key-management agent's work before pushing (full test suite + `-race`, manual review of `orgAPIKeyHandler`/`orgKey`'s cross-tenant isolation and scope validation, OpenAPI, Docker boot smoke) and additionally live-tested the exact end-to-end claim that matters most: signed up a real account via `POST /v1/auth/signup`, created an org, minted an API key via `POST /v1/orgs/{id}/api-keys`, and used the raw key to successfully call the real `GET /v1/domains` (a `requireScope`-protected, API-key-only route) against the running server - confirming a dashboard-signed-up user can now reach the rest of the tenant-scoped API without any CLI/operator involvement, closing the gap this milestone exists to close. Resolved a DEC-number collision with the concurrently-built email-verification work (both independently claimed DEC-241..243 from the same base commit): renumbered this work's entries to DEC-245..247 in decisions.md and the two source files (`internal/api/apikeys_handler.go`, `internal/ratelimit/policy.go`) that reference them. - DEC-249 [PR #28, CodeRabbit review pass]: fixed 3 findings. (1) **Rotate error mapping** (functional correctness): `auth.Service.Rotate` returned a bare `fmt.Errorf` string for a revoked/expired key, not the `auth.ErrRevoked`/`ErrExpired` sentinels used elsewhere - so the HTTP rotate handler's `errors.Is` check could never match the race where a key is revoked/expired concurrently between the handler's own unlocked pre-check and the actual `Rotate` call, falling through to a generic 500 instead of the correct 409 `api_key_not_active`. Fixed by wrapping both returns with their sentinel (`%w`) and adding both to the handler's `errors.Is` check; strengthened the two existing tests (`TestServiceRotateRejectsExpiredKey`/`RevokedKey`, previously only checking `err != nil`) to assert the specific sentinel. (2) **Unbounded verification-email send** (stability): `SignUp` called `sendVerificationEmail` synchronously with no timeout on its own request context, so a slow `SubmissionAcceptor.Accept` (synchronous file+DB work) could stall account creation indefinitely; a naive fix of detaching it into a goroutine tied to a context that gets canceled after the response is written would risk losing the durable outbound record mid-write. Fixed by wrapping the call in a 10-second `context.WithTimeout`, keeping it synchronous (so success/failure still means the record was actually durably written or cleanly gave up) while capping how long a slow mailer can hold up signup. (3) **Stale architecture doc**: `architecture.md`'s email-verification section still described the pre-DEC-244 invalidate-before-send design; updated to describe the current create-send-then-supersede flow. Verified: gofmt/go vet/go build clean, full `go test ./...` and `go test -race ./...` clean, Docker rebuild+boot smoke clean. + +- DEC-250 [broadcast lifecycle controls, PR #30]: tenant-scoped `POST /v1/broadcasts/{id}/cancel` and `POST /v1/broadcasts/{id}/reschedule` require `broadcasts:write`. Cancel accepted/expanding broadcasts without recalling queued messages; reschedule only accepted broadcasts to a future RFC3339 `send_at`. Lock the broadcast before recipient rows, and commit message/outbox handoff with recipient progress. Recheck due time during activation. Project cancelled pending recipients at read time instead of updating the whole audience. Migration 000035 adds cancelled to the status constraint; rollback maps cancelled to failed with `failure_reason = 'cancelled'` before restoring the old constraint, preventing reactivation. Upgrade all participating processes before using controls. diff --git a/.ilana/ledger.md b/.ilana/ledger.md index db4f1cf..776b437 100644 --- a/.ilana/ledger.md +++ b/.ilana/ledger.md @@ -359,3 +359,6 @@ Merged the API-key-management agent's work (built concurrently with email verifi ## 2026-09-26 | PR #28: CodeRabbit review pass | GATE PASS Checked CodeRabbit on PR #28 as asked and got 3 real, all-minor findings, fixed all three. The most consequential: auth.Service.Rotate returned a bare error string instead of a matchable sentinel for a revoked/expired key, so the exact race the HTTP handler was written to handle (key revoked concurrently between its own pre-check and the Rotate call) fell through to a generic 500 instead of the intended 409 - the handler's error-mapping code was correct in shape but had nothing real to match against. Fixed by wrapping the returns with auth.ErrRevoked/ErrExpired and strengthening two existing tests that had been asserting only "an error happened" to assert the actual sentinel. Also bounded a previously-unbounded email send in SignUp with a 10s timeout (stalls signup less under a slow mailer, without risking the durable-record-loss a naive goroutine-detach would introduce) and fixed a stale architecture.md paragraph describing the pre-DEC-244 email-verification design. Verified: gofmt/go vet/go build clean, full go test ./... and go test -race ./... clean, Docker rebuild+boot smoke clean. Ilana updated: decisions.md (DEC-249), state.json (DEC counter). + +## 2026-10-17 | PR #30 broadcast-control documentation | VERIFIED +Updated architecture, DEC-250, milestones, RSK-039 and state to match the cancel/reschedule endpoints, cancelled status and migration 000035. Documented rollback to failed with `failure_reason = 'cancelled'`, preserving the stop across rollback/reapply. Verified against route registration, handlers, OpenAPI and both migration files. Focused existing endpoint, OpenAPI and PostgreSQL rollback/reapply tests passed without skips. No production code changes. diff --git a/.ilana/milestones.md b/.ilana/milestones.md index 59ffa48..6dac0b8 100644 --- a/.ilana/milestones.md +++ b/.ilana/milestones.md @@ -132,3 +132,8 @@ explicitly deferred to a later phase — v0.47 as a whole is NOT complete. ## v0.47 dashboard — Org API-key management over HTTP — COMPLETE (DEC-245..247) - Owner-managed create/list/rotate/revoke under `/v1/orgs/{id}/api-keys` (human JWT), reusing the CLI's `auth.Service`. Unblocker for the rest of the dashboard: domains/emails/templates/webhooks/logs routes stay API-key + `requireScope`, and a web-signed-up org can now mint that key itself. - Tests: `internal/api/apikeys_handler_test.go` (non-member 404 / non-owner 403 table; HTTP-created key authenticates on real `GET /v1/domains`; scope enforced (403 without domains:read); list leaks no key material; rotate kills old key and new key works; revoke kills key; unknown/duplicate/empty scope 422). Rate limiter itself not exercised by a test (mirrors the tested invite limiter). + +## Broadcast lifecycle controls — PR #30 +- Implemented: tenant-scoped `POST /v1/broadcasts/{id}/cancel` and `POST /v1/broadcasts/{id}/reschedule` (`broadcasts:write`). Cancellation changes accepted/expanding to cancelled; rescheduling accepts a future RFC3339 `send_at` only while accepted. Already queued messages continue. +- Migration 000035 adds cancelled to the broadcast status constraint. Rollback changes cancelled broadcasts to failed with `failure_reason = 'cancelled'` before restoring the previous constraint; rollback/reapply does not restart them. +- Verified: endpoint workflow, authorization/isolation, input validation, expanding-state conflicts, OpenAPI/runtime route agreement and migration rollback/reapply against real PostgreSQL. Upgrade all participating processes before enabling controls. Pending PR review; no new numbered milestone declared. diff --git a/.ilana/risks.md b/.ilana/risks.md index b8d9cfd..22e8405 100644 --- a/.ilana/risks.md +++ b/.ilana/risks.md @@ -47,7 +47,7 @@ - RSK-037 [low, v0.32]: no provider-specific complaint adapters (Gmail/Outlook FBL etc.) are implemented; only a generic authenticated JSON envelope. - RSK-029 [medium, v0.30, unchanged]: RCPT is still all-or-error; not touched by v0.32. - RSK-038 [low, v0.36, reconfirmed v0.37]: a member removed from an Audience after its broadcast's snapshot watermark but before its snapshot batch is scanned may be silently excluded from that broadcast (a narrow async-expansion race, not a correctness bug — documented, not solved). v0.37 audit: scheduling a broadcast for later does NOT enlarge this window, because `audience_snapshot_at` is stamped at acceptance regardless of `send_at` (DEC-128) — a long scheduling delay changes when expansion runs, not which acceptance-time watermark it scans against. Proven by `TestScheduledBroadcastSnapshotIsAtAcceptanceNotActivation`. -- RSK-039 [low, v0.36, unchanged by v0.37]: no cancellation is implemented; an accepted broadcast always runs to completion. v0.37 deliberately did not add reschedule/cancel either (DEC-130) — scheduled sends create real product pressure for "cancel before send_at" but implementing it honestly needs the same concurrency care as RSK-039 already flags, so it stays deferred rather than adding an unsafe/racy cancel path. +- RSK-039 [addressed in PR #30; DEC-250]: accepted/expanding broadcasts can be cancelled and accepted broadcasts rescheduled. Locks fence activation, snapshots and message inserts. Already queued messages continue by design. All participating processes must be upgraded before controls are used. PR #30 is pending review. - RSK-040 [low, PR review, RECONFIRMED after DEC-147]: `ClaimActiveBroadcasts`'s broadcast-level SKIP LOCKED select still releases its row lock as soon as the query returns (unchanged) — safe today because SnapshotBroadcastBatch and the now-atomic recipient claim are each individually guarded downstream, but a FUTURE broadcast-level operation added directly inside ClaimActiveBroadcasts' result-processing loop (before any per-item guard) could reintroduce the same class of race the recipient-claim fix (DEC-134) closed. An atomic-lease fix (matching DEC-134) was attempted and reverted (DEC-147): it broke legitimate same-instance multi-tick re-claiming of a still-in-progress broadcast. A correct fix would need a heartbeat-renewed lease tied to the owning instance's tick loop, not a fixed-duration one — deferred, since the residual risk is wasted redundant work under genuine multi-instance overlap, never a duplicate send or quota charge. Flag for review if the claim loop grows new unguarded side effects, or if this residual risk needs closing for a future multi-instance-at-scale deployment. - RSK-041 [low, v0.46 PR review]: `internal/database.findRecipientsByAddress` (GDPR export/erasure subject matching) streams and Go-decodes EVERY recipient row for the tenant to find matches for one address — on a tenant with a large recipient history this is a full scan that could exceed the operator CLI's fixed context deadline. Left as-is deliberately for this PR-review-fix pass: it is an operator-only CLI path (`mailx gdpr-export`/`gdpr-delete`), not a hot request path, and a real fix (an indexed normalized-address column on `recipients`, populated at insert time) touches `messages.go`'s INSERT path — a bigger, separate change not undertaken here given the session's cost ceiling. Revisit if GDPR requests need to run routinely against large tenants, or if the CLI's context deadline is ever hit in practice. - RSK-042 [low, v0.47 phase 1 PR review, decided with the human operator]: `POST /v1/auth/signup` returns a distinct `email_taken` (409) for an already-registered address, while `POST /v1/auth/login` deliberately returns the same generic error for both "wrong password" and "unknown email" (anti-enumeration). This is a real, acknowledged inconsistency — an attacker can use signup instead of login to probe which addresses have accounts. Not fixed: the correct fix is to make signup never synchronously confirm existence (respond identically either way, and notify the real account owner by email that someone tried to sign up with their address) — MailX has no human-facing email-sending capability yet to deliver that notification, and changing signup's response shape would break the already-established `Mailx_fe` mock contract (`{name,email,password} -> session`) this phase was built to match. Mitigated, not eliminated, by the IP-keyed rate limit added in the same PR review pass (`authIPLimitMiddleware`, `MAILX_LIMIT_AUTH_IP_RPS`/`_BURST`), which bounds how fast an attacker can enumerate via signup. Revisit once MailX has an email-verification/notification flow for human accounts (a natural fit for a later auth phase, alongside password reset). diff --git a/.ilana/state.json b/.ilana/state.json index 94760a0..259d572 100644 --- a/.ilana/state.json +++ b/.ilana/state.json @@ -18,7 +18,7 @@ "DEF": 27, "CR": 24, "RSK": 49, - "DEC": 249, + "DEC": 250, "MET": 72, "ETH": 1 }, @@ -38,6 +38,18 @@ "ilana_current_through": "v0.47 email verification", "current_milestone": "v0.47 Human Accounts & Organizations", "current_milestone_status": "v0.47 phase 1 (human auth, orgs, password reset, invitations), phase 2 (billing), phase 3a (dashboard backend), phase 3b (OAuth + TOTP MFA, DEC-231..234, independently security-reviewed) and phase 3c (opt-in plan auto-renewal + reminders, DEC-235..238, RSK-044 closed, residuals RSK-048; pending live Paystack test-mode verification) complete; email verification (DEC-241..244, RSK-049 closed) complete; dashboard org API-key management over HTTP (DEC-245..247) complete - the real unblocker for domains/emails/templates/webhooks/logs; leave-org/transfer-ownership, email change, org slug still deferred", - "next_milestone": "v0.48 (TBD); live Paystack test-mode verification of auto-renewal before launch (RSK-048)" + "next_milestone": "v0.48 (TBD); live Paystack test-mode verification of auto-renewal before launch (RSK-048)", + "broadcast_controls": { + "status": "implemented in PR #30; pending review", + "decision": "DEC-250", + "scope": "broadcasts:write", + "endpoints": [ + "POST /v1/broadcasts/{id}/cancel", + "POST /v1/broadcasts/{id}/reschedule" + ], + "status_added": "cancelled", + "migration": "000035_broadcast_control", + "rollback": "cancelled -> failed; failure_reason = 'cancelled'; no reactivation" + } } }