Adventure draft: 🧪 Blind by Design (OpenFeature + flagd)

.devcontainer/00-blind-by-design_01-beginner/devcontainer.json

@@ -0,0 +1,36 @@
+{
+  "name": "🧪 Adventure 00 | 🟢 Beginner (Stand up the lab)",
+  "dockerComposeFile": "docker-compose.yml",
+  "service": "workspace",
+  "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}/adventures/planned/00-blind-by-design/beginner",
+  "postCreateCommand": "bash /workspaces/${localWorkspaceFolderBasename}/.devcontainer/00-blind-by-design_01-beginner/post-create.sh",
+  "postStartCommand": "bash /workspaces/${localWorkspaceFolderBasename}/.devcontainer/00-blind-by-design_01-beginner/post-start.sh",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "vscjava.vscode-java-pack",
+        "vmware.vscode-spring-boot",
+        "vscjava.vscode-spring-boot-dashboard",
+        "redhat.vscode-xml"
+      ]
+    },
+    "codespaces": {
+      "openFiles": [
+        "adventures/planned/00-blind-by-design/docs/beginner.md",
+        "adventures/planned/00-blind-by-design/beginner/src/main/java/dev/openfeature/demo/java/demo/Trial.java",
+        "adventures/planned/00-blind-by-design/beginner/flags.json"
+      ]
+    }
+  },
+  "forwardPorts": [8080, 8013, 8014, 8015, 8016],
+  "portsAttributes": {
+    "8080": { "label": "Lab (Spring Boot)", "onAutoForward": "notify" },
+    "8013": { "label": "flagd gRPC eval", "onAutoForward": "ignore" },
+    "8014": { "label": "flagd management/metrics", "onAutoForward": "ignore" },
+    "8015": { "label": "flagd sync (IN_PROCESS)", "onAutoForward": "ignore" },
+    "8016": { "label": "flagd OFREP", "onAutoForward": "ignore" }
+  },
+  "otherPortsAttributes": {
+    "onAutoForward": "ignore"
+  }
+}

.devcontainer/00-blind-by-design_01-beginner/docker-compose.yml

@@ -0,0 +1,40 @@
+# Multi-container devcontainer for Beginner. The lab itself runs in
+# `workspace`; flagd runs as a sibling so participants meet the realistic
+# shape ("the SDK talks RPC to a separate flag service") from level 1
+# instead of running file-mode in-process and throwing it away for
+# Intermediate.
+#
+# Both services bind-mount the same workspace at the same path. flagd
+# watches the participant's flags.json directly — edit it in the IDE,
+# the file watcher reloads, the next request sees the new variant.
+
+services:
+  workspace:
+    image: mcr.microsoft.com/devcontainers/java:1-21
+    volumes:
+      - ../..:/workspaces/${localWorkspaceFolderBasename:-open-ecosystem-challenges}:cached
+    command: sleep infinity
+    environment:
+      # The flagd Java provider reads these env vars by default when
+      # FlagdOptions.builder() is invoked without an explicit host/port.
+      # Pre-set so a vanilla `Resolver.RPC` config Just Works inside the
+      # devcontainer — and a participant who runs the lab from their host
+      # machine after `docker compose up flagd` will hit `localhost:8013`
+      # via the published port.
+      - FLAGD_HOST=flagd
+      - FLAGD_PORT=8013
+
+  flagd:
+    image: ghcr.io/open-feature/flagd:latest
+    container_name: side-effects-beginner-flagd
+    volumes:
+      - ../..:/workspaces/${localWorkspaceFolderBasename:-open-ecosystem-challenges}:ro
+    command:
+      - start
+      - --uri
+      - file:/workspaces/${localWorkspaceFolderBasename:-open-ecosystem-challenges}/adventures/planned/00-blind-by-design/beginner/flags.json
+    ports:
+      - "8013:8013"
+      - "8014:8014"
+      - "8015:8015"
+      - "8016:8016"

.devcontainer/00-blind-by-design_01-beginner/post-create.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -e
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+CHALLENGE_DIR="$REPO_ROOT/adventures/planned/00-blind-by-design/beginner"
+
+# shellcheck disable=SC1091
+source "$REPO_ROOT/lib/scripts/tracker.sh"
+set_tracking_context "00-blind-by-design" "beginner"
+track_codespace_created
+
+# Install gum (used by the verify.sh output helpers).
+"$REPO_ROOT/lib/shared/init.sh" --version v0.17.0 # https://github.com/charmbracelet/gum/releases
+
+# jq is needed by verify.sh; the Java devcontainer image is debian-based.
+if ! command -v jq >/dev/null 2>&1; then
+  sudo apt-get update -y
+  sudo apt-get install -y --no-install-recommends jq
+fi
+
+# Java 21 is provided by the devcontainer image (mcr.microsoft.com/devcontainers/java:1-21-bullseye).
+# Pre-fetch Maven dependencies so the IDE is responsive immediately.
+echo "✨ Resolving Maven dependencies for the lab..."
+cd "$CHALLENGE_DIR"
+chmod +x ./mvnw
+./mvnw -q -B -DskipTests dependency:go-offline || true
+
+echo "✅ Post-create complete."

.devcontainer/00-blind-by-design_01-beginner/post-start.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+set -e
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+CHALLENGE_DIR="$REPO_ROOT/adventures/planned/00-blind-by-design/beginner"
+
+cat <<EOF
+
+✨ Adventure 00 — Level 1 (🟢 Beginner): Stand up the lab
+
+📂 Challenge directory:
+   $CHALLENGE_DIR
+
+🧬 A flagd sidecar is already running next to your workspace
+   - gRPC eval  :8013   (this is what your FlagdProvider will talk to)
+   - management :8014   (Prometheus metrics + /healthz, /readyz)
+   - sync       :8015   (used in the Intermediate IN_PROCESS sidebar)
+   - OFREP      :8016   (HTTP eval API, handy for poking flagd directly)
+   FLAGD_HOST=flagd is exported into this shell, so a default
+   Resolver.RPC config picks the sidecar up automatically.
+
+▶  Run the lab — one launch config in .vscode/launch.json:
+     🧪  Run the Lab
+   Open the Run and Debug view (Ctrl/Cmd + Shift + D) and hit ▶.
+
+   Or from the terminal:
+     ./mvnw spring-boot:run
+
+👉 In another terminal, hit it:
+     curl -s http://localhost:8080/ | jq
+
+✅ Run the verification when you're ready:
+     ./verify.sh
+   or use the 🧪 Verify Solution task: Tasks → Run Test Task.
+
+EOF
+
+# Track that the environment is ready.
+# shellcheck disable=SC1091
+source "$REPO_ROOT/lib/scripts/tracker.sh"
+track_codespace_initialized
+
+# Open the relevant files in the connected editor. customizations.codespaces.openFiles
+# is unreliable for dockerComposeFile-based devcontainers (the orchestrator merges
+# devcontainer.json and the field is sometimes dropped). `code` is the same CLI the
+# editor uses internally and works against either the web or desktop client.
+if command -v code >/dev/null 2>&1; then
+  code "$REPO_ROOT/adventures/planned/00-blind-by-design/docs/beginner.md" \
+       "$CHALLENGE_DIR/src/main/java/dev/openfeature/demo/java/demo/Trial.java" \
+       2>/dev/null || true
+fi

.devcontainer/00-blind-by-design_02-intermediate/devcontainer.json

@@ -0,0 +1,35 @@
+{
+  "name": "🧪 Adventure 00 | 🟡 Intermediate (Outcome by cohort)",
+  "dockerComposeFile": "docker-compose.yml",
+  "service": "workspace",
+  "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}/adventures/planned/00-blind-by-design/intermediate",
+  "postCreateCommand": "bash /workspaces/${localWorkspaceFolderBasename}/.devcontainer/00-blind-by-design_02-intermediate/post-create.sh",
+  "postStartCommand": "bash /workspaces/${localWorkspaceFolderBasename}/.devcontainer/00-blind-by-design_02-intermediate/post-start.sh",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "vscjava.vscode-java-pack",
+        "vmware.vscode-spring-boot",
+        "vscjava.vscode-spring-boot-dashboard"
+      ]
+    },
+    "codespaces": {
+      "openFiles": [
+        "adventures/planned/00-blind-by-design/docs/intermediate.md",
+        "adventures/planned/00-blind-by-design/intermediate/src/main/java/dev/openfeature/demo/java/demo/OpenFeatureConfig.java",
+        "adventures/planned/00-blind-by-design/intermediate/flags.json"
+      ]
+    }
+  },
+  "forwardPorts": [8080, 8013, 8014, 8015, 8016],
+  "portsAttributes": {
+    "8080": { "label": "Lab (Spring Boot)", "onAutoForward": "notify" },
+    "8013": { "label": "flagd gRPC eval", "onAutoForward": "ignore" },
+    "8014": { "label": "flagd management/metrics", "onAutoForward": "ignore" },
+    "8015": { "label": "flagd sync (IN_PROCESS)", "onAutoForward": "ignore" },
+    "8016": { "label": "flagd OFREP", "onAutoForward": "ignore" }
+  },
+  "otherPortsAttributes": {
+    "onAutoForward": "ignore"
+  }
+}

