[api] add RFC9727 support

.github/workflows/terraform-validate.yml

@@ -14,9 +14,6 @@ jobs:
     name: Validate Terraform
     runs-on: ubuntu-latest
     if: github.actor != 'dependabot[bot]'
-    env:
-      AWS_ACCESS_KEY_ID: ${{secrets.AWS_ACCESS_KEY_ID}}
-      AWS_SECRET_ACCESS_KEY: ${{secrets.AWS_SECRET_ACCESS_KEY}}
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -28,7 +25,7 @@ jobs:
 
       - name: Initialize Terraform
         working-directory: deployments/docker-swarm-terraform
-        run: terraform init
+        run: terraform init -backend=false
 
       - name: Validate Terraform
         working-directory: deployments/docker-swarm-terraform

api/requests.http

@@ -289,3 +289,8 @@ GET http://localhost:3000/health/ready HTTP/1.1
 ###
 GET http://localhost:3000/health/live HTTP/1.1
 
+###
+HEAD {{baseUrl}}/.well-known/api-catalog HTTP/1.1
+
+###
+GET {{baseUrl}}/.well-known/api-catalog HTTP/1.1

deployments/docker-swarm-terraform/main.tf

@@ -159,6 +159,19 @@ resource "docker_service" "app" {
     label = "traefik.http.routers.${var.app-name}-new.tls.certresolver"
     value = "le"
   }
+
+  labels {
+    label = "traefik.http.routers.${var.app-name}-wellknown.rule"
+    value = "Host(`api.sms-gate.app`) && PathPrefix(`/.well-known`) && Method(`GET`,`HEAD`)"
+  }
+  labels {
+    label = "traefik.http.routers.${var.app-name}-wellknown.entrypoints"
+    value = "https"
+  }
+  labels {
+    label = "traefik.http.routers.${var.app-name}-wellknown.tls.certresolver"
+    value = "le"
+  }
   #endregion
 
   #region Primary Limited

internal/sms-gateway/handlers/3rdparty.go

@@ -73,6 +73,12 @@ func newThirdPartyHandler(
 func (h *thirdPartyHandler) Register(router fiber.Router) {
 	router = router.Group("/3rdparty/v1")
 
+	// Add Link header pointing to api-catalog (RFC 9727 Section 3)
+	router.Use(func(c *fiber.Ctx) error {
+		c.Set(fiber.HeaderLink, `</.well-known/api-catalog>; rel="api-catalog"`)
+		return c.Next()
+	})
+
 	h.healthHandler.Register(router)
 
 	router.Use(

internal/sms-gateway/handlers/api_catalog.go

@@ -0,0 +1,100 @@
+package handlers
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"github.com/gofiber/fiber/v2/middleware/limiter"
+	"go.uber.org/zap"
+)
+
+type APICatalogHandler struct {
+	config Config
+	logger *zap.Logger
+}
+
+func newAPICatalogHandler(cfg Config, logger *zap.Logger) *APICatalogHandler {
+	return &APICatalogHandler{
+		config: cfg,
+		logger: logger.Named("api_catalog"),
+	}
+}
+
+func (h *APICatalogHandler) get(c *fiber.Ctx) error {
+	const (
+		fieldHref = "href"
+		fieldType = "type"
+	)
+
+	c.Set(fiber.HeaderLink, `</.well-known/api-catalog>; rel="api-catalog"`)
+	c.Set(fiber.HeaderCacheControl, "public, max-age=3600")
+
+	host := h.getHost(c)
+	path := h.getPath()
+	base := fmt.Sprintf("https://%s", host)
+	if path != "" {
+		base = fmt.Sprintf("%s/%s", base, path)
+	}
+
+	linkset := fiber.Map{
+		"linkset": []fiber.Map{
+			{
+				"anchor": fmt.Sprintf("%s/3rdparty/v1", base),
+				"service-desc": []fiber.Map{
+					{
+						fieldHref: fmt.Sprintf("%s/docs/doc.json", base),
+						fieldType: "application/json",
+					},
+				},
+				"service-doc": []fiber.Map{
+					{
+						fieldHref: "https://docs.sms-gate.app/",
+						fieldType: "text/html",
+					},
+				},
+				"status": []fiber.Map{
+					{
+						fieldHref: fmt.Sprintf("%s/3rdparty/v1/health/ready", base),
+						fieldType: "application/json",
+					},
+				},
+			},
+		},
+	}
+
+	return c.JSON(linkset, `application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"`)
+}
+
+func (h *APICatalogHandler) head(c *fiber.Ctx) error {
+	c.Set(fiber.HeaderContentType, `application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"`)
+	c.Set(fiber.HeaderLink, `</.well-known/api-catalog>; rel="api-catalog"`)
+	c.Set(fiber.HeaderCacheControl, "public, max-age=3600")
+	return c.SendStatus(fiber.StatusOK)
+}
+
+func (h *APICatalogHandler) getHost(c *fiber.Ctx) string {
+	if h.config.PublicHost != "" {
+		return h.config.PublicHost
+	}
+	return c.Hostname()
+}
+
+func (h *APICatalogHandler) getPath() string {
+	return strings.Trim(h.config.PublicPath, "/")
+}
+
+func (h *APICatalogHandler) Register(app *fiber.App) {
+	const limit = 60
+
+	rateLimiter := limiter.New(limiter.Config{
+		Max:               limit,
+		Expiration:        time.Minute,
+		LimiterMiddleware: limiter.SlidingWindow{},
+	})
+
+	group := app.Group("/.well-known/api-catalog", rateLimiter)
+	group.Get("", h.get)
+	group.Head("", h.head)
+}

internal/sms-gateway/handlers/module.go

@@ -22,6 +22,7 @@ func Module() fx.Option {
 		}),
 		fx.Provide(
 			http.AsRootHandler(newRootHandler),
+			http.AsRootHandler(newAPICatalogHandler),
 			http.AsApiHandler(newThirdPartyHandler),
 			http.AsApiHandler(newMobileHandler),
 			http.AsApiHandler(newUpstreamHandler),