test: add cross-module dependency testing and CI pipeline

Implements a comprehensive dependency testing strategy to catch
regressions when any component changes:

Phase 1 — Isolated Contract Tests (no Docker):
- Gateway <-> Broker: contract_test.go (8 tests)
  - Verifies Gateway handles Broker schema drift (null fields,
    missing state, empty body, status code mapping)
  - Tests Broker-down scenario
- Gateway <-> Bridge: fault_injection_test.go (3 tests)
  - Verifies 429 rate limiting is treated as recoverable (retried)
  - Verifies 401 unauthorized is treated as permanent (no retry)
  - Verifies ErrorEnvelope.StatusCode type assertion contract

Phase 2 — E2E Orchestration:
- scripts/test-e2e.sh: runs Phase 1 then optionally spins up the
  full Docker stack and runs all SDK smoke tests against it

Phase 3 — CI Pipeline:
- .github/workflows/ci.yml: runs on every PR and push to main
  - Go: SDK, Gateway, Bridge, Broker tests
  - TypeScript: SDK build verification
  - Python: full unit test suite

Makefile updated:
- 'make test' now includes Python + TS SDKs
- 'make test-e2e' for full dependency verification

Verified: make test ✅ (all modules pass)

Author: sangalo20

.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Unit & Contract Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: nexus-gateway/go.mod
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install TS SDK dependencies
+        working-directory: nexus-sdk-ts
+        run: npm ci
+
+      # --- Go Modules ---
+      - name: Go SDK — test
+        working-directory: nexus-sdk
+        run: go test ./... -count=1
+
+      - name: Gateway — test (incl. broker contract tests)
+        working-directory: nexus-gateway
+        run: go test ./... -count=1
+
+      - name: Bridge — test (incl. fault injection)
+        working-directory: nexus-bridge
+        run: go test ./... -count=1 -timeout=30s
+
+      - name: Broker — test
+        working-directory: nexus-broker
+        run: go test ./... -count=1
+
+      # --- TypeScript SDK ---
+      - name: TypeScript SDK — build
+        working-directory: nexus-sdk-ts
+        run: npm run build
+
+      # --- Python SDK ---
+      - name: Python SDK — test
+        working-directory: nexus-sdk-python
+        run: python3 -m unittest discover -s tests -v

Makefile

@@ -21,13 +21,19 @@ logs:
 build:
 	docker-compose build
 
-# Run all tests (Broker + Gateway + Bridge + SDK)
+# Run all unit + contract tests (no Docker required)
 test:
 	@echo "Running tests for all modules..."
 	(cd nexus-broker && go test ./...)
 	(cd nexus-gateway && go test ./...)
-	(cd nexus-bridge && go test ./...)
+	(cd nexus-bridge && go test ./... -timeout=30s)
 	(cd nexus-sdk && go test ./...)
+	(cd nexus-sdk-python && python3 -m unittest discover -s tests -q)
+	(cd nexus-sdk-ts && npm run build)
+
+# Run full E2E dependency tests (Phase 1 + Phase 2 with Docker)
+test-e2e:
+	@bash scripts/test-e2e.sh
 
 # Clean up build artifacts and temp files
 clean:

nexus-bridge/fault_injection_test.go

@@ -0,0 +1,148 @@
+package bridge_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/Prescott-Data/nexus-framework/nexus-bridge"
+	"github.com/Prescott-Data/nexus-framework/nexus-bridge/pkg/auth"
+	oauthsdk "github.com/Prescott-Data/nexus-framework/nexus-sdk"
+)
+
+// --- Gateway <-> Bridge Fault Injection Tests ---
+// These tests verify that the Bridge correctly handles error conditions
+// from the Gateway (via the SDK). If the Gateway's error contract changes,
+// these tests will fail, preventing silent dependency breaks.
+
+// mockFaultTokenProvider lets us inject specific SDK errors.
+type mockFaultTokenProvider struct {
+	getTokenFunc          func(ctx context.Context, connectionID string) (*auth.Token, error)
+	refreshConnectionFunc func(ctx context.Context, connectionID string) (*auth.Token, error)
+}
+
+func (m *mockFaultTokenProvider) GetToken(ctx context.Context, connectionID string) (*auth.Token, error) {
+	return m.getTokenFunc(ctx, connectionID)
+}
+
+func (m *mockFaultTokenProvider) RefreshConnection(ctx context.Context, connectionID string) (*auth.Token, error) {
+	if m.refreshConnectionFunc != nil {
+		return m.refreshConnectionFunc(ctx, connectionID)
+	}
+	return nil, errors.New("not implemented")
+}
+
+// TestBridge_RateLimited429_IsRecoverable verifies that when the Gateway
+// returns a 429 (via ErrorEnvelope.StatusCode), the Bridge treats it as
+// a recoverable error and retries instead of marking it permanent.
+func TestBridge_RateLimited429_IsRecoverable(t *testing.T) {
+	t.Parallel()
+
+	var callCount int
+	provider := &mockFaultTokenProvider{
+		getTokenFunc: func(ctx context.Context, connectionID string) (*auth.Token, error) {
+			callCount++
+			if callCount <= 2 {
+				// Simulate what the SDK returns on 429
+				return nil, oauthsdk.ErrorEnvelope{
+					Code:       "rate_limited",
+					Message:    "Too Many Requests",
+					StatusCode: 429,
+				}
+			}
+			// Third call succeeds
+			return &auth.Token{
+				Strategy:    auth.AuthStrategy{Type: "oauth2"},
+				Credentials: auth.Credentials{"access_token": "tok"},
+				ExpiresAt:   time.Now().Add(1 * time.Hour).Unix(),
+			}, nil
+		},
+	}
+
+	retryPolicy := bridge.RetryPolicy{
+		MinBackoff: 10 * time.Millisecond,
+		MaxBackoff: 50 * time.Millisecond,
+		Jitter:     5 * time.Millisecond,
+	}
+	b := bridge.New(provider, bridge.WithRetryPolicy(retryPolicy), bridge.WithLogger(&testLogger{t: t}))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	// MaintainWebSocket will try to get a token, get 429'd twice, then succeed
+	// and try to connect to a bogus URL — which fails permanently.
+	// We just need to verify the 429 was retried (callCount > 1).
+	_ = b.MaintainWebSocket(ctx, "conn-rate-limited", "ws://127.0.0.1:1", &noopHandler{})
+
+	if callCount < 2 {
+		t.Errorf("expected at least 2 GetToken calls (429 should be retried), got %d", callCount)
+	}
+}
+
+// TestBridge_AuthError401_IsPermanent verifies that a 401 Unauthorized
+// from the Gateway is treated as a permanent error (no retry).
+func TestBridge_AuthError401_IsPermanent(t *testing.T) {
+	t.Parallel()
+
+	var callCount int
+	provider := &mockFaultTokenProvider{
+		getTokenFunc: func(ctx context.Context, connectionID string) (*auth.Token, error) {
+			callCount++
+			return nil, oauthsdk.ErrorEnvelope{
+				Code:       "unauthorized",
+				Message:    "Invalid credentials",
+				StatusCode: 401,
+			}
+		},
+	}
+
+	retryPolicy := bridge.RetryPolicy{
+		MinBackoff: 10 * time.Millisecond,
+		MaxBackoff: 50 * time.Millisecond,
+		Jitter:     5 * time.Millisecond,
+	}
+	b := bridge.New(provider, bridge.WithRetryPolicy(retryPolicy), bridge.WithLogger(&testLogger{t: t}))
+
+	err := b.MaintainWebSocket(context.Background(), "conn-401", "ws://127.0.0.1:1", &noopHandler{})
+
+	// Should be a PermanentError — not retried
+	var permErr *bridge.PermanentError
+	if !errors.As(err, &permErr) {
+		t.Fatalf("expected PermanentError for 401, got: %v", err)
+	}
+
+	if callCount != 1 {
+		t.Errorf("expected exactly 1 GetToken call (401 should NOT be retried), got %d", callCount)
+	}
+}
+
+// TestBridge_SDKErrorEnvelopeContract verifies the Bridge can type-assert
+// on oauthsdk.ErrorEnvelope and access StatusCode. If the SDK changes the
+// ErrorEnvelope type or removes StatusCode, this test breaks.
+func TestBridge_SDKErrorEnvelopeContract(t *testing.T) {
+	t.Parallel()
+
+	// Create an ErrorEnvelope as the SDK would
+	err := oauthsdk.ErrorEnvelope{
+		Code:       "rate_limited",
+		Message:    "slow down",
+		StatusCode: 429,
+	}
+
+	// Verify it implements the error interface
+	var _ error = err
+
+	// Verify errors.As works (this is how the bridge detects it)
+	var envErr oauthsdk.ErrorEnvelope
+	if !errors.As(err, &envErr) {
+		t.Fatal("errors.As failed to match ErrorEnvelope")
+	}
+
+	if envErr.StatusCode != 429 {
+		t.Errorf("expected StatusCode 429, got %d", envErr.StatusCode)
+	}
+	if envErr.Code != "rate_limited" {
+		t.Errorf("expected Code 'rate_limited', got %q", envErr.Code)
+	}
+}