.devcontainer/00-blind-by-design_02-intermediate/docker-compose.yml

@@ -0,0 +1,41 @@
+# Multi-container devcontainer for Intermediate. The lab itself runs in
+# `workspace`; flagd runs as a sibling so participants who finish the
+# FILE-mode path early can flip the FlagdProvider to RPC mode and talk
+# to flagd:8013 without any Docker-in-Docker dance.
+#
+# Both services bind-mount the same workspace at the same path. flagd
+# watches the participant's flags.json directly — edit it in the IDE,
+# the file watcher reloads.
+
+services:
+  workspace:
+    image: mcr.microsoft.com/devcontainers/java:1-21
+    volumes:
+      - ../..:/workspaces/${localWorkspaceFolderBasename:-open-ecosystem-challenges}:cached
+    command: sleep infinity
+    environment:
+      # Pre-set FLAGD_HOST so participants who switch to RPC mode in
+      # OpenFeatureConfig do not have to hard-code the hostname.
+      - FLAGD_HOST=flagd
+      - FLAGD_PORT=8013
+      # The trial's country of registration. Used by OpenFeatureConfig
+      # via System.getenv("COUNTRY") to populate the global eval context.
+      # `de` by default so F5 / Spring Boot Dashboard runs already exercise
+      # the country-targeting branch. Override with run-austria.sh or
+      # `COUNTRY=at ./mvnw spring-boot:run` to flip.
+      - COUNTRY=de
+
+  flagd:
+    image: ghcr.io/open-feature/flagd:latest
+    container_name: side-effects-intermediate-flagd
+    volumes:
+      - ../..:/workspaces/${localWorkspaceFolderBasename:-open-ecosystem-challenges}:ro
+    command:
+      - start
+      - --uri
+      - file:/workspaces/${localWorkspaceFolderBasename:-open-ecosystem-challenges}/adventures/planned/00-blind-by-design/intermediate/flags.json
+    ports:
+      - "8013:8013"
+      - "8014:8014"
+      - "8015:8015"
+      - "8016:8016"

.devcontainer/00-blind-by-design_02-intermediate/post-create.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -e
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+# shellcheck disable=SC1091
+source "$REPO_ROOT/lib/scripts/tracker.sh"
+set_tracking_context "00-blind-by-design" "intermediate"
+track_codespace_created
+
+"$REPO_ROOT/lib/shared/init.sh" --version v0.17.0 # https://github.com/charmbracelet/gum/releases
+
+# jq is needed by verify.sh; the Java devcontainer image is debian-based.
+if ! command -v jq >/dev/null 2>&1; then
+  sudo apt-get update -y
+  sudo apt-get install -y --no-install-recommends jq
+fi
+
+CHALLENGE_DIR="$REPO_ROOT/adventures/planned/00-blind-by-design/intermediate"
+
+# Make the Maven wrapper executable so the participant can just `./mvnw ...`
+if [[ -f "$CHALLENGE_DIR/mvnw" ]]; then
+  chmod +x "$CHALLENGE_DIR/mvnw"
+fi
+
+echo "✨ Pre-warming the Maven dependency cache so the first ./mvnw is fast..."
+( cd "$CHALLENGE_DIR" && ./mvnw -q -DskipTests dependency:go-offline ) || \
+  echo "⚠️  Dependency pre-warm skipped (network or wrapper not ready yet)"
+
+echo "✅ Post-create complete."

