Make DSH agents-as-a-service browser-usable; fix probe crash-loop (#3)

* Rewrite DSH gateway for browser sessions, HTTP and WebSocket

- Replace the Flask proxy with a Starlette ASGI app (uvicorn factory),
  keeping the control plane (claims, wake/suspend, idle sweeper).
- Add HttpOnly gateway sessions and a server-side DSH launch-token
  handshake: read the token from pod logs, exchange it for a dsh-auth
  cookie, cache per (user, pod UID, Host), refresh once on 401.
- Proxy HTTP/SSE and WebSocket (/api/remote.mux) under /u/<user>/, with
  header stripping/injection, Location rewriting and wake-on-connect.
- Add a landing/signup/login page, health endpoint, pinned dependencies,
  a read-only-rootfs gateway image, 87 cluster-free tests and docs.

* Fix DSH probe crash-loop and harden gateway manifests

- Probe /favicon.svg instead of /: DSH gates / behind its launch-token
  cookie and returns 401, which made warm-pool pods crash-loop.
- Pass DSH_TRUSTED_HOSTS through the entrypoint as --trusted-host args
  for public/ingress hosts; keep localhost trusted.
- Deploy the published :gateway image, add pods/pods-log RBAC, /healthz
  probes, read-only rootfs with a /tmp emptyDir and non-root security.
- Add optional Traefik Ingress and document the prerequisites.

* Update CI, smoke tests, build tooling and docs

- Run gateway pytest/ruff and build/smoke-test the image in CI.
- Parameterize the DSH build version and pnpm version inputs.
- Exercise cookie signup, HTML proxy, WebSocket auth, suspend/wake and
  delete in run-test-kind.sh.
- Add Makefile/build.sh targets and document the architecture, handshake,
  probes, trusted hosts, troubleshooting and limitations.

---------

Co-authored-by: SREDevOpsAgents <agents@sredevops.org>

.github/workflows/multi-build-gateway.yaml

@@ -1,5 +1,7 @@
-# This workflow builds a multi-arch Docker image using GitHub Actions and separated Github Runners with native support for ARM64 and AMD64 architectures, without using QEMU emulation.
-# It uses Docker Buildx to build and push the image to GitHub Container Registry (GHCR).
+# This workflow builds the multi-arch gateway image (Starlette ASGI, served by
+# uvicorn on :8080) and pushes it to GHCR as
+# ghcr.io/<owner>/<repo>:gateway. The DSH Web image is built by multi-build.yaml.
+# It uses Docker Buildx with native AMD64 and ARM64 runners, without QEMU.
 name: Gateway Build multi arch Docker Image with separate Github Runners
 
 on:
@@ -11,9 +13,7 @@ on:
       - 'examples/dsh-agents-as-a-service/gateway/**'
       - '.github/workflows/multi-build-gateway.yaml'
 env:
-  # The name of the Docker image to be built and pushed to GHCR
-  # The image name is derived from the GitHub repository name and the GitHub Container Registry (GHCR) URL.
-  # The image name will be in the format: ghcr.io/<owner>/<repo>
+  # ghcr.io/<owner>/<repo>; this workflow always publishes the `:gateway` tag.
   GHCR_IMAGE: ghcr.io/${{ github.repository }}
 permissions:
   # Global permissions for the workflow, which can be overridden at the job level

.github/workflows/multi-build.yaml

@@ -4,6 +4,17 @@ name: Build multi arch Docker Image with separate Github Runners
 
 on:
   workflow_dispatch:
+    inputs:
+      dsh_version:
+        description: "DSH git ref to build (tag or branch)"
+        required: true
+        default: dsh-v0.2.1-rc.2
+        type: string
+      pnpm_version:
+        description: "pnpm version used to build DSH"
+        required: true
+        default: "11.28.5"
+        type: string
   push:
     branches:
       - main
@@ -15,7 +26,10 @@ env:
   # The image name is derived from the GitHub repository name and the GitHub Container Registry (GHCR) URL.
   # The image name will be in the format: ghcr.io/<owner>/<repo>
   GHCR_IMAGE: ghcr.io/${{ github.repository }}
-  DSH_VERSION: dsh-v0.2.1-rc.2 #TODO: Make this configurable from workflow inputs and/or an custom Github Action
+  # workflow_dispatch inputs win; pushes to main fall back to the pinned
+  # defaults. Both values flow into the Docker build args and the image tags.
+  DSH_VERSION: ${{ inputs.dsh_version || 'dsh-v0.2.1-rc.2' }}
+  PNPM_VERSION: ${{ inputs.pnpm_version || '11.28.5' }}
 permissions:
   # Global permissions for the workflow, which can be overridden at the job level
   contents: read
@@ -130,14 +144,14 @@ jobs:
         uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
         env:
           DOCKER_BUILDKIT: 1
-          DSH_VERSION: dsh-v0.2.1-rc.2 #TODO: Make this configurable from workflow inputs and/or an custom Github Action
-          PNPM_VERSION: 11.28.5
           DSH_PORT: 3080
         with:
           context: .
           platforms: ${{ matrix.platform }}
           labels: ${{ steps.meta.outputs.labels }}
-          build-args: DSH_VERSION=${{ env.DSH_VERSION }}
+          build-args: |
+            DSH_VERSION=${{ env.DSH_VERSION }}
+            PNPM_VERSION=${{ env.PNPM_VERSION }}
           annotations: ${{ steps.meta.outputs.annotations }}
           outputs: type=image,name=${{ env.GHCR_IMAGE }},push-by-digest=true,name-canonical=true,push=true,oci-mediatypes=true
           cache-from: type=gha,scope=${{ github.repository }}-${{ github.ref_name }}-${{ matrix.platform }}
@@ -209,8 +223,6 @@ jobs:
         # The metadata includes information such as the image name, tags, and labels.
         id: meta
         uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
-        env:
-          DSH_VERSION: ${{ env.DSH_VERSION }}
         with:
           images: ${{ env.GHCR_IMAGE }}
           annotations: |
@@ -218,7 +230,7 @@ jobs:
           tags: |
             type=raw,value=main,enable=${{ github.ref_name == 'main' }}
             type=raw,value=latest,enable=${{ github.ref_name == 'main' }}
-            type=raw,value=${{ env.DSH_VERSION }},enable=${{ github.ref_name == 'main' }}
+            type=raw,value=${{ env.DSH_VERSION }},enable=${{ github.ref_name == 'main' || github.event_name == 'workflow_dispatch' }}
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1

.github/workflows/validate.yaml

@@ -1,8 +1,9 @@
 name: Validate
 
 # Validates the Kubernetes manifests against the real agent-sandbox CRD
-# schema (server-side dry-run on a throwaway kind cluster) and runs the
-# gateway unit tests. Runs on every PR and on pushes to main.
+# schema (server-side dry-run on a throwaway kind cluster), runs the gateway
+# unit tests + lint, and builds/smoke-tests the gateway image without a
+# cluster. Runs on every PR and on pushes to main.
 on:
   pull_request:
   push:
@@ -45,6 +46,10 @@ jobs:
           echo "all manifests validated"
 
   gateway-tests:
+    # The gateway lives in examples/dsh-agents-as-a-service/gateway/. Its
+    # runtime pins and dev pins are kept separate so the image only ships
+    # requirements.txt while CI installs both files.
+    name: Gateway unit tests and lint
     runs-on: ubuntu-latest
     defaults:
       run:
@@ -57,9 +62,76 @@ jobs:
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.12"
+          cache: pip
+          cache-dependency-path: |
+            examples/dsh-agents-as-a-service/gateway/requirements.txt
+            examples/dsh-agents-as-a-service/gateway/requirements-dev.txt
 
       - name: Install dependencies
-        run: pip install -r requirements.txt pytest
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt -r requirements-dev.txt
+
+      - name: Lint (ruff)
+        run: python -m ruff check .
 
       - name: Run gateway unit tests
-        run: python -m pytest test_gateway.py -v
+        run: python -m pytest -v
+
+  gateway-image:
+    # No cluster and no real credentials: the gateway must start and answer
+    # /healthz with a dummy kubeconfig, which catches broken imports, missing
+    # runtime deps, and an unresponsive ASGI entrypoint.
+    name: Build and smoke-test gateway image
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Build gateway image
+        run: |
+          docker build \
+            -t dsh-aaas-gateway:ci \
+            examples/dsh-agents-as-a-service/gateway/
+
+      - name: Smoke-test /healthz without a cluster
+        run: |
+          set -euo pipefail
+          cat > /tmp/kubeconfig <<'EOF'
+          apiVersion: v1
+          kind: Config
+          clusters:
+            - name: dummy
+              cluster:
+                server: https://127.0.0.1:6443
+                insecure-skip-tls-verify: true
+          contexts:
+            - name: dummy
+              context:
+                cluster: dummy
+                user: dummy
+          users:
+            - name: dummy
+              user: {}
+          current-context: dummy
+          EOF
+          docker run -d --name gateway-smoke \
+            -p 18080:8080 \
+            -e NAMESPACE=dsh-demo \
+            -e POOL=dsh-pool \
+            -e KUBECONFIG=/tmp/kubeconfig \
+            -v /tmp/kubeconfig:/tmp/kubeconfig:ro \
+            dsh-aaas-gateway:ci
+          trap 'docker logs gateway-smoke || true; docker rm -f gateway-smoke || true' EXIT
+
+          code=""
+          for _ in $(seq 1 30); do
+            code=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:18080/healthz || true)
+            [ "$code" = "200" ] && break
+            sleep 1
+          done
+          if [ "$code" != "200" ]; then
+            echo "gateway /healthz returned '$code' instead of 200" >&2
+            exit 1
+          fi
+          echo "gateway image healthy: GET /healthz -> 200"