Upgrade Harper to v5: add integration tests, CI workflow, and dev tooling by BboyAkers · Pull Request #48 · HarperFast/prometheus-exporter

BboyAkers · 2026-06-08T20:27:18Z

Summary

Install harper@^5.0.28 and @harperfast/integration-testing@^0.4.0 as devDependencies
Add TypeScript devDependency and tsconfig.json
Add integrationTests/metrics.test.ts covering:
- Harper starts successfully
- GET /prometheus_exporter/metrics returns HTTP 200 with Prometheus/OpenMetrics text
- Response content-type is text/plain or application/openmetrics-text
- Default Node.js process metrics (from prom-client collectDefaultMetrics()) are present
- /metrics/fast path returns 200
- PrometheusExporterSettings table is accessible via REST
- forceAuthorization setting is initialized
Apply harperBinPath fix in test setup (workaround for ERR_PACKAGE_PATH_NOT_EXPORTED — harper's exports map only exposes ".", so harper/dist/bin/harper.js is not resolvable via the harness auto-resolve path)
Add .github/workflows/integration-tests.yml (Node matrix 22/24/26, pinned actions to commit hashes)
Regenerate package-lock.json with --os=linux --cpu=x64 --include=optional so bufferutil, utf-8-validate, and node-gyp-build are recorded for Linux CI
Un-ignore package-lock.json (was in .gitignore; CI needs it for npm ci)
Update package.json author branding: HarperDB, Inc. → Harper
Update README note: exporter supports Harper v5 in addition to v4.2+

Migration items applied / N/A

Item	Status
`harperdb` → `harper` import swap	N/A — `harperdb`/`harper` is a runtime-provided global, not a listed dependency
`Table.get()` returns plain frozen records	Already handled — `recordProp` compat shim added in commit `73e2fa6`
`wasLoadedFromSource()` → `target.loadedFromSource`	N/A — no cache source pattern
`Blob.save()` → `saveBeforeCommit`	N/A — no blob storage
Process spawning whitelisting	N/A — no child process spawning
Transaction context	N/A — no explicit transaction management

Known issues / Notes

Local tests fail with EADDRNOTAVAIL: macOS loopback aliases are not configured on this machine (only 127.0.0.1 exists, and the integration harness binds Harper to 127.0.0.2+). This is environmental — CI runs on ubuntu-latest which supports the full 127.0.0.0/8 range. CI is the gate.
harperBinPath workaround: upstream issue — harper package should export its bin path or the harness should resolve via the package root instead of the blocked deep subpath.

npm scope

The package name is @harperdb/prometheus-exporter. If this should move to a current Harper npm scope (@harperfast/ or similar), that is a manual step — flagged for the team per the upgrade plan (§11.1).

Test plan

CI passes on Node 22, 24, and 26
GET /prometheus_exporter/metrics returns valid Prometheus/OpenMetrics text
PrometheusExporterSettings table initializes correctly on first boot

🤖 Generated with Claude Code

- Install harper@5.0.28 and @harperfast/integration-testing as devDependencies - Add TypeScript devDependency and tsconfig.json - Add integrationTests/metrics.test.ts covering the /metrics endpoint, content-type, default Node.js process metrics, and PrometheusExporterSettings table initialization; apply harperBinPath fix (ERR_PACKAGE_PATH_NOT_EXPORTED) - Add .github/workflows/integration-tests.yml (Node matrix 22/24/26, pinned actions) - Regenerate package-lock.json with --os=linux --cpu=x64 --include=optional so bufferutil/utf-8-validate/node-gyp-build are recorded for Linux CI - Un-ignore package-lock.json (was in .gitignore; CI needs it for npm ci) - Update package.json author branding HarperDB, Inc. -> Harper - Update README note: exporter supports Harper v5 in addition to v4.2+ Migration items N/A: no harperdb imports (runtime global); no Table.get() return shape issues; no Blob.save(); no wasLoadedFromSource(); v5 plain-record access fix was already applied in commit 73e2fa6 (recordProp compat shim). Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

gemini-code-assist · 2026-06-08T20:27:22Z

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

Harper returns the Prometheus string as application/json when no explicit Accept header is sent. Update the content-type test to accept that, and add an extractMetricsText() helper that unwraps JSON-encoded strings before checking for Prometheus metric comments. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

- Anchor harperBinPath at package root via harper/package.json instead of main-entry dirname - Throw on non-string JSON body in extractMetricsText instead of silently stringifying - Remove HTTP 400 from accepted status set in 'Harper starts successfully' test - Remove catch-all text/ and dead text/plain arms from content-type assertion - Remove unnecessary checkout step from generate-node-version-matrix CI job Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Bump the harper dependency to ^5.2.1 and regenerate the lockfile. Regenerated in full so the optional native deps (bufferutil, utf-8-validate, segfault-handler) stay in the tree for Linux CI. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The previous lockfile was generated with npm 11, which does not auto-install the peer dependencies of an optional dependency. harper 5.2.1 pulls alasql, which optionally depends on react-native-fs, whose peers (react-native, react) npm 12 installs and npm 11 does not. CI runs npm 12 on Node 24/26, so npm ci failed there with those packages "missing from lock file" while Node 22 (npm 11) passed. Regenerated with npm 12 so the lockfile carries the full tree. lockfileVersion stays 3; npm ci verified under both npm 11 and npm 12. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Walk up from the resolved main entry to the package root and read the CLI path out of harper's `bin` field, rather than assuming the main entry sits at the root of dist/. Survives a dist/ restructure and fails with a named error instead of a cryptic ENOENT. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

BboyAkers and others added 2 commits June 8, 2026 16:29

Fix CI shell injection in integration-tests workflow

6016e65

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>