chore(stovepipe): set up dlv debugging setup in container

.gitignore

@@ -2,7 +2,8 @@
 /bazel-*
 MODULE.bazel.lock
 /pkg/**
-.vscode/
+.vscode/*
+!.vscode/launch.json
 .idea/
 .claude/
 .mcp.json

.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug: attach (dlv in docker)",
+      "type": "go",
+      "request": "attach",
+      "mode": "remote",
+      "cwd": "${workspaceFolder}",
+      "host": "127.0.0.1",
+      "port": 2345,
+      "showLog": true
+    }
+  ]
+}

Makefile

@@ -14,6 +14,7 @@ SUBMITQUEUE_LOCAL_PROJECT = submitqueue
 
 # Stovepipe compose file (single Ping-only service)
 STOVEPIPE_COMPOSE_FILE = service/stovepipe/docker-compose.yml
+STOVEPIPE_DEBUG_COMPOSE_FILE = service/stovepipe/docker-compose.debug.yml
 
 # Fixed project name for local manual testing (tests use unique random names)
 STOVEPIPE_LOCAL_PROJECT = stovepipe
@@ -51,7 +52,7 @@ define assert_clean
 	fi
 endef
 
-.PHONY: build build-all-linux build-runway-linux build-submitqueue-gateway-linux build-submitqueue-orchestrator-linux build-stovepipe-linux check-gazelle check-mocks check-tidy clean clean-proto deps e2e-test fmt gazelle integration-test integration-test-submitqueue-consumer integration-test-extensions integration-test-submitqueue-gateway integration-test-submitqueue-orchestrator license-fix lint lint-fmt lint-license local-init-runway-queue-schema local-init-stovepipe-schemas local-runway-start local-runway-stop local-submitqueue-clean local-submitqueue-gateway-start local-submitqueue-gateway-stop local-init-submitqueue-schemas local-submitqueue-logs local-submitqueue-orchestrator-start local-submitqueue-orchestrator-stop local-submitqueue-ps local-submitqueue-restart local-submitqueue-start local-stop local-stovepipe-logs local-stovepipe-start local-stovepipe-stop mocks proto query-deps query-targets run-client-runway run-client-submitqueue-gateway run-client-submitqueue-orchestrator run-client-stovepipe run-queue-admin test test-no-cache tidy tidy-bazel tidy-go help
+.PHONY: build build-all-linux build-runway-linux build-submitqueue-gateway-linux build-submitqueue-orchestrator-linux build-stovepipe-linux build-stovepipe-linux-debug check-gazelle check-mocks check-tidy clean clean-proto deps e2e-test fmt gazelle integration-test integration-test-submitqueue-consumer integration-test-extensions integration-test-submitqueue-gateway integration-test-submitqueue-orchestrator license-fix lint lint-fmt lint-license local-init-runway-queue-schema local-init-stovepipe-schemas local-runway-start local-runway-stop local-submitqueue-clean local-submitqueue-gateway-start local-submitqueue-gateway-stop local-init-submitqueue-schemas local-submitqueue-logs local-submitqueue-orchestrator-start local-submitqueue-orchestrator-stop local-submitqueue-ps local-submitqueue-restart local-submitqueue-start local-stop local-stovepipe-debug-start local-stovepipe-logs local-stovepipe-start local-stovepipe-stop mocks proto query-deps query-targets run-client-runway run-client-submitqueue-gateway run-client-submitqueue-orchestrator run-client-stovepipe run-queue-admin test test-no-cache tidy tidy-bazel tidy-go help
 
 
 build: ## Build all services and examples
@@ -95,6 +96,14 @@ build-stovepipe-linux: ## Build Stovepipe Linux binary for Docker
 	 cp -f bazel-bin/service/stovepipe/server/stovepipe .docker-bin/stovepipe
 	@echo "Stovepipe Linux binary ready at .docker-bin/stovepipe"
 
+build-stovepipe-linux-debug: ## Build Stovepipe Linux debug binary for Docker/delve (symbols, no optimizations)
+	@echo "Building Stovepipe Linux debug binary for Docker..."
+	@$(BAZEL) build --compilation_mode=dbg --platforms=@rules_go//go/toolchain:linux_amd64 //service/stovepipe/server:stovepipe
+	@mkdir -p .docker-bin
+	@cp -f bazel-bin/service/stovepipe/server/stovepipe_/stovepipe .docker-bin/stovepipe-debug 2>/dev/null || \
+	 cp -f bazel-bin/service/stovepipe/server/stovepipe .docker-bin/stovepipe-debug
+	@echo "Stovepipe Linux debug binary ready at .docker-bin/stovepipe-debug"
+
 check-gazelle: ## Check BUILD.bazel files are up to date
 	@echo "Running Gazelle to check BUILD files..."
 	@$(BAZEL) run //:gazelle
@@ -320,6 +329,19 @@ local-stop: ## Stop all services (keep data)
 	@$(COMPOSE) -f $(RUNWAY_COMPOSE_FILE) -p $(RUNWAY_LOCAL_PROJECT) down
 	@echo "Services stopped. Data volumes preserved."
 
+local-stovepipe-debug-start: build-stovepipe-linux-debug ## Start Stovepipe under delve in Docker (attach IDE to :2345)
+	@echo "Starting Stovepipe service with compose (debug)..."
+	@$(COMPOSE) -f $(STOVEPIPE_COMPOSE_FILE) -f $(STOVEPIPE_DEBUG_COMPOSE_FILE) -p $(STOVEPIPE_LOCAL_PROJECT) up -d --build --wait
+	@echo "Applying storage and queue schemas..."
+	@$(MAKE) -s local-init-stovepipe-schemas
+	@echo ""
+	@echo "✅ Stovepipe debug is running (delve :2345)!"
+	@echo ""
+	@$(COMPOSE) -f $(STOVEPIPE_COMPOSE_FILE) -f $(STOVEPIPE_DEBUG_COMPOSE_FILE) -p $(STOVEPIPE_LOCAL_PROJECT) ps
+	@echo ""
+	@echo "Stovepipe gRPC port: $$(docker port $(STOVEPIPE_LOCAL_PROJECT)-stovepipe-service-1 8080 2>/dev/null | cut -d: -f2 || echo 'unknown')"
+	@echo "Delve: 127.0.0.1:2345 — run launch config \"Debug: attach (dlv in docker)\""
+
 local-stovepipe-logs: ## View logs from the running Stovepipe service
 	@$(COMPOSE) -f $(STOVEPIPE_COMPOSE_FILE) -p $(STOVEPIPE_LOCAL_PROJECT) logs -f
 

service/stovepipe/README.md

@@ -52,6 +52,19 @@ make local-stovepipe-logs    # follow logs
 
 The compose service key is **`stovepipe-service`**, so under the default project **`stovepipe`** the container is **`stovepipe-stovepipe-service-1`**. Inside the container the server listens on `:8080`, published on a random ephemeral host port.
 
+### Breakpoint debugging (dlv debugger)
+
+```bash
+make local-stovepipe-debug-start
+```
+
+Attach with `.vscode/launch.json` (**Debug: attach (dlv in docker)**), then send a request using the gRPC port from the make output.
+
+```bash
+# Ingest example
+grpcurl -plaintext -d '{"queue":"monorepo/main"}' localhost:PORT uber.submitqueue.stovepipe.Stovepipe/Ingest
+```
+
 ### Bazel / Go
 
 ```bash
@@ -75,4 +88,3 @@ grpcurl -plaintext -d '{"message": "hello"}' localhost:8083 uber.submitqueue.sto
 ## Shutdown
 
 The server handles `SIGINT` / `SIGTERM` gracefully: it drains in-flight RPCs, then stops the process consumer (30s timeout). It exits `0` on clean shutdown, `143` (128 + SIGTERM) when stopped by signal, and `1` on startup/runtime errors (details on stderr). Shutdown errors override the signal exit code.
-</content>

service/stovepipe/docker-compose.debug.yml

@@ -0,0 +1,7 @@
+# Debug override for make local-stovepipe-debug-start — delve on :2345.
+services:
+  stovepipe-service:
+    build:
+      dockerfile: service/stovepipe/server/Dockerfile.debug
+    ports:
+      - "2345:2345"

service/stovepipe/server/Dockerfile.debug

@@ -0,0 +1,17 @@
+# Debug image: delve wraps a -compilation_mode=dbg binary (make build-stovepipe-linux-debug).
+FROM golang:1.24-bookworm AS dlv
+RUN go install github.com/go-delve/delve/cmd/dlv@v1.24.2
+
+FROM debian:bookworm-slim
+
+RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
+COPY --from=dlv /go/bin/dlv /usr/local/bin/dlv
+WORKDIR /root/
+
+# Copy pre-built Linux debug binary.
+# Built via: make build-stovepipe-linux-debug
+COPY .docker-bin/stovepipe-debug ./stovepipe
+
+EXPOSE 8080 2345
+
+CMD ["dlv", "exec", "./stovepipe", "--headless", "--listen=:2345", "--api-version=2", "--accept-multiclient"]