feat(api): list policies, held queue and member bounce state

- Add post_policy and join_policy to lists, patchable per field
- Add held message listing, approve and discard endpoints
- Expose disabled and bounce_count on members
- Reject '+' in list names, it is the command separator
- Wire the router release into the daemon
- Update OpenAPI description and README
This commit is contained in:
tgiachi 2026-11-09 15:05:11 +01:00
commit ad58789630
4 changed files with 317 additions and 24 deletions

View file

@ -5,6 +5,10 @@ A modern, single-binary mailing list manager: an evolution of Mailman.
- Postfix delivers to parsimony over LMTP; parsimony relays through SMTP.
- Discussion lists with member-only posting, `List-*` headers, one-click unsubscribe
and DMARC-safe `From` rewriting.
- Self-service subscribe and unsubscribe by email with double opt-in:
send to `list+join@domain` or `list+leave@domain`, then reply to the confirmation.
- Moderated lists: posts wait in a queue that the API can approve or discard.
- VERP bounces: every recipient gets a signed return address; 3 hard bounces disable a member.
- SQLite storage, one YAML config file.
- Admin REST API under `/api/v1` (see `docs/openapi.yaml`).
@ -20,3 +24,13 @@ The API is disabled when `PARSIMONY_API_TOKEN` is not set.
```
curl -H "Authorization: Bearer $PARSIMONY_API_TOKEN" -d '{"name":"dev","domain":"example.org","title":"Dev"}' localhost:8080/api/v1/lists
```
## Postfix
Deliver the list domains to parsimony over LMTP and keep the `+` extensions intact, for example:
```
transport_maps = hash:/etc/postfix/transport
# /etc/postfix/transport
lists.example.org lmtp:inet:127.0.0.1:2424
```

View file

@ -20,11 +20,23 @@ components:
domain: {type: string}
title: {type: string}
address: {type: string}
post_policy: {type: string, enum: [members, moderated]}
join_policy: {type: string, enum: [open, closed]}
Member:
type: object
properties:
address: {type: string}
display_name: {type: string}
disabled: {type: boolean, description: Disabled after 3 hard bounces; re-adding the member re-enables it}
bounce_count: {type: integer}
Held:
type: object
properties:
id: {type: integer}
sender: {type: string}
subject: {type: string}
size: {type: integer}
created_at: {type: string, format: date-time}
Error:
type: object
properties:
@ -85,16 +97,17 @@ paths:
schema: {$ref: '#/components/schemas/List'}
'404': {$ref: '#/components/responses/Error'}
patch:
summary: Update the list title
summary: Update title and policies (send only the fields to change)
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [title]
properties:
title: {type: string}
post_policy: {type: string, enum: [members, moderated]}
join_policy: {type: string, enum: [open, closed]}
responses:
'200':
description: OK
@ -149,3 +162,32 @@ paths:
responses:
'204': {description: Removed}
'404': {$ref: '#/components/responses/Error'}
/lists/{id}/held:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
get:
summary: Messages waiting for moderation
responses:
'200':
description: OK
content:
application/json:
schema: {type: array, items: {$ref: '#/components/schemas/Held'}}
'404': {$ref: '#/components/responses/Error'}
/held/{id}/approve:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
post:
summary: Approve and deliver a held message
responses:
'204': {description: Delivered}
'404': {$ref: '#/components/responses/Error'}
'501': {$ref: '#/components/responses/Error'}
/held/{id}:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
delete:
summary: Discard a held message
responses:
'204': {description: Discarded}
'404': {$ref: '#/components/responses/Error'}

View file

