Merge pull request #75 from PostHog/jose-sequeira/sdk-compliance

feat: SDK Compliance

Author: rafaeelaudibert

.github/workflows/sdk-compliance.yml

@@ -0,0 +1,21 @@
+name: SDK Compliance Tests
+
+permissions:
+  contents: read
+  packages: read
+  pull-requests: write
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+
+jobs:
+  compliance:
+    name: PostHog SDK compliance tests
+    uses: PostHog/posthog-sdk-test-harness/.github/workflows/test-sdk-action.yml@main
+    with:
+      adapter-dockerfile: "sdk_compliance_adapter/Dockerfile"
+      adapter-context: "."
+      test-harness-version: "latest"

sdk_compliance_adapter/Dockerfile

@@ -0,0 +1,57 @@
+# Build stage - use Debian for better compatibility
+FROM elixir:1.17 AS builder
+
+WORKDIR /app
+
+# Install hex and rebar
+RUN mix local.hex --force && mix local.rebar --force
+
+# Set build environment
+ENV MIX_ENV=prod
+
+# Copy the main SDK source
+COPY mix.exs mix.lock ./
+COPY lib ./lib
+COPY config ./config
+
+# Copy the adapter
+COPY sdk_compliance_adapter/mix.exs ./sdk_compliance_adapter/
+COPY sdk_compliance_adapter/lib ./sdk_compliance_adapter/lib
+COPY sdk_compliance_adapter/config ./sdk_compliance_adapter/config
+
+# Fetch and compile dependencies for the adapter
+WORKDIR /app/sdk_compliance_adapter
+RUN mix deps.get --only prod
+RUN mix compile
+
+# Build release
+RUN mix release
+
+# Runtime stage - use same base as build to avoid OpenSSL mismatch
+FROM debian:bookworm-slim AS runtime
+
+# Install runtime dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libstdc++6 \
+    openssl \
+    libncurses6 \
+    locales \
+    && rm -rf /var/lib/apt/lists/* \
+    && sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen \
+    && locale-gen
+
+ENV LANG=en_US.UTF-8
+ENV LANGUAGE=en_US:en
+ENV LC_ALL=en_US.UTF-8
+
+WORKDIR /app
+
+# Copy the release from builder
+COPY --from=builder /app/sdk_compliance_adapter/_build/prod/rel/sdk_compliance_adapter ./
+
+# Set environment
+ENV PORT=8080
+
+EXPOSE 8080
+
+CMD ["bin/sdk_compliance_adapter", "start"]

sdk_compliance_adapter/README.md

@@ -0,0 +1,74 @@
+# PostHog Elixir SDK Compliance Adapter
+
+This adapter wraps the posthog-elixir SDK for compliance testing with the [PostHog SDK Test Harness](https://github.com/PostHog/posthog-sdk-test-harness).
+
+## Running Tests
+
+Tests run automatically in CI via GitHub Actions. See the test harness repo for details.
+
+### Locally with Docker Compose
+
+```bash
+# From the posthog-elixir/sdk_compliance_adapter directory
+docker-compose up --build --abort-on-container-exit
+```
+
+This will:
+
+1. Build the Elixir SDK adapter
+2. Pull the test harness image
+3. Run all compliance tests
+4. Show results
+
+### Manually with Docker
+
+```bash
+# Create network
+docker network create test-network
+
+# Build and run adapter
+docker build -f sdk_compliance_adapter/Dockerfile -t posthog-elixir-adapter .
+docker run -d --name sdk-adapter --network test-network -p 8080:8080 posthog-elixir-adapter
+
+# Run test harness
+docker run --rm \
+  --name test-harness \
+  --network test-network \
+  ghcr.io/posthog/sdk-test-harness:latest \
+  run --adapter-url http://sdk-adapter:8080 --mock-url http://test-harness:8081
+
+# Cleanup
+docker stop sdk-adapter && docker rm sdk-adapter
+docker network rm test-network
+```
+
+## Implementation
+
+See [lib/sdk_compliance_adapter/](lib/sdk_compliance_adapter/) for the adapter implementation.
+
+The adapter implements the standard SDK adapter interface defined in the [test harness CONTRACT](https://github.com/PostHog/posthog-sdk-test-harness/blob/main/CONTRACT.yaml).
+
+### Architecture
+
+The adapter is a standalone Elixir application that:
+
+1. Starts an HTTP server (using Plug/Cowboy) on port 8080
+2. Dynamically starts/stops the PostHog SDK based on `/init` and `/reset` requests
+3. Uses a custom `TrackedClient` to intercept HTTP requests and track them for assertions
+4. Maintains state (events captured, sent, retries, etc.) for the test harness to query
+
+### Endpoints
+
+- `GET /health` - Health check, returns SDK name/version
+- `POST /init` - Initialize SDK with configuration
+- `POST /capture` - Capture a single event
+- `POST /flush` - Flush pending events
+- `GET /state` - Get internal state for test assertions
+- `POST /reset` - Reset SDK state
+
+## Documentation
+
+For complete documentation, see:
+
+- [PostHog SDK Test Harness](https://github.com/PostHog/posthog-sdk-test-harness)
+- [Adapter Implementation Guide](https://github.com/PostHog/posthog-sdk-test-harness/blob/main/ADAPTER_GUIDE.md)

sdk_compliance_adapter/config/config.exs

@@ -0,0 +1,4 @@
+import Config
+
+# Disable default PostHog startup - we manage it dynamically
+config :posthog, enable: false

sdk_compliance_adapter/docker-compose.yml

@@ -0,0 +1,25 @@
+version: "3.8"
+
+services:
+  # PostHog Elixir SDK adapter
+  sdk-adapter:
+    build:
+      context: ..
+      dockerfile: sdk_compliance_adapter/Dockerfile
+    ports:
+      - "8080:8080"
+    networks:
+      - test-network
+
+  # Test harness
+  test-harness:
+    image: ghcr.io/posthog/sdk-test-harness:latest
+    command: ["run", "--adapter-url", "http://sdk-adapter:8080", "--mock-url", "http://test-harness:8081"]
+    networks:
+      - test-network
+    depends_on:
+      - sdk-adapter
+
+networks:
+  test-network:
+    driver: bridge

sdk_compliance_adapter/lib/sdk_compliance_adapter.ex

@@ -0,0 +1,12 @@
+defmodule SdkComplianceAdapter do
+  @moduledoc """
+  SDK Compliance Adapter for PostHog Elixir SDK.
+
+  This adapter wraps the posthog-elixir SDK for compliance testing with the
+  PostHog SDK Test Harness.
+  """
+
+  @version "1.0.0"
+
+  def version, do: @version
+end

sdk_compliance_adapter/lib/sdk_compliance_adapter/application.ex

@@ -0,0 +1,21 @@
+defmodule SdkComplianceAdapter.Application do
+  @moduledoc false
+  use Application
+
+  @impl true
+  def start(_type, _args) do
+    port = System.get_env("PORT", "8080") |> String.to_integer()
+
+    children = [
+      SdkComplianceAdapter.State,
+      {DynamicSupervisor, strategy: :one_for_one, name: SdkComplianceAdapter.DynamicSupervisor},
+      {Plug.Cowboy, scheme: :http, plug: SdkComplianceAdapter.Router, options: [port: port]}
+    ]
+
+    opts = [strategy: :one_for_one, name: SdkComplianceAdapter.Supervisor]
+
+    IO.puts("Starting PostHog Elixir SDK adapter on port #{port}")
+
+    Supervisor.start_link(children, opts)
+  end
+end