fix(core): 디버그 라우트 그룹 게이트 일원화 + 확장 자산 CSS 상대 참조 치환

https://github.com/gnuboard/g7/issues/128 (제보자 glitter-gim) 과 그 부수의무
전수조사에서 확정한 결함군을 닫는다.

## 디버그 라우트 게이트 (F1~F5)

게이트가 핸들러 안에 흩어져 있어 8개 라우트 중 3개에만 붙어 있었다. 빠진 쪽에
`File::cleanDirectory(storage/debug-dump)` 를 수행하는 `DELETE clear` 가 있었고,
production·APP_DEBUG=false 에서도 미인증 200 으로 덤프 전체가 지워졌다. GET 4종은
User SPA catch-all 이 등록 순서상 앞서 가려 주고 있었을 뿐이라, 보호를 우연에 맡긴
구조였다.

게이트를 `bootstrap/app.php` 의 devtools 래퍼 한 곳(`debug.gate` 그룹 미들웨어)으로
올린다. 새 라우트는 자동으로 덮이고, 부착 지점이 하나라 훼손이 곧바로 드러난다.
`withRouting(channels:)` 인자가 함께 등록하던 게이트 없는 `/broadcasting/auth` 는
제거하고, 채널 정의 로드만 `BroadcastServiceProvider` 로 옮겨 웹소켓 킬스위치
우회로를 없앤다. catch-all 제외 패턴에는 예약 프리픽스를 전수 추가했다.

## 확장 자산 CSS 상대 참조 (범위 추가 — 결정)

`asset_url_mode=extensionless` 에서 자산 URL 이 쿼리 형태가 되면 브라우저의 기준
디렉토리가 `/api/{타입}/assets/` 로 잡혀, CSS 안의 `url('./woff2/f.woff2')` 가
존재하지 않는 주소가 된다. 사용자 템플릿 웹폰트 1건과 관리자 템플릿 국기 아이콘
약 500건이 이 상태였다. 병합 CSS 번들은 더 나빴다 — 상대 참조를 가진 확장을 번들에서
통째로 제외하고 있었는데, 번들 URL 이 내려오면 프론트는 개별 로딩을 아예 타지 않으므로
제외는 곧 그 확장 스타일이 하나도 적용되지 않음을 뜻했다.

둘 다 서빙 시점에 절대 자산 URL 로 치환한다. 최종 URL 은 런타임 모드와 캐시 버전이
정하므로 빌드 시점에는 알 수 없고, 동봉 자산은 제3자 산출물이라 원본을 손대면 상류
갱신마다 재작업이 된다. 개별 서빙 3경로와 병합 번들이 같은 해석 규칙을 공유한다 —
갈라지면 한쪽만 고쳐진 채 남는다.

이 결함군은 공통적으로 예외도 서버 로그 흔적도 남기지 않는다. 열린 엔드포인트가
정상 응답하는 것, 404 로 글꼴이 기본 서체가 되는 것이 유일한 증상이다.

## 회귀 잠금

되돌림 red 를 모집단 전원에 대해 실측했다 — 그룹 미들웨어 제거, 개별 게이트 재주입,
`channels:` 복원, catch-all 예외 제거, 컨트롤러 3원의 `fileResponse` 회귀, 번들
치환 제거가 각각 어느 테스트를 red 로 만드는지 확인하고 원상 복구했다.

