feat: backend service

backend/internal/server/clientip/clientip.go

@@ -0,0 +1,41 @@
+// Package clientip exposes the helper that resolves the originating client
+// IP for an inbound HTTP request. Backend trusts the value because the
+// network segment between gateway and backend is the trust boundary
+// (`ARCHITECTURE.md` §15-16): gateway is responsible for sanitising and
+// populating `X-Forwarded-For` before the request reaches backend.
+//
+// Both the public-auth handler chain (handlers_auth_helpers.go) and the
+// user-surface geo-counter middleware reuse the same extraction so the two
+// surfaces never disagree about the IP they record.
+package clientip
+
+import (
+	"net"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+// ExtractSourceIP returns the originating client IP for the request behind
+// c. The leftmost entry of `X-Forwarded-For` is preferred; when the header
+// is absent or empty, the connection RemoteAddr is used (with the port
+// stripped). The empty string is returned when neither source yields a
+// usable value, which lets callers treat the result as "no IP available"
+// and skip dependent work.
+func ExtractSourceIP(c *gin.Context) string {
+	if c == nil || c.Request == nil {
+		return ""
+	}
+	if xff := c.GetHeader("X-Forwarded-For"); xff != "" {
+		first := xff
+		if idx := strings.IndexByte(first, ','); idx >= 0 {
+			first = first[:idx]
+		}
+		return strings.TrimSpace(first)
+	}
+	addr := c.Request.RemoteAddr
+	if host, _, err := net.SplitHostPort(addr); err == nil {
+		return host
+	}
+	return addr
+}

backend/internal/server/clientip/clientip_test.go

@@ -0,0 +1,84 @@
+package clientip
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestExtractSourceIP(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name       string
+		header     string
+		remoteAddr string
+		want       string
+	}{
+		{
+			name:       "single XFF entry trimmed",
+			header:     "  198.51.100.7  ",
+			remoteAddr: "10.0.0.1:5000",
+			want:       "198.51.100.7",
+		},
+		{
+			name:       "first XFF entry wins",
+			header:     "198.51.100.7, 10.0.0.1, 192.168.1.1",
+			remoteAddr: "10.0.0.1:5000",
+			want:       "198.51.100.7",
+		},
+		{
+			name:       "fallback to RemoteAddr without port",
+			header:     "",
+			remoteAddr: "203.0.113.42:65000",
+			want:       "203.0.113.42",
+		},
+		{
+			name:       "RemoteAddr without port preserved",
+			header:     "",
+			remoteAddr: "203.0.113.42",
+			want:       "203.0.113.42",
+		},
+		{
+			name:       "no header and no RemoteAddr returns empty",
+			header:     "",
+			remoteAddr: "",
+			want:       "",
+		},
+	}
+
+	gin.SetMode(gin.TestMode)
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			req := httptest.NewRequest(http.MethodGet, "/", nil)
+			req.RemoteAddr = tc.remoteAddr
+			if tc.header != "" {
+				req.Header.Set("X-Forwarded-For", tc.header)
+			}
+			c, _ := gin.CreateTestContext(httptest.NewRecorder())
+			c.Request = req
+
+			got := ExtractSourceIP(c)
+			if got != tc.want {
+				t.Fatalf("ExtractSourceIP() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestExtractSourceIPNilSafety(t *testing.T) {
+	t.Parallel()
+
+	if got := ExtractSourceIP(nil); got != "" {
+		t.Fatalf("nil context: want empty, got %q", got)
+	}
+
+	c, _ := gin.CreateTestContext(httptest.NewRecorder())
+	if got := ExtractSourceIP(c); got != "" {
+		t.Fatalf("context with nil Request: want empty, got %q", got)
+	}
+}