From 1ba42316fd22894e9aea4700052ed000e0050b79 Mon Sep 17 00:00:00 2001 From: tgiachi Date: Mon, 9 Nov 2026 14:57:57 +0100 Subject: [PATCH] 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 --- README.md | 19 +++++ docs/openapi.yaml | 151 +++++++++++++++++++++++++++++++++ internal/config/config.go | 4 + internal/config/config_test.go | 6 +- parsimony.example.yaml | 3 + 5 files changed, 180 insertions(+), 3 deletions(-) create mode 100644 docs/openapi.yaml diff --git a/README.md b/README.md index de2f36f..042171c 100644 --- a/README.md +++ b/README.md @@ -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= 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 +``` diff --git a/docs/openapi.yaml b/docs/openapi.yaml new file mode 100644 index 0000000..ad0a4db --- /dev/null +++ b/docs/openapi.yaml @@ -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'} diff --git a/internal/config/config.go b/internal/config/config.go index 6693b08..83027b5 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -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 { diff --git a/internal/config/config_test.go b/internal/config/config_test.go index d8721a0..99d0729 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -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) } } diff --git a/parsimony.example.yaml b/parsimony.example.yaml index 1475d39..7240253 100644 --- a/parsimony.example.yaml +++ b/parsimony.example.yaml @@ -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.