@ -2,26 +2,37 @@
package api
import (
"bytes"
"context"
"crypto/subtle"
"encoding/json"
"errors"
"mime"
"net/http"
"net/mail"
"strconv"
"strings"
"time"
"codeberg.org/squidd/parsimony/internal/store"
)
// Releaser approves a held message: it delivers it to the list.
type Releaser interface {
Release(ctx context.Context, heldID int64) error
}
type server struct {
store *store.Store
token string
store *store.Store
token string
releaser Releaser
}
// New returns the API handler. Every route except /api/v1/health needs
// "Authorization: Bearer <token>". An empty token rejects all requests.
func New(s *store.Store, token string) http.Handler {
srv := &server{store: s, token: token}
// rel may be nil: approving held messages then answers 501.
func New(s *store.Store, token string, rel Releaser) http.Handler {
srv := &server{store: s, token: token, releaser: rel}
mux := http.NewServeMux()
mux.HandleFunc("GET /api/v1/health", func(w http.ResponseWriter, _ *http.Request) {
writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
@ -34,6 +45,9 @@ func New(s *store.Store, token string) http.Handler {
mux.Handle("GET /api/v1/lists/{id}/members", srv.auth(srv.listMembers))
mux.Handle("POST /api/v1/lists/{id}/members", srv.auth(srv.addMember))
mux.Handle("DELETE /api/v1/lists/{id}/members/{address}", srv.auth(srv.removeMember))
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))
return mux
}
@ -57,15 +71,21 @@ type listDTO struct {
Domain string `json:"domain"`
Title string `json:"title"`
Address string `json:"address"`
PostPolicy string `json:"post_policy"`
JoinPolicy string `json:"join_policy"`
}
func toListDTO(l store.List) listDTO {
return listDTO{ID: l.ID, Name: l.Name, Domain: l.Domain, Title: l.Title, Address: l.Address()}
return listDTO{ID: l.ID, Name: l.Name, Domain: l.Domain, Title: l.Title, Address: l.Address(),
PostPolicy: l.PostPolicy, JoinPolicy: l.JoinPolicy}
}
type memberDTO struct {
Address string `json:"address"`
DisplayName string `json:"display_name"`
Disabled bool `json:"disabled"`
BounceCount int `json:"bounce_count"`
}
// Helpers.
@ -138,8 +158,8 @@ func (s *server) createList(w http.ResponseWriter, r *http.Request) {
return
}
in.Name, in.Domain = strings.TrimSpace(in.Name), strings.TrimSpace(in.Domain)
if in.Name == "" || in.Domain == "" || strings.ContainsAny(in.Name+in.Domain, "@ \r\n") {
writeError(w, http.StatusBadRequest, "name and domain are required and must not contain '@' or spaces")
if in.Name == "" || in.Domain == "" || strings.ContainsAny(in.Name+in.Domain, "@+ \r\n") {
writeError(w, http.StatusBadRequest, "name and domain are required and must not contain '@', '+' or spaces")
return
}
if in.Title == "" {
@ -172,18 +192,15 @@ func (s *server) updateList(w http.ResponseWriter, r *http.Request) {
return
}
var in struct {
Title string `json:"title"`
Title *string `json:"title"`
PostPolicy *string `json:"post_policy"`
JoinPolicy *string `json:"join_policy"`
}
if !decodeBody(w, r, &in) {
return
}
title := strings.TrimSpace(in.Title)
if title == "" || strings.ContainsAny(title, "\r\n") {
writeError(w, http.StatusBadRequest, "title is required and must be a single line")
return
}
if err := s.store.UpdateList(id, title); err != nil {
storeError(w, err)
if in.Title == nil && in.PostPolicy == nil && in.JoinPolicy == nil {
writeError(w, http.StatusBadRequest, "nothing to update")
return
}
l, err := s.store.GetList(id)
@ -191,6 +208,34 @@ func (s *server) updateList(w http.ResponseWriter, r *http.Request) {
storeError(w, err)
return
}
if in.Title != nil {
title := strings.TrimSpace(*in.Title)
if title == "" || strings.ContainsAny(title, "\r\n") {
writeError(w, http.StatusBadRequest, "title must be a non-empty single line")
return
}
l.Title = title
}
if in.PostPolicy != nil {
l.PostPolicy = *in.PostPolicy
}
if in.JoinPolicy != nil {
l.JoinPolicy = *in.JoinPolicy
}
// Validate before writing anything.
if (l.PostPolicy != store.PostMembers && l.PostPolicy != store.PostModerated) ||
(l.JoinPolicy != store.JoinOpen && l.JoinPolicy != store.JoinClosed) {
writeError(w, http.StatusBadRequest, "post_policy must be members or moderated; join_policy must be open or closed")
return
}
if err := s.store.UpdateList(id, l.Title); err != nil {
storeError(w, err)
return
}
if err := s.store.SetPolicies(id, l.PostPolicy, l.JoinPolicy); err != nil {
storeError(w, err)
return
}
writeJSON(w, http.StatusOK, toListDTO(l))
}
@ -224,7 +269,7 @@ func (s *server) listMembers(w http.ResponseWriter, r *http.Request) {
}
out := make([]memberDTO, 0, len(ms))
for _, m := range ms {
out = append(out, memberDTO{Address: m.Address, DisplayName: m.DisplayName})
out = append(out, memberDTO{Address: m.Address, DisplayName: m.DisplayName, Disabled: m.Disabled, BounceCount: m.BounceCount})
}
writeJSON(w, http.StatusOK, out)
}
@ -269,3 +314,74 @@ func (s *server) removeMember(w http.ResponseWriter, r *http.Request) {
}
w.WriteHeader(http.StatusNoContent)
}
// Handlers: held messages.
type heldDTO struct {
ID int64 `json:"id"`
Sender string `json:"sender"`
Subject string `json:"subject"`
Size int `json:"size"`
CreatedAt time.Time `json:"created_at"`
}
func subjectOf(data []byte) string {
m, err := mail.ReadMessage(bytes.NewReader(data))
if err != nil {
return ""
}
subj := m.Header.Get("Subject")
if dec, err := new(mime.WordDecoder).DecodeHeader(subj); err == nil {
return dec
}
return subj
}
func (s *server) listHeld(w http.ResponseWriter, r *http.Request) {
id, ok := listID(w, r)
if !ok {
return
}
if _, err := s.store.GetList(id); err != nil {
storeError(w, err)
return
}
hs, err := s.store.ListHeld(id)
if err != nil {
storeError(w, err)
return
}
out := make([]heldDTO, 0, len(hs))
for _, h := range hs {
out = append(out, heldDTO{ID: h.ID, Sender: h.Sender, Subject: subjectOf(h.Data), Size: len(h.Data), CreatedAt: h.CreatedAt})
}
writeJSON(w, http.StatusOK, out)
}
func (s *server) approveHeld(w http.ResponseWriter, r *http.Request) {
id, ok := listID(w, r)
if !ok {
return
}
if s.releaser == nil {
writeError(w, http.StatusNotImplemented, "delivery is not configured")
return
}
if err := s.releaser.Release(r.Context(), id); err != nil {
storeError(w, err)
return
}
w.WriteHeader(http.StatusNoContent)
}
func (s *server) discardHeld(w http.ResponseWriter, r *http.Request) {
id, ok := listID(w, r)
if !ok {
return
}
if err := s.store.DeleteHeld(id); err != nil {
storeError(w, err)
return
}
w.WriteHeader(http.StatusNoContent)
}

View file

@ -1,6 +1,7 @@
package api
import (
"context"
"encoding/json"
"net/http"
"net/http/httptest"
@ -19,7 +20,7 @@ func newServer(t *testing.T) http.Handler {
t.Fatal(err)
}
t.Cleanup(func() { s.Close() })
return New(s, token)
return New(s, token, nil)
}
func do(t *testing.T, h http.Handler, method, path, body string, auth bool) *httptest.ResponseRecorder {
@ -68,7 +69,7 @@ func TestAuthRequired(t *testing.T) {
func TestEmptyTokenRejectsEverything(t *testing.T) {
s, _ := store.Open(":memory:")
defer s.Close()
h := New(s, "")
h := New(s, "", nil)
req := httptest.NewRequest("GET", "/api/v1/lists", nil)
req.Header.Set("Authorization", "Bearer ")
rec := httptest.NewRecorder()
@ -77,11 +78,13 @@ func TestEmptyTokenRejectsEverything(t *testing.T) {
}
type listJSON struct {
ID int64 `json:"id"`
Name string `json:"name"`
Domain string `json:"domain"`
Title string `json:"title"`
Address string `json:"address"`
ID int64 `json:"id"`
Name string `json:"name"`
Domain string `json:"domain"`
Title string `json:"title"`
Address string `json:"address"`
PostPolicy string `json:"post_policy"`
JoinPolicy string `json:"join_policy"`
}
func createList(t *testing.T, h http.Handler) listJSON {
@ -141,6 +144,7 @@ func TestCreateListValidation(t *testing.T) {
`{}`,
`{"name":"","domain":"example.org"}`,
`{"name":"a@b","domain":"example.org"}`,
`{"name":"a+b","domain":"example.org"}`,
`{"name":"dev","domain":""}`,
`{"name":"dev","domain":"example.org","bogus":1}`,
} {
@ -159,6 +163,8 @@ func TestCreateListValidation(t *testing.T) {
type memberJSON struct {
Address string `json:"address"`
DisplayName string `json:"display_name"`
Disabled bool `json:"disabled"`
BounceCount int `json:"bounce_count"`
}
func TestMembers(t *testing.T) {
@ -194,3 +200,118 @@ func TestMembers(t *testing.T) {
expect(t, do(t, h, "DELETE", "/api/v1/lists/1/members/alice%40example.com", "", true), 204)
expect(t, do(t, h, "DELETE", "/api/v1/lists/1/members/alice%40example.com", "", true), 404)
}
func TestListPoliciesViaAPI(t *testing.T) {
h := newServer(t)
l := createList(t, h)
if l.PostPolicy != "members" || l.JoinPolicy != "open" {
t.Fatalf("defaults: %+v", l)
}
rec := do(t, h, "PATCH", "/api/v1/lists/1", `{"post_policy":"moderated"}`, true)
expect(t, rec, 200)
var u listJSON
decode(t, rec, &u)
if u.PostPolicy != "moderated" || u.JoinPolicy != "open" || u.Title != "Dev" {
t.Fatalf("patched: %+v", u)
}
expect(t, do(t, h, "PATCH", "/api/v1/lists/1", `{"join_policy":"closed","title":"New"}`, true), 200)
rec = do(t, h, "GET", "/api/v1/lists/1", "", true)
decode(t, rec, &u)
if u.JoinPolicy != "closed" || u.Title != "New" || u.PostPolicy != "moderated" {
t.Fatalf("after: %+v", u)
}
expect(t, do(t, h, "PATCH", "/api/v1/lists/1", `{"post_policy":"bogus"}`, true), 400)
}
func TestMemberBounceState(t *testing.T) {
s, _ := store.Open(":memory:")
defer s.Close()
h := New(s, token, nil)
l, _ := s.CreateList("dev", "example.org", "Dev")
s.AddMember(l.ID, "a@x.com", "A")
ms, _ := s.Members(l.ID)
for i := 0; i < 3; i++ {
s.RecordHardBounce(ms[0].ID, 3)
}
rec := do(t, h, "GET", "/api/v1/lists/1/members", "", true)
var out []memberJSON
decode(t, rec, &out)
if len(out) != 1 || !out[0].Disabled || out[0].BounceCount != 3 {
t.Fatalf("members: %+v", out)
}
// Re-adding re-enables.
expect(t, do(t, h, "POST", "/api/v1/lists/1/members", `{"address":"a@x.com"}`, true), 201)
rec = do(t, h, "GET", "/api/v1/lists/1/members", "", true)
decode(t, rec, &out)
if out[0].Disabled || out[0].BounceCount != 0 {
t.Fatalf("after re-add: %+v", out)
}
}
type fakeReleaser struct{ released []int64 }
func (f *fakeReleaser) Release(_ context.Context, id int64) error {
f.released = append(f.released, id)
return nil
}
func heldServer(t *testing.T) (http.Handler, *store.Store, *fakeReleaser) {
t.Helper()
s, _ := store.Open(":memory:")
t.Cleanup(func() { s.Close() })
l, _ := s.CreateList("dev", "example.org", "Dev")
s.HoldMessage(l.ID, "Bob@x.com", []byte("From: Bob <bob@x.com>\r\nSubject: Hello there\r\n\r\nbody"))
rel := &fakeReleaser{}
return New(s, token, rel), s, rel
}
type heldJSON struct {
ID int64 `json:"id"`
Sender string `json:"sender"`
Subject string `json:"subject"`
Size int `json:"size"`
}
func TestHeldQueueAPI(t *testing.T) {
h, _, rel := heldServer(t)
rec := do(t, h, "GET", "/api/v1/lists/1/held", "", true)
expect(t, rec, 200)
var hs []heldJSON
decode(t, rec, &hs)
if len(hs) != 1 || hs[0].Sender != "bob@x.com" || hs[0].Subject != "Hello there" || hs[0].Size == 0 {
t.Fatalf("held: %+v", hs)
}
expect(t, do(t, h, "GET", "/api/v1/lists/99/held", "", true), 404)
expect(t, do(t, h, "POST", "/api/v1/held/1/approve", "", true), 204)
if len(rel.released) != 1 || rel.released[0] != 1 {
t.Fatalf("released: %v", rel.released)
}
expect(t, do(t, h, "DELETE", "/api/v1/held/1", "", true), 204)
expect(t, do(t, h, "DELETE", "/api/v1/held/1", "", true), 404)
expect(t, do(t, h, "DELETE", "/api/v1/held/abc", "", true), 404)
}
func TestHeldRequiresAuth(t *testing.T) {
h, _, _ := heldServer(t)
expect(t, do(t, h, "POST", "/api/v1/held/1/approve", "", false), 401)
expect(t, do(t, h, "GET", "/api/v1/lists/1/held", "", false), 401)
}
func TestApproveWithoutReleaser(t *testing.T) {
s, _ := store.Open(":memory:")
defer s.Close()
h := New(s, token, nil)
expect(t, do(t, h, "POST", "/api/v1/held/1/approve", "", true), 501)
}
func TestApproveUnknownHeld(t *testing.T) {
s, _ := store.Open(":memory:")
defer s.Close()
h := New(s, token, errReleaser{store.ErrNotFound})
expect(t, do(t, h, "POST", "/api/v1/held/5/approve", "", true), 404)
}
type errReleaser struct{ err error }
func (e errReleaser) Release(context.Context, int64) error { return e.err }