Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 47 additions & 1 deletion hydra-gates/scripts/lib/test_gate_route_registration.sh
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,8 @@ for _f in routes-standard routes-standard-missing-update \
delegated-registrar delegated-registrar-absent \
store-plane store-plane-absent store-plane-coincidental \
monitoring-capitalised monitoring-per-object monitoring-per-object-only \
monitoring-none knr-braces; do
monitoring-none knr-braces \
apphost-engine-generics apphost-engine-generics-leaf; do
[ -d "${FIXTURES}/${_f}" ] || _bad "fixture ${FIXTURES}/${_f} does not exist — this suite would be green on nothing"
done

Expand Down Expand Up @@ -395,6 +396,51 @@ if _run "${FIXTURES}/knr-braces"; then
"knr-braces: exactly ONE finding — brace style changed nothing but the phantom"
fi

# ---------------------------------------------------------------------------
# THE ENGINE'S OWN GENERICS ARE A LIBRARY, NOT ITS ENDPOINTS (2026-11-06)
#
# ADR-040: `lib/AppHost/Controller/Generic*` is shipped by the engine (the
# repo with lib/AppHost/Bootstrap.php) and SERVED in a leaf app, where
# `Bootstrap::register()` binds the classes and `Routes::standard()` names
# their routes. In the engine repo the generics it does not use itself have
# no route, by design. Enumerated like any controller they were a permanent
# finding in exactly one repo — measured on openregister, `beta` and
# `development` alike: twelve `missing-route` lines over GenericDashboard,
# GenericPreferences, GenericSettings and GenericStore on every pull request.
#
# Control pair. `apphost-engine-generics/` carries Bootstrap.php and an
# unrouted GenericDashboard (page, catchAll): NOT reported. Its `gadget#run`
# — a conventional controller, routed nowhere — MUST still be reported, so
# the exemption is one directory in one kind of repo, not a blanket. The
# routed GenericHealth stays judged on the route side. The anti-widening
# half, `apphost-engine-generics-leaf/`, is the SAME tree minus
# Bootstrap.php — a leaf that copied a generic in — and there both
# GenericDashboard methods MUST be reported.
# ---------------------------------------------------------------------------
if _run "${FIXTURES}/apphost-engine-generics"; then
_expect_gate 14 "FAIL" "apphost-engine-generics: the engine's genuinely unrouted conventional method is still a finding"
_expect_log "${_RRLOG}" "GadgetController\.php method=run .*rule=missing-route" \
"apphost-engine-generics: gadget#run — routed nowhere — IS reported"
_expect_not_log "${_RRLOG}" "GenericDashboardController" \
"apphost-engine-generics: the engine's unrouted GenericDashboard is a library class and is NOT reported"
_expect_not_log "${_RRLOG}" "GenericHealthController" \
"apphost-engine-generics: the routed GenericHealth resolves through its binding and is NOT reported"
_expect_lines "${_RRLOG}" 1 \
"apphost-engine-generics: exactly ONE finding — the exemption is lib/AppHost/Controller/Generic* in the engine, nothing else"
fi

if _run "${FIXTURES}/apphost-engine-generics-leaf"; then
_expect_gate 14 "FAIL" "apphost-engine-generics-leaf: without Bootstrap.php this is a leaf, and its copied generic IS judged"
_expect_log "${_RRLOG}" "GenericDashboardController\.php method=page .*rule=missing-route" \
"apphost-engine-generics-leaf: genericDashboard#page IS reported"
_expect_log "${_RRLOG}" "GenericDashboardController\.php method=catchAll .*rule=missing-route" \
"apphost-engine-generics-leaf: genericDashboard#catchAll IS reported"
_expect_log "${_RRLOG}" "GadgetController\.php method=run .*rule=missing-route" \
"apphost-engine-generics-leaf: gadget#run IS reported"
_expect_lines "${_RRLOG}" 3 \
"apphost-engine-generics-leaf: exactly THREE findings — the same tree minus the engine marker loses the exemption and nothing else changes"
fi

echo
echo "== summary =="
printf ' passed: %d\n failed: %d\n' "${_pass_n}" "${_fail_n}"
Expand Down
38 changes: 38 additions & 0 deletions hydra-gates/scripts/run-hydra-gates.sh
Original file line number Diff line number Diff line change
Expand Up @@ -3993,6 +3993,44 @@ if [ -f appinfo/routes.php ] && [ -n "$(_enum_controllers tracked | head -1)" ];
# arms are recorded here rather than at one convenient place.
echo "${_ctrl_path}" >> "${_rr_seen}"

