` 로 실행해도 등록 로직은 동일하게 동작한다. * * 정렬/필터(`hasAssets()` && strategy==='global' + `uasort(priority)`) 는 * TemplateComposer 와 공유하는 SSoT 로 이 서비스에 둔다(drift 방지). * * 경로는 절대경로 게터(`getBuiltAssetAbsolutePaths()`)를 재사용한다 — * `ModuleService::getAssetFilePath()` 의 `base_path("modules/{id}/...")` * 하드코딩을 복제하지 않아야 `_bundled` 확장에서도 정확히 읽는다(제약 4). * 소실 판정만 선언 축 게터(`getDeclaredAssetAbsolutePaths()`)를 쓴다 — 그 게터는 * `file_exists()` 게이트를 타지 않아 "선언은 있는데 파일이 없다" 를 셀 수 있다. * * @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'; /** * 원자적 쓰기 임시 파일(`*.tmp.{pid}`)을 잔존물로 보는 나이 (초). * * pid 는 재사용되므로 "그 pid 가 살아 있는가" 로는 진행 중 여부를 판정할 수 없다. */ private const TEMP_BUNDLE_STALE_SECONDS = 600; /** * 캐시 미스 빌드를 (type, kind, version) 단위로 수렴시키는 잠금 키 접두사. */ private const BUILD_LOCK_PREFIX = 'ext-bundles.build.'; /** * 빌드 잠금의 보유 상한 (초). 좀비 잠금 방지용이며 실제 빌드는 밀리초 단위다. */ private const BUILD_LOCK_TTL_SECONDS = 30; /** * 다른 프로세스의 빌드를 기다리는 상한 (초). 초과하면 잠금 없이 각자 빌드한다. */ private const BUILD_LOCK_WAIT_SECONDS = 5; /** * 서비스 주입 * * @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). * * `cssRelPath` 는 확장 루트 기준 상대 경로다 — 병합 시 CSS 안의 상대 참조를 그 CSS 가 * 놓인 위치 기준으로 풀어야 하는데, 절대 경로만으로는 확장 루트를 되짚을 수 없다. * * @param string $type 'module' | 'plugin' * @return array * 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; } // CSS 안의 상대 참조를 풀려면 그 CSS 가 확장 안에서 **어디에 놓였는지**가 필요하다. // 절대 경로만으로는 확장 루트를 되짚을 수 없으므로 선언된 상대 경로를 함께 싣는다. $cssRelPath = $extension->getBuiltAssetPaths()['css'] ?? null; $ordered[$extension->getIdentifier()] = [ 'jsAbsPath' => $jsAbsPath, 'cssAbsPath' => $cssAbsPath, 'cssRelPath' => $cssRelPath, '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` 구분자로 이어붙인다. CSS 안의 상대 * `url(...)`·`@import` 참조는 그 확장의 절대 자산 URL 로 치환한다 — 병합본의 주소는 * 어느 확장의 dist 디렉토리도 아니라 상대 해석이 반드시 어긋나기 때문이다. * * 치환은 개별 자산 서빙(ServesRewritableCssAssets)과 같은 규칙(AssetCssUrlRewriter)을 * 쓴다. 두 경로가 서로 다른 코드로 갈라지면 한쪽만 고쳐진 채 남는다. * * @param string $type 'module' | 'plugin' * @return string 병합된 CSS (활성 global 에셋이 없으면 빈 문자열) */ public function buildCssBundle(string $type): string { $ordered = $this->getOrderedGlobalAssetPaths($type); $isProduction = app()->environment('production'); $typeSegment = $type === 'plugin' ? 'plugins' : 'modules'; $version = $this->getCurrentVersion(); $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; } // 상대 참조는 **치환**한다. 병합본의 주소(`/api/{type}/bundle.css` 또는 정적 // 게시본)는 어느 확장의 dist 디렉토리도 아니므로 상대 해석이 반드시 어긋나는데, // 그 실패는 404 하나로만 나타나 서버 로그에 흔적이 없다. // // 종전에는 그런 CSS 를 가진 확장을 번들에서 통째로 제외했다. 그러나 번들 URL 이 // 내려오면 프론트는 개별 로딩을 아예 타지 않으므로(TemplateApp.loadExtensionAssets) // 제외 = 그 확장의 스타일이 **하나도 적용되지 않음** 이었다. 주석이 말하던 // "개별 폴백" 은 bundleUrls 부재(구버전 blade) 경로에만 있다. $content = AssetCssUrlRewriter::rewrite( $content, (string) ($paths['cssRelPath'] ?? ''), fn (string $path): string => AssetUrl::extensionApiAsset( $typeSegment, $identifier, $path, $version ) ); $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 를 즉시 반영한다. * * 프로덕션에서 **캐시 존재 확인이 빌드보다 먼저** 온다. 캐시 키는 인자만으로 * 계산되므로 빌드가 필요 없는데, 빌드를 앞세우면 캐시가 있어도 요청마다 활성 확장을 * 열거하고 산출물을 전부 읽는다. 응답은 정상 200 이라 그 반복은 타이밍 말고는 드러나지 * 않고, 원본이 사라지는 순간에는 멀쩡한 캐시를 두고 빈 경로가 반환되어 503 이 된다. * * @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 { $relativeName = $this->bundleFileName($type, $kind, $version); // 디스크 캐시는 **최적화**다 — 쓰기 실패가 공개 엔드포인트의 500 이 되면 안 된다. // `ext-bundles` 디스크는 `throw => true` 라 권한 문제(uid 독점 0700 등)에서 // `UnableToWriteFile` 이 그대로 올라오고, 그러면 모든 확장의 프론트엔드 JS/CSS 가 // 통째로 나가지 못한다. 병합 결과는 이미 메모리에 있으므로 그것을 그대로 응답하면 // 화면은 정상이다 (커밋 63a30ab29 의 AbstractCacheDriver fail-soft 와 같은 원칙). try { $storage = $this->bundleStorage(); // 비프로덕션은 캐시하지 않고 임시 파일로 매번 build → rebuild 즉시 반영 if (! app()->environment('production')) { $content = $this->buildBundleContent($type, $kind); // 병합할 에셋이 하나도 없으면 파일을 만들지 않는다(호출측이 빈 문자열로 판단). if ($content === '') { return ''; } return $this->writeAtomically($storage, $relativeName, $content, cache: false); } // 프로덕션: 동일 version 캐시가 있으면 빌드 없이 그대로 사용 if ($storage->exists('', $relativeName)) { return $storage->getBasePath('').'/'.$relativeName; } return $this->buildAndCacheOnce($storage, $type, $kind, $version, $relativeName); } catch (\Throwable $e) { Log::warning('확장 번들 디스크 캐시 실패 — 메모리 병합 결과로 서빙합니다', [ 'type' => $type, 'kind' => $kind, 'version' => $version, 'error' => $e->getMessage(), ]); return ''; } } /** * 캐시 미스에서 한 번만 병합해 캐시 파일을 만들고 그 절대 경로를 반환합니다. * * 같은 (type, kind, version) 의 동시 요청은 잠금으로 하나에 수렴시킨다 — 버전 교체 * 직후에는 캐시가 없는 상태로 요청이 몰리고, 각자 병합하면 그 비용이 워커 수만큼 곱해진다. * 잠금은 **최적화**이므로 대기 초과·저장소 장애는 실패로 바꾸지 않고 각자 빌드로 폴백한다 * (정적 게시 잠금 `ext-static.publish.{v}` 와 같은 저장소·같은 규율이며 키가 달라 자기 * 교착이 없다). * * 병합 결과가 비어 있어도 선언한 산출물이 **전부 존재하면**(또는 선언이 0이면) 0바이트 * 캐시 파일을 만든다. 그래야 정적 게시 대상이 되어 방문자가 웹서버에서 직접 받는다 — * 만들지 않으면 그 구성의 모든 페이지 로드가 PHP 를 거친다. 선언한 산출물이 **소실**된 * 경우에만 캐시하지 않아, 호출측의 503 판정이 그대로 유지된다. * * @param CoreStorageDriver $storage 번들 디스크 스토리지 * @param string $type 'module' | 'plugin' * @param string $kind 'js' | 'css' * @param int $version 확장 캐시 버전 * @param string $relativeName 캐시 파일명 * @return string 캐시 파일의 절대 경로 (캐시하지 않았으면 빈 문자열) */ private function buildAndCacheOnce( CoreStorageDriver $storage, string $type, string $kind, int $version, string $relativeName ): string { $lock = null; $acquired = false; try { $lock = Cache::lock(self::BUILD_LOCK_PREFIX."{$type}.{$kind}.{$version}", self::BUILD_LOCK_TTL_SECONDS); $acquired = (bool) $lock->block(self::BUILD_LOCK_WAIT_SECONDS); } catch (LockTimeoutException $e) { // 대기 초과는 정상적인 경합이다 — 흔적만 남기고 각자 빌드한다. Log::debug('확장 번들 빌드 잠금 대기 초과 — 잠금 없이 병합합니다', [ 'type' => $type, 'kind' => $kind, 'version' => $version, ]); } catch (\Throwable $e) { // 저장소가 잠금을 제공하지 못한다(드라이버 미지원, 캐시 디렉토리 권한 등). // 번들 서빙 자체를 막지는 않으므로 사유만 남기고 계속한다. Log::warning('확장 번들 빌드 잠금 획득 불가 — 잠금 없이 병합합니다', [ 'type' => $type, 'kind' => $kind, 'version' => $version, 'store' => config('cache.default'), 'error' => $e->getMessage(), ]); } try { // 기다리는 동안 다른 프로세스가 완성했을 수 있다 — 병합 전에 다시 본다. if ($storage->exists('', $relativeName)) { return $storage->getBasePath('').'/'.$relativeName; } $content = $this->buildBundleContent($type, $kind); // 비었는데 선언한 산출물이 소실이면 캐시하지 않는다 — 배포 중 dist 가 잠깐 빈 // 장애가 0바이트 캐시로 굳어 정상(빈 200)으로 위장되면 안 된다. if ($content === '' && $this->findMissingDeclaredAssets($type, $kind) !== []) { return ''; } return $this->writeAtomically($storage, $relativeName, $content, cache: true); } finally { if ($acquired && $lock !== null) { try { $lock->release(); } catch (\Throwable $e) { // 해제 실패는 TTL 이 정리한다 — 서빙에는 영향이 없다. } } } } /** * 번들을 서빙할 때 쓸 병합 결과를 반환합니다 (디스크 캐시 실패 시 메모리 폴백용). * * @param string $type 'module' | 'plugin' * @param string $kind 'js' | 'css' * @return string 병합 결과 (없으면 빈 문자열) */ public function buildBundleContent(string $type, string $kind): string { return $kind === 'css' ? $this->buildCssBundle($type) : $this->buildJsBundle($type); } /** * 해당 타입에서 프론트엔드 에셋을 **선언한** 활성 확장 수를 반환합니다. * * 이 값은 **선언 축**이다 — 503 의 판정은 소실 축(`findMissingDeclaredAssets()`)이 * 한다. 선언 축만으로 "선언 > 0 && 병합 결과 0 = 장애" 로 등치하면, 산출물이 존재하되 * 비어 있는 정당한 상태(스타일이 비어 있는 확장)까지 배포 장애로 잡혀 그 확장만 * 설치된 기본 구성이 통째로 503 이 된다. * * 선언 축은 로그 컨텍스트(운영자가 보는 "선언한 확장이 몇 개인가")와 화면 진단이 * 근거로 삼는다. * * 판정은 **kind 별**이다 — js 만 선언한 확장이 있는 상태에서 css 번들이 비는 것은 * 정상이므로, 그 경우까지 장애로 보면 정상 구성이 503 이 된다. * * 근거는 manifest 의 `assets.{kind}.output` **선언**이며 산출물 파일의 존재를 보지 * 않는다. `getOrderedGlobalAssetPaths()` / `hasAssets()` / `getBuiltAssetPaths()` 는 * 전부 `file_exists()` 게이트를 타므로, 그 경로로 세면 "dist 가 잠깐 빔" 이 곧 * "선언 0" 이 되어 **막으려던 바로 그 상태가 정상(빈 200)으로 판정된다.** 선언과 * 산출은 다른 축이고, 이 메서드가 재는 것은 선언 축이다. * * @param string $type 'module' | 'plugin' * @param string $kind 'js' | 'css' * @return int 해당 kind 의 에셋을 선언한 활성 확장 수 */ public function countAssetDeclaringExtensions(string $type, string $kind): int { try { $extensions = $type === 'plugin' ? $this->pluginManager->getActivePlugins() : $this->moduleManager->getActiveModules(); $declared = 0; foreach ($extensions as $extension) { // global 전략만 번들 대상 — 병합 대상 모집단과 동일한 필터를 쓴다 if (($extension->getAssetLoadingConfig()['strategy'] ?? 'global') !== 'global') { continue; } if (! empty($extension->getAssets()[$kind]['output'] ?? null)) { $declared++; } } return $declared; } catch (\Throwable $e) { Log::warning('확장 에셋 선언 수 집계 실패', [ 'type' => $type, 'kind' => $kind, 'error' => $e->getMessage(), ]); return 0; } } /** * 선언된 산출물 중 **소실·판독 불가**한 것의 절대 경로 목록을 반환합니다. * * 503 의 근거는 선언이 아니라 이 소실 축이다. 선언만으로 판정하면 "선언됨 + 산출물이 존재하지만 * 0바이트"(스타일이 비어 있는 확장의 정당한 상태) 와 "선언됨 + 산출물 소실"(배포 중 dist 가 잠깐 빔) * 이 구분되지 않아 정상 구성이 503 이 된다 — 번들 확장만 설치한 기본 구성 전부가 그랬다. * * 모집단은 countAssetDeclaringExtensions() 와 같다. 경로는 확장의 선언 축 게터로만 얻는다 — * getBuiltAssetAbsolutePaths() 는 file_exists() 게이트라 부재를 셀 수 없고, base_path("modules"…) * 직접 조립은 _bundled 확장에서 어긋난다. * * @param string $type 'module' | 'plugin' * @param string $kind 'js' | 'css' * @return list 소실·판독 불가 산출물의 절대 경로 (없으면 빈 배열) */ public function findMissingDeclaredAssets(string $type, string $kind): array { try { $extensions = $type === 'plugin' ? $this->pluginManager->getActivePlugins() : $this->moduleManager->getActiveModules(); $missing = []; foreach ($extensions as $extension) { // global 전략만 번들 대상 — 병합 대상 모집단과 동일한 필터를 쓴다 if (($extension->getAssetLoadingConfig()['strategy'] ?? 'global') !== 'global') { continue; } $path = $extension->getDeclaredAssetAbsolutePaths()[$kind] ?? null; if ($path !== null && (! is_file($path) || ! is_readable($path))) { $missing[] = $path; } } return $missing; } catch (\Throwable $e) { // 판정 자체가 실패하면 장애로 단정하지 않는다(선언 축 카운트와 같은 fail-open). 흔적은 error 로 — // 출하 기본 로그 수준이 error 라 warning 은 기록되지 않는다. Log::error('확장 에셋 소실 판정 실패', [ 'type' => $type, 'kind' => $kind, 'error' => $e->getMessage(), ]); return []; } } /** * 현재 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; } // 원자적 쓰기의 임시 파일(`{type}.{v}.{kind}.tmp.{pid}`)은 번들 파일 패턴에 // 맞지 않아 GC 대상에서 통째로 빠져 있었다 — rename 이 실패한 만큼 영구 // 잔존한다(실측 560개). 나이 가드를 붙여 진행 중인 쓰기는 건드리지 않는다. if ($this->isStaleTempBundleFile($name, $storage)) { if ($storage->delete('', $name)) { $deleted++; } continue; } if ($this->isBundleFile($name) && $storage->delete('', $name)) { $deleted++; } } return $deleted; } /** * 파일명이 **오래된** 원자적 쓰기 임시 파일인지 판정합니다. * * 진행 중인 쓰기를 파괴하지 않도록 나이 가드를 둔다 — pid 는 재사용되므로 "그 pid 가 * 살아 있는가" 로는 판정할 수 없다. * * @param string $name 파일명 * @param CoreStorageDriver $storage 번들 디스크 스토리지 * @return bool 삭제 대상 여부 */ private function isStaleTempBundleFile(string $name, CoreStorageDriver $storage): bool { if (! preg_match('/^(module|plugin)\.\d+\.(js|css)\.tmp\.\d+$/', $name)) { return false; } $mtime = @filemtime($storage->getBasePath('').'/'.$name); // 나이를 읽지 못하면 남긴다 — 진행 중인 쓰기를 지우는 쪽이 더 나쁘다. return $mtime !== false && (time() - $mtime) > self::TEMP_BUNDLE_STALE_SECONDS; } /** * 번들 캐시 파일을 삭제합니다(cache-clear 커맨드용). * * **현재 버전은 보존한다** — `cleanupStaleBundles()` 와 같은 정책이다. 현재 버전까지 * 지우면 같은 순간 서빙 중인 웹 요청이 "존재함" 판정 직후 `filemtime()` 에서 500 을 * 낸다(bump 직후 TOCTOU). 캐시 파일은 없으면 다음 요청이 다시 만들므로, 지우는 것의 * 이득은 없고 그 창의 500 만 남는다. * * @param string|null $type 'module' | 'plugin' 지정 시 해당 타입만, null 이면 전체 * @return int 삭제된 파일 수 */ public function clearBundles(?string $type = null): int { $storage = $this->bundleStorage(); $currentVersion = $this->getCurrentVersion(); $deleted = 0; foreach ($storage->files('', '') as $file) { $name = basename($file); if ($name === '.gitignore' || ! $this->isBundleFile($name)) { continue; } // 현재 버전 보존 (cleanupStaleBundles 와 동형 — 정책이 갈라지면 한쪽이 창을 연다) if ($this->matchesVersion($name, $currentVersion)) { 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; } /** * 번들 디스크용 스토리지 드라이버를 반환합니다(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(); } }