Merge branch 'main' into feat/hedged-reads

Author: pchieneye

.adr-dir

@@ -0,0 +1 @@
+docs/adr

.dockerignore

@@ -0,0 +1,38 @@
+# Exclude the .git directory and scratch artefacts so the build context stays small
+# and reproducible.
+.git
+.gitignore
+.github
+
+# Local config and secrets (env files must never ship in the image).
+.env
+.env.*
+*.pem
+*.key
+audit.log
+coverage.out
+coverage.html
+
+# CI / development helpers
+scripts
+tools
+tests/integration
+staging
+tmp
+
+# Editor / OS junk
+.DS_Store
+*.swp
+*.swo
+
+# Coverage profiles and reports (regenerated in CI).
+*.coverprofile
+
+# Built binary (regenerated in Dockerfile).
+stellarbill-backend
+.git
+.github
+docs
+*.md
+LICENSE
+Makefile

.github/workflows/benchmarks.yml

@@ -81,41 +81,26 @@ jobs:
       - name: Enforce benchmark thresholds
         run: |
           go test ./internal/handlers/... -bench=. -benchmem -benchtime=3s -run=^$ 2>&1 | tee threshold_check.txt
-          
+
           # Check PlansSmall
           SMALL_LATENCY=$(grep -oP 'Plans/Small\t*\d+\s+ns/op' threshold_check.txt | awk '{print $2}')
           if [ -n "$SMALL_LATENCY" ] && [ "$SMALL_LATENCY" -gt 30000 ]; then
             echo "❌ Plans Small latency ($SMALL_LATENCY ns) exceeds threshold (30000 ns)"
             exit 1
           fi
-          
-          # Check SubscriptionsSmall  
+
+          # Check SubscriptionsSmall
           SUB_LATENCY=$(grep -oP 'Subscriptions/Small\t*\d+\s+ns/op' threshold_check.txt | awk '{print $2}')
           if [ -n "$SUB_LATENCY" ] && [ "$SUB_LATENCY" -gt 35000 ]; then
             echo "❌ Subscriptions Small latency ($SUB_LATENCY ns) exceeds threshold (35000 ns)"
             exit 1
           fi
-          
-          echo "✅ All benchmark thresholds enforced"
-      
-      - name: Enforce benchmark thresholds
-        run: |
+
           echo "## Performance Threshold Check" >> $GITHUB_STEP_SUMMARY
-          
-          # Run threshold-enforcing benchmarks
-          go test ./internal/handlers/... -run=^TestBenchmarkThresholds -v | tee threshold_check.txt
-          
-          # Check if thresholds are being met
-          if grep -q "FAIL\|FAIL" threshold_check.txt; then
-            echo "❌ Performance thresholds not met"
-            cat threshold_check.txt >> $GITHUB_STEP_SUMMARY
-            exit 1
-          fi
-          
-          echo "✅ All benchmark thresholds passed"
           echo '```' >> $GITHUB_STEP_SUMMARY
           cat threshold_check.txt >> $GITHUB_STEP_SUMMARY
           echo '```' >> $GITHUB_STEP_SUMMARY
+          echo "✅ All benchmark thresholds enforced"
       
       - name: Upload results
         uses: actions/upload-artifact@v4
@@ -130,17 +115,19 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: benchmark-baseline
-          path: new.txt
+          path: |
+            handlers_new.txt
+            subscriptions_new.txt
 
   security:
     runs-on: ubuntu-latest
-    
+
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
-      
+        uses: actions/checkout@v4
+
       - name: Set up Go
-        uses: actions/setup-go@v4
+        uses: actions/setup-go@v5
         with:
           go-version: '1.22'
 

.github/workflows/buf.yml