# THE ENGINE'S OWN GENERICS ARE A LIBRARY, NOT THIS APP'S ENDPOINTS.
#
# ADR-040: the AppHost generics (`lib/AppHost/Controller/Generic*`)
# are shipped by the engine — the repo that carries
# `lib/AppHost/Bootstrap.php` — and served in a LEAF app, where
# `Bootstrap::register()` binds them and `Routes::standard()` names
# their routes. In the engine repo itself they are source files with
# no route of their own, by design: the engine routes what it uses
# (`AppHost\Controller\GenericHealth#index`, `…GenericMetrics#index`)
# and leaves the rest to the adopters.
#
# Judged like any controller they are a permanent finding in exactly
# one repo. MEASURED 2026-11-06 on openregister, `beta` and
# `development` alike: twelve `missing-route` lines over
# GenericDashboard, GenericPreferences, GenericSettings and
# GenericStore, on every pull request, with no route anyone would
# add — adding one would turn a library class into a live endpoint.
#
# Narrow on purpose: the file must sit under lib/AppHost/Controller/
# AND this repo must define the engine's Bootstrap (a leaf imports
# `OCA\OpenRegister\AppHost\Bootstrap`; it never ships the file). A
# leaf that copies a generic into its own lib/AppHost/Controller/ is
# still judged — `apphost-engine-generics-leaf/` asserts that — and
# so is every conventional controller in the engine
# (`apphost-engine-generics/` keeps a `gadget#run` that MUST fail).
# A generic the engine DOES route is unaffected: the route-side
# check (`method-not-found-on-target-controller`) runs on route
# names, not on this enumeration.
case "${_ctrl_path}" in
lib/AppHost/Controller/Generic*Controller.php)
if [ -f lib/AppHost/Bootstrap.php ] \
&& _php_code_only lib/AppHost/Bootstrap.php | grep -qE '^[[:space:]]*(abstract[[:space:]]+|final[[:space:]]+)?class[[:space:]]+Bootstrap\b' \
&& _php_code_only lib/AppHost/Bootstrap.php | grep -qE 'function[[:space:]]+register[[:space:]]*\('; then
continue
fi
;;
esac

# Derive the controller route slug — strip lib/Controller/ prefix +
# Controller.php suffix, lowercase the first character. Settings/
# subnamespace becomes `Settings\Foo`.
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<?php
// SPDX-License-Identifier: EUPL-1.2
//
// The engine routes what it USES of its own generics (health here) and
// nothing else: GenericDashboard is shipped for the leaf apps, which name
// its routes through Routes::standard(). `gadget#run` has no route anywhere
// and must stay a finding — the exemption is one directory, not a blanket.
return [
'routes' => [
['name' => 'AppHost\Controller\GenericHealth#index', 'url' => '/api/health', 'verb' => 'GET'],
['name' => 'ping#index', 'url' => '/api/ping', 'verb' => 'GET'],
],
];
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<?php
// SPDX-License-Identifier: EUPL-1.2
declare(strict_types=1);

namespace OCA\Fixture\AppHost\Controller;

