From a46eebbae7413c95b1f596717b5d1f8ce0ba73ea Mon Sep 17 00:00:00 2001 From: "Alessandro (Ale) Segala" <43508+ItalyPaleAle@users.noreply.github.com> Date: Wed, 19 Aug 2026 06:30:27 +0000 Subject: [PATCH] tests: run the E2E suite against a standalone Francis runtime Adds a matrix entry that starts a SQLite-backed Francis runtime next to Pocket ID and points FRANCIS_HOST at it, so the same Playwright suite runs with the actor state, alarms, and placement owned by the runtime instead of embedded in Pocket ID. The suite needs no changes to work in that topology: the E2E reset seeds every actor through actors.Service() and deliberately leaves the actor store alone, so it behaves the same whichever side owns it. The CLI spec is the exception, since export and import are the two commands whose behaviour genuinely differs. It now picks the right Compose file, expects an export to carry no francis.bin, feeds the import an archive without one, and gains a case asserting that an archive that does carry one is refused. The runtime is reached over the Compose network on its UDP port, so nothing is published to the host, and the cluster CA is left unpinned, which exercises the same trust-on-first-use path an operator gets without FRANCIS_CA. Pinning is covered by a unit test instead. --- .github/workflows/e2e-tests.yml | 55 ++++++++++++++++- AGENTS.md | 1 + CONTRIBUTING.md | 8 +++ .../bootstrap/actors_bootstrap_test.go | 54 +++++++++++++++++ tests/setup/docker-compose-francis.yml | 48 +++++++++++++++ tests/setup/francis-config.yaml | 26 ++++++++ tests/specs/cli.spec.ts | 59 +++++++++++++++++-- 7 files changed, 243 insertions(+), 8 deletions(-) create mode 100644 tests/setup/docker-compose-francis.yml create mode 100644 tests/setup/francis-config.yaml diff --git a/.github/workflows/e2e-tests.yml b/.github/workflows/e2e-tests.yml index 2e929af8..a6419d40 100644 --- a/.github/workflows/e2e-tests.yml +++ b/.github/workflows/e2e-tests.yml @@ -25,17 +25,26 @@ jobs: strategy: fail-fast: false matrix: + # "francis" selects where the actor runtime lives: embedded in Pocket ID, or a standalone runtime it connects to include: - db: sqlite storage: filesystem + francis: embedded - db: postgres storage: filesystem + francis: embedded - db: sqlite storage: s3 + francis: embedded - db: sqlite storage: database + francis: embedded - db: postgres storage: database + francis: embedded + - db: sqlite + storage: filesystem + francis: remote steps: - name: Checkout code @@ -109,6 +118,31 @@ jobs: if: matrix.storage == 's3' && steps.s3-cache.outputs.cache-hit == 'true' run: docker load < /tmp/localstack-s3-image.tar + - name: Resolve Francis runtime image + if: matrix.francis == 'remote' + id: francis-image + working-directory: ./tests/setup + # The Compose file is the single source of truth for the version, so the cache key follows it automatically + run: | + IMAGE=$(grep -oP '(?<=image: )ghcr\.io/italypaleale/francis:\S+' docker-compose-francis.yml) + echo "image=$IMAGE" >> "$GITHUB_OUTPUT" + echo "key=$(echo "$IMAGE" | tr '/:' '--')" >> "$GITHUB_OUTPUT" + - name: Cache Francis runtime Docker image + if: matrix.francis == 'remote' + uses: actions/cache@v5 + id: francis-cache + with: + path: /tmp/francis-image.tar + key: ${{ steps.francis-image.outputs.key }}-${{ runner.os }} + - name: Pull and save Francis runtime image + if: matrix.francis == 'remote' && steps.francis-cache.outputs.cache-hit != 'true' + run: | + docker pull "${{ steps.francis-image.outputs.image }}" + docker save "${{ steps.francis-image.outputs.image }}" > /tmp/francis-image.tar + - name: Load Francis runtime image + if: matrix.francis == 'remote' && steps.francis-cache.outputs.cache-hit == 'true' + run: docker load < /tmp/francis-image.tar + - name: Install test dependencies run: pnpm --filter pocket-id-tests install --frozen-lockfile @@ -128,7 +162,9 @@ jobs: SCIM_SERVICE_PROVIDER_URL_INTERNAL=http://scim-test-server:8080/v2 EOF - if [ "${{ matrix.db }}" = "postgres" ]; then + if [ "${{ matrix.francis }}" = "remote" ]; then + DOCKER_COMPOSE_FILE=docker-compose-francis.yml + elif [ "${{ matrix.db }}" = "postgres" ]; then DOCKER_COMPOSE_FILE=docker-compose-postgres.yml elif [ "${{ matrix.storage }}" = "s3" ]; then DOCKER_COMPOSE_FILE=docker-compose-s3.yml @@ -150,6 +186,10 @@ jobs: done } & + if [ "${{ matrix.francis }}" = "remote" ]; then + docker compose -f "$DOCKER_COMPOSE_FILE" logs -f --no-log-prefix francis-runtime > /tmp/francis-runtime.log 2>&1 & + fi + - name: Run Playwright tests working-directory: ./tests run: pnpm exec playwright test @@ -158,7 +198,7 @@ jobs: uses: actions/upload-artifact@v7 if: always() && github.event.pull_request.head.ref != 'i18n_crowdin' with: - name: playwright-report-${{ matrix.db }}-${{ matrix.storage }} + name: playwright-report-${{ matrix.db }}-${{ matrix.storage }}-francis-${{ matrix.francis }} path: tests/.report include-hidden-files: true retention-days: 15 @@ -167,7 +207,16 @@ jobs: uses: actions/upload-artifact@v7 if: always() && github.event.pull_request.head.ref != 'i18n_crowdin' with: - name: backend-${{ matrix.db }}-${{ matrix.storage }} + name: backend-${{ matrix.db }}-${{ matrix.storage }}-francis-${{ matrix.francis }} path: /tmp/backend.log include-hidden-files: true retention-days: 15 + + - name: Upload Francis Runtime Report + uses: actions/upload-artifact@v7 + if: always() && matrix.francis == 'remote' && github.event.pull_request.head.ref != 'i18n_crowdin' + with: + name: francis-runtime-${{ matrix.db }}-${{ matrix.storage }} + path: /tmp/francis-runtime.log + include-hidden-files: true + retention-days: 15 diff --git a/AGENTS.md b/AGENTS.md index 2e46f9a6..ed612d29 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,6 +27,7 @@ End-to-end (needs Docker; **stop any local backend on `:1411` first** — see go ```sh cd tests/setup && docker compose up -d --build # rebuild after ANY code change, or you test stale code +# docker-compose-francis.yml runs the same suite against a standalone Francis runtime instead of the embedded one cd ../.. && pnpm test # = playwright test in tests/ ``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 12820898..38cf1d01 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -121,6 +121,14 @@ The tests can be run like this: If you make any changes to the application, you have to rebuild the test environment by running `docker compose up -d --build` again. +By default the test environment runs Pocket ID with the Francis actor runtime embedded in it. To run the same suite against a **standalone Francis runtime** instead, start the environment from the other Compose file: + +```bash +docker compose -f docker-compose-francis.yml up -d --build +``` + +That brings up a SQLite-backed Francis runtime alongside Pocket ID and points `FRANCIS_HOST` at it, so Pocket ID starts no embedded runtime and the actor state, alarms, and placement all live in the runtime instead. The tests themselves are unchanged. CI runs this as an extra matrix entry. + #### Unit tests In the backend we are using unit tests with the built-in Go testing framework. The tests are located in the same folder as the code they are testing and have the `_test.go` suffix. diff --git a/backend/internal/bootstrap/actors_bootstrap_test.go b/backend/internal/bootstrap/actors_bootstrap_test.go index 9a1b7fc1..e8a9b08b 100644 --- a/backend/internal/bootstrap/actors_bootstrap_test.go +++ b/backend/internal/bootstrap/actors_bootstrap_test.go @@ -3,11 +3,18 @@ package bootstrap import ( "bytes" "context" + "crypto/ed25519" + "crypto/rand" + "crypto/x509" + "crypto/x509/pkix" "encoding/hex" + "encoding/pem" "log/slog" + "math/big" "os" "path/filepath" "testing" + "time" francishost "github.com/italypaleale/francis/host" "github.com/italypaleale/francis/host/local" @@ -125,6 +132,30 @@ func TestNewActorsSelectsTopology(t *testing.T) { } }) + // The E2E suite runs the remote variant without a pinned CA, so this is the only place the pinning branch is exercised + t.Run("pinning the cluster CA builds a valid remote host", func(t *testing.T) { + cfg := baseConfig(t) + cfg.FrancisAddresses = []string{"runtime-1.example.com:8443"} + cfg.FrancisHostPSK = []byte("bootstrap-psk-that-is-long-enough") + cfg.FrancisCA = testCAPEM(t) + + opts := NewActorsOpts{EnvConfig: cfg, InstanceID: "ee05c3eb-8129-47a6-a1c7-849998b6f876"} + h, err := opts.newRemoteHost(slog.New(slog.DiscardHandler)) + require.NoError(t, err) + require.NotNil(t, h) + }) + + t.Run("an unparsable cluster CA is rejected", func(t *testing.T) { + cfg := baseConfig(t) + cfg.FrancisAddresses = []string{"runtime-1.example.com:8443"} + cfg.FrancisHostPSK = []byte("bootstrap-psk-that-is-long-enough") + cfg.FrancisCA = []byte("-----BEGIN CERTIFICATE-----\nnot a certificate\n-----END CERTIFICATE-----") + + opts := NewActorsOpts{EnvConfig: cfg, InstanceID: "ee05c3eb-8129-47a6-a1c7-849998b6f876"} + _, err := opts.newRemoteHost(slog.New(slog.DiscardHandler)) + require.Error(t, err) + }) + t.Run("no bootstrap method is rejected by Francis", func(t *testing.T) { cfg := baseConfig(t) cfg.FrancisAddresses = []string{"runtime-1.example.com:8443"} @@ -197,3 +228,26 @@ func TestNewActorsBackupProvider(t *testing.T) { err = provider.Restore(t.Context(), bytes.NewReader(buf.Bytes())) require.NoError(t, err) } + +// testCAPEM returns a self-signed CA certificate in PEM form, standing in for the cluster CA an operator would pin with FRANCIS_CA +func testCAPEM(t *testing.T) []byte { + t.Helper() + + pub, priv, err := ed25519.GenerateKey(rand.Reader) + require.NoError(t, err) + + tmpl := &x509.Certificate{ + SerialNumber: big.NewInt(1), + Subject: pkix.Name{CommonName: "test-cluster-ca"}, + NotBefore: time.Now().Add(-time.Hour), + NotAfter: time.Now().Add(time.Hour), + IsCA: true, + KeyUsage: x509.KeyUsageCertSign, + BasicConstraintsValid: true, + } + + der, err := x509.CreateCertificate(rand.Reader, tmpl, tmpl, pub, priv) + require.NoError(t, err) + + return pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der}) +} diff --git a/tests/setup/docker-compose-francis.yml b/tests/setup/docker-compose-francis.yml new file mode 100644 index 00000000..fd63d25b --- /dev/null +++ b/tests/setup/docker-compose-francis.yml @@ -0,0 +1,48 @@ +# This Docker Compose file is used to set up the environment for the tests. +# It's the variant where Pocket ID does not embed the Francis actor runtime, but connects to a standalone one instead. +services: + lldap: + extends: + file: docker-compose.yml + service: lldap + scim-test-server: + extends: + file: docker-compose.yml + service: scim-test-server + francis-runtime: + image: ghcr.io/italypaleale/francis:0.1.0-rc.1 + volumes: + - ./francis-config.yaml:/etc/francis/config.yaml:ro + - francis-test-data:/data + # The image ships its own HEALTHCHECK, which probes the runtime over the loopback + # It's repeated here so Pocket ID can wait on it, and so a runtime that never comes up fails fast instead of after the default retries + healthcheck: + test: ["CMD", "/bin/francis", "healthcheck"] + interval: 2s + timeout: 5s + retries: 15 + start_period: 5s + pocket-id: + extends: + file: docker-compose.yml + service: pocket-id + environment: + APP_ENV: test + ENCRYPTION_KEY: test-encryption-key + FILE_BACKEND: ${FILE_BACKEND} + # The runtime's port is UDP, since WebTransport runs over HTTP/3 + FRANCIS_HOST: francis-runtime:7400 + # Must match "bootstrap.hostPSK" in francis-config.yaml + FRANCIS_HOST_PSK: e2e-host-bootstrap-psk-0123456789 + # FRANCIS_CA is intentionally unset, so this exercises the same trust-on-first-use path an operator gets without it + # The cluster only exists inside this Compose network for the duration of the tests + # + # Peers reach actors placed on this host at ACTORS_HOST, which the runtime hands out, so it has to be the address other containers resolve rather than the default wildcard + ACTORS_HOST: pocket-id + depends_on: + francis-runtime: + condition: service_healthy + +volumes: + pocket-id-test-data: + francis-test-data: diff --git a/tests/setup/francis-config.yaml b/tests/setup/francis-config.yaml new file mode 100644 index 00000000..6c490807 --- /dev/null +++ b/tests/setup/francis-config.yaml @@ -0,0 +1,26 @@ +# Configuration for the standalone Francis runtime used by the "remote Francis" E2E variant. +# In that variant Pocket ID does not embed the actor runtime: it connects to this one instead, which owns the actor state, placement, and alarms. +# These secrets are fixed test values and must match the FRANCIS_HOST_PSK passed to Pocket ID in docker-compose-francis.yml. + +# The WebTransport server runs over HTTP/3, so this port is UDP +bind: "0.0.0.0:7400" + +# The runtime PSKs derive the cluster CA that signs every workload certificate +runtimePSKs: + - "e2e-runtime-psk-0123456789abcdef" + +# Hosts prove they may join by presenting this pre-shared key +bootstrap: + method: psk + hostPSK: "e2e-host-bootstrap-psk-0123456789" + +# The runtime owns its own SQLite store, which is separate from Pocket ID's database +# It lives on a volume because the image runs as a non-root user that cannot write to the image filesystem +provider: + connectionString: "/data/francis.db" + +# A single Pocket ID replica joins the cluster, matching the cap the embedded runtime applies when HA is off +maxHosts: 1 + +log: + level: debug diff --git a/tests/specs/cli.spec.ts b/tests/specs/cli.spec.ts index 6d0d3c06..a10adbbd 100644 --- a/tests/specs/cli.spec.ts +++ b/tests/specs/cli.spec.ts @@ -12,11 +12,19 @@ const containerName = 'pocket-id'; const setupDir = pathFromRoot('setup'); const exampleExportPath = pathFromRoot('resources/export'); const dockerCommandMaxBuffer = 100 * 1024 * 1024; -let mode: 'sqlite' | 'postgres' | 's3' = 'sqlite'; +let mode: 'sqlite' | 'postgres' | 's3' | 'francis' = 'sqlite'; + +// With a standalone Francis runtime the actor data lives in the runtime's own store rather than in Pocket ID's database, +// so an export cannot include francis.bin and an import refuses an archive that carries one. +function isRemoteFrancis(): boolean { + return mode === 'francis'; +} test.beforeAll(() => { const dockerComposeLs = runDockerCommand(['compose', 'ls', '--format', 'json']); - if (dockerComposeLs.includes('postgres')) { + if (dockerComposeLs.includes('francis')) { + mode = 'francis'; + } else if (dockerComposeLs.includes('postgres')) { mode = 'postgres'; } else if (dockerComposeLs.includes('s3')) { mode = 's3'; @@ -104,6 +112,30 @@ test('Import SQLite export via stdin', async () => { compareExports(exampleExportPath, exportExtracted); }); +test('Import rejects an archive with actor data against a standalone runtime', async () => { + test.skip( + !isRemoteFrancis(), + 'Only applies when a standalone Francis runtime owns the actor data' + ); + + // Keeping francis.bin makes this the archive of a deployment that embedded the runtime, which has nowhere to be restored here + const archivePath = path.join(tmpDir, 'example-export-with-actors.zip'); + const archive = archiveExampleExport(archivePath, true); + + // The import aborts before it opens the database, so the running instance is left untouched + let stderr = ''; + expect(() => { + try { + runImportFromStdin(archive); + } catch (err: any) { + stderr = err?.stderr?.toString() ?? ''; + throw err; + } + }).toThrow(); + + expect(stderr).toContain('francis.bin'); +}); + function compareExports(dir1: string, dir2: string): void { const hashes1 = hashAllFiles(dir1); const hashes2 = hashAllFiles(dir2); @@ -135,9 +167,18 @@ function compareExports(dir1: string, dir2: string): void { expect(normalizedActual).toEqual(normalizedExpected); // Compare francis.bin contents + // The reference export always carries it, while the produced one only does when Pocket ID owns the actor data const file1 = path.join(dir1, 'francis.bin'); const file2 = path.join(dir2, 'francis.bin'); - + + if (isRemoteFrancis()) { + expect( + fs.existsSync(file2), + `${file2} must not exist: the standalone Francis runtime owns the actor data` + ).toBe(false); + return; + } + for (const filePath of [file1, file2]) { expect(fs.existsSync(filePath), `${filePath} should exist`).toBe(true); @@ -149,12 +190,18 @@ function compareExports(dir1: string, dir2: string): void { } } -function archiveExampleExport(outputPath: string): Buffer { +// archiveExampleExport zips the reference export so it can be fed back to the import command. +// With a standalone Francis runtime it drops francis.bin, so the archive matches what an export produces in that topology; keepActorsBackup overrides that to build the archive the import is expected to reject. +function archiveExampleExport(outputPath: string, keepActorsBackup = false): Buffer { fs.rmSync(outputPath, { force: true }); + const skipActorsBackup = isRemoteFrancis() && !keepActorsBackup; + const zip = new AdmZip(); const files = fs.readdirSync(exampleExportPath); for (const file of files) { + if (skipActorsBackup && file === 'francis.bin') continue; + const filePath = path.join(exampleExportPath, file); if (fs.statSync(filePath).isFile()) { zip.addLocalFile(filePath); @@ -168,7 +215,6 @@ function archiveExampleExport(outputPath: string): Buffer { return buffer; } - // Helper to load JSON files function loadJSON(path: string) { return JSON.parse(fs.readFileSync(path, 'utf-8')); @@ -382,6 +428,9 @@ function dockerComposeArgs(args: string[]): string[] { case 's3': dockerComposeFile = 'docker-compose-s3.yml'; break; + case 'francis': + dockerComposeFile = 'docker-compose-francis.yml'; + break; } return ['compose', '-f', dockerComposeFile, ...args]; }