feat(api): inspect and discard the outbound queue

- Add GET /api/v1/queue with totals, oldest age and up to 100 deliveries, failing ones first
- Add DELETE /api/v1/queue/{id} to discard a stuck delivery
- Never expose message contents
This commit is contained in:
tgiachi 2026-11-09 15:54:13 +01:00
commit 98bbcf6b68
2 changed files with 139 additions and 0 deletions

View file

@ -48,6 +48,8 @@ func New(s *store.Store, token string, rel Releaser) http.Handler {
mux.Handle("GET /api/v1/lists/{id}/archive", srv.auth(srv.listArchive))
mux.Handle("GET /api/v1/archive/{id}", srv.auth(srv.getArchived))
mux.Handle("DELETE /api/v1/archive/{id}", srv.auth(srv.deleteArchived))
mux.Handle("GET /api/v1/queue", srv.auth(srv.getQueue))
mux.Handle("DELETE /api/v1/queue/{id}", srv.auth(srv.discardQueued))
mux.Handle("GET /api/v1/lists/{id}/held", srv.auth(srv.listHeld))
mux.Handle("POST /api/v1/held/{id}/approve", srv.auth(srv.approveHeld))
mux.Handle("DELETE /api/v1/held/{id}", srv.auth(srv.discardHeld))
@ -491,3 +493,53 @@ func (s *server) deleteArchived(w http.ResponseWriter, r *http.Request) {
}
w.WriteHeader(http.StatusNoContent)
}
// Handlers: outbound queue.
const queueListLimit = 100
type queuedDTO struct {
ID int64 `json:"id"`
Recipient string `json:"recipient"`
Attempts int `json:"attempts"`
LastError string `json:"last_error"`
NextAttempt time.Time `json:"next_attempt"`
CreatedAt time.Time `json:"created_at"`
}
func (s *server) getQueue(w http.ResponseWriter, _ *http.Request) {
st, err := s.store.OutboxStats()
if err != nil {
storeError(w, err)
return
}
items, err := s.store.ListOutbox(queueListLimit)
if err != nil {
storeError(w, err)
return
}
out := make([]queuedDTO, 0, len(items))
for _, it := range items {
out = append(out, queuedDTO{ID: it.ID, Recipient: it.Rcpt, Attempts: it.Attempts, LastError: it.LastError,
NextAttempt: it.NextAt, CreatedAt: it.CreatedAt})
}
var oldest *time.Time
if !st.Oldest.IsZero() {
oldest = &st.Oldest
}
writeJSON(w, http.StatusOK, map[string]any{
"pending": st.Pending, "retrying": st.Retrying, "oldest": oldest, "items": out,
})
}
func (s *server) discardQueued(w http.ResponseWriter, r *http.Request) {
id, ok := listID(w, r)
if !ok {
return
}
if err := s.store.CompleteOutbox(id); err != nil {
storeError(w, err)
return
}
w.WriteHeader(http.StatusNoContent)
}

View file

@ -435,3 +435,90 @@ func TestArchiveGetAndDelete(t *testing.T) {
expect(t, do(t, h, "DELETE", "/api/v1/archive/1", "", true), 404)
expect(t, do(t, h, "DELETE", "/api/v1/archive/2", "", false), 401)
}
func queueServer(t *testing.T) (http.Handler, *store.Store) {
t.Helper()
s, _ := store.Open(":memory:")
t.Cleanup(func() { s.Close() })
return New(s, token, nil), s
}
type queueJSON struct {
Pending int `json:"pending"`
Retrying int `json:"retrying"`
Oldest *time.Time `json:"oldest"`
Items []struct {
ID int64 `json:"id"`
Recipient string `json:"recipient"`
Attempts int `json:"attempts"`
LastError string `json:"last_error"`
NextAttempt time.Time `json:"next_attempt"`
CreatedAt time.Time `json:"created_at"`
} `json:"items"`
}
func TestQueueEmpty(t *testing.T) {
h, _ := queueServer(t)
rec := do(t, h, "GET", "/api/v1/queue", "", true)
expect(t, rec, 200)
var q queueJSON
decode(t, rec, &q)
if q.Pending != 0 || q.Retrying != 0 || q.Oldest != nil || q.Items == nil || len(q.Items) != 0 {
t.Fatalf("empty queue: %+v (items must be [] not null)", q)
}
}
func TestQueueShowsPendingAndFailingDeliveries(t *testing.T) {
h, s := queueServer(t)
s.Enqueue([]byte("Subject: x\r\n\r\nx"), []store.NewOutbound{
{From: "b@x.org", Rcpt: "a@x.com"}, {From: "b@x.org", Rcpt: "b@x.com"}, {From: "b@x.org", Rcpt: "c@x.com"},
})
due, _ := s.DueOutbox(10)
s.RetryOutbox(due[1].ID, time.Now().Add(time.Hour), "connection refused")
rec := do(t, h, "GET", "/api/v1/queue", "", true)
expect(t, rec, 200)
var q queueJSON
decode(t, rec, &q)
if q.Pending != 3 || q.Retrying != 1 || q.Oldest == nil || len(q.Items) != 3 {
t.Fatalf("queue: %+v", q)
}
if q.Items[0].Recipient != "b@x.com" || q.Items[0].Attempts != 1 || q.Items[0].LastError != "connection refused" {
t.Fatalf("failing deliveries come first: %+v", q.Items[0])
}
if strings.Contains(rec.Body.String(), "Subject") {
t.Fatal("message contents must not be exposed")
}
}
func TestQueueListIsCapped(t *testing.T) {
h, s := queueServer(t)
var items []store.NewOutbound
for i := 0; i < queueListLimit+20; i++ {
items = append(items, store.NewOutbound{From: "b@x.org", Rcpt: fmt.Sprintf("u%d@x.com", i)})
}
s.Enqueue([]byte("x"), items)
var q queueJSON
decode(t, do(t, h, "GET", "/api/v1/queue", "", true), &q)
if q.Pending != queueListLimit+20 || len(q.Items) != queueListLimit {
t.Fatalf("pending=%d items=%d", q.Pending, len(q.Items))
}
}
func TestQueueDiscard(t *testing.T) {
h, s := queueServer(t)
s.Enqueue([]byte("x"), []store.NewOutbound{{From: "b@x.org", Rcpt: "a@x.com"}, {From: "b@x.org", Rcpt: "b@x.com"}})
due, _ := s.DueOutbox(10)
expect(t, do(t, h, "DELETE", fmt.Sprintf("/api/v1/queue/%d", due[0].ID), "", true), 204)
expect(t, do(t, h, "DELETE", fmt.Sprintf("/api/v1/queue/%d", due[0].ID), "", true), 404)
expect(t, do(t, h, "DELETE", "/api/v1/queue/abc", "", true), 404)
if st, _ := s.OutboxStats(); st.Pending != 1 {
t.Fatalf("pending = %d", st.Pending)
}
}
func TestQueueRequiresAuth(t *testing.T) {
h, _ := queueServer(t)
expect(t, do(t, h, "GET", "/api/v1/queue", "", false), 401)
expect(t, do(t, h, "DELETE", "/api/v1/queue/1", "", false), 401)
}