test(bridge): integration test against real forgejo-mcp (forgejo-mcp-broker-xot)

Spawns a real forgejo-mcp --transport stdio subprocess, runs the
canonical MCP handshake (initialize → notifications/initialized →
tools/list → tools/call get_forgejo_mcp_server_version) through the
bridge, and verifies each step. Validates that the opaque-pipe
assumption holds end-to-end: every JSON-RPC message round-trips
correctly with no hand-rolled framing surprises.

Binary discovery (skipped if none found):
  1. $FORGEJO_MCP_BIN
  2. ../../../forgejo-mcp/forgejo-mcp (sibling-repo built binary)
  3. go build of ../../../forgejo-mcp into a temp dir

Fake Forgejo (httptest.Server) covers the two probes the SDK and
forgejo-mcp's testConnection do at startup:
  - GET /api/v1/version → returns 11.0.0 (>=1.11.0 satisfies SDK gate)
  - GET /api/v1/user    → returns a minimal authenticated user blob

Skipped under -short. Catch-all 404 handler logs unexpected probes so
new SDK or forgejo-mcp behaviour surfaces clearly in test output.

Closes forgejo-mcp-broker-xot. Phase 4 complete.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.beads/issues.jsonl

@@ -1,8 +1,8 @@
 {"id":"forgejo-mcp-broker-q4x","title":"Phase 5c: idle reaper + Forgejo token rotation + child respawn","description":"Reaper (30s tick) applies idle timeout. Rotation (1-min tick) refreshes Forgejo tokens expiring \u003c2min, SIGTERMs child, respawns on next request (design.md §6). Token revocation tears down sessions.","acceptance_criteria":"Clock-injected tests: idle kill, rotation triggers respawn, revocation tears down sessions. Smoke test: 20 concurrent sessions for 10min with mid-test rotations.","status":"open","priority":1,"issue_type":"task","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:18Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T15:45:18Z","dependencies":[{"issue_id":"forgejo-mcp-broker-q4x","depends_on_id":"forgejo-mcp-broker-pur","type":"blocks","created_at":"2026-04-24T17:45:31Z","created_by":"Ole-Morten Duesund","metadata":"{}"},{"issue_id":"forgejo-mcp-broker-q4x","depends_on_id":"forgejo-mcp-broker-t81","type":"blocks","created_at":"2026-04-24T17:45:31Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":2,"dependent_count":1,"comment_count":0}
 {"id":"forgejo-mcp-broker-ytw","title":"Phase 5b: bearer-token middleware on /mcp","description":"Middleware reads Authorization: Bearer \u003cmcp_token\u003e, resolves via store, attaches Forgejo access token to request context. 401 for missing/expired/revoked.","acceptance_criteria":"Table-driven tests: missing header, malformed, unknown token, expired, revoked, valid. Valid-token path puts Forgejo token on ctx via typed key.","status":"open","priority":1,"issue_type":"task","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:18Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T15:45:18Z","dependencies":[{"issue_id":"forgejo-mcp-broker-ytw","depends_on_id":"forgejo-mcp-broker-pur","type":"blocks","created_at":"2026-04-24T17:45:30Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":1,"dependent_count":1,"comment_count":0}
 {"id":"forgejo-mcp-broker-t81","title":"Phase 5a: session registry + spawn-on-initialize","description":"Map Mcp-Session-Id -\u003e supervisor.Child + user metadata. On first initialize for unknown sid, spawn forgejo-mcp with user's Forgejo token in env, bind to bridge. LastActive bumped per request.","acceptance_criteria":"Tests with fake supervisor + fake bridge cover: spawn-on-initialize, reuse for subsequent messages, unknown-sid returns 410, max-sessions cap enforced.","status":"open","priority":1,"issue_type":"task","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:17Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T15:45:17Z","dependencies":[{"issue_id":"forgejo-mcp-broker-t81","depends_on_id":"forgejo-mcp-broker-am1","type":"blocks","created_at":"2026-04-24T17:45:29Z","created_by":"Ole-Morten Duesund","metadata":"{}"},{"issue_id":"forgejo-mcp-broker-t81","depends_on_id":"forgejo-mcp-broker-pur","type":"blocks","created_at":"2026-04-24T17:45:30Z","created_by":"Ole-Morten Duesund","metadata":"{}"},{"issue_id":"forgejo-mcp-broker-t81","depends_on_id":"forgejo-mcp-broker-zuq","type":"blocks","created_at":"2026-04-24T17:45:28Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":3,"dependent_count":2,"comment_count":0}
-{"id":"forgejo-mcp-broker-xot","title":"Phase 4b: bridge integration test against real forgejo-mcp","description":"Drive the bridge with initialize -\u003e tools/list -\u003e tools/call get_forgejo_mcp_server_version against a real forgejo-mcp subprocess. Validates the opaque-pipe assumption.","acceptance_criteria":"Full handshake, tools/list returns expected set, tools/call returns a version string. Tagged as integration test if runtime exceeds 2s.","status":"open","priority":1,"issue_type":"task","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:16Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T15:45:16Z","dependencies":[{"issue_id":"forgejo-mcp-broker-xot","depends_on_id":"forgejo-mcp-broker-am1","type":"blocks","created_at":"2026-04-24T17:45:28Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
+{"id":"forgejo-mcp-broker-xot","title":"Phase 4b: bridge integration test against real forgejo-mcp","description":"Drive the bridge with initialize -\u003e tools/list -\u003e tools/call get_forgejo_mcp_server_version against a real forgejo-mcp subprocess. Validates the opaque-pipe assumption.","acceptance_criteria":"Full handshake, tools/list returns expected set, tools/call returns a version string. Tagged as integration test if runtime exceeds 2s.","status":"in_progress","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:16Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T14:10:04Z","started_at":"2026-04-27T14:10:04Z","dependencies":[{"issue_id":"forgejo-mcp-broker-xot","depends_on_id":"forgejo-mcp-broker-am1","type":"blocks","created_at":"2026-04-24T17:45:28Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
-{"id":"forgejo-mcp-broker-31t","title":"Phase 3b: supervisor stress tests (FD/goroutine/zombie leak detection)","description":"1000 spawn/stop cycles under -race. Verify no FD leak, no goroutine leak (go.uber.org/goleak), no zombies (wait4 returns ECHILD when idle).","acceptance_criteria":"Cycle test passes under -race. FD count stable within a small constant. goleak detects no extra goroutines after test.","status":"in_progress","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:15Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T12:00:32Z","started_at":"2026-04-27T12:00:32Z","dependencies":[{"issue_id":"forgejo-mcp-broker-31t","depends_on_id":"forgejo-mcp-broker-zuq","type":"blocks","created_at":"2026-04-24T17:45:26Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
+{"id":"forgejo-mcp-broker-31t","title":"Phase 3b: supervisor stress tests (FD/goroutine/zombie leak detection)","description":"1000 spawn/stop cycles under -race. Verify no FD leak, no goroutine leak (go.uber.org/goleak), no zombies (wait4 returns ECHILD when idle).","acceptance_criteria":"Cycle test passes under -race. FD count stable within a small constant. goleak detects no extra goroutines after test.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:15Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T14:04:42Z","started_at":"2026-04-27T12:00:32Z","closed_at":"2026-04-27T14:04:42Z","close_reason":"Stress tests in place: 1000-cycle spawn/reap and 200-cycle Stop both clean under -race; FD/goroutine/zombie deltas all single-digit. Driver: /bin/true and /bin/cat (helper-process recursion at scale exposed an unrelated Go pidfd interaction). Supervisor now defensively closes pipe handles post-Wait.","dependencies":[{"issue_id":"forgejo-mcp-broker-31t","depends_on_id":"forgejo-mcp-broker-zuq","type":"blocks","created_at":"2026-04-24T17:45:26Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
 {"id":"forgejo-mcp-broker-am1","title":"Phase 4a: internal/bridge JSON-RPC pipe + SSE writer","description":"Given a supervisor.Child: inbound HTTP JSON -\u003e newline-framed stdin; stdout lines -\u003e SSE frames. Handle client disconnect without killing the child.","acceptance_criteria":"Unit tests with mock Child that echoes: request/response round trip, multiple concurrent requests with correct id routing, client disconnect mid-stream.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:15Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T11:59:35Z","started_at":"2026-04-27T11:56:15Z","closed_at":"2026-04-27T11:59:35Z","close_reason":"Bridge shipped: per-id routing, SSE responses for request/reply messages, 204 for notifications, structured 4xx/5xx for malformed input. Decoupled from supervisor (takes pipes directly) for clean testing via io.Pipe. 90.0% coverage.","dependencies":[{"issue_id":"forgejo-mcp-broker-am1","depends_on_id":"forgejo-mcp-broker-zuq","type":"blocks","created_at":"2026-04-24T17:45:27Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":1,"dependent_count":2,"comment_count":0}
 {"id":"forgejo-mcp-broker-wgo","title":"Phase 2e: OAuth security review + attack-path tests","description":"Phase 2 exit gate. Review every handler for classic OAuth vulns (open redirect, code replay, mix-up, token leak in logs, host spoofing). Add at least one test per attack class. Update design.md §8 with findings.","acceptance_criteria":"Review checklist documented. Tests added for: PKCE mismatch, stale code, token absent from log attributes, bad redirect_uri, mismatched state, replay of used code.","status":"open","priority":1,"issue_type":"task","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:14Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-24T15:45:14Z","dependencies":[{"issue_id":"forgejo-mcp-broker-wgo","depends_on_id":"forgejo-mcp-broker-b2o","type":"blocks","created_at":"2026-04-24T17:45:26Z","created_by":"Ole-Morten Duesund","metadata":"{}"},{"issue_id":"forgejo-mcp-broker-wgo","depends_on_id":"forgejo-mcp-broker-pur","type":"blocks","created_at":"2026-04-24T17:45:25Z","created_by":"Ole-Morten Duesund","metadata":"{}"}],"dependency_count":2,"dependent_count":0,"comment_count":0}
 {"id":"forgejo-mcp-broker-zuq","title":"Phase 3a: internal/supervisor managed stdio subprocess","description":"Child type: Start, Stop(ctx) with SIGTERM -\u003e grace -\u003e SIGKILL, Wait+reap goroutine (no zombies), stderr drainer with prefix. Protocol-agnostic.","acceptance_criteria":"Unit tests against an echo-loop helper: round trip, graceful stop, kill-after-grace, child-exits-on-own detection, stderr capture. Manual spawn of real forgejo-mcp --transport stdio works.","status":"closed","priority":1,"issue_type":"task","assignee":"Ole-Morten Duesund","owner":"olemd@glemt.net","created_at":"2026-04-24T15:45:14Z","created_by":"Ole-Morten Duesund","updated_at":"2026-04-27T11:41:07Z","started_at":"2026-04-27T11:32:54Z","closed_at":"2026-04-27T11:41:07Z","close_reason":"internal/supervisor shipped: Start/Stop/Done/ExitErr/Pid, SIGTERM-\u003egrace-\u003eSIGKILL escalation, mandatory wait-and-reap. Test uses TestMain helper-process pattern; coverage 89.6% on the testable surface.","dependency_count":0,"dependent_count":3,"comment_count":0}

internal/bridge/integration_test.go

@@ -0,0 +1,200 @@
+package bridge_test
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"kode.naiv.no/olemd/forgejo-mcp-broker/internal/bridge"
+	brokerlog "kode.naiv.no/olemd/forgejo-mcp-broker/internal/log"
+	"kode.naiv.no/olemd/forgejo-mcp-broker/internal/supervisor"
+)
+
+// TestBridge_AgainstRealForgejoMCP is the phase-4b acceptance test. It
+// drives a real `forgejo-mcp --transport stdio` subprocess through the
+// bridge and runs the canonical MCP handshake plus a tool call that
+// doesn't require Forgejo network access.
+//
+// Skipped under -short. Skipped entirely when no forgejo-mcp binary or
+// source tree is available — see findOrBuildForgejoMCP for the search.
+//
+// Driving the bridge confirms the opaque-pipe assumption holds in
+// practice: every JSON-RPC message we forward to the child gets a
+// response routed by id, with no protocol-level surprises.
+func TestBridge_AgainstRealForgejoMCP(t *testing.T) {
+	if testing.Short() {
+		t.Skip("integration test (~3s); rerun without -short")
+	}
+
+	binPath := findOrBuildForgejoMCP(t)
+
+	// forgejo-mcp probes Forgejo (GET /api/v1/user) at startup. Stand up a
+	// minimal fake instead of requiring a real Forgejo deployment.
+	fakeForgejo := newFakeForgejoServer(t)
+
+	child, err := supervisor.Start(t.Context(), supervisor.Config{
+		Cmd: []string{binPath, "--transport", "stdio", "--url", fakeForgejo.URL},
+		Env: []string{
+			"FORGEJO_ACCESS_TOKEN=integration-test-token",
+		},
+		OnStderr: func(line string) { t.Logf("forgejo-mcp[stderr]: %s", line) },
+	})
+	if err != nil {
+		t.Fatalf("Start forgejo-mcp: %v", err)
+	}
+	t.Cleanup(func() {
+		stopCtx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+		defer cancel()
+		_ = child.Stop(stopCtx)
+	})
+
+	b := bridge.New(child.Stdin, child.Stdout, child.Done(), brokerlog.Discard())
+	b.Start()
+
+	srv := httptest.NewServer(http.HandlerFunc(b.HandleSSE))
+	t.Cleanup(srv.Close)
+
+	// 1. initialize — kicks off the MCP handshake.
+	initBody := `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"fjmcp-broker-test","version":"1"}}}`
+	initResp := postSSEMustOK(t, srv.URL, initBody)
+	if !strings.Contains(initResp, `"protocolVersion"`) {
+		t.Errorf("initialize response missing protocolVersion: %s", initResp)
+	}
+	if !strings.Contains(initResp, `"serverInfo"`) {
+		t.Errorf("initialize response missing serverInfo: %s", initResp)
+	}
+
+	// 2. notifications/initialized — required by the MCP spec before any
+	// further requests. Bridge returns 204 for notifications.
+	notified := postBody(t, srv.URL, `{"jsonrpc":"2.0","method":"notifications/initialized"}`)
+	if notified.StatusCode != http.StatusNoContent {
+		t.Errorf("notifications/initialized status = %d, want 204", notified.StatusCode)
+	}
+
+	// 3. tools/list — must include the version tool.
+	listBody := `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`
+	listResp := postSSEMustOK(t, srv.URL, listBody)
+	if !strings.Contains(listResp, "get_forgejo_mcp_server_version") {
+		t.Errorf("tools/list missing get_forgejo_mcp_server_version. Body: %s", listResp)
+	}
+
+	// 4. tools/call get_forgejo_mcp_server_version — does no Forgejo
+	// network work, so the fake instance is irrelevant here. We just
+	// confirm the call succeeds and a result comes back.
+	callBody := `{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_forgejo_mcp_server_version","arguments":{}}}`
+	callResp := postSSEMustOK(t, srv.URL, callBody)
+	if !strings.Contains(callResp, `"content"`) {
+		t.Errorf("tools/call response missing content. Body: %s", callResp)
+	}
+	// Sanity: response should not be an error.
+	if strings.Contains(callResp, `"isError":true`) {
+		t.Errorf("tools/call returned isError=true. Body: %s", callResp)
+	}
+}
+
+// findOrBuildForgejoMCP locates a forgejo-mcp binary the test can spawn.
+// Search order:
+//  1. $FORGEJO_MCP_BIN
+//  2. ../../../forgejo-mcp/forgejo-mcp (sibling repo with a built binary)
+//  3. go build of ../../../forgejo-mcp into a temp dir
+// Skips the test (not fails) if none of those work.
+func findOrBuildForgejoMCP(t *testing.T) string {
+	t.Helper()
+
+	if p := os.Getenv("FORGEJO_MCP_BIN"); p != "" {
+		if _, err := os.Stat(p); err == nil {
+			return p
+		}
+		t.Skipf("FORGEJO_MCP_BIN=%q does not exist", p)
+	}
+
+	// Sibling-repo binary.
+	if abs, err := filepath.Abs("../../../forgejo-mcp/forgejo-mcp"); err == nil {
+		if _, err := os.Stat(abs); err == nil {
+			return abs
+		}
+	}
+
+	// Sibling-repo source build.
+	if abs, err := filepath.Abs("../../../forgejo-mcp"); err == nil {
+		if _, err := os.Stat(filepath.Join(abs, "main.go")); err == nil {
+			bin := filepath.Join(t.TempDir(), "forgejo-mcp")
+			build := exec.Command("go", "build", "-o", bin, ".")
+			build.Dir = abs
+			build.Env = os.Environ()
+			out, err := build.CombinedOutput()
+			if err != nil {
+				t.Skipf("go build of sibling forgejo-mcp failed: %v\n%s", err, out)
+			}
+			return bin
+		}
+	}
+
+	t.Skip("forgejo-mcp binary not found: set $FORGEJO_MCP_BIN or place a sibling repo at ../forgejo-mcp")
+	return ""
+}
+
+// newFakeForgejoServer stands up the minimum Forgejo API surface
+// forgejo-mcp probes during startup:
+//   - GET /api/v1/version — the SDK requires the server be >= 1.11.0
+//   - GET /api/v1/user    — VerifyConnection's authenticated probe
+//
+// Any other path responds 404 with a t.Log so future probes added
+// upstream show up clearly in test output.
+func newFakeForgejoServer(t *testing.T) *httptest.Server {
+	t.Helper()
+	mux := http.NewServeMux()
+	mux.HandleFunc("/api/v1/version", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"version":"11.0.0"}`)
+	})
+	mux.HandleFunc("/api/v1/user", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"id":1,"login":"integration-tester","username":"integration-tester","full_name":"Integration Tester","email":"itester@example.com","avatar_url":"https://example.com/a.png"}`)
+	})
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		t.Logf("fake forgejo: unexpected probe %s %s", r.Method, r.URL.Path)
+		w.WriteHeader(http.StatusNotFound)
+	})
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+// postSSEMustOK posts a JSON-RPC body, expects a 200 + text/event-stream
+// response, and returns the raw body. Fails the test on any other shape.
+func postSSEMustOK(t *testing.T, url, body string) string {
+	t.Helper()
+	resp := postBody(t, url, body)
+	defer resp.Body.Close()
+	b, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("POST %s: status %d, body %s", url, resp.StatusCode, b)
+	}
+	if ct := resp.Header.Get("Content-Type"); !strings.HasPrefix(ct, "text/event-stream") {
+		t.Fatalf("POST %s: Content-Type %q, want text/event-stream", url, ct)
+	}
+	return string(b)
+}
+
+func postBody(t *testing.T, url, body string) *http.Response {
+	t.Helper()
+	req, err := http.NewRequestWithContext(t.Context(), http.MethodPost, url, strings.NewReader(body))
+	if err != nil {
+		t.Fatalf("build request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("POST: %v", err)
+	}
+	return resp
+}
+