2.6 KiB
Contracts
A contract is a frozen file describing something that crosses from one tree to another. Each side builds and tests against the file and its fixture, not against the other side's code. The first four were frozen for the 2.0 launch.
| # | Contract | Producer | Consumer | In use since |
|---|---|---|---|---|
| 1 | License file | surfsense_backend license routes |
surfsense_local license module |
2.0.0 |
| 2 | Scraper API auth | the plugin host; surfsense_backend capabilities routes |
the desktop app; surfsense_mcp |
plugin host and app since 2.2.1; backend and MCP not built |
| 3 | Export bundle | surfsense_backend export |
surfsense_local import |
2.0.0 |
| 5 | Desktop telemetry | Electron main (the update check and the usage report); surfsense_local backend (the local summary) |
www's /api/updates and /api/usage routes; the app's UI (the bridge) |
released in 2.2.4; revision 1.1 in 2.2.5 |
Fixtures
export-sample/is an unzipped contract-3 bundle. Tests zip it in a setup step. Check it withpython3 check-export-sample.py.license-sample/holds contract-1 files signed by a test key, plus the generator that makes them. Regenerate and self-check withnode license-sample/generate.mjs.
Both checks are dependency-free and run from this folder.
Five tests read files in this folder by path. surfsense_local/backend/tests/integration/migration/test_import.py, surfsense_local/backend/tests/integration/license/test_license.py and surfsense_backend/tests/unit/services/test_account_export.py read the fixtures; surfsense_backend/tests/integration/test_account_export.py runs check-export-sample.py against a real export; and the release build's test-key guard, surfsense_local/backend/tests/packaging/test_license_key.py, reads the test public key. Moving this folder means updating all five in the same change, plus the skip entry in scripts/check_docs.py and the docs/contracts/** path filter in .github/workflows/desktop-tests.yml.
Changing a contract
A contract changes by a pull request that the owners of both sides approve. CODEOWNERS requests their review, but GitHub accepts one approval, so the second is by agreement. If the change is not backward compatible, bump the version field the contract names (format for the bundle, the alg/field list for the license file) and update the fixture in the same PR. Never change a fixture without changing the contract text that describes it.