Appearance
Modules: sign, test, release and upgrade
Signing
Real servers accept a source module only when it's signed with a key they trust. The signature (Ed25519) covers the manifest, whose files lists the sha256 of every file, so one signature covers the whole module.
bash
php bin/console module:keygen <key_id> # once; never reuse a key id
php bin/console module:package modules/source/hello --key=<key_id> --write-manifest
php bin/console module:verify modules/source/hello # "verified"Servers trust keys whose .pub is in storage/modules/keys/trusted/. Keep private keys off servers; BMA's release build signs modules for you.
| Refused as | Means |
|---|---|
module_unsigned | no signature (accepted only on a local sandbox) |
module_signature_invalid | wrong or untrusted key, or the manifest changed after signing: never accepted |
module_package_tampered | a file is missing, changed or not listed: rebuild and stamp again |
module_bundle_unlisted | the UI bundle isn't in files: build, then stamp |
version_exists | that version is already registered: bump version |
Tests
Module tests live in the repository's tests/Modules/<Name>Test.php and run against a sandbox:
php
class HelloRoutesTest
{
public function testHello()
{
assert_status(401, TestApi::anon()->get('/hello/hello'));
assert_status(200, TestApi::as('ta_alpha')->get('/hello/hello'));
assert_status(403, TestApi::as('ta_beta')->get('/hello/hello')); // not enabled for beta
}
}Every endpoint needs: signed out → 401, another organization → 403 or 404, no permission → 403, and the happy path. bin/check runs the whole suite plus the scope lint, and builds and registers every module. Before review: module:validate passes, the scope lint is clean, your router serves only its prefixes.
Releasing a new version
- Change the code, bump
version(add anx-changelogline). - Build, sign,
module:register(add--channel=betato try it on beta first). - Organizations move in Tenant Modules (or
POST /tenants/<id>/modules/<id>/upgrade {"to": "1.1.0"}), after a preview: migrations to run, permissions and menus added or removed, requirements, warnings. - There's no promotion from beta: register the same code again as a stable version.
Overrides and variants
- Overrides: an organization renames, hides or moves your menu items and screens, or changes
x-config, within the paths you list inoverridable. They follow every upgrade; ones that stop applying are reported. - Variants: a private copy an organization owns (
extends: {id, version}). Builder modules are forked from Tenant Modules → Create variant; source modules withphp bin/console module:fork <base> <new-id> --tenant=<code>. A module and its variant can't both be on unless both setcoexist.module:diffmerges a newer base into a variant.