refactor(shared): move the OpenAPI document handler to packages/shared

GitOrigin-RevId: 9a9b3d97b843cc8955bd145fdf7e6bd928461e99

Author: roman-e2b

packages/api/internal/openapispec/handler_test.go

@@ -33,7 +33,6 @@ import (
 	"github.com/e2b-dev/infra/packages/api/internal/middleware/idempotency"
 	"github.com/e2b-dev/infra/packages/api/internal/middleware/ratelimit"
 	"github.com/e2b-dev/infra/packages/api/internal/oauth"
-	"github.com/e2b-dev/infra/packages/api/internal/openapispec"
 	"github.com/e2b-dev/infra/packages/api/internal/utils"
 	"github.com/e2b-dev/infra/packages/auth/pkg/auth"
 	sqlcdb "github.com/e2b-dev/infra/packages/db/client"
@@ -50,6 +49,7 @@ import (
 	metricsMiddleware "github.com/e2b-dev/infra/packages/shared/pkg/middleware/otel/metrics"
 	tracingMiddleware "github.com/e2b-dev/infra/packages/shared/pkg/middleware/otel/tracing"
 	"github.com/e2b-dev/infra/packages/shared/pkg/mtls"
+	"github.com/e2b-dev/infra/packages/shared/pkg/openapispec"
 	"github.com/e2b-dev/infra/packages/shared/pkg/removedroutes"
 	"github.com/e2b-dev/infra/packages/shared/pkg/telemetry"
 	sharedutils "github.com/e2b-dev/infra/packages/shared/pkg/utils"

packages/api/main.go

@@ -1,28 +1,28 @@
-// Package openapispec serves the OpenAPI document the API validates requests
-// against, so a client can learn which operations this deployment supports.
+// Package openapispec serves the OpenAPI document a service validates requests
+// against, so a client can learn which operations the deployment supports.
 package openapispec
 
 import (
 	"bytes"
 	"crypto/sha256"
 	"encoding/hex"
+	"encoding/json"
 	"fmt"
 	"net/http"
 	"time"
 
-	"github.com/getkin/kin-openapi/openapi3"
 	"github.com/gin-gonic/gin"
 )
 
-// Path is where the document is served. It is not an operation in the spec,
-// so it must be registered before the request validator, which rejects paths
-// the spec does not declare.
+// Path is where the API serves its document. A document is not an operation
+// in its own spec, so its route must be registered before the request
+// validator, which rejects paths the spec does not declare.
 const Path = "/openapi.json"
 
 // Handler serves doc as JSON. The document is rendered once. Its ETag is a
 // hash of the rendered bytes, so a client that sends it back in
 // If-None-Match gets a 304 until the document changes.
-func Handler(doc *openapi3.T) (gin.HandlerFunc, error) {
+func Handler(doc json.Marshaler) (gin.HandlerFunc, error) {
 	body, err := doc.MarshalJSON()
 	if err != nil {
 		return nil, fmt.Errorf("render the OpenAPI document: %w", err)

…ages/api/internal/openapispec/handler.go …ckages/shared/pkg/openapispec/handler.gopackages/api/internal/openapispec/handler.go renamed to packages/shared/pkg/openapispec/handler.go packages/api/internal/openapispec/handler.go renamed to packages/shared/pkg/openapispec/handler.go

@@ -0,0 +1,89 @@
+package openapispec
+
+import (
+	"encoding/json"
+	"maps"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+const (
+	document        = `{"openapi":"3.0.0","info":{"title":"API","version":"1"},"paths":{"/sandboxes":{"post":{"security":[{"ApiKeyAuth":[]}],"responses":{"201":{"description":"Created"}}}}}}`
+	changedDocument = `{"openapi":"3.0.0","info":{"title":"API","version":"1"},"paths":{}}`
+)
+
+// serve sends one request to a Handler serving doc at Path, for GET and HEAD
+// as the services register it.
+func serve(t *testing.T, doc string, method string, header http.Header) *httptest.ResponseRecorder {
+	t.Helper()
+
+	handler, err := Handler(json.RawMessage(doc))
+	require.NoError(t, err)
+
+	engine := gin.New()
+	engine.GET(Path, handler)
+	engine.HEAD(Path, handler)
+
+	req := httptest.NewRequestWithContext(t.Context(), method, Path, nil)
+	maps.Copy(req.Header, header)
+	actualResponse := httptest.NewRecorder()
+	engine.ServeHTTP(actualResponse, req)
+
+	return actualResponse
+}
+
+func Test_Handler(t *testing.T) {
+	t.Parallel()
+
+	// A client reads the served document to learn the deployment's
+	// operations and their security.
+	t.Run("should serve the document as JSON", func(t *testing.T) {
+		t.Parallel()
+
+		// Act
+		actualResponse := serve(t, document, http.MethodGet, nil)
+
+		// Assert
+		require.Equal(t, http.StatusOK, actualResponse.Code)
+		assert.Equal(t, "application/json", actualResponse.Header().Get("Content-Type"))
+		assert.Equal(t, "no-cache", actualResponse.Header().Get("Cache-Control"))
+		assert.JSONEq(t, document, actualResponse.Body.String())
+	})
+
+	t.Run("should answer HEAD with the ETag and no body", func(t *testing.T) {
+		t.Parallel()
+
+		// Act
+		actualResponse := serve(t, document, http.MethodHead, nil)
+
+		// Assert
+		assert.Equal(t, http.StatusOK, actualResponse.Code)
+		assert.NotEmpty(t, actualResponse.Header().Get("ETag"))
+		assert.Empty(t, actualResponse.Body.Bytes())
+	})
+
+	// A client refreshing the document pays a 304 until the document changes.
+	t.Run("should answer 304 to its ETag until the document changes", func(t *testing.T) {
+		t.Parallel()
+
+		// Arrange
+		etag := serve(t, document, http.MethodGet, nil).Header().Get("ETag")
+		require.NotEmpty(t, etag)
+		ifNoneMatch := http.Header{"If-None-Match": {etag}}
+
+		// Act
+		unchanged := serve(t, document, http.MethodGet, ifNoneMatch)
+		changed := serve(t, changedDocument, http.MethodGet, ifNoneMatch)
+
+		// Assert
+		assert.Equal(t, http.StatusNotModified, unchanged.Code)
+		assert.Empty(t, unchanged.Body.Bytes())
+		assert.Equal(t, http.StatusOK, changed.Code)
+		assert.NotEqual(t, etag, changed.Header().Get("ETag"))
+	})
+}