HeuJung
15cd4452bf
nginx 의 정규식 location 은 프리픽스 location 보다 먼저 매칭되므로, `location ~* \.(js|css|json)$` 블록이 있는 서버에서는 확장자 붙은 동적 엔드포인트가 `try_files ... /index.php` 폴백이 실행될 기회 없이 404 가 된다. aaPanel/CyberPanel/Plesk 기본 템플릿에 들어있어 드물지 않으며, 관리자 화면조차 뜨지 않아 "서버 설정을 고치세요" 안내가 순환 참조가 된다. 관례를 깬 쪽이 G7 이므로 해소 책임도 G7 에 두고, 두 형태를 모두 서빙한 뒤 환경에 따라 택일한다. 확장자 형태는 영구 유지한다 — 제거하면 URL 을 하드코딩한 서드파티 확장이 깨진다. - 라우트: dualSuffix / dualSuffixSegment / dualAsset 매크로로 23개 엔드포인트와 프로브를 이중 등록. 확장자 형태를 먼저 등록한다 — 확장자 없는 쪽이 더 느슨한 패턴이라 순서가 뒤집히면 `.json` 요청까지 삼킨다 - URL 생성: 서버 App\Support\AssetUrl, 프론트 core/support/assetUrl.ts 로 집약. 기본 모드에서 생성 결과는 치환 이전과 문자열까지 동일하다 (쿼리 순서 포함 — 순서가 바뀌면 의미는 같아도 HTTP 캐시 키가 갈린다) - 자가 복구: 부트스트랩 자산 로드 실패 시 확장자 없는 형태로 1회 단방향 전환. 역방향 금지 + 기존 재시도 예산 공유로 무한 왕복을 막는다 - 감지·전환: 인스톨러 프로브(설치 시 확정) / 관리자 환경설정 일반 탭 / g7:asset-url-mode. 판정은 상태코드가 아니라 매직 토큰 + Content-Type 으로 한다. 상태코드만 보면 "404 대신 200 + 에러 HTML" 환경에서 영원히 오판한다 - 봇은 JavaScript 를 실행하지 않아 자가 복구가 닿지 않으므로, 모드 변경 시 SEO 프리렌더 캐시를 비워 재생성시킨다 가드: audit 룰 2종(dynamic-route-static-extension / asset-url-builder-required), Playwright 6건(정적 블록 가로채기 시뮬레이션), 루프 방지 불변식 L1~L9 전수 red 증명. 부수 정리: 양 Composer 에 중복돼 있던 확장 에셋 수집 123줄을 트레이트로 통합하고, 자산 확장자 화이트리스트 누락(.map)과 경로 정규화 우회 가능성을 함께 교정. sir.kr 커뮤니티의 hang 님께서 제보해주셨습니다.
505 lines
19 KiB
PHP
505 lines
19 KiB
PHP
<?php
|
|
|
|
namespace App\Services;
|
|
|
|
use App\Extension\ModuleManager;
|
|
use App\Extension\PluginManager;
|
|
use App\Extension\Storage\CoreStorageDriver;
|
|
use App\Extension\Traits\ClearsTemplateCaches;
|
|
use App\Http\View\Composers\TemplateComposer;
|
|
use App\Support\AssetUrl;
|
|
use Illuminate\Support\Facades\Log;
|
|
|
|
/**
|
|
* 확장(모듈/플러그인) 프론트엔드 IIFE/CSS 번들 병합 서비스
|
|
*
|
|
* 활성 모듈/플러그인의 개별 IIFE JS·CSS 에셋을 타입별로 하나의 번들 파일로
|
|
* 이어붙여(concat) 서빙 오버헤드(HTTP 요청 수)를 줄인다. 각 확장 IIFE 는
|
|
* 자체 클로저에서 자가등록(`window.G7ModuleRegistry`/`G7PluginRegistry` +
|
|
* 핸들러/리스너)을 수행하므로, N개 IIFE 를 priority 순으로 이어붙여 1개
|
|
* `<script>` 로 실행해도 등록 로직은 동일하게 동작한다.
|
|
*
|
|
* 정렬/필터(`hasAssets()` && strategy==='global' + `uasort(priority)`) 는
|
|
* TemplateComposer 와 공유하는 SSoT 로 이 서비스에 둔다(drift 방지).
|
|
*
|
|
* 경로는 절대경로 게터(`getBuiltAssetAbsolutePaths()`)를 재사용한다 —
|
|
* `ModuleService::getAssetFilePath()` 의 `base_path("modules/{id}/...")`
|
|
* 하드코딩을 복제하지 않아야 `_bundled` 확장에서도 정확히 읽는다(제약 4).
|
|
*
|
|
* @see TemplateComposer
|
|
*/
|
|
class ExtensionBundleService
|
|
{
|
|
// ext.cache_version 게터 재사용 — 트레이트를 use 해 self:: 로 호출(트레이트명
|
|
// 직접 정적 호출은 PHP 8.3+ deprecated). 인스턴스 캐시 무효화 메서드는 미사용.
|
|
use ClearsTemplateCaches;
|
|
|
|
/**
|
|
* 번들 캐시 파일이 저장되는 스토리지 디스크(= storage/app/ext-bundles).
|
|
*/
|
|
private const BUNDLE_DISK = 'ext-bundles';
|
|
|
|
/**
|
|
* 서비스 주입
|
|
*
|
|
* @param ModuleManager $moduleManager 모듈 매니저
|
|
* @param PluginManager $pluginManager 플러그인 매니저
|
|
*/
|
|
public function __construct(
|
|
private readonly ModuleManager $moduleManager,
|
|
private readonly PluginManager $pluginManager
|
|
) {}
|
|
|
|
/**
|
|
* 확장 타입별 global 전략 에셋을 priority 오름차순으로 정렬해 반환합니다.
|
|
*
|
|
* TemplateComposer 의 개별 에셋 URL 생성과 번들러의 concat 이 동일한
|
|
* 필터/정렬을 쓰도록 하는 SSoT. 순서 제어는 오직 manifest
|
|
* `loading.priority` 숫자 오름차순뿐이며 특정 확장 이름 하드코딩은 없다(제약 1).
|
|
*
|
|
* @param string $type 'module' | 'plugin'
|
|
* @return array<string, array{jsAbsPath: ?string, cssAbsPath: ?string, priority: int}>
|
|
* identifier => 절대경로/우선순위 (priority 오름차순 정렬)
|
|
*/
|
|
public function getOrderedGlobalAssetPaths(string $type): array
|
|
{
|
|
$extensions = $type === 'plugin'
|
|
? $this->pluginManager->getActivePlugins()
|
|
: $this->moduleManager->getActiveModules();
|
|
|
|
$ordered = [];
|
|
|
|
foreach ($extensions as $extension) {
|
|
if (! $extension->hasAssets()) {
|
|
continue;
|
|
}
|
|
|
|
$loadingConfig = $extension->getAssetLoadingConfig();
|
|
|
|
// global 전략만 번들 대상 (layout, lazy 는 레이아웃에서 개별 처리)
|
|
if (($loadingConfig['strategy'] ?? 'global') !== 'global') {
|
|
continue;
|
|
}
|
|
|
|
$absolutePaths = $extension->getBuiltAssetAbsolutePaths();
|
|
|
|
$jsAbsPath = $absolutePaths['js'] ?? null;
|
|
$cssAbsPath = $absolutePaths['css'] ?? null;
|
|
|
|
// JS/CSS 둘 다 없으면 번들에 기여할 것이 없으므로 제외
|
|
if ($jsAbsPath === null && $cssAbsPath === null) {
|
|
continue;
|
|
}
|
|
|
|
$ordered[$extension->getIdentifier()] = [
|
|
'jsAbsPath' => $jsAbsPath,
|
|
'cssAbsPath' => $cssAbsPath,
|
|
'priority' => (int) ($loadingConfig['priority'] ?? 100),
|
|
];
|
|
}
|
|
|
|
// priority 오름차순 (낮을수록 먼저) — 개별 로딩과 동일 규칙
|
|
uasort($ordered, fn ($a, $b) => $a['priority'] <=> $b['priority']);
|
|
|
|
return $ordered;
|
|
}
|
|
|
|
/**
|
|
* 확장 타입의 JS 번들 문자열을 생성합니다.
|
|
*
|
|
* priority 순으로 각 IIFE 파일을 읽어 `\n;\n` 구분자로 이어붙인다(제약 2 —
|
|
* ASI 경계 보호). 각 파일 끝의 `//# sourceMappingURL` 주석은 prod 에서는
|
|
* strip(맵 생략), dev 에서는 개별 에셋 서빙 절대 URL 로 rewrite 한다(제약 3).
|
|
*
|
|
* 확장별 fine-grained try/catch — 파일 읽기 실패 시 해당 확장만 skip +
|
|
* Log::warning, 나머지 병합 지속(한 확장 실패가 번들 전체를 붕괴시키지 않음).
|
|
*
|
|
* @param string $type 'module' | 'plugin'
|
|
* @return string 병합된 JS (활성 global 에셋이 없으면 빈 문자열)
|
|
*/
|
|
public function buildJsBundle(string $type): string
|
|
{
|
|
$ordered = $this->getOrderedGlobalAssetPaths($type);
|
|
$isProduction = app()->environment('production');
|
|
$segments = [];
|
|
|
|
foreach ($ordered as $identifier => $paths) {
|
|
if (empty($paths['jsAbsPath'])) {
|
|
continue;
|
|
}
|
|
|
|
try {
|
|
$content = @file_get_contents($paths['jsAbsPath']);
|
|
|
|
if ($content === false) {
|
|
Log::warning('확장 JS 번들 병합: 파일 읽기 실패, 해당 확장 skip', [
|
|
'type' => $type,
|
|
'identifier' => $identifier,
|
|
'path' => $paths['jsAbsPath'],
|
|
]);
|
|
|
|
continue;
|
|
}
|
|
|
|
$segments[] = $this->processJsSourceMap($content, $type, $identifier, $isProduction);
|
|
} catch (\Throwable $e) {
|
|
Log::warning('확장 JS 번들 병합 중 오류, 해당 확장 skip', [
|
|
'type' => $type,
|
|
'identifier' => $identifier,
|
|
'error' => $e->getMessage(),
|
|
]);
|
|
}
|
|
}
|
|
|
|
return implode("\n;\n", $segments);
|
|
}
|
|
|
|
/**
|
|
* 확장 타입의 CSS 번들 문자열을 생성합니다.
|
|
*
|
|
* priority 순으로 각 CSS 파일을 읽어 `\n` 구분자로 이어붙인다. 상대경로
|
|
* `url(...)` 참조가 있는 CSS 는 병합 시 경로가 깨지므로 번들에서 제외하고
|
|
* 경고 로그를 남긴다(안전장치 — 현재 번들 CSS 는 url() 0건).
|
|
*
|
|
* @param string $type 'module' | 'plugin'
|
|
* @return string 병합된 CSS (활성 global 에셋이 없으면 빈 문자열)
|
|
*/
|
|
public function buildCssBundle(string $type): string
|
|
{
|
|
$ordered = $this->getOrderedGlobalAssetPaths($type);
|
|
$isProduction = app()->environment('production');
|
|
$segments = [];
|
|
|
|
foreach ($ordered as $identifier => $paths) {
|
|
if (empty($paths['cssAbsPath'])) {
|
|
continue;
|
|
}
|
|
|
|
try {
|
|
$content = @file_get_contents($paths['cssAbsPath']);
|
|
|
|
if ($content === false) {
|
|
Log::warning('확장 CSS 번들 병합: 파일 읽기 실패, 해당 확장 skip', [
|
|
'type' => $type,
|
|
'identifier' => $identifier,
|
|
'path' => $paths['cssAbsPath'],
|
|
]);
|
|
|
|
continue;
|
|
}
|
|
|
|
// 상대경로 url() 참조가 있으면 병합 시 폰트/이미지 경로가 깨진다.
|
|
// 절대/data URI 는 안전하므로 상대경로만 검출해 해당 CSS 제외.
|
|
if ($this->hasRelativeUrl($content)) {
|
|
Log::warning('확장 CSS 에 상대경로 url() 존재 — 번들에서 제외(개별 폴백 유지)', [
|
|
'type' => $type,
|
|
'identifier' => $identifier,
|
|
]);
|
|
|
|
continue;
|
|
}
|
|
|
|
$segments[] = $this->processCssSourceMap($content, $isProduction);
|
|
} catch (\Throwable $e) {
|
|
Log::warning('확장 CSS 번들 병합 중 오류, 해당 확장 skip', [
|
|
'type' => $type,
|
|
'identifier' => $identifier,
|
|
'error' => $e->getMessage(),
|
|
]);
|
|
}
|
|
}
|
|
|
|
return implode("\n", $segments);
|
|
}
|
|
|
|
/**
|
|
* 캐시된 번들 파일의 절대 경로를 반환합니다(없으면 build → 원자적 write).
|
|
*
|
|
* 파일명에 version 을 포함(`{type}.{version}.{js|css}`)하므로 활성 조합이
|
|
* 바뀌어 version 이 bump 되면 새 파일명으로 자연 무효화된다. 프로덕션에서만
|
|
* 디스크 캐시하며, 비프로덕션(dev/watch)에서는 캐시하지 않고 매 요청 build 해
|
|
* rebuild 를 즉시 반영한다.
|
|
*
|
|
* @param string $type 'module' | 'plugin'
|
|
* @param string $kind 'js' | 'css'
|
|
* @param int $version 확장 캐시 버전(ClearsTemplateCaches::getExtensionCacheVersion)
|
|
* @return string 캐시(또는 방금 build 한) 파일의 절대 경로. 병합 결과가 빈 문자열이면 빈 문자열.
|
|
*/
|
|
public function getBundleFilePath(string $type, string $kind, int $version): string
|
|
{
|
|
$content = $kind === 'css'
|
|
? $this->buildCssBundle($type)
|
|
: $this->buildJsBundle($type);
|
|
|
|
// 병합할 에셋이 하나도 없으면 파일을 만들지 않는다(호출측이 빈 문자열로 판단).
|
|
if ($content === '') {
|
|
return '';
|
|
}
|
|
|
|
$storage = $this->bundleStorage();
|
|
$relativeName = $this->bundleFileName($type, $kind, $version);
|
|
|
|
// 비프로덕션은 캐시하지 않고 임시 파일로 매번 build → rebuild 즉시 반영
|
|
if (! app()->environment('production')) {
|
|
return $this->writeAtomically($storage, $relativeName, $content, cache: false);
|
|
}
|
|
|
|
// 프로덕션: 동일 version 캐시가 있으면 그대로 사용
|
|
if ($storage->exists('', $relativeName)) {
|
|
return $storage->getBasePath('').'/'.$relativeName;
|
|
}
|
|
|
|
return $this->writeAtomically($storage, $relativeName, $content, cache: true);
|
|
}
|
|
|
|
/**
|
|
* 현재 version 외의 오래된 번들 파일을 삭제하고 삭제 건수를 반환합니다.
|
|
*
|
|
* @param int $currentVersion 보존할 현재 캐시 버전
|
|
* @return int 삭제된 파일 수
|
|
*/
|
|
public function cleanupStaleBundles(int $currentVersion): int
|
|
{
|
|
$storage = $this->bundleStorage();
|
|
$deleted = 0;
|
|
|
|
foreach ($storage->files('', '') as $file) {
|
|
$name = basename($file);
|
|
|
|
// 현재 version 파일과 .gitignore 는 보존
|
|
if ($name === '.gitignore' || $this->matchesVersion($name, $currentVersion)) {
|
|
continue;
|
|
}
|
|
|
|
if ($this->isBundleFile($name) && $storage->delete('', $name)) {
|
|
$deleted++;
|
|
}
|
|
}
|
|
|
|
return $deleted;
|
|
}
|
|
|
|
/**
|
|
* 번들 캐시 파일을 삭제합니다(cache-clear 커맨드용).
|
|
*
|
|
* @param string|null $type 'module' | 'plugin' 지정 시 해당 타입만, null 이면 전체
|
|
* @return int 삭제된 파일 수
|
|
*/
|
|
public function clearBundles(?string $type = null): int
|
|
{
|
|
$storage = $this->bundleStorage();
|
|
$deleted = 0;
|
|
|
|
foreach ($storage->files('', '') as $file) {
|
|
$name = basename($file);
|
|
|
|
if ($name === '.gitignore' || ! $this->isBundleFile($name)) {
|
|
continue;
|
|
}
|
|
|
|
// 타입 필터 (파일명 접두사 `{type}.`)
|
|
if ($type !== null && ! str_starts_with($name, $type.'.')) {
|
|
continue;
|
|
}
|
|
|
|
if ($storage->delete('', $name)) {
|
|
$deleted++;
|
|
}
|
|
}
|
|
|
|
return $deleted;
|
|
}
|
|
|
|
/**
|
|
* 번들 파일명을 생성합니다(`{type}.{version}.{kind}`).
|
|
*
|
|
* @param string $type 'module' | 'plugin'
|
|
* @param string $kind 'js' | 'css'
|
|
* @param int $version 캐시 버전
|
|
* @return string 파일명 (디렉토리 제외)
|
|
*/
|
|
private function bundleFileName(string $type, string $kind, int $version): string
|
|
{
|
|
return "{$type}.{$version}.{$kind}";
|
|
}
|
|
|
|
/**
|
|
* 파일명이 번들 파일 패턴(`{type}.{version}.{kind}`)인지 확인합니다.
|
|
*
|
|
* @param string $name 파일명
|
|
* @return bool 번들 파일이면 true
|
|
*/
|
|
private function isBundleFile(string $name): bool
|
|
{
|
|
return (bool) preg_match('/^(module|plugin)\.\d+\.(js|css)$/', $name);
|
|
}
|
|
|
|
/**
|
|
* 파일명이 지정한 version 의 번들인지 확인합니다.
|
|
*
|
|
* @param string $name 파일명
|
|
* @param int $version 비교할 버전
|
|
* @return bool 해당 version 파일이면 true
|
|
*/
|
|
private function matchesVersion(string $name, int $version): bool
|
|
{
|
|
return (bool) preg_match('/^(module|plugin)\.'.preg_quote((string) $version, '/').'\.(js|css)$/', $name);
|
|
}
|
|
|
|
/**
|
|
* 병합 결과를 원자적으로(임시 파일 → rename) 기록하고 절대 경로를 반환합니다.
|
|
*
|
|
* @param CoreStorageDriver $storage 번들 디스크 스토리지
|
|
* @param string $relativeName 대상 파일명
|
|
* @param string $content 기록할 내용
|
|
* @param bool $cache true 면 version 파일명 유지, false 면 임시 파일 사용
|
|
* @return string 기록된 파일의 절대 경로
|
|
*/
|
|
private function writeAtomically(CoreStorageDriver $storage, string $relativeName, string $content, bool $cache): string
|
|
{
|
|
$basePath = $storage->getBasePath('');
|
|
|
|
if (! is_dir($basePath)) {
|
|
@mkdir($basePath, 0o755, true);
|
|
}
|
|
|
|
$finalPath = $basePath.'/'.$relativeName;
|
|
|
|
if (! $cache) {
|
|
// 비프로덕션: 매 요청 덮어써도 무방(원자성 불요), 그대로 write
|
|
$storage->put('', $relativeName, $content);
|
|
|
|
return $finalPath;
|
|
}
|
|
|
|
// 프로덕션: 임시 파일에 쓴 뒤 rename 으로 원자적 게시(부분 파일 서빙 방지)
|
|
$tmpName = $relativeName.'.tmp.'.getmypid();
|
|
$storage->put('', $tmpName, $content);
|
|
|
|
$tmpPath = $basePath.'/'.$tmpName;
|
|
|
|
if (! @rename($tmpPath, $finalPath)) {
|
|
// rename 실패 시(경합으로 이미 존재 등) 임시 파일 정리 후 최종 경로 사용
|
|
$storage->delete('', $tmpName);
|
|
}
|
|
|
|
return $finalPath;
|
|
}
|
|
|
|
/**
|
|
* IIFE 소스맵 주석을 환경에 맞게 처리합니다.
|
|
*
|
|
* prod: `//# sourceMappingURL` 라인 strip(맵 생략).
|
|
* dev: 개별 에셋 서빙 절대 URL(`/api/{type}s/assets/{id}/dist/js/*.map`)로
|
|
* rewrite → 브라우저가 확장별 원본 맵을 추적(완벽한 통합 맵은 아님).
|
|
*
|
|
* @param string $content 원본 IIFE 내용
|
|
* @param string $type 'module' | 'plugin'
|
|
* @param string $identifier 확장 식별자
|
|
* @param bool $isProduction 프로덕션 여부
|
|
* @return string 처리된 내용
|
|
*/
|
|
private function processJsSourceMap(string $content, string $type, string $identifier, bool $isProduction): string
|
|
{
|
|
// 구분자로 `~` 사용 — 패턴 자체에 `#`(`//#`)가 포함되어 `#` 구분자는 못 씀
|
|
$pattern = '~//# sourceMappingURL=(\S+)~';
|
|
|
|
if ($isProduction) {
|
|
// prod: 맵 참조 제거
|
|
return preg_replace($pattern, '', $content) ?? $content;
|
|
}
|
|
|
|
// dev: 상대 맵 파일명을 개별 에셋 서빙 절대 URL 로 rewrite
|
|
$typeSegment = $type === 'plugin' ? 'plugins' : 'modules';
|
|
|
|
return preg_replace_callback($pattern, function (array $m) use ($typeSegment, $identifier) {
|
|
$mapFile = ltrim($m[1], './');
|
|
|
|
return '//# sourceMappingURL='.AssetUrl::extensionAsset(
|
|
$typeSegment,
|
|
$identifier,
|
|
'dist/js/'.basename($mapFile)
|
|
);
|
|
}, $content) ?? $content;
|
|
}
|
|
|
|
/**
|
|
* CSS 소스맵 주석을 환경에 맞게 처리합니다.
|
|
*
|
|
* CSS 는 JS 와 주석 문법이 달라 소스맵 참조를 블록 주석으로 표기하므로
|
|
* processJsSourceMap() 의 `//#` 패턴으로는 검출되지 않는다.
|
|
*
|
|
* prod: 주석 strip(맵 참조 제거). dev: 원본 유지.
|
|
* 병합 번들에서는 개별 맵 URL 이 어차피 어긋나므로 dev rewrite 는 하지 않는다.
|
|
*
|
|
* @param string $content 원본 CSS 내용
|
|
* @param bool $isProduction 프로덕션 여부
|
|
* @return string 처리된 내용
|
|
*/
|
|
private function processCssSourceMap(string $content, bool $isProduction): string
|
|
{
|
|
if (! $isProduction) {
|
|
return $content;
|
|
}
|
|
|
|
// 구분자로 `~` 사용 — 패턴에 `/`, `#` 가 포함됨
|
|
return preg_replace('~/\*#\s*sourceMappingURL=\S+?\s*\*/~', '', $content) ?? $content;
|
|
}
|
|
|
|
/**
|
|
* CSS 내용에 상대경로 url() 참조가 있는지 확인합니다.
|
|
*
|
|
* 절대 URL(http/https), 루트 절대경로(/), data URI 는 병합에 안전하므로
|
|
* 그 외의 url() 참조만 상대경로로 간주한다.
|
|
*
|
|
* @param string $css CSS 내용
|
|
* @return bool 상대경로 url() 이 하나라도 있으면 true
|
|
*/
|
|
private function hasRelativeUrl(string $css): bool
|
|
{
|
|
if (! preg_match_all('/url\(\s*[\'"]?([^\'")]+)[\'"]?\s*\)/i', $css, $matches)) {
|
|
return false;
|
|
}
|
|
|
|
foreach ($matches[1] as $url) {
|
|
$url = trim($url);
|
|
|
|
if ($url === '') {
|
|
continue;
|
|
}
|
|
|
|
$isAbsolute = str_starts_with($url, 'http://')
|
|
|| str_starts_with($url, 'https://')
|
|
|| str_starts_with($url, '//')
|
|
|| str_starts_with($url, '/')
|
|
|| str_starts_with($url, 'data:');
|
|
|
|
if (! $isAbsolute) {
|
|
return true;
|
|
}
|
|
}
|
|
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* 번들 디스크용 스토리지 드라이버를 반환합니다(StorageInterface 경유).
|
|
*
|
|
* @return CoreStorageDriver ext-bundles 디스크 스토리지
|
|
*/
|
|
private function bundleStorage(): CoreStorageDriver
|
|
{
|
|
return (new CoreStorageDriver)->withDisk(self::BUNDLE_DISK);
|
|
}
|
|
|
|
/**
|
|
* 현재 확장 캐시 버전을 반환합니다.
|
|
*
|
|
* @return int 캐시 버전
|
|
*/
|
|
public function getCurrentVersion(): int
|
|
{
|
|
return self::getExtensionCacheVersion();
|
|
}
|
|
}
|