feat: wire REST API into the daemon and document it

- Add api.listen config; token comes from PARSIMONY_API_TOKEN
- Disable the API when the token is not set
- Add OpenAPI description and README usage
This commit is contained in:
tgiachi 2026-11-09 14:57:57 +01:00
commit 1ba42316fd
5 changed files with 180 additions and 3 deletions

View file

@ -1,3 +1,22 @@
# parsimony
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.
- SQLite storage, one YAML config file.
- Admin REST API under `/api/v1` (see `docs/openapi.yaml`).
## Run
```
cp parsimony.example.yaml parsimony.yaml
PARSIMONY_API_TOKEN=<token> go run ./cmd/parsimony -config parsimony.yaml
```
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
```

151
docs/openapi.yaml Normal file
View file

@ -0,0 +1,151 @@
openapi: 3.0.3
info:
title: Parsimony admin API
version: 1.0.0
servers:
- url: /api/v1
security:
- bearer: []
components:
securitySchemes:
bearer:
type: http
scheme: bearer
schemas:
List:
type: object
properties:
id: {type: integer}
name: {type: string}
domain: {type: string}
title: {type: string}
address: {type: string}
Member:
type: object
properties:
address: {type: string}
display_name: {type: string}
Error:
type: object
properties:
error: {type: string}
responses:
Error:
description: Error
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
paths:
/health:
get:
security: []
summary: Liveness check
responses:
'200': {description: OK}
/lists:
get:
summary: List all lists
responses:
'200':
description: OK
content:
application/json:
schema: {type: array, items: {$ref: '#/components/schemas/List'}}
post:
summary: Create a list
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [name, domain]
properties:
name: {type: string}
domain: {type: string}
title: {type: string}
responses:
'201':
description: Created
content:
application/json:
schema: {$ref: '#/components/schemas/List'}
'400': {$ref: '#/components/responses/Error'}
'409': {$ref: '#/components/responses/Error'}
/lists/{id}:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
get:
summary: Get a list
responses:
'200':
description: OK
content:
application/json:
schema: {$ref: '#/components/schemas/List'}
'404': {$ref: '#/components/responses/Error'}
patch:
summary: Update the list title
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [title]
properties:
title: {type: string}
responses:
'200':
description: OK
content:
application/json:
schema: {$ref: '#/components/schemas/List'}
'400': {$ref: '#/components/responses/Error'}
'404': {$ref: '#/components/responses/Error'}
delete:
summary: Delete a list and its members
responses:
'204': {description: Deleted}
'404': {$ref: '#/components/responses/Error'}
/lists/{id}/members:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
get:
summary: List members
responses:
'200':
description: OK
content:
application/json:
schema: {type: array, items: {$ref: '#/components/schemas/Member'}}
'404': {$ref: '#/components/responses/Error'}
post:
summary: Add a member (idempotent)
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [address]
properties:
address: {type: string}
display_name: {type: string}
responses:
'201':
description: Created
content:
application/json:
schema: {$ref: '#/components/schemas/Member'}
'400': {$ref: '#/components/responses/Error'}
'404': {$ref: '#/components/responses/Error'}
/lists/{id}/members/{address}:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
- {name: address, in: path, required: true, schema: {type: string}}
delete:
summary: Remove a member
responses:
'204': {description: Removed}
'404': {$ref: '#/components/responses/Error'}

View file

@ -17,6 +17,9 @@ type Config struct {
Network string `yaml:"network"` // tcp or unix
Addr string `yaml:"addr"`
} `yaml:"lmtp"`
API struct {
Listen string `yaml:"listen"` // HTTP listen address; the bearer token comes from PARSIMONY_API_TOKEN
} `yaml:"api"`
Relay struct {
Addr string `yaml:"addr"` // host:port of the outgoing SMTP relay
} `yaml:"relay"`
@ -29,6 +32,7 @@ func Load(path string) (Config, error) {
c.LMTP.Network = "tcp"
c.LMTP.Addr = "127.0.0.1:2424"
c.Relay.Addr = "127.0.0.1:25"
c.API.Listen = "127.0.0.1:8080"
b, err := os.ReadFile(path)
if err != nil {

View file

@ -20,17 +20,17 @@ func TestLoadDefaults(t *testing.T) {
if err != nil {
t.Fatal(err)
}
if c.DB != "parsimony.db" || c.LMTP.Network != "tcp" || c.LMTP.Addr != "127.0.0.1:2424" || c.Relay.Addr != "127.0.0.1:25" {
if c.DB != "parsimony.db" || c.LMTP.Network != "tcp" || c.LMTP.Addr != "127.0.0.1:2424" || c.Relay.Addr != "127.0.0.1:25" || c.API.Listen != "127.0.0.1:8080" {
t.Fatalf("defaults: %+v", c)
}
}
func TestLoadValues(t *testing.T) {
c, err := Load(write(t, "db: /var/lib/p.db\nbase_url: https://l.example.org\nlmtp:\n network: unix\n addr: /run/p.sock\nrelay:\n addr: mx:587\n"))
c, err := Load(write(t, "db: /var/lib/p.db\nbase_url: https://l.example.org\nlmtp:\n network: unix\n addr: /run/p.sock\nrelay:\n addr: mx:587\napi:\n listen: 0.0.0.0:9000\n"))
if err != nil {
t.Fatal(err)
}
if c.DB != "/var/lib/p.db" || c.BaseURL != "https://l.example.org" || c.LMTP.Network != "unix" || c.LMTP.Addr != "/run/p.sock" || c.Relay.Addr != "mx:587" {
if c.DB != "/var/lib/p.db" || c.BaseURL != "https://l.example.org" || c.LMTP.Network != "unix" || c.LMTP.Addr != "/run/p.sock" || c.Relay.Addr != "mx:587" || c.API.Listen != "0.0.0.0:9000" {
t.Fatalf("values: %+v", c)
}
}

View file

@ -5,3 +5,6 @@ lmtp:
addr: 0.0.0.0:2424
relay:
addr: postfix:25
api:
listen: 0.0.0.0:8080
# The API token is read from the PARSIMONY_API_TOKEN environment variable.