@@ -0,0 +1,69 @@
+name: Buf Lint
+
+# Runs Buf lint and breaking-change detection on every push and PR.
+# Proto files live in proto/; OpenAPI linting is handled via buf plugins
+# when a buf.build/community/stephanain-openapi plugin is configured.
+#
+# This job is intentionally separate from ci.yml so it can be required
+# independently on branch protection rules.
+
+on:
+  push:
+    branches: [main, master, develop]
+    paths:
+      - 'proto/**'
+      - 'openapi/**'
+      - 'buf.yaml'
+      - 'buf.gen.yaml'
+      - '.github/workflows/buf.yml'
+  pull_request:
+    branches: [main, master, develop]
+    paths:
+      - 'proto/**'
+      - 'openapi/**'
+      - 'buf.yaml'
+      - 'buf.gen.yaml'
+      - '.github/workflows/buf.yml'
+
+concurrency:
+  group: buf-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  buf-lint:
+    name: Buf Lint & Breaking Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Full history required for breaking-change detection against main.
+          fetch-depth: 0
+
+      - name: Set up Buf
+        uses: bufbuild/buf-setup-action@v1
+        with:
+          version: '1.32.2'
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Buf lint
+        run: buf lint
+        # Lint always runs; an empty proto/ dir with no .proto files
+        # is valid — buf exits 0 when there is nothing to lint.
+
+      - name: Buf breaking-change detection
+        # Only run on pull_request so we always have a clear base branch.
+        if: github.event_name == 'pull_request'
+        run: |
+          buf breaking --against '.git#branch=${{ github.base_ref }}'
+        # This step FAILS if a field is removed, a type is changed, or an
+        # enum value is removed relative to the base branch.
+        # Use `buf breaking --error-format=json` for machine-parseable output.
+
+      - name: Buf lint report (summary)
+        if: failure()
+        run: |
+          echo "## Buf Lint Report" >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          buf lint --error-format=text 2>&1 || true >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"

.github/workflows/chaos-migration-drill.yml

@@ -0,0 +1,91 @@
+name: Chaos Migration Drill
+
+# Nightly chaos drill: starts a migration, kills Postgres mid-flight,
+# restarts it, and verifies the runner recovers cleanly.
+#
+# SAFETY: runs only on ephemeral containers — never against a shared DB.
+# The workflow does NOT require DATABASE_URL from secrets; it spins up
+# a throwaway Postgres container on the runner itself.
+
+on:
+  schedule:
+    # Nightly at 02:00 UTC (low-traffic window)
+    - cron: '0 2 * * *'
+  workflow_dispatch:
+    inputs:
+      kill_delay_min:
+        description: 'Min seconds before kill (float)'
+        default: '0.05'
+        required: false
+      kill_delay_max:
+        description: 'Max seconds before kill (float)'
+        default: '2.0'
+        required: false
+  pull_request:
+    branches: [main, master, develop]
+    paths:
+      - 'internal/migrations/**'
+      - 'scripts/drills/kill_pg_migration.sh'
+      - '.github/workflows/chaos-migration-drill.yml'
+      - 'migrations/**'
+
+concurrency:
+  group: chaos-drill-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  chaos-migration-drill:
+    name: Kill-During-Migration Drill
+    runs-on: ubuntu-latest
+    # Hard timeout: the drill should complete well within 10 minutes.
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Run chaos migration drill
+        env:
+          POSTGRES_IMAGE: postgres:17-alpine
+          POSTGRES_CONTAINER: stellabill-chaos-pg
+          POSTGRES_USER: drill
+          POSTGRES_PASSWORD: drill
+          POSTGRES_DB: drill
+          POSTGRES_PORT: '15432'
+          KILL_DELAY_MIN: ${{ github.event.inputs.kill_delay_min || '0.05' }}
+          KILL_DELAY_MAX: ${{ github.event.inputs.kill_delay_max || '2.0' }}
+          RESULTS_CSV: drill-results.csv
+          SLACK_WEBHOOK_URL: ${{ secrets.CHAOS_DRILL_SLACK_WEBHOOK }}
+        run: bash scripts/drills/kill_pg_migration.sh
+
+      - name: Upload drill results artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: chaos-drill-results-${{ github.run_id }}
+          path: |
+            drill-results.csv
+            /tmp/drill-migrate-pre.log
+            /tmp/drill-migrate-post.log
+          retention-days: 30
+
+      - name: Summarise result
+        if: always()
+        run: |
+          echo "## Chaos Migration Drill Results" >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          cat drill-results.csv 2>/dev/null || echo "(no results file)"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Notify on failure (no Slack webhook configured)
+        if: failure() && env.SLACK_WEBHOOK_URL == ''
+        run: |
+          echo "::warning::Chaos drill failed. Configure CHAOS_DRILL_SLACK_WEBHOOK secret for Slack notifications."
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.CHAOS_DRILL_SLACK_WEBHOOK }}