Skip to content

fix(apphost): register OpenRegister's autoloader before referencing AppHost (gate-64 / ADR-040) - #288

Merged
rubenvdlinde merged 4 commits into
developmentfrom
fix/adr-040-autoload-prelude
Aug 6, 2026
Merged

rubenvdlinde merged 4 commits into
developmentfrom
fix/adr-040-autoload-prelude

Conversation

@rubenvdlinde

Copy link
Copy Markdown
Contributor

The defect

Nextcloud registers apps in sorted order: OC_App::getEnabledApps() does sort($apps) and Coordinator::registerApps() walks that list calling OC_App::registerAutoloading($appId, $path) and then $app->register() one app at a time. Every app's register() therefore runs before the PSR-4 prefix of every alphabetically-later app exists.

scholiq sorts after openregister, so OCA\OpenRegister\ happens to be autoloadable here today — by alphabet, not by design. Scholiq leans on that accident harder than most apps do: its Bootstrap::register() call is unguarded. The moment the ordering stops holding — an app id change, a multi-apps_paths install, this composition root moving into a package that sorts earlier — the resulting \Error aborts the whole of Application::register(). Coordinator::registerApps() catches the Throwable, logs an emergency and continues, so Scholiq would stay enabled and keep serving with ServiceOverrideRegistrar and EventListenerWiring silently never run.

hydra gate-64 apphost-autoload-prelude flags this, and it is the one failure on the hydra-gates v1.5.0 bump PR #287.

The fix

lib/AppInfo/OpenRegisterAutoloader.php — register OpenRegister's PSR-4 prefix ourselves before touching any OCA\OpenRegister\… name:

  • OC_App::registerAutoloading() touches only the autoloader and is idempotent, so on the current ordering this call costs nothing.
  • IAppManager::loadApp('openregister') is deliberately not used: it marks OpenRegister loaded and calls Coordinator::bootApp(), booting it before its own register() has run.
  • The prelude never throws — an exception escaping it would introduce exactly the aborted-register() failure it exists to prevent.

It lives in its own class so that "never throws" contract is reachable from a unit test: Application cannot be constructed without a Nextcloud DI container.

Verification

  • hydra gate-64 goes FAIL → PASS on this branch under the v1.5.0 gate script. Positive control: deleting OpenRegisterAutoloader.php from the same tree puts it back to FAIL.
  • New tests/Unit/AppInfo/OpenRegisterAutoloaderTest.php asserts the never-throws and idempotence contracts.

With this merged, #287 (hydra-gates-ref → v1.5.0) should go green.

Spec: new requirement in openspec/specs/apphost-adoption/spec.md.