게이트 부착 축은 행위 테스트로 대체할 수 없다 — 가려진 라우트는 행위상 "막힌 것" 과
구분되지 않으므로, `gatherMiddleware` 를 직접 보는 등록 계약 테스트를 둔다. 치환
배선도 같은 이유로 라우트 이름 규약에서 모집단을 도출하는 계약 검사를 둔다(손으로 적은
목록은 네 번째 경로가 생기는 순간 조용히 낡는다).
This commit is contained in:
HeuJung
2026-09-03 07:42:28 +09:00
parent db8640df86
commit 5d14d01d50
31 changed files with 2037 additions and 122 deletions
@@ -251,6 +251,83 @@ class DevtoolsRouteCacheTest extends TestCase
}
}
/**
* 그룹 게이트는 라우트 캐시 상태에서도 살아 있어야 한다 (이슈 #128).
*
* 게이트를 핸들러 안에서 그룹 미들웨어로 올렸으므로, 이제 게이트 적용은 **미들웨어가
* 라우트와 함께 캐시에 구워지는가**에 달려 있다. 구워지지 않으면 캐시된 사이트에서만
* `DELETE clear` 가 다시 열리는데 — 라우트 캐시는 확장 설치·활성화 등 수명주기 지점에서
* 자동 생성되므로 그쪽이 오히려 흔한 상태다 — 예외도 로그도 없이 파괴적 엔드포인트가
* 미인증 200 을 돌려준다.
*
* `storage/debug-dump` 를 실제로 지우지 않는 것까지 확인한다: 자식 프로세스는 실
* storage 를 쓰므로, 게이트가 없으면 이 테스트 한 번으로 개발자 덤프가 사라진다.
*/
public function test_debug_gate_blocks_destructive_clear_under_route_cache(): void
{
$dumpDir = base_path('storage/debug-dump');
$before = is_dir($dumpDir) ? count(glob($dumpDir.'/*') ?: []) : 0;
$result = $this->dispatch('DELETE', '/_boost/g7-debug/clear', '', debug: false);
$this->assertTrue(
$result['routesAreCached'],
'라우트 캐시가 걸리지 않은 채 통과하면 이 테스트는 아무것도 검증하지 못합니다 (가짜 green).'
);
$this->assertStringContainsString('route-cache-', $result['cachedRoutesPath']);
// 403 이 "debug on 인데도 막혔다" 가 아니라 "debug off 라서 막혔다" 임을 고정한다.
$this->assertFalse(
$result['appDebug'],
'자식 프로세스가 APP_DEBUG=false 로 부팅되지 않았습니다 (하네스 인자 전달 실패).'
);
$this->assertSame(
403,
$result['status'],
"라우트 캐시 상태에서도 DELETE clear 는 403 이어야 합니다.
body: {$result['body']}"
);
$after = is_dir($dumpDir) ? count(glob($dumpDir.'/*') ?: []) : 0;
$this->assertSame(
$before,
$after,
'DELETE clear 가 차단되었는데도 덤프 파일 수가 변했습니다 (게이트가 삭제 뒤에 걸렸습니다).'
);
}
/**
* 디버그 ON 에서는 캐시 상태에서도 GET 조회가 도달해야 한다 (게이트가 상시 차단이 아님).
*
* `_boost/g7-debug/state` 는 `routes/web.php` 의 User catch-all 제외 패턴에 `_boost` 가
* 들어가면서 비로소 도달 가능해진 경로다. 캐시된 라우트에도 그 제외가 구워지는지 본다.
*/
public function test_gated_get_endpoint_is_reachable_under_route_cache_when_debug_enabled(): void
{
$result = $this->dispatch('GET', '/_boost/g7-debug/state');
$this->assertTrue($result['routesAreCached']);
$this->assertTrue($result['appDebug']);
$this->assertSame(
200,
$result['status'],
"라우트 캐시 상태에서 GET state 가 200 이어야 합니다.
body: {$result['body']}"
);
// 하네스는 본문을 4000자로 자른다 (`state` 덤프는 그보다 훨씬 크다) — 전체 JSON 파싱은
// 원리상 실패하므로 앞머리로 판정한다. 여기서 가려야 하는 것은 "DevTools JSON 인가
// SPA 셸 HTML 인가" 뿐이다.
$this->assertMatchesRegularExpression(
'/^\{"status":"(success|no_data)"/',
$result['body'],
'SPA 셸 HTML 이 아니라 DevTools JSON 이어야 합니다 (catch-all shadow 회귀).'
);
$this->assertStringNotContainsString('<!DOCTYPE', $result['body']);
}
/**
* 임시 경로에 라우트 캐시를 굽는다 (클래스당 1회).
*
@@ -285,9 +362,10 @@ class DevtoolsRouteCacheTest extends TestCase
* @param string $method HTTP 메서드
* @param string $uri 요청 URI
* @param string $body JSON 본문
* @param bool $debug 자식 프로세스의 APP_DEBUG (false 면 DevTools 그룹 게이트가 차단해야 한다)
* @return array<string, mixed> 하네스 dispatch 결과
*/
private function dispatch(string $method, string $uri, string $body = ''): array
private function dispatch(string $method, string $uri, string $body = '', bool $debug = true): array
{
$this->bakeOnce();
@@ -299,6 +377,7 @@ class DevtoolsRouteCacheTest extends TestCase
$method,
$uri,
$body === '' ? '' : base64_encode($body),
$debug ? 'on' : 'off',
]);
return $this->parseHarnessOutput($output);