Add examples and package CI

.gitattributes

@@ -0,0 +1,5 @@
+*.roc text eol=lf
+*.sh text eol=lf
+*.py text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: package examples (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-24.04
+          - macos-15
+          - windows-2025
+    defaults:
+      run:
+        shell: bash
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Zig
+        uses: mlugg/setup-zig@8d6198c65fb0feaa111df26e6b467fea8345e46f # ratchet:mlugg/setup-zig@v2.0.5
+        with:
+          version: 0.15.2
+          use-cache: false
+
+      - name: Clone Roc source
+        run: |
+          ROC_COMMIT=$(python3 ci/get_roc_commit.py)
+
+          git init roc-src
+          cd roc-src
+          git remote add origin https://github.com/roc-lang/roc
+          git fetch --depth 1 origin "$ROC_COMMIT"
+          git checkout --detach "$ROC_COMMIT"
+
+      - name: Build Roc
+        uses: roc-lang/roc/.github/actions/flaky-retry@3d0fdde9ae6ffb5ef411f8c8c2fc2cdce22a74fe
+        with:
+          command: cd roc-src && zig build roc
+          error_string_contains: "build.zig.zon"
+
+      - name: Add Roc to PATH
+        run: echo "$(pwd)/roc-src/zig-out/bin" >> "$GITHUB_PATH"
+
+      - name: Run checks
+        run: ci/all_tests.sh

.github/workflows/release.yml

@@ -0,0 +1,171 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: "Release tag, e.g. v0.1.0"
+        required: true
+        type: string
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-bundle:
+    name: Build package bundle
+    runs-on: ubuntu-24.04
+    outputs:
+      bundle_filename: ${{ steps.bundle.outputs.bundle_filename }}
+    defaults:
+      run:
+        shell: bash
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Zig
+        uses: mlugg/setup-zig@8d6198c65fb0feaa111df26e6b467fea8345e46f # ratchet:mlugg/setup-zig@v2.0.5
+        with:
+          version: 0.15.2
+          use-cache: false
+
+      - name: Clone Roc source
+        run: |
+          ROC_COMMIT=$(python3 ci/get_roc_commit.py)
+
+          git init roc-src
+          cd roc-src
+          git remote add origin https://github.com/roc-lang/roc
+          git fetch --depth 1 origin "$ROC_COMMIT"
+          git checkout --detach "$ROC_COMMIT"
+
+      - name: Build Roc
+        uses: roc-lang/roc/.github/actions/flaky-retry@3d0fdde9ae6ffb5ef411f8c8c2fc2cdce22a74fe
+        with:
+          command: cd roc-src && zig build roc
+          error_string_contains: "build.zig.zon"
+
+      - name: Add Roc to PATH
+        run: echo "$(pwd)/roc-src/zig-out/bin" >> "$GITHUB_PATH"
+
+      - name: Check format and package
+        run: |
+          roc fmt --check package examples
+          roc check package/main.roc
+          roc test package/main.roc
+
+      - name: Bundle package
+        id: bundle
+        run: |
+          BUNDLE_OUTPUT=$(scripts/bundle.sh --output-dir dist 2>&1)
+          echo "$BUNDLE_OUTPUT"
+
+          BUNDLE_PATH=$(echo "$BUNDLE_OUTPUT" | grep "^Created:" | awk '{print $2}')
+          BUNDLE_FILENAME=$(basename "$BUNDLE_PATH")
+
+          if [ -z "$BUNDLE_FILENAME" ]; then
+            echo "Error: could not extract bundle filename from roc bundle output"
+            exit 1
+          fi
+
+          echo "bundle_filename=$BUNDLE_FILENAME" >> "$GITHUB_OUTPUT"
+
+      - name: Upload package bundle artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: package-bundle
+          path: dist/${{ steps.bundle.outputs.bundle_filename }}
+          retention-days: 30
+
+  test-bundle:
+    name: Test package bundle (${{ matrix.os }})
+    needs: build-bundle
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-24.04
+          - macos-15
+          - windows-2025
+    defaults:
+      run:
+        shell: bash
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Zig
+        uses: mlugg/setup-zig@8d6198c65fb0feaa111df26e6b467fea8345e46f # ratchet:mlugg/setup-zig@v2.0.5
+        with:
+          version: 0.15.2
+          use-cache: false
+
+      - name: Clone Roc source
+        run: |
+          ROC_COMMIT=$(python3 ci/get_roc_commit.py)
+
+          git init roc-src
+          cd roc-src
+          git remote add origin https://github.com/roc-lang/roc
+          git fetch --depth 1 origin "$ROC_COMMIT"
+          git checkout --detach "$ROC_COMMIT"
+
+      - name: Build Roc
+        uses: roc-lang/roc/.github/actions/flaky-retry@3d0fdde9ae6ffb5ef411f8c8c2fc2cdce22a74fe
+        with:
+          command: cd roc-src && zig build roc
+          error_string_contains: "build.zig.zon"
+
+      - name: Add Roc to PATH
+        run: echo "$(pwd)/roc-src/zig-out/bin" >> "$GITHUB_PATH"
+
+      - name: Download package bundle artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: package-bundle
+          path: dist
+
+      - name: Test examples against downloaded bundle
+        run: python3 ci/test_bundle_examples.py --bundle-path "dist/${{ needs.build-bundle.outputs.bundle_filename }}"
+
+  create-release:
+    name: Create GitHub release
+    needs:
+      - build-bundle
+      - test-bundle
+    runs-on: ubuntu-24.04
+    if: github.event_name == 'workflow_dispatch'
+    permissions:
+      contents: write
+    defaults:
+      run:
+        shell: bash
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Download package bundle artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: package-bundle
+          path: dist
+
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          BUNDLE_FILE="dist/${{ needs.build-bundle.outputs.bundle_filename }}"
+          ROC_COMMIT=$(python3 ci/get_roc_commit.py | cut -c1-8)
+
+          gh release create "${{ github.event.inputs.release_tag }}" \
+            "$BUNDLE_FILE" \
+            --title "${{ github.event.inputs.release_tag }}" \
+            --generate-notes \
+            --notes "HTTP package bundle built with Roc $ROC_COMMIT."

.gitignore

@@ -0,0 +1,5 @@
+build-output/
+dist/
+generated-docs/
+roc-src/
+__pycache__/

README.md

@@ -30,3 +30,42 @@ metadata in those records based on new HTTP spec releases.
 `Method` should in the future become a non-exhaustive custom tag union, also
 for backwards-compatibility. This means if new HTTP spec releases introduce
 new relevant methods, we can expand the tag union to include them as a nonbreaking change.
+
+## Examples
+
+The `examples/` directory contains small apps that demonstrate requests, responses, headers,
+body bytes, timeouts, custom methods, and pure mock HTTP workflows.
+
+Run an example with:
+
+```bash
+roc examples/hello_request.roc
+```
+
+Run the example test module with:
+
+```bash
+roc test examples/tests.roc
+```
+
+## Bundling
+
+Create a package bundle with:
+
+```bash
+scripts/bundle.sh
+```
+
+This writes a `.tar.zst` package archive to `dist/`.
+
+## CI checks
+
+Run the same checks used by CI with:
+
+```bash
+ci/all_tests.sh
+```
+
+The checks format the package and examples, check/test the package, generate docs, bundle the
+package, serve that bundle from localhost, and then check, test, run, build, and execute every
+example against the bundled package URL.

ci/ROC_COMMIT

@@ -0,0 +1 @@
+cf21a1e29315caf430bea4e67269bb94e51b5b3d

ci/all_tests.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$root_dir"
+
+if [ -n "${ROC_HTTP_TMPDIR:-}" ]; then
+    tmp_base="$ROC_HTTP_TMPDIR"
+elif [ -d /private/tmp ]; then
+    tmp_base=/private/tmp
+else
+    tmp_base="${TMPDIR:-/tmp}"
+fi
+
+tmp_dir="$tmp_base/roc-http-ci"
+docs_dir="$tmp_dir/docs"
+bundle_dir="$tmp_dir/bundle"
+
+rm -rf "$tmp_dir"
+mkdir -p "$docs_dir" "$bundle_dir"
+
+echo "roc $(roc version)"
+
+echo ""
+echo "Checking format..."
+roc fmt --check package examples
+
+echo ""
+echo "Checking package..."
+roc check package/main.roc
+
+echo ""
+echo "Running package tests..."
+roc test package/main.roc
+
+echo ""
+echo "Generating package docs..."
+roc docs package/main.roc --output="$docs_dir"
+
+echo ""
+echo "Bundling package..."
+scripts/bundle.sh --output-dir "$bundle_dir"
+
+echo ""
+echo "Testing examples against localhost bundle..."
+python3 ci/test_bundle_examples.py

ci/get_roc_commit.py

@@ -0,0 +1,19 @@
+import re
+from pathlib import Path
+
+
+def main() -> None:
+    commit_path = Path(__file__).resolve().parent / "ROC_COMMIT"
+    try:
+        commit = commit_path.read_text().strip()
+    except FileNotFoundError:
+        raise SystemExit(f"Missing ROC_COMMIT at {commit_path}")
+
+    if not re.fullmatch(r"[0-9a-fA-F]{40}", commit):
+        raise SystemExit(f"Invalid commit hash in ROC_COMMIT: {commit!r}")
+
+    print(commit)
+
+
+if __name__ == "__main__":
+    main()