// The generic the engine ships for its leaf apps and does NOT route itself.
// In the engine (`apphost-engine-generics/`, lib/AppHost/Bootstrap.php present)
// this is a library class and NOT a finding; in a leaf that merely copied it
// (`apphost-engine-generics-leaf/`, no Bootstrap.php) both methods ARE.
class GenericDashboardController extends Controller
{
#[NoAdminRequired]
public function page(): TemplateResponse
{
return new TemplateResponse('fixture', 'index');
}

#[NoAdminRequired]
public function catchAll(string $path): TemplateResponse
{
return new TemplateResponse('fixture', 'index');
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<?php
// SPDX-License-Identifier: EUPL-1.2
declare(strict_types=1);

namespace OCA\Fixture\AppHost\Controller;

// A generic the engine DOES route (see appinfo/routes.php).
class GenericHealthController extends Controller
{
#[PublicPage]
#[NoCSRFRequired]
public function index(): JSONResponse
{
return new JSONResponse(['status' => 'ok']);
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<?php
// SPDX-License-Identifier: EUPL-1.2
declare(strict_types=1);

namespace OCA\Fixture\AppInfo;

// Binds the ONE generic this app routes itself, as the engine does for its
// health and metrics endpoints; the resolver maps the namespaced route name
// to lib/AppHost/Controller/ through this binding.
class Application
{
public function register($context): void
{
$context->registerService(
'AppHost\\Controller\\GenericHealthController',
static fn ($c) => new \OCA\Fixture\AppHost\Controller\GenericHealthController()
);
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
<?php
// SPDX-License-Identifier: EUPL-1.2
declare(strict_types=1);

namespace OCA\Fixture\Controller;

// NO route anywhere. MUST be reported in both fixtures of the pair.
class GadgetController extends Controller
{
public function run(): JSONResponse
{
return new JSONResponse(['ran' => true]);
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<?php
// SPDX-License-Identifier: EUPL-1.2
declare(strict_types=1);

namespace OCA\Fixture\Controller;

// Routed, conventional — the control that the engine's own endpoints are
// still enumerated and still judged.
class PingController extends Controller
{
#[PublicPage]
public function index(): JSONResponse
{
return new JSONResponse(['pong' => true]);
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<?php
// SPDX-License-Identifier: EUPL-1.2
//
// The engine routes what it USES of its own generics (health here) and
// nothing else: GenericDashboard is shipped for the leaf apps, which name
// its routes through Routes::standard(). `gadget#run` has no route anywhere
// and must stay a finding — the exemption is one directory, not a blanket.
return [
'routes' => [
['name' => 'AppHost\Controller\GenericHealth#index', 'url' => '/api/health', 'verb' => 'GET'],
['name' => 'ping#index', 'url' => '/api/ping', 'verb' => 'GET'],
],
];
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<?php
// SPDX-License-Identifier: EUPL-1.2
declare(strict_types=1);

namespace OCA\Fixture\AppHost;

// THE ENGINE MARKER. A leaf app imports `OCA\OpenRegister\AppHost\Bootstrap`
// and calls `Bootstrap::register()`; only the engine ships this file. Its
// presence, as a class named Bootstrap with a register() method, is what
// makes lib/AppHost/Controller/Generic* a library here rather than this
// app's unrouted endpoints.
class Bootstrap
{
public static function register($context, array $options = []): void
{
// Binds the generics in the leaf's container; the leaf names their
// routes through Routes::standard().
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<?php
// SPDX-License-Identifier: EUPL-1.2
declare(strict_types=1);

namespace OCA\Fixture\AppHost\Controller;

// The generic the engine ships for its leaf apps and does NOT route itself.
// In the engine (`apphost-engine-generics/`, lib/AppHost/Bootstrap.php present)
// this is a library class and NOT a finding; in a leaf that merely copied it
// (`apphost-engine-generics-leaf/`, no Bootstrap.php) both methods ARE.
class GenericDashboardController extends Controller
{
#[NoAdminRequired]
public function page(): TemplateResponse
{
return new TemplateResponse('fixture', 'index');
}

#[NoAdminRequired]
public function catchAll(string $path): TemplateResponse
{
return new TemplateResponse('fixture', 'index');
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<?php
// SPDX-License-Identifier: EUPL-1.2
declare(strict_types=1);

namespace OCA\Fixture\AppHost\Controller;

// A generic the engine DOES route (see appinfo/routes.php).
class GenericHealthController extends Controller
{
#[PublicPage]
#[NoCSRFRequired]
public function index(): JSONResponse
{
return new JSONResponse(['status' => 'ok']);
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<?php
// SPDX-License-Identifier: EUPL-1.2
declare(strict_types=1);

namespace OCA\Fixture\AppInfo;

// Binds the ONE generic this app routes itself, as the engine does for its
// health and metrics endpoints; the resolver maps the namespaced route name
// to lib/AppHost/Controller/ through this binding.
class Application
{
public function register($context): void
{
$context->registerService(
'AppHost\\Controller\\GenericHealthController',
static fn ($c) => new \OCA\Fixture\AppHost\Controller\GenericHealthController()
);
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
<?php
// SPDX-License-Identifier: EUPL-1.2
declare(strict_types=1);

namespace OCA\Fixture\Controller;

// NO route anywhere. MUST be reported in both fixtures of the pair.
class GadgetController extends Controller
{
public function run(): JSONResponse
{
return new JSONResponse(['ran' => true]);
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<?php
// SPDX-License-Identifier: EUPL-1.2
declare(strict_types=1);

namespace OCA\Fixture\Controller;

// Routed, conventional — the control that the engine's own endpoints are
// still enumerated and still judged.
class PingController extends Controller
{
#[PublicPage]
public function index(): JSONResponse
{
return new JSONResponse(['pong' => true]);
}
}
Loading