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:
parent
7ce6a1c98e
commit
1ba42316fd
5 changed files with 180 additions and 3 deletions
19
README.md
19
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=<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
151
docs/openapi.yaml
Normal 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'}
|
||||
|
|
@ -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 {
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue