Skip to content

armgit / posta

Public Imported from GitHub
0

Self-hosted email delivery platform that enables applications to send emails via HTTP APIs while handling SMTP delivery, templates, storage, security, and analytics. Fully self-hostable alternative to services like SendGrid or Mailgun.

fix(routes): give clashing operations unique OpenAPI operation IDs

Jonas Kaninda5b2ae32f2137
diff --git a/internal/config/config.go b/internal/config/config.go
index b32a523..6f586be 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -438,6 +438,29 @@ func (c *Config) validateWorker() error {
warnRemovedEnvVars()
return c.ValidateWorker()
}
+// OpenAPISecuritySchemes are the security schemes the API documentation
+// declares. Routes reference them by name with WithSecurity.
+func OpenAPISecuritySchemes() okapi.SecuritySchemes {
+ return okapi.SecuritySchemes{
+ // Dashboard / JWT-authenticated endpoints.
+ {
+ Name: "BearerAuth",
+ Description: "Bearer token issued by /auth/login. Send as: `Authorization: Bearer <JWT>`.",
+ Type: "http",
+ Scheme: "bearer",
+ BearerFormat: "JWT",
+ },
+ // API-key authenticated endpoints.
+ {
+ Name: "ApiKeyAuth",
+ Description: "Long-lived API key. Send as: `Authorization: Bearer <API_KEY>`. Manage keys under Settings → API Keys.",
+ Type: "http",
+ Scheme: "bearer",
+ BearerFormat: "Posta API Key",
+ },
+ }
+}
+
func (c *Config) Initialize(app *okapi.Okapi) error {
if err := c.validate(); err != nil {
return err
@@ -470,22 +493,7 @@ func (c *Config) Initialize(app *okapi.Okapi) error {
})
if c.OpenAPIDocs {
- // Dashboard / JWT-authenticated endpoints.
- c.securitySchemes = append(c.securitySchemes, okapi.SecurityScheme{
- Name: "BearerAuth",
- Description: "Bearer token issued by /auth/login. Send as: `Authorization: Bearer <JWT>`.",
- Type: "http",
- Scheme: "bearer",
- BearerFormat: "JWT",
- })
- // API-key authenticated endpoints.
- c.securitySchemes = append(c.securitySchemes, okapi.SecurityScheme{
- Name: "ApiKeyAuth",
- Description: "Long-lived API key. Send as: `Authorization: Bearer <API_KEY>`. Manage keys under Settings → API Keys.",
- Type: "http",
- Scheme: "bearer",
- BearerFormat: "Posta API Key",
- })
+ c.securitySchemes = append(c.securitySchemes, OpenAPISecuritySchemes()...)
app.WithOpenAPIDocs(okapi.OpenAPI{
Title: "Posta API",
Version: Version,
diff --git a/internal/routes/admin_routes.go b/internal/routes/admin_routes.go
index 742863c..5e76e30 100644
--- a/internal/routes/admin_routes.go
+++ b/internal/routes/admin_routes.go
@@ -514,6 +514,7 @@ func (r *Router) adminRoutes() []okapi.RouteDefinition {
Path: "/workspaces/{id:int}/plan",
Handler: okapi.H(r.h.plan.GetWorkspacePlan),
Group: adminGroup,
+ OperationId: "admin-get-workspace-plan",
Summary: "Get workspace plan",
Description: "Get the effective plan for a workspace",
Response: &dto.Response[models.Plan]{},
diff --git a/internal/routes/openapi_test.go b/internal/routes/openapi_test.go
new file mode 100644
index 0000000..033444b
--- /dev/null
+++ b/internal/routes/openapi_test.go
@@ -0,0 +1,65 @@
+// Copyright (c) 2026 Jonas Kaninda.
+//
+// This file is part of Posta.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+package routes
+
+import (
+ "testing"
+
+ "github.com/goposta/posta/internal/config"
+ "github.com/jkaninda/okapi"
+)
+
+// The server validates the OpenAPI document at startup and only logs a
+// warning, so a broken document (two operations with one operationId, an
+// undeclared security scheme) would otherwise ship unnoticed. okapi derives
+// an operationId from the summary, so two routes with the same summary clash.
+func TestOpenAPIDocumentIsValid(t *testing.T) {
+ app := okapi.New().WithOpenAPIDocs(okapi.OpenAPI{
+ Title: "Posta API",
+ Version: "test",
+ SecuritySchemes: config.OpenAPISecuritySchemes(),
+ })
+ r := &Router{
+ app: app,
+ cfg: &config.Config{InboundEnabled: true, MessagesEnabled: true},
+ v1: app.Group("/api/v1"),
+ }
+ app.Register(r.healthRoutes()...)
+ app.Register(r.infoRoute())
+ app.Register(r.authRoutes()...)
+ app.Register(r.apiAuthRoutes()...)
+ app.Register(r.userRoutes()...)
+ app.Register(r.workspaceRoutes()...)
+ app.Register(r.workspaceResourceRoutes()...)
+ app.Register(r.oauthRoutes()...)
+ app.Register(r.trackingRoutes()...)
+ app.Register(r.trackingAnalyticsRoutes()...)
+ app.Register(r.bounceWebhookRoutes()...)
+ app.Register(r.inboundWebhookRoutes()...)
+ app.Register(r.inboundWorkspaceRoutes()...)
+ app.Register(r.formIngestRoutes()...)
+ app.Register(r.messageWorkspaceRoutes()...)
+ app.Register(r.adminSSERoutes()...)
+ app.Register(r.adminRoutes()...)
+
+ if err := app.ValidateOpenAPI(); err != nil {
+ t.Fatal(err)
+ }
+}
diff --git a/internal/routes/workspace_resource_routes.go b/internal/routes/workspace_resource_routes.go
index ed22cb2..7160818 100644
--- a/internal/routes/workspace_resource_routes.go
+++ b/internal/routes/workspace_resource_routes.go
@@ -81,18 +81,20 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {
Path: "/emails",
Handler: okapi.H(r.h.email.List),
Group: opsGroup,
+ OperationId: "workspace-list-emails",
Summary: "List emails",
Description: "List sent emails with pagination",
Request: &handlers.ListRequest{},
Response: &dto.PageableResponse[models.Email]{},
},
{
- Method: http.MethodGet,
- Path: "/emails/{id}",
- Handler: okapi.H(r.h.email.Get),
- Group: opsGroup,
- Summary: "Get email details",
- Response: &dto.Response[models.Email]{},
+ Method: http.MethodGet,
+ Path: "/emails/{id}",
+ Handler: okapi.H(r.h.email.Get),
+ Group: opsGroup,
+ OperationId: "workspace-get-email-details",
+ Summary: "Get email details",
+ Response: &dto.Response[models.Email]{},
Options: []okapi.RouteOption{
okapi.DocPathParam("id", "string", "Email UUID"),
okapi.DocResponse(404, &dto.ErrorResponseBody{}),
@@ -103,6 +105,7 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {
Path: "/emails/{id}/status",
Handler: okapi.H(r.h.email.GetStatus),
Group: opsGroup,
+ OperationId: "workspace-get-email-delivery-status",
Summary: "Get email delivery status",
Description: "Returns a lightweight status view for polling email delivery progress. Only the email owner can access this.",
Response: &dto.Response[handlers.EmailStatusResponse]{},
@@ -116,6 +119,7 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {
Path: "/emails/{id}/retry",
Handler: okapi.H(r.h.email.Retry),
Group: opsGroup,
+ OperationId: "workspace-retry-failed-email",
Summary: "Retry failed email",
Description: "Re-enqueue a failed email for another delivery attempt",
Response: &dto.Response[email.SendResponse]{},
@@ -130,6 +134,7 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {
Path: "/emails/preview",
Handler: okapi.H(r.h.email.Preview),
Group: opsGroup,
+ OperationId: "workspace-preview-email-from-template",
Summary: "Preview email from template",
Description: "Render a template with variables and return the HTML, text, and subject without sending.",
Request: &handlers.PreviewEmailRequest{},
@@ -704,33 +709,36 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {
},
},
{
- Method: http.MethodPost,
- Path: pathWebhooks,
- Handler: okapi.H(r.h.webhook.Create),
- Group: opsGroup,
- Tags: []string{tagUser},
- Summary: "Create webhook",
- Request: &handlers.CreateWebhookRequest{},
+ Method: http.MethodPost,
+ Path: pathWebhooks,
+ Handler: okapi.H(r.h.webhook.Create),
+ Group: opsGroup,
+ Tags: []string{tagUser},
+ OperationId: "workspace-create-webhook",
+ Summary: "Create webhook",
+ Request: &handlers.CreateWebhookRequest{},
Options: []okapi.RouteOption{
okapi.DocResponse(201, &dto.Response[models.Webhook]{}),
},
},
{
- Method: http.MethodGet,
- Path: pathWebhooks,
- Handler: okapi.H(r.h.webhook.List),
- Group: opsGroup,
- Summary: "List webhooks",
- Request: &handlers.ListRequest{},
- Response: &dto.PageableResponse[models.Webhook]{},
+ Method: http.MethodGet,
+ Path: pathWebhooks,
+ Handler: okapi.H(r.h.webhook.List),
+ Group: opsGroup,
+ OperationId: "workspace-list-webhooks",
+ Summary: "List webhooks",
+ Request: &handlers.ListRequest{},
+ Response: &dto.PageableResponse[models.Webhook]{},
},
{
- Method: http.MethodDelete,
- Path: "/webhooks/{id:int}",
- Handler: okapi.H(r.h.webhook.Delete),
- Group: opsGroup,
- Tags: []string{tagUser},
- Summary: "Delete webhook",
+ Method: http.MethodDelete,
+ Path: "/webhooks/{id:int}",
+ Handler: okapi.H(r.h.webhook.Delete),
+ Group: opsGroup,
+ Tags: []string{tagUser},
+ OperationId: "workspace-delete-webhook",
+ Summary: "Delete webhook",
Options: []okapi.RouteOption{
okapi.DocPathParam("id", "integer", "Webhook ID"),
okapi.DocResponse(204, nil),
@@ -738,13 +746,14 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {
},
},
{
- Method: http.MethodGet,
- Path: "/webhook-deliveries",
- Handler: okapi.H(r.h.webhookDelivery.List),
- Group: opsGroup,
- Summary: "List webhook deliveries",
- Request: &handlers.ListRequest{},
- Response: &dto.PageableResponse[models.WebhookDelivery]{},
+ Method: http.MethodGet,
+ Path: "/webhook-deliveries",
+ Handler: okapi.H(r.h.webhookDelivery.List),
+ Group: opsGroup,
+ OperationId: "workspace-list-webhook-deliveries",
+ Summary: "List webhook deliveries",
+ Request: &handlers.ListRequest{},
+ Response: &dto.PageableResponse[models.WebhookDelivery]{},
},
{
Method: http.MethodPost,
@@ -819,13 +828,14 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {
},
},
{
- Method: http.MethodGet,
- Path: pathBounces,
- Handler: okapi.H(r.h.bounce.List),
- Group: opsGroup,
- Summary: "List bounces",
- Request: &handlers.ListRequest{},
- Response: &dto.PageableResponse[models.Bounce]{},
+ Method: http.MethodGet,
+ Path: pathBounces,
+ Handler: okapi.H(r.h.bounce.List),
+ Group: opsGroup,
+ OperationId: "workspace-list-bounces",
+ Summary: "List bounces",
+ Request: &handlers.ListRequest{},
+ Response: &dto.PageableResponse[models.Bounce]{},
},
{
Method: http.MethodPost,
@@ -1104,6 +1114,7 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {
Handler: okapi.H(r.h.subscriberList.UnsubscribeByEmail),
Group: opsGroup,
Tags: []string{tagSubscriberLists},
+ OperationId: "workspace-unsubscribe-an-email-from-a-list",
Summary: "Unsubscribe an email from a list",
Description: "API-key-accessible list opt-out. Idempotent. Does not change global subscriber status.",
Request: &handlers.ListUnsubscribeByEmailRequest{},
@@ -1116,6 +1127,7 @@ func (r *Router) workspaceResourceRoutes() []okapi.RouteDefinition {
Handler: okapi.H(r.h.subscriberList.ResubscribeByEmail),
Group: opsGroup,
Tags: []string{tagSubscriberLists},
+ OperationId: "workspace-re-subscribe-an-email-to-a-list",
Summary: "Re-subscribe an email to a list",
Description: "Reverses a list-scoped opt-out and re-adds to the list (static lists). Idempotent.",
Request: &handlers.ListResubscribeByEmailRequest{},