feat(qwp): add QWP WebSocket transport (store-and-forward ingest, typed errors, failover, query client)

.github/workflows/binary-check.yml

@@ -0,0 +1,60 @@
+name: Binary check
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  reject-binaries:
+    name: Reject committed executables
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Scan for executable binaries
+        run: |
+          set -euo pipefail
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            base="${{ github.event.pull_request.base.sha }}"
+            head="${{ github.event.pull_request.head.sha }}"
+            list_cmd=(git diff --name-only --diff-filter=AMRC "$base...$head")
+            scope="PR diff ($base..$head)"
+          else
+            list_cmd=(git ls-files)
+            scope="full tree"
+          fi
+          count=0
+          violations=()
+          while IFS= read -r f; do
+            count=$((count + 1))
+            [ -f "$f" ] || continue
+            mime=$(file --brief --mime-type -- "$f" 2>/dev/null || true)
+            case "$mime" in
+              *application/x-mach-binary*|\
+              *application/x-executable*|\
+              *application/x-pie-executable*|\
+              *application/x-sharedlib*|\
+              *application/x-dosexec*)
+                summary=$(printf '%s\n' "$mime" | head -n1)
+                violations+=("$f — $summary")
+                ;;
+            esac
+          done < <("${list_cmd[@]}")
+          echo "Scanned $scope: $count file(s)"
+          if [ ${#violations[@]} -gt 0 ]; then
+            echo "::error::Committed executable binaries detected:"
+            for v in "${violations[@]}"; do
+              echo "  - $v"
+            done
+            echo
+            echo "Build artifacts must not be committed. For example dirs, use"
+            echo "'go run .' (no artifact) or 'go install' with GOBIN pointing"
+            echo "at a gitignored directory."
+            exit 1
+          fi
+          echo "OK: no committed executables."

.github/workflows/build.yml

@@ -2,6 +2,88 @@ name: build
 on: [push]
 
 jobs:
+  # Cross-repo trigger: fire the questdb-enterprise
+  # build-and-test-e2e-go-client pipeline with this build's SHA so
+  # the go_client-marked failover tests run against an Enterprise
+  # primary. The Enterprise pipeline posts a status check back on the
+  # PR (`enterprise-e2e-go-client` context); this job fire-and-forgets.
+  dispatch-enterprise-e2e:
+    runs-on: ubuntu-latest
+    if: ${{ !github.event.repository.fork }}
+    steps:
+      - name: Queue enterprise go_client e2e
+        env:
+          ENT_DISPATCH_PAT: ${{ secrets.ENT_DISPATCH_PAT }}
+          ENT_ORG_URL: ${{ secrets.ENT_ORG_URL }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "${ENT_DISPATCH_PAT:-}" ] || [ -z "${ENT_ORG_URL:-}" ]; then
+            echo "ENT_DISPATCH_PAT or ENT_ORG_URL not set; skipping enterprise e2e dispatch."
+            exit 0
+          fi
+
+          PROJECT="questdb-enterprise"
+          PIPELINE_NAME="build-and-test-e2e-go-client"
+
+          echo "Looking up '${PIPELINE_NAME}' in '${PROJECT}'..."
+          PIPELINES=$(curl -fsS -u ":${ENT_DISPATCH_PAT}" \
+            "${ENT_ORG_URL}${PROJECT}/_apis/pipelines?api-version=7.0")
+          PIPELINE_ID=$(echo "$PIPELINES" | jq -r --arg n "$PIPELINE_NAME" \
+            '.value[] | select(.name == $n) | .id' | head -1)
+
+          if [ -z "$PIPELINE_ID" ] || [ "$PIPELINE_ID" = "null" ]; then
+            echo "Pipeline '${PIPELINE_NAME}' not found in '${PROJECT}'; skipping."
+            exit 0
+          fi
+
+          CLIENT_BRANCH="${GITHUB_REF_NAME}"
+          CLIENT_PR_NUMBER=""
+
+          # Azure DevOps rejects empty-string template parameters with
+          # "The 'X' parameter is not a valid String." even when the
+          # pipeline YAML declares `type: string, default: ''`. Omitting
+          # the key entirely lets the YAML default kick in; the
+          # enterprise pipeline already handles empty goClientPrNumber
+          # by skipping the GitHub PR status post.
+          BODY=$(jq -n \
+            --arg commit "${GITHUB_SHA}" \
+            --arg pr "${CLIENT_PR_NUMBER}" \
+            --arg branch "${CLIENT_BRANCH}" \
+            '{
+              templateParameters: ({
+                goClientCommit: $commit,
+                goClientPrNumber: $pr,
+                clientBranch: $branch
+              } | with_entries(select(.value != ""))),
+              resources: { repositories: { self: { refName: "refs/heads/main" } } }
+            }')
+
+          echo "Dispatching enterprise e2e: commit=${GITHUB_SHA} branch=${CLIENT_BRANCH}"
+
+          # Capture status and body separately so we can surface Azure
+          # DevOps's error message on 4xx. With -fsS the body is dropped
+          # and only "curl: (22) ... error: 400" reaches the log, which
+          # is useless for diagnosing parameter / YAML mismatches.
+          RESPONSE_FILE=$(mktemp)
+          HTTP_STATUS=$(curl -sS -u ":${ENT_DISPATCH_PAT}" \
+            -H "Content-Type: application/json" \
+            -X POST \
+            -d "$BODY" \
+            -o "$RESPONSE_FILE" \
+            -w '%{http_code}' \
+            "${ENT_ORG_URL}${PROJECT}/_apis/pipelines/${PIPELINE_ID}/runs?api-version=7.0")
+
+          if [ "$HTTP_STATUS" -lt 200 ] || [ "$HTTP_STATUS" -ge 300 ]; then
+            echo "Dispatch failed with HTTP ${HTTP_STATUS}. Response body:"
+            cat "$RESPONSE_FILE"
+            echo ""
+            exit 1
+          fi
+
+          RUN_URL=$(jq -r '._links.web.href // ""' "$RESPONSE_FILE")
+          echo "Enterprise build queued: ${RUN_URL}"
+
   test:
     runs-on: ubuntu-latest
     strategy:
@@ -21,10 +103,57 @@ jobs:
           cache: true
 
       - name: Run vet
+        # Pin to the matrix-installed Go. Without this, a stray
+        # `toolchain` line re-added to go.mod by `go mod tidy` on a
+        # newer box would silently switch this job off the matrix
+        # version; `local` makes that fail loudly instead.
+        env:
+          GOTOOLCHAIN: local
         run: go vet ./...
 
       - name: Run Staticcheck
         run: go run honnef.co/go/tools/cmd/staticcheck@v0.7.0 ./...
 
+      - name: Build bench modules
+        # bench/* are separate Go modules with their own go.mod, so
+        # the root `go vet`/`go test ./...` above never touches them.
+        # Project convention is that bench/ builds. `go mod tidy
+        # -diff` fails (with an actionable diff) on go.mod/go.sum
+        # drift — e.g. an indirect dep pulled transitively from the
+        # root via `replace => ../..` but missing from the bench
+        # go.mod; `go build ./...` then proves they compile. The loop
+        # globs bench/*/go.mod so new bench modules are auto-gated.
+        # GOTOOLCHAIN=local pins to the matrix Go (see "Run vet"); the
+        # bench go.mod `go` directive is 1.23, satisfied by both
+        # matrix versions.
+        env:
+          GOTOOLCHAIN: local
+        run: |
+          set -euo pipefail
+          for mod in bench/*/go.mod; do
+            dir=$(dirname "$mod")
+            echo "::group::$dir"
+            ( cd "$dir" && go mod tidy -diff && go build ./... )
+            echo "::endgroup::"
+          done
+
+      - name: Run zero-alloc invariant (non-race)
+        # The QWP hot-path 0-allocs/op pins (the Test*ZeroAllocs cases in
+        # qwp_bench_test.go) self-skip under -race: race instrumentation
+        # forces stack-allocatable values to escape and inflates
+        # allocs/op. The "Run tests" step below is -race only, so without
+        # this dedicated non-race run the headline allocation-free
+        # guarantee would never actually be exercised in CI. Cheap — a
+        # handful of testing.AllocsPerRun loops, no network or Docker.
+        # GOTOOLCHAIN=local pins to the matrix Go (see "Run vet").
+        env:
+          GOTOOLCHAIN: local
+        run: go test -run ZeroAllocs -count=1 .
+
       - name: Run tests
-        run: go test -v ./...
+        # Pin to the matrix-installed Go (see "Run vet"). The
+        # Staticcheck step deliberately omits this: staticcheck@v0.7.0
+        # needs go1.25 to build and must stay on GOTOOLCHAIN=auto.
+        env:
+          GOTOOLCHAIN: local
+        run: go test -race -v ./...

.github/workflows/qwp-fuzz.yml

@@ -0,0 +1,127 @@
+# Builds QuestDB from source and runs the Go QWP fuzz suite against it.
+#
+# Modelled on c-questdb-client's ci/run_fuzz_pipeline.yaml (clone questdb,
+# build with Maven, point the test fixture at the built repo). The fixture
+# (qwp_fuzz_fixture_test.go) then launches the SNAPSHOT jar exactly as
+# system_test/fixture.py does.
+#
+# This job MUST actually build, start the server, and run the fuzz tests —
+# never silently skip. Two guards enforce that:
+#   * QDB_FUZZ_STRICT=1 turns an unresolved/unstartable server from a
+#     green t.Skip into a red t.Fatal (see fuzzStrict in the fixture).
+#   * the explicit "Verify QuestDB jar" step fails the job with an
+#     actionable message if the build produced no server jar.
+# The regular build.yml workflow is unaffected: it sets neither QDB_REPO
+# nor QDB_FUZZ_STRICT, so the fuzz tests skip cleanly there.
+#
+# Runs on every pull request (and on demand). The QuestDB build plus
+# first-time dependency download takes a few minutes; the ~/.m2 cache
+# below keeps repeat runs short.
+name: qwp-fuzz
+
+on:
+  workflow_dispatch:
+  pull_request:
+
+jobs:
+  qwp-fuzz:
+    name: QWP fuzz vs QuestDB master
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - name: Checkout go-questdb-client
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.24.x"
+          cache: true
+
+      # QuestDB's maven-enforcer-plugin pins java.enforce.version=25
+      # (core/pom.xml); building with anything else fails the build.
+      # c-questdb-client uses JDK 25 for the same reason.
+      - name: Install JDK 25
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "25"
+
+      - name: Clone QuestDB
+        # Shallow clone of master. The C submodules ship prebuilt, so no
+        # blanket submodule init is needed; the java-questdb-client
+        # submodule is fetched on demand by the detect step below.
+        run: git clone --depth 1 https://github.com/questdb/questdb.git
+
+      - name: Detect local client profile
+        # core/pom.xml has a test-scoped dependency on
+        # org.questdb:questdb-client, and `package -DskipTests` still
+        # compiles tests, so Maven must resolve it. A release version
+        # resolves from Maven Central; a -SNAPSHOT version (server and
+        # client evolving in lockstep) exists only as the
+        # java-questdb-client submodule, built in-reactor via the
+        # local-client profile. Mirrors the server repo's
+        # .github/actions/detect-local-client composite action.
+        id: client
+        run: |
+          set -euo pipefail
+          version="$(sed -n 's/.*<questdb.client.version>\(.*\)<\/questdb.client.version>.*/\1/p' questdb/core/pom.xml | head -1)"
+          echo "questdb.client.version=${version:-<not found>}"
+          if [[ "$version" == *-SNAPSHOT ]]; then
+            echo "SNAPSHOT client version — building the java-questdb-client submodule via -Plocal-client"
+            git -C questdb submodule update --init java-questdb-client
+            echo "client_profile=-Plocal-client" >> "$GITHUB_OUTPUT"
+          else
+            echo "Release client version — resolving from Maven Central"
+            echo "client_profile=" >> "$GITHUB_OUTPUT"
+          fi
+
+      # QuestDB pulls a large, slow-moving dependency set; cache ~/.m2 so
+      # repeat runs skip the multi-minute first-time download. Key
+      # rotates when this workflow changes.
+      - name: Cache Maven repository
+        uses: actions/cache@v4
+        with:
+          path: ~/.m2/repository
+          key: m2-questdb-${{ runner.os }}-${{ hashFiles('.github/workflows/qwp-fuzz.yml') }}
+          restore-keys: |
+            m2-questdb-${{ runner.os }}-
+
+      - name: Build QuestDB server jar
+        # Minimal, verified build: produces core/target/questdb-
+        # <ver>-SNAPSHOT.jar + core/target/classes/.../site/conf in ~30s
+        # (warm .m2). With local-client active, -am additionally builds
+        # the java-questdb-client module ahead of core (~10s). No
+        # -Pbuild-web-console: the embedded console UI is irrelevant to
+        # QWP / /exec / /ping, and skipping it removes the Node-download
+        # failure surface. JAVA_HOME is exported by setup-java; the
+        # enforcer verifies it is JDK 25.
+        run: mvn -B -ntp -DskipTests -pl core -am package -f questdb/pom.xml ${{ steps.client.outputs.client_profile }}
+
+      - name: Verify QuestDB jar exists
+        # Defense in depth: if Maven "succeeded" but emitted no server
+        # jar (wrong module, layout change), fail HERE with a precise
+        # message instead of letting the fuzz step skip/fatal opaquely.
+        run: |
+          set -euo pipefail
+          jar="$(ls questdb/core/target/questdb-*-SNAPSHOT.jar 2>/dev/null \
+                 | grep -v -- '-tests.jar' | head -n1 || true)"
+          if [ -z "$jar" ]; then
+            echo "::error::No QuestDB server jar under questdb/core/target — the build did not produce it."
+            ls -la questdb/core/target/ || true
+            exit 1
+          fi
+          echo "Found server jar: $jar"
+
+      - name: Run QWP fuzz + integration tests
+        env:
+          GOTOOLCHAIN: local
+          QDB_REPO: ${{ github.workspace }}/questdb
+          # Make a missing/unstartable server a hard failure, not a skip.
+          # Applies to both ^TestQwpFuzz and ^TestQwpIntegration: the
+          # integration suite now boots the same shared fuzz fixture
+          # instead of probing an absent localhost:9000 server.
+          QDB_FUZZ_STRICT: "1"
+        run: go test -count=1 -timeout 30m -run '^TestQwp(Fuzz|Integration)' -v .

.gitignore

@@ -11,6 +11,28 @@
 # Test binary, built with `go test -c`
 *.test
 
+# Go build artifacts from the `package main` dirs (each `go build`
+# produces a binary named after its directory). binary-check.yml is the
+# CI backstop; these keep `git status` clean locally.
+/bench/qwp-egress-read/qwp-egress-read
+/bench/qwp-egress-read-wide/qwp-egress-read-wide
+/examples/from-conf/from-conf
+/examples/tcp/basic/basic
+/examples/tcp/auth/auth
+/examples/tcp/auth-and-tls/auth-and-tls
+/examples/http/basic/basic
+/examples/http/auth/auth
+/examples/http/auth-and-tls/auth-and-tls
+/examples/qwp/basic/basic
+/examples/qwp/basic-query/basic-query
+/examples/qwp/sf/sf
+/system_test/enterprise_e2e/sidecar/sidecar
+
+# Python caches from the system_test/enterprise_e2e fixtures
+__pycache__/
+.pytest_cache/
+.venv/
+
 # Output of the go coverage tool, specifically when used with LiteIDE
 *.out