test(server): hold the route table to the claims it makes

A required argument makes a reason impossible to omit. Only an inventory of the claims makes an
empty one impossible to merge, so this reads back what the route table declared while it was
built and refuses a claim that says nothing. A second test proves that check bites rather than
passing because it looks at nothing.

The exempt set names the routes that are not resource operations and so keep a direct
registration. Echo does not expose a route's handler, so no test can prove that a route outside
the set went through a wrapper; what the set buys is the other direction, where joining it is a
visible edit next to the reason each member is exempt. Each member is cross-checked against the
router, so an entry that outlives its route fails.

The three converted routes are pinned to both their shape and their address, which rules out a
claim recorded by a wrapper nothing mounted.

Fixes: #6940

Author: otavio

server/api/routes/route_table_test.go

@@ -0,0 +1,136 @@
+package routes
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/shellhub-io/shellhub/server/api/pkg/gateway"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// unstatedClaims names every declaration that takes an exception to the default rules without
+// saying why. A reason is a required argument, so it cannot be omitted — but it can be left empty,
+// and this is what refuses that.
+func unstatedClaims(declarations []gateway.Declaration) []string {
+	unstated := make([]string, 0)
+
+	for _, declaration := range declarations {
+		if declaration.Unbounded && strings.TrimSpace(declaration.UnboundedReason) == "" {
+			unstated = append(unstated, fmt.Sprintf("%s reads across namespaces and states no reason", declaration.Handler))
+		}
+
+		if declaration.Anonymous && strings.TrimSpace(declaration.AnonymousReason) == "" {
+			unstated = append(unstated, fmt.Sprintf("%s requires no actor and states no reason", declaration.Handler))
+		}
+	}
+
+	return unstated
+}
+
+// TestRouteTableStatesEveryClaim reads the claims the route table made while it was built. A route
+// that reads across namespaces, or that needs no actor, has to say why — otherwise breadth and
+// anonymity arrive by omission, which is what the two claims exist to prevent.
+func TestRouteTableStatesEveryClaim(t *testing.T) {
+	authenticatedRouter(t)
+
+	declarations := gateway.Declarations()
+	require.NotEmpty(t, declarations, "the route table registered no wrapped route")
+
+	assert.Empty(t, unstatedClaims(declarations))
+}
+
+// TestUnstatedClaimsRefusesAnEmptyReason proves the check above bites, rather than passing because
+// it looks at nothing.
+func TestUnstatedClaimsRefusesAnEmptyReason(t *testing.T) {
+	unstated := unstatedClaims([]gateway.Declaration{
+		{Handler: "silent", Unbounded: true, Anonymous: true},
+		{Handler: "stated", Unbounded: true, UnboundedReason: "because"},
+	})
+
+	require.Len(t, unstated, 2)
+	for _, complaint := range unstated {
+		assert.Contains(t, complaint, "silent")
+	}
+}
+
+// wrapperExemptRoutes is the set of routes that are not API resource operations and so keep a
+// direct registration instead of one of the gateway shapes.
+//
+// The install script serves a shell script rather than JSON. The local user authentication
+// exchange derives three non-200 outcomes from values that are not errors, and sets two headers
+// the console reads. The tag creation handler returns its identifier in a response header, and
+// leaves this set once that identifier moves into the response body.
+//
+// Echo does not expose a route's handler, so no test can prove that a route outside this set went
+// through a wrapper. What the set buys is the other direction: joining it is a visible edit here,
+// where a reviewer reads why each member is exempt.
+var wrapperExemptRoutes = []string{
+	"GET /api/install",
+	"POST /api/login",
+	"POST /api/auth/user",
+	"POST /api/tags",
+	"POST /api/namespaces/:tenant/tags",
+}
+
+// TestWrapperExemptRoutesAreRegistered catches a stale member: an exempt route that no longer
+// exists, or was renamed, leaves the set claiming an exemption for nothing.
+func TestWrapperExemptRoutesAreRegistered(t *testing.T) {
+	router, _, _ := authenticatedRouter(t)
+
+	registered := make(map[string]struct{})
+	for _, route := range router.Router().Routes() {
+		registered[route.Method+" "+route.Path] = struct{}{}
+	}
+
+	for _, exempt := range wrapperExemptRoutes {
+		assert.Contains(t, registered, exempt, "the exempt set names %q but no such route is registered", exempt)
+	}
+}
+
+// methodName reduces the fully qualified name the runtime reports for a method value to the method
+// itself, so a test can name a handler the way the route table does.
+func methodName(qualified string) string {
+	return strings.TrimSuffix(qualified[strings.LastIndex(qualified, ".")+1:], "-fm")
+}
+
+// TestConvertedRoutesDeclareTheirShape pins the three routes this change converted: each answers
+// with the shape it was registered under, and each is mounted at the address it claims.
+//
+// The second half is what keeps the declaration honest. Echo does not expose a route's handler, so
+// a declaration cannot be matched to its route in general — but for a named handler at a known
+// address, asserting both is enough to rule out a claim recorded by a wrapper nothing mounted.
+func TestConvertedRoutesDeclareTheirShape(t *testing.T) {
+	router, _, _ := authenticatedRouter(t)
+
+	registered := make(map[string]struct{})
+	for _, route := range router.Router().Routes() {
+		registered[route.Method+" "+route.Path] = struct{}{}
+	}
+
+	shapes := make(map[string]gateway.Shape)
+	for _, declaration := range gateway.Declarations() {
+		shapes[methodName(declaration.Handler)] = declaration.Shape
+	}
+
+	converted := []struct {
+		handler string
+		shape   gateway.Shape
+		route   string
+	}{
+		{handler: "EvaluateHealth", shape: gateway.ShapeNone, route: "GET /api" + HealthCheckURL},
+		{handler: "GetDevice", shape: gateway.ShapeOne, route: "GET /api" + GetDeviceURL},
+		{handler: "GetDeviceList", shape: gateway.ShapeList, route: "GET /api" + GetDeviceListURL},
+	}
+
+	for _, tc := range converted {
+		t.Run(tc.handler, func(tt *testing.T) {
+			declared, found := shapes[tc.handler]
+
+			require.True(tt, found, "%s is not registered through a gateway shape", tc.handler)
+			assert.Equal(tt, tc.shape, declared, "%s answers with the wrong shape", tc.handler)
+			assert.Contains(tt, registered, tc.route, "%s declares a shape but is not mounted", tc.handler)
+		})
+	}
+}