.devcontainer/00-blind-by-design_02-intermediate/post-start.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+set -e
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+CHALLENGE_DIR="$REPO_ROOT/adventures/planned/00-blind-by-design/intermediate"
+
+cat <<EOF
+
+✨ Level 2 - 🟡 Intermediate (Outcome by cohort)
+
+📂 Challenge directory:
+   $CHALLENGE_DIR
+
+🧪 Sibling services already running (managed by devcontainer compose):
+   - flagd  → reachable at flagd:8013 (gRPC eval) / flagd:8016 (OFREP HTTP)
+              Management/metrics on :8014, sync stream on :8015.
+              All four ports are forwarded to localhost.
+
+▶  Run the lab — three named launch configs ship in .vscode/launch.json:
+     🇩🇪  Run the Lab — Germany (COUNTRY=de)
+     🇦🇹  Run the Lab — Austria (COUNTRY=at)
+     🌍  Run the Lab — No country
+   Open the Run and Debug view (Ctrl/Cmd + Shift + D) and pick one.
+
+   Or from the terminal:
+     ./run-germany.sh   # COUNTRY=de + tee app.log
+     ./run-austria.sh   # COUNTRY=at + tee app.log
+
+👉 In another terminal, exercise the cohorts:
+     curl 'http://localhost:8080/?species=zyklop'   # per-subject targeting
+     curl 'http://localhost:8080/'               # falls through to country branch
+
+✅ Run the verification when you're ready:
+     ./verify.sh
+   or use the 🧪 Verify Solution task: Tasks → Run Test Task.
+
+EOF
+
+# Track that the environment is ready
+# shellcheck disable=SC1091
+source "$REPO_ROOT/lib/scripts/tracker.sh"
+set_tracking_context "blind-by-design" "intermediate"
+track_codespace_initialized
+
+# Open the relevant files in the connected editor. customizations.codespaces.openFiles
+# is unreliable for dockerComposeFile-based devcontainers (the orchestrator merges
+# devcontainer.json and the field is sometimes dropped). `code` is the same CLI the
+# editor uses internally and works against either the web or desktop client.
+if command -v code >/dev/null 2>&1; then
+  code "$REPO_ROOT/adventures/planned/00-blind-by-design/docs/intermediate.md" \
+       "$CHALLENGE_DIR/src/main/java/dev/openfeature/demo/java/demo/OpenFeatureConfig.java" \
+       "$CHALLENGE_DIR/flags.json" \
+       2>/dev/null || true
+fi

.devcontainer/00-blind-by-design_03-expert/devcontainer.json

@@ -0,0 +1,41 @@
+{
+  "name": "🧪 Adventure 00 | 🔴 Expert (Phase 3 — read the chart)",
+  "dockerComposeFile": "docker-compose.yml",
+  "service": "workspace",
+  "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}/adventures/planned/00-blind-by-design/expert",
+  "postCreateCommand": "bash /workspaces/${localWorkspaceFolderBasename}/.devcontainer/00-blind-by-design_03-expert/post-create.sh",
+  "postStartCommand": "bash /workspaces/${localWorkspaceFolderBasename}/.devcontainer/00-blind-by-design_03-expert/post-start.sh",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "vscjava.vscode-java-pack",
+        "redhat.vscode-yaml",
+        "ms-azuretools.vscode-docker"
+      ]
+    },
+    "codespaces": {
+      "openFiles": [
+        "adventures/planned/00-blind-by-design/docs/expert.md",
+        "adventures/planned/00-blind-by-design/expert/src/main/java/dev/openfeature/demo/java/demo/OpenTelemetryConfig.java",
+        "adventures/planned/00-blind-by-design/expert/src/main/java/dev/openfeature/demo/java/demo/OpenFeatureConfig.java",
+        "adventures/planned/00-blind-by-design/expert/flags.json"
+      ]
+    }
+  },
+  "forwardPorts": [8080, 3000, 4317, 4318, 9090, 3200, 8013, 8014, 8015, 8016],
+  "portsAttributes": {
+    "8080": { "label": "Spring Boot lab", "onAutoForward": "notify" },
+    "3000": { "label": "Grafana", "onAutoForward": "notify" },
+    "4317": { "label": "OTLP gRPC", "onAutoForward": "ignore" },
+    "4318": { "label": "OTLP HTTP", "onAutoForward": "ignore" },
+    "9090": { "label": "Prometheus", "onAutoForward": "ignore" },
+    "3200": { "label": "Tempo HTTP API", "onAutoForward": "ignore" },
+    "8013": { "label": "flagd gRPC eval", "onAutoForward": "ignore" },
+    "8014": { "label": "flagd management/metrics", "onAutoForward": "ignore" },
+    "8015": { "label": "flagd sync (IN_PROCESS)", "onAutoForward": "ignore" },
+    "8016": { "label": "flagd OFREP", "onAutoForward": "ignore" }
+  },
+  "otherPortsAttributes": {
+    "onAutoForward": "ignore"
+  }
+}