Ref: ADR-040, hydra-gates gate-64 (ConductionNL/.github#174).

…ppHost

Nextcloud registers apps in sorted order: OC_App::getEnabledApps() does
sort($apps) and Coordinator::registerApps() walks that list calling
OC_App::registerAutoloading($appId, $path) and then $app->register() for one
app at a time, so every app registers before the PSR-4 prefix of every
alphabetically-later app exists.

`scholiq` sorts after `openregister`, so OCA\OpenRegister\ happens to be
autoloadable here today — by alphabet, not by design. Scholiq depends on that
accident more sharply than most: its Bootstrap::register() call is UNGUARDED,
so the moment the ordering stops holding the resulting \Error aborts the WHOLE
of Application::register(). Coordinator catches it, logs an 'emergency' and
continues, leaving Scholiq enabled and serving with ServiceOverrideRegistrar
and EventListenerWiring silently never run.

Fix: register OpenRegister's prefix ourselves first. registerAutoloading()
touches only the autoloader and is idempotent, so on the current ordering this
costs nothing. IAppManager::loadApp() is deliberately NOT used: it marks
OpenRegister loaded and calls Coordinator::bootApp(), booting it before its own
register() has run.

Caught by hydra gate-64 (apphost-autoload-prelude), ADR-040. Unblocks the
gate-64 failure on the hydra-gates v1.5.0 bump PR (#287).
@github-actions

github-actions Bot commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/scholiq @ 3f3b7f5

Check PHP Vue Security License Tests
lint ✅
phpcs ✅
phpmd ❌
psalm ❌
phpstan ✅
phpmetrics ✅
eslint ✅
stylelint ✅
build ✅
check-specs ✅
composer ✅ ✅ 100/100
npm ✅ ✅ 750/750
PHPUnit ❌
Newman ⏭️
Playwright ⏭️
Hydra gates ❌

Quality workflow — 2026-08-06 08:05 UTC

Download the full PDF report from the workflow artifacts.

Two CI findings on the prelude, both real:

1. psalm UndefinedClass on \OC_App. It is Nextcloud's server-private legacy
   bootstrap class, absent from nextcloud/ocp, and there is no OCP interface
   for registering another app's autoloader. Declared as a suppressed
   referencedClass in psalm.xml, the same way doriath declares it.

2. The coverage ratchet. `return true` after the call plus `return false` in
   the catch gave the method a branch that NO environment can exercise both
   sides of — whichever runs, the other is dead in that run — so the class
   could never reach full line coverage. No caller ever consumed the return
   value either: what callers depend on is the class_exists() guard that
   follows the call. The method is now void with a single statement in the
   try and a comment-only catch, so every executable line runs in every
   environment.

The tests now assert the two things that are actually observable: that control
returns to the caller at all (a Throwable escaping would fail the test, and in
production would abort the whole register()), and that a second call does not
stack another autoloader.

phpmd StaticAccess on the new composition-root call is documented on the
calling method rather than baselined.
…narios

The two scenarios added for the ADR-040 prelude each carried an '@e2e exclude'.
An exclusion is not evidence, and neither behaviour is reachable from a browser
or an HTTP client: both live in the app-registration phase, which completes
before the first request is dispatched, and the absent-OpenRegister path cannot
be set up on an instance that needs OpenRegister to serve the app at all.

Stated in the requirement prose instead, naming the unit test that does assert
them (tests/Unit/AppInfo/OpenRegisterAutoloaderTest.php). No scenario is
declared, so none is excluded.
@github-actions

github-actions Bot commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/scholiq @ 806cd76

Check PHP Vue Security License Tests
lint ✅
phpcs ✅
phpmd ✅
psalm ✅
phpstan ✅
phpmetrics ✅
eslint ✅
stylelint ✅
build ✅
check-specs ✅
composer ✅ ✅ 100/100
npm ✅ ✅ 750/750
PHPUnit ❌
Newman ⏭️
Playwright ⏭️
Hydra gates ❌

Quality workflow — 2026-08-06 08:18 UTC

Download the full PDF report from the workflow artifacts.

@github-actions

github-actions Bot commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/scholiq @ 08403e2

Check PHP Vue Security License Tests
lint ✅
phpcs ✅
phpmd ✅
psalm ✅
phpstan ✅
phpmetrics ✅
eslint ✅
stylelint ✅
build ✅
check-specs ✅
composer ✅ ✅ 100/100
npm ✅ ✅ 750/750
PHPUnit ❌
Newman ⏭️
Playwright ⏭️
Hydra gates ❌

Quality workflow — 2026-08-06 08:25 UTC

Download the full PDF report from the workflow artifacts.

The coverage ratchet was right and the code was wrong. Clover for scholiq shows
it exactly: line 100 (the registerAutoloading call) count=2, line 101 (the
catch) count=0. The catch was never entered — because every instance this suite
runs on HAS OpenRegister installed, so getAppPath() never throws. The
never-rethrow branch, which is the entire reason this class exists, had never
once been executed by a test.

register() now takes an optional app id. Production callers pass nothing and get
'openregister'; the new test passes an id that cannot resolve, so
getAppPath() throws and the catch runs. The literal stays AT the
registerAutoloading call site rather than becoming a signature default, so it
remains visible to a reader and to hydra gate-64, which reads that call's
arguments.

The new test asserts something real rather than merely not throwing: a prelude
whose app cannot be resolved must leave spl_autoload_functions() untouched.
@github-actions

github-actions Bot commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/scholiq @ 58b3241

Check PHP Vue Security License Tests
lint ✅
phpcs ✅
phpmd ✅
psalm ✅
phpstan ✅
phpmetrics ✅
eslint ✅
stylelint ✅
build ✅
check-specs ✅
composer ✅ ✅ 100/100
npm ✅ ✅ 750/750
PHPUnit ✅
Newman ⏭️
Playwright ⏭️
Hydra gates ✅

Quality workflow — 2026-08-06 08:42 UTC

Download the full PDF report from the workflow artifacts.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant