parsimony/internal/api/api.go
tgiachi ad58789630 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
2026-11-09 15:05:11 +01:00

387 lines
10 KiB
Go

// Package api exposes the administration REST API.
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
releaser Releaser
}
// New returns the API handler. Every route except /api/v1/health needs
// "Authorization: Bearer <token>". An empty token rejects all requests.
// 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"})
})
mux.Handle("GET /api/v1/lists", srv.auth(srv.listLists))
mux.Handle("POST /api/v1/lists", srv.auth(srv.createList))
mux.Handle("GET /api/v1/lists/{id}", srv.auth(srv.getList))
mux.Handle("PATCH /api/v1/lists/{id}", srv.auth(srv.updateList))
mux.Handle("DELETE /api/v1/lists/{id}", srv.auth(srv.deleteList))
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
}
func (s *server) auth(next http.HandlerFunc) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
got, ok := strings.CutPrefix(r.Header.Get("Authorization"), "Bearer ")
if !ok || s.token == "" || subtle.ConstantTimeCompare([]byte(got), []byte(s.token)) != 1 {
w.Header().Set("WWW-Authenticate", `Bearer realm="parsimony"`)
writeError(w, http.StatusUnauthorized, "invalid or missing token")
return
}
next(w, r)
})
}
// JSON shapes.
type listDTO struct {
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 toListDTO(l store.List) listDTO {
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.
func writeJSON(w http.ResponseWriter, code int, v any) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(code)
json.NewEncoder(w).Encode(v)
}
func writeError(w http.ResponseWriter, code int, msg string) {
writeJSON(w, code, map[string]string{"error": msg})
}
// storeError maps store errors to HTTP responses.
func storeError(w http.ResponseWriter, err error) {
switch {
case errors.Is(err, store.ErrNotFound):
writeError(w, http.StatusNotFound, "not found")
case errors.Is(err, store.ErrExists):
writeError(w, http.StatusConflict, "already exists")
default:
writeError(w, http.StatusInternalServerError, "internal error")
}
}
func decodeBody(w http.ResponseWriter, r *http.Request, v any) bool {
r.Body = http.MaxBytesReader(w, r.Body, 1<<20)
dec := json.NewDecoder(r.Body)
dec.DisallowUnknownFields()
if err := dec.Decode(v); err != nil {
writeError(w, http.StatusBadRequest, "invalid JSON body")
return false
}
return true
}
// listID parses the {id} path value. Anything unusable is a 404.
func listID(w http.ResponseWriter, r *http.Request) (int64, bool) {
id, err := strconv.ParseInt(r.PathValue("id"), 10, 64)
if err != nil {
writeError(w, http.StatusNotFound, "not found")
return 0, false
}
return id, true
}
// Handlers: lists.
func (s *server) listLists(w http.ResponseWriter, _ *http.Request) {
ls, err := s.store.ListLists()
if err != nil {
storeError(w, err)
return
}
out := make([]listDTO, 0, len(ls))
for _, l := range ls {
out = append(out, toListDTO(l))
}
writeJSON(w, http.StatusOK, out)
}
func (s *server) createList(w http.ResponseWriter, r *http.Request) {
var in struct {
Name string `json:"name"`
Domain string `json:"domain"`
Title string `json:"title"`
}
if !decodeBody(w, r, &in) {
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")
return
}
if in.Title == "" {
in.Title = in.Name
}
l, err := s.store.CreateList(in.Name, in.Domain, in.Title)
if err != nil {
storeError(w, err)
return
}
writeJSON(w, http.StatusCreated, toListDTO(l))
}
func (s *server) getList(w http.ResponseWriter, r *http.Request) {
id, ok := listID(w, r)
if !ok {
return
}
l, err := s.store.GetList(id)
if err != nil {
storeError(w, err)
return
}
writeJSON(w, http.StatusOK, toListDTO(l))
}
func (s *server) updateList(w http.ResponseWriter, r *http.Request) {
id, ok := listID(w, r)
if !ok {
return
}
var in struct {
Title *string `json:"title"`
PostPolicy *string `json:"post_policy"`
JoinPolicy *string `json:"join_policy"`
}
if !decodeBody(w, r, &in) {
return
}
if in.Title == nil && in.PostPolicy == nil && in.JoinPolicy == nil {
writeError(w, http.StatusBadRequest, "nothing to update")
return
}
l, err := s.store.GetList(id)
if err != nil {
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))
}
func (s *server) deleteList(w http.ResponseWriter, r *http.Request) {
id, ok := listID(w, r)
if !ok {
return
}
if err := s.store.DeleteList(id); err != nil {
storeError(w, err)
return
}
w.WriteHeader(http.StatusNoContent)
}
// Handlers: members.
func (s *server) listMembers(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
}
ms, err := s.store.Members(id)
if err != nil {
storeError(w, err)
return
}
out := make([]memberDTO, 0, len(ms))
for _, m := range ms {
out = append(out, memberDTO{Address: m.Address, DisplayName: m.DisplayName, Disabled: m.Disabled, BounceCount: m.BounceCount})
}
writeJSON(w, http.StatusOK, out)
}
func (s *server) addMember(w http.ResponseWriter, r *http.Request) {
id, ok := listID(w, r)
if !ok {
return
}
var in memberDTO
if !decodeBody(w, r, &in) {
return
}
a, err := mail.ParseAddress(strings.TrimSpace(in.Address))
if err != nil || a.Name != "" {
writeError(w, http.StatusBadRequest, "a valid email address is required")
return
}
if strings.ContainsAny(in.DisplayName, "\r\n") {
writeError(w, http.StatusBadRequest, "display_name must be a single line")
return
}
if _, err := s.store.GetList(id); err != nil {
storeError(w, err)
return
}
if err := s.store.AddMember(id, a.Address, in.DisplayName); err != nil {
storeError(w, err)
return
}
writeJSON(w, http.StatusCreated, memberDTO{Address: strings.ToLower(a.Address), DisplayName: in.DisplayName})
}
func (s *server) removeMember(w http.ResponseWriter, r *http.Request) {
id, ok := listID(w, r)
if !ok {
return
}
if err := s.store.RemoveMember(id, r.PathValue("address")); err != nil {
storeError(w, err)
return
}
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)
}