HeuJung
3945b6f1b3
공개 저장소 이슈 gnuboard/g7 (@bigmsg) 제보에서 출발한 작업이다. 브라우저가 화면을 그리려고 제3자 CDN 에 도달해야 하면, 그 도달 실패는 예외도 로그도 남기지 않고 화면 기능만 조용히 사라진다. 폐쇄망·방화벽·광고차단기에서 재현되는데 자체 서버 로그에는 흔적이 없어 운영자가 원인을 특정할 수 없다. 제보된 것은 편집기 하나였지만 같은 구조가 아이콘·글꼴·코드편집기·압축 라이브러리·설치 마법사·개발 대시보드에 똑같이 있었으므로, 번들 확장과 템플릿 전체를 자체 제공으로 옮겼다. 런타임에 외부로 나가는 것은 주소 검색 서비스 하나만 남았다. 자체 제공만으로는 부족하다 — 자기 서버에서 받는 파일도 실패할 수 있고, 종전에는 그 실패가 무음이었다. CSS 경로에 재시도 계층을 세우고(스크립트 경로와 동형), 서버가 HTML 에 직접 심는 externals 까지 실패를 붙잡아 안내 배너와 [다시 시도]로 표면화했다. 편집기·코드편집기는 확보 실패 시 평문 입력으로 내려앉되 저장 계약을 유지한다. 두 번째 축은 운영자가 CSS 를 덧붙일 자리가 없던 문제다(sir.kr 문의). 확장 디렉토리의 custom/ 을 운영자 소유로 정해, 확장 교체가 그 디렉토리만은 보존하게 했다. 출처에 의존하지 않는 서술자로 해석하므로 나중에 다른 출처가 붙어도 소비자는 바뀌지 않는다. 확장 자산과 같은 메커니즘으로 정적 게시되어 CSS 내부 상대 url 도 해석되고, 파일을 고치면 그 변경을 감지해 재게시까지 예약된다. FTP 접근이 없는 운영자에게는 그 자리도 없는 것과 같으므로 레이아웃 편집기에서 직접 넣고 고칠 수 있게 했다. 모듈·플러그인·템플릿이 한 엔드포인트를 공유한다 — 타입별로 나누면 같은 검증이 세 벌로 갈리고 그중 약한 하나가 우회로가 된다. 여기서 올린 스크립트는 그 레이아웃 한 장이 아니라 사이트 전 화면에서 실행되므로 레이아웃 편집과 분리된 전용 권한으로 연다. 운영자 CSS 가 화면을 조작 불능으로 만들면 그것을 고칠 화면에도 같은 CSS 가 실려 스스로 갇히므로, 서버가 목록을 비우는 탈출구(?custom=off)를 함께 뒀다. 동봉 자산은 재생성 경로에 버전 대조 가드를 붙였다. 선언과 다른 버전을 버전 디렉토리에 써 넣는 조용한 거짓말은 배포된 뒤에는 드러나지 않는다.
759 lines
30 KiB
PHP
759 lines
30 KiB
PHP
<?php
|
||
|
||
namespace App\Services;
|
||
|
||
use App\Contracts\Repositories\ModuleRepositoryInterface;
|
||
use App\Contracts\Repositories\PluginRepositoryInterface;
|
||
use App\Contracts\Repositories\TemplateRepositoryInterface;
|
||
use App\Exceptions\StaticCachePublishException;
|
||
use App\Extension\Helpers\FilePermissionHelper;
|
||
use App\Extension\Traits\ClearsTemplateCaches;
|
||
use App\Helpers\ResponseHelper;
|
||
use App\Models\Template;
|
||
use App\Rules\AllowedTemplateFileType;
|
||
use App\Support\CustomAssets;
|
||
use Illuminate\Support\Facades\Cache;
|
||
use Illuminate\Support\Facades\File;
|
||
use Illuminate\Support\Facades\Log;
|
||
|
||
/**
|
||
* 부트스트랩 리소스 정적 게시(bake) 서비스.
|
||
*
|
||
* 병합 결과물(다국어·컴포넌트 정의·라우트·확장 번들·템플릿 dist 에셋)을
|
||
* 캐시 버전 디렉토리(`public/build/ext/{v}/`)에 실파일로 게시해 웹서버가
|
||
* rewrite 전에 직접 서빙하게 한다 (#122). 병합 로직은 새로 만들지 않고
|
||
* 전부 기존 SSoT(TemplateService/ExtensionBundleService)를 호출한다.
|
||
*
|
||
* 원자성: `{v}.tmp/` 에 전부 쓴 뒤 디렉토리 rename → `{v}/`, manifest.json 은
|
||
* rename 후 마지막에 기록한다. manifest 존재 = 게시 완료(부분 게시 참조 방지).
|
||
*
|
||
* 실패 정책: 쓰기 실패는 예외를 삼키고 Log::warning + tmp 정리 — 사이트는
|
||
* API 폴백으로 정상 유지된다(fail-open 이 아니라 "정적 fast path 미적용" 상태).
|
||
*/
|
||
class ExtensionStaticCacheService
|
||
{
|
||
use ClearsTemplateCaches;
|
||
|
||
/** 게시 완료 마커 파일명 */
|
||
private const MANIFEST_FILE = 'manifest.json';
|
||
|
||
/** 게시 락 이름 접두사 */
|
||
private const LOCK_PREFIX = 'ext-static.publish.';
|
||
|
||
/** 확장 식별자 패턴 (vendor-name) — 경로 세그먼트 화이트리스트 */
|
||
private const IDENTIFIER_PATTERN = '/^[a-z0-9]+-[a-z0-9_]+$/';
|
||
|
||
/** 로케일 패턴 — 경로 세그먼트 화이트리스트 */
|
||
private const LOCALE_PATTERN = '/^[a-z]{2}(?:[-_][A-Za-z0-9]{2,8})?$/';
|
||
|
||
/** terminating 게시 예약 플래그 (프로세스당 1회) */
|
||
private static bool $publishScheduled = false;
|
||
|
||
/** 테스트 전용 — root 프로세스 판정 오버라이드 (null = 실판정) */
|
||
private static ?bool $rootProcessForTesting = null;
|
||
|
||
/** isPublished 요청당 메모이즈 (version => 존재 여부) */
|
||
private array $publishedMemo = [];
|
||
|
||
public function __construct(
|
||
private TemplateService $templateService,
|
||
private TemplateRepositoryInterface $templateRepository,
|
||
private ModuleRepositoryInterface $moduleRepository,
|
||
private PluginRepositoryInterface $pluginRepository,
|
||
private ExtensionBundleService $bundleService,
|
||
private LanguagePackService $languagePackService,
|
||
) {}
|
||
|
||
/**
|
||
* 현재 확장 캐시 버전 기준으로 게시합니다.
|
||
*
|
||
* 이미 게시 완료(manifest 존재) 상태면 skip(멱등). `Cache::lock` 으로 단일
|
||
* 실행을 보장하며, 락 미획득 시 다른 프로세스가 게시 중인 것으로 보고 skip.
|
||
*
|
||
* @param bool $force 게시 완료 상태여도 강제 재게시
|
||
* @return bool 게시 완료 상태로 끝났으면 true (skip 포함), 실패/비활성이면 false
|
||
*/
|
||
public function publishCurrent(bool $force = false): bool
|
||
{
|
||
if (! $this->isEnabled()) {
|
||
return false;
|
||
}
|
||
|
||
$version = self::getExtensionCacheVersion();
|
||
|
||
if (! $force && $this->isPublished($version)) {
|
||
return true;
|
||
}
|
||
|
||
$lock = Cache::lock(self::LOCK_PREFIX.$version, 300);
|
||
|
||
if (! $lock->get()) {
|
||
return false;
|
||
}
|
||
|
||
try {
|
||
// 락 대기 중 다른 프로세스가 완료했을 수 있다 (멱등 재확인)
|
||
unset($this->publishedMemo[$version]);
|
||
if (! $force && $this->isPublished($version)) {
|
||
return true;
|
||
}
|
||
|
||
return $this->publishVersion($version);
|
||
} finally {
|
||
$lock->release();
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 해당 버전이 게시 완료 상태인지 확인합니다 (manifest 존재 = 완료).
|
||
*
|
||
* AssetUrl 게이트가 요청당 여러 번 호출하므로 메모이즈한다.
|
||
*
|
||
* @param int $version 확장 캐시 버전
|
||
* @return bool 게시 완료 여부
|
||
*/
|
||
public function isPublished(int $version): bool
|
||
{
|
||
return $this->publishedMemo[$version] ??= is_file(
|
||
$this->versionDir($version).DIRECTORY_SEPARATOR.self::MANIFEST_FILE
|
||
);
|
||
}
|
||
|
||
/**
|
||
* 현재 버전 + 직전 1개를 보존하고 나머지 게시 디렉토리를 삭제합니다.
|
||
*
|
||
* 직전 버전을 남기는 이유: 브라우저에 캐시된 직전 렌더 HTML 이 아직 구버전
|
||
* 정적 URL 을 참조할 수 있다 (asset-url-recovery 파샬이 최후 방어).
|
||
*
|
||
* @return int 삭제된 디렉토리 수
|
||
*/
|
||
public function cleanup(): int
|
||
{
|
||
$base = $this->baseDir();
|
||
|
||
if (! File::isDirectory($base)) {
|
||
return 0;
|
||
}
|
||
|
||
$current = self::getExtensionCacheVersion();
|
||
$versions = [];
|
||
$deleted = 0;
|
||
|
||
foreach (File::directories($base) as $dir) {
|
||
$name = basename($dir);
|
||
|
||
// 미완료 tmp 잔존물은 무조건 제거 대상 (rename 전 실패 흔적)
|
||
if (str_ends_with($name, '.tmp')) {
|
||
File::deleteDirectory($dir);
|
||
$deleted++;
|
||
|
||
continue;
|
||
}
|
||
|
||
if (ctype_digit($name)) {
|
||
$versions[(int) $name] = $dir;
|
||
}
|
||
}
|
||
|
||
// 현재 버전과, 현재를 제외한 최신 1개(직전) 보존
|
||
$keep = [$current];
|
||
$others = array_keys($versions);
|
||
rsort($others);
|
||
foreach ($others as $v) {
|
||
if ($v !== $current) {
|
||
$keep[] = $v;
|
||
break;
|
||
}
|
||
}
|
||
|
||
foreach ($versions as $v => $dir) {
|
||
if (! in_array($v, $keep, true)) {
|
||
File::deleteDirectory($dir);
|
||
$deleted++;
|
||
}
|
||
}
|
||
|
||
return $deleted;
|
||
}
|
||
|
||
/**
|
||
* 수명주기 이벤트에서 호출되는 terminating 게시 예약.
|
||
*
|
||
* `incrementExtensionCacheVersion()` 내부 단일 지점에서 호출된다.
|
||
* 프로세스당 1회만 등록하며, 게시는 예약 시점이 아니라 **실행 시점의 현재
|
||
* 버전**으로 수행되어 연속 bump(일괄 업데이트)를 자연 병합한다.
|
||
*
|
||
* 프로덕션 전용 — 비프로덕션은 blade 가 정적 URL 을 방출하지 않으므로
|
||
* 게시 자체가 무의미하고(§2-2), testing 환경의 파일 쓰기 부수효과도 차단한다.
|
||
*/
|
||
public static function schedulePublishOnTerminate(): void
|
||
{
|
||
if (self::$publishScheduled || ! app()->environment('production')) {
|
||
return;
|
||
}
|
||
|
||
// root 프로세스(sudo 코어 업데이트 등)에서는 예약하지 않는다 — 게시가 만드는
|
||
// 캐시 락 샤드 디렉토리(storage/framework/cache/data/xx)와 병합 번들
|
||
// (storage/app/ext-bundles)이 root 소유로 남아, 이후 웹 프로세스의 캐시
|
||
// 쓰기가 그 샤드에 해시되는 순간 Permission denied 로 죽는다 (실사례:
|
||
// sudo 업데이트 직후 전면 500). normalizeOwnership 은 게시 트리(build/ext)만
|
||
// 다루므로 storage 측 부수 산출물은 회피가 정답이다. 게시는 다음 웹 렌더의
|
||
// 자가 치유(웹 계정)가 수행하고, 명시적 `ext-static:publish` 커맨드는 이
|
||
// 게이트를 거치지 않는다 (운영자 책임 — 규정 문서 §6).
|
||
if (self::isRootProcess()) {
|
||
return;
|
||
}
|
||
|
||
self::$publishScheduled = true;
|
||
|
||
app()->terminating(static function (): void {
|
||
// 실행 시점에 재무장 가능 상태로 복귀 — 요청마다 앱 인스턴스를 새로 쓰는
|
||
// 장수 프로세스(Octane 류)에서는 static 플래그만 살아남으므로, 리셋 없이는
|
||
// 2번째 이후 bump 가 새 앱에 콜백을 등록하지 못한 채 영구 미게시가 된다
|
||
// (자가 치유도 같은 플래그 공유). FPM(요청=프로세스)에서는 무영향.
|
||
self::$publishScheduled = false;
|
||
|
||
try {
|
||
app(self::class)->publishCurrent();
|
||
} catch (\Throwable $e) {
|
||
Log::warning('정적 게시 terminating 실행 실패 — 다음 렌더의 자가 치유가 재시도합니다', [
|
||
'error' => $e->getMessage(),
|
||
]);
|
||
}
|
||
});
|
||
}
|
||
|
||
/**
|
||
* 테스트 격리용 — terminating 예약 플래그를 초기화합니다.
|
||
*/
|
||
public static function resetPublishScheduleForTesting(): void
|
||
{
|
||
self::$publishScheduled = false;
|
||
self::$rootProcessForTesting = null;
|
||
}
|
||
|
||
/**
|
||
* 테스트 전용 — root 프로세스 판정을 강제합니다 (null 로 실판정 복귀).
|
||
*
|
||
* @param bool|null $isRoot 강제할 판정값
|
||
*/
|
||
public static function fakeRootProcessForTesting(?bool $isRoot): void
|
||
{
|
||
self::$rootProcessForTesting = $isRoot;
|
||
}
|
||
|
||
/**
|
||
* 현재 프로세스가 root(euid 0)로 실행 중인지 판정합니다.
|
||
*
|
||
* posix 확장이 없는 환경(Windows, 함수 비활성 호스팅)은 root 아님으로 본다.
|
||
*
|
||
* @return bool root 실행 여부
|
||
*/
|
||
private static function isRootProcess(): bool
|
||
{
|
||
if (self::$rootProcessForTesting !== null) {
|
||
return self::$rootProcessForTesting;
|
||
}
|
||
|
||
return function_exists('posix_geteuid') && posix_geteuid() === 0;
|
||
}
|
||
|
||
/**
|
||
* 게시 루트 디렉토리 절대 경로를 반환합니다.
|
||
*
|
||
* @return string `public/build/ext` 절대 경로
|
||
*/
|
||
public function baseDir(): string
|
||
{
|
||
return public_path('build/ext');
|
||
}
|
||
|
||
/**
|
||
* 버전 디렉토리 절대 경로를 반환합니다.
|
||
*
|
||
* @param int $version 확장 캐시 버전
|
||
* @return string 버전 디렉토리 절대 경로
|
||
*/
|
||
public function versionDir(int $version): string
|
||
{
|
||
return $this->baseDir().DIRECTORY_SEPARATOR.$version;
|
||
}
|
||
|
||
/**
|
||
* kill-switch 판정 (`core.static_cache.enabled`, .env `G7_STATIC_CACHE`).
|
||
*
|
||
* @return bool 정적 게시 활성 여부
|
||
*/
|
||
public function isEnabled(): bool
|
||
{
|
||
return (bool) config('core.static_cache.enabled', true);
|
||
}
|
||
|
||
/**
|
||
* 한 버전의 게시를 실제 수행합니다 (tmp 쓰기 → rename → manifest → GC).
|
||
*
|
||
* @param int $version 게시할 확장 캐시 버전
|
||
* @return bool 성공 여부
|
||
*/
|
||
private function publishVersion(int $version): bool
|
||
{
|
||
$base = $this->baseDir();
|
||
$tmp = $base.DIRECTORY_SEPARATOR.$version.'.tmp';
|
||
$final = $this->versionDir($version);
|
||
|
||
try {
|
||
File::deleteDirectory($tmp);
|
||
File::ensureDirectoryExists($tmp, 0775);
|
||
|
||
$files = [];
|
||
|
||
$this->writeHtaccess($tmp, $files);
|
||
|
||
$locales = $this->publishableLocales();
|
||
|
||
foreach ($this->templateRepository->getActive() as $template) {
|
||
$this->publishTemplate($tmp, $template, $locales, $files);
|
||
}
|
||
|
||
$this->publishBundles($tmp, $version, $files);
|
||
|
||
$this->publishExtensionCustomAssets($tmp, $files);
|
||
|
||
// 원자적 스왑 — force 재게시 시 기존 디렉토리를 비켜낸 뒤 rename
|
||
if (File::isDirectory($final)) {
|
||
File::deleteDirectory($final);
|
||
}
|
||
|
||
if (! @rename($tmp, $final)) {
|
||
throw new StaticCachePublishException("Failed to rename publish directory: {$tmp} -> {$final}");
|
||
}
|
||
|
||
// manifest 는 rename 후 마지막 기록 — 존재 = 게시 완료
|
||
$this->writeManifest($final, $version, $files);
|
||
unset($this->publishedMemo[$version]);
|
||
|
||
// sudo/root CLI 게시 대응 — terminating 게시는 코어 업데이트의
|
||
// restoreOwnership **이후**(프로세스 종료 시)에 실행되므로, root 소유로
|
||
// 남으면 이후 php-fpm 의 재게시·GC 가 영구 실패한다. 부모(public/build)
|
||
// 소유권을 상속시킨다 (FilePermissionHelper::copyFile 의 sudo 대응 선례).
|
||
$this->normalizeOwnership();
|
||
|
||
// 인라인 GC (현재 + 직전 1개 보존)
|
||
$this->cleanup();
|
||
|
||
Log::info('부트스트랩 리소스 정적 게시 완료', [
|
||
'version' => $version,
|
||
'files' => count($files),
|
||
]);
|
||
|
||
return true;
|
||
} catch (\Throwable $e) {
|
||
// 예외 종류와 발생 위치까지 남긴다. 메시지만으로는 파일시스템 오류인지 병합
|
||
// 오류인지 구분되지 않아, 운영자도 개발자도 재현부터 다시 해야 한다 —
|
||
// 게시 실패는 사이트를 멈추지 않고 폴백으로 넘어가므로 이 로그가 유일한 흔적이다.
|
||
Log::warning('부트스트랩 리소스 정적 게시 실패 — API 폴백으로 동작합니다', [
|
||
'version' => $version,
|
||
'exception' => $e::class,
|
||
'error' => $e->getMessage(),
|
||
'at' => $e->getFile().':'.$e->getLine(),
|
||
]);
|
||
File::deleteDirectory($tmp);
|
||
|
||
return false;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* root 로 실행된 CLI 게시의 산출물 소유권을 부모 디렉토리 기준으로 정상화합니다.
|
||
*
|
||
* root 가 아닌 프로세스는 chown 자체가 불가능하고 필요도 없다(자기 소유로 생성됨)
|
||
* — 그 경우 즉시 no-op. 실패는 chownRecursive 가 경고 로그로 누적한다.
|
||
* 게시 루트 전체(`build/ext`)를 대상으로 하므로 방금 게시된 버전 디렉토리와
|
||
* 잔존 구버전이 함께 정상화된다.
|
||
*/
|
||
private function normalizeOwnership(): void
|
||
{
|
||
if (! function_exists('chown') || ! function_exists('posix_geteuid') || posix_geteuid() !== 0) {
|
||
return;
|
||
}
|
||
|
||
$parent = dirname($this->baseDir());
|
||
$owner = @fileowner($parent);
|
||
$group = @filegroup($parent);
|
||
|
||
if ($owner === false || $owner === 0) {
|
||
return;
|
||
}
|
||
|
||
FilePermissionHelper::chownRecursive($this->baseDir(), $owner, $group);
|
||
}
|
||
|
||
/**
|
||
* 활성 템플릿 1개의 게시물(lang/components/routes/assets)을 기록합니다.
|
||
*
|
||
* @param string $tmp tmp 디렉토리 절대 경로
|
||
* @param Template $template 활성 템플릿
|
||
* @param array<string> $locales 게시 대상 로케일
|
||
* @param array<string> $files 기록된 상대 경로 누적 (참조)
|
||
*/
|
||
private function publishTemplate(string $tmp, Template $template, array $locales, array &$files): void
|
||
{
|
||
$identifier = (string) $template->identifier;
|
||
|
||
if (! preg_match(self::IDENTIFIER_PATTERN, $identifier)) {
|
||
Log::warning('정적 게시 제외 — 식별자 패턴 불일치', ['identifier' => $identifier]);
|
||
|
||
return;
|
||
}
|
||
|
||
$templateDir = $tmp.DIRECTORY_SEPARATOR.'templates'.DIRECTORY_SEPARATOR.$identifier;
|
||
|
||
// 1. lang 병합 결과 (코어→템플릿→모듈→플러그인→언어팩 훅) — 현 lang API 와 동일 형상(raw)
|
||
foreach ($locales as $locale) {
|
||
$result = $this->templateService->getLanguageDataWithModules($identifier, $locale);
|
||
|
||
if (! ($result['success'] ?? false) || ! is_array($result['data'] ?? null)) {
|
||
continue;
|
||
}
|
||
|
||
$this->writeJson(
|
||
$templateDir.DIRECTORY_SEPARATOR.'lang'.DIRECTORY_SEPARATOR.$locale.'.json',
|
||
$result['data'],
|
||
$files,
|
||
$tmp
|
||
);
|
||
}
|
||
|
||
// 2. components.json 사본 (raw)
|
||
$componentsPath = base_path("templates/{$identifier}/components.json");
|
||
if (is_file($componentsPath)) {
|
||
$this->copyFile($componentsPath, $templateDir.DIRECTORY_SEPARATOR.'components.json', $files, $tmp);
|
||
}
|
||
|
||
// 3. routes 병합 결과 — 프론트 소비 코드 무변경을 위한 성공 봉투 포함.
|
||
// 열화 스냅샷(확장 업데이트 진행 중 등)은 게시하지 않는다 — 정적 파일은
|
||
// 스스로 회복되지 않으므로 열화 상태가 다음 bump 까지 박제된다 (getRoutes 와 동일 규율)
|
||
$routesResult = $this->templateService->getRoutesDataWithModules($identifier);
|
||
|
||
if (($routesResult['success'] ?? false) && ! $this->templateService->lastRouteMergeWasDegraded()) {
|
||
$this->writeJson(
|
||
$templateDir.DIRECTORY_SEPARATOR.'routes.json',
|
||
['success' => true, 'message' => '', 'data' => $routesResult['data']],
|
||
$files,
|
||
$tmp
|
||
);
|
||
} elseif ($routesResult['success'] ?? false) {
|
||
Log::warning('정적 게시에서 routes 제외 — 라우트 병합 열화 상태 (확장 업데이트 진행 중 추정)', [
|
||
'template' => $identifier,
|
||
]);
|
||
}
|
||
|
||
// 4. dist 에셋 사본 (확장자 화이트리스트, *.map 제외)
|
||
$this->publishDistAssets(
|
||
base_path("templates/{$identifier}/dist"),
|
||
$templateDir.DIRECTORY_SEPARATOR.'assets',
|
||
$files,
|
||
$tmp
|
||
);
|
||
|
||
// 5. 운영자 소유 디렉토리(`custom/`) 사본
|
||
//
|
||
// 게시하지 않으면 이 자산만 API 경로에 남는데, 그 경로에서는 CSS 내부 상대
|
||
// `url()` 이 해석되지 않는다 — `?file=` 형태는 기준 URL 이 `/api/templates/assets/`
|
||
// 라 `url('./font.woff2')` 가 그 디렉토리를 가리키고, 확장자 형태는 정적 최적화
|
||
// 서버가 먼저 가로챈다(그래서 `extensionless` 모드가 존재한다). 즉 정적 확장자
|
||
// URL 은 **public 아래 실제 파일일 때만** 200 이 되므로, 문서가 안내하는
|
||
// "폰트·이미지를 custom/ 에 두고 상대 경로로 참조" 를 성립시키는 방법은 게시뿐이다.
|
||
//
|
||
// 갱신 축은 확장 자산과 동일하다 — 운영자가 파일을 고치면 `CustomAssets` 가
|
||
// 그것을 감지해 `ext.cache_version` 을 올리고, 그 단일 지점이 재게시까지 예약한다.
|
||
$this->publishDistAssets(
|
||
base_path("templates/{$identifier}/".CustomAssets::DIRECTORY),
|
||
$templateDir.DIRECTORY_SEPARATOR.'assets'.DIRECTORY_SEPARATOR.CustomAssets::DIRECTORY,
|
||
$files,
|
||
$tmp,
|
||
excludeCustom: false
|
||
);
|
||
}
|
||
|
||
/**
|
||
* 템플릿 dist 디렉토리를 재귀 복사합니다 (허용 확장자만, 소스맵 제외).
|
||
*
|
||
* @param string $sourceDir 원본 절대 경로 (dist 또는 custom)
|
||
* @param string $targetDir 게시 대상 절대 경로
|
||
* @param array<string> $files 기록된 상대 경로 누적 (참조)
|
||
* @param string $tmp tmp 루트 (상대 경로 계산용)
|
||
* @param bool $excludeCustom 원본 안의 `custom/` 하위를 건너뛸지 (dist 원본에서만 참)
|
||
*/
|
||
private function publishDistAssets(
|
||
string $sourceDir,
|
||
string $targetDir,
|
||
array &$files,
|
||
string $tmp,
|
||
bool $excludeCustom = true
|
||
): void {
|
||
$realSource = realpath($sourceDir);
|
||
|
||
if ($realSource === false || ! is_dir($realSource)) {
|
||
return;
|
||
}
|
||
|
||
// 소스맵은 배포 금지 정책(`*.map` gitignore)과 동일하게 제외
|
||
$allowed = array_diff(AllowedTemplateFileType::getAllowedExtensions(), ['map']);
|
||
|
||
$iterator = new \RecursiveIteratorIterator(
|
||
new \RecursiveDirectoryIterator($realSource, \FilesystemIterator::SKIP_DOTS)
|
||
);
|
||
|
||
/** @var \SplFileInfo $file */
|
||
foreach ($iterator as $file) {
|
||
if (! $file->isFile()) {
|
||
continue;
|
||
}
|
||
|
||
$extension = strtolower($file->getExtension());
|
||
if (! in_array($extension, $allowed, true)) {
|
||
continue;
|
||
}
|
||
|
||
// 컨테인먼트 검증 — 심볼릭 링크 등으로 dist 밖을 가리키는 실경로 차단
|
||
$realFile = $file->getRealPath();
|
||
if ($realFile === false || ! str_starts_with($realFile, $realSource.DIRECTORY_SEPARATOR)) {
|
||
continue;
|
||
}
|
||
|
||
$relative = substr($realFile, strlen($realSource) + 1);
|
||
|
||
// dist 원본에서는 `custom/` 하위를 건너뛴다 — 운영자 파일은 자기 원본
|
||
// 루트로 따로 게시되므로, dist 를 통해 한 번 더 실리면 같은 파일이 두 경로에
|
||
// 놓여 어느 쪽이 유효한지가 갈린다. custom 원본으로 호출될 때는 끄고 들어온다
|
||
// (그러지 않으면 `custom/custom/…` 이 조용히 누락된다).
|
||
if ($excludeCustom && $this->isCustomAssetPath($relative)) {
|
||
continue;
|
||
}
|
||
|
||
$this->copyFile($realFile, $targetDir.DIRECTORY_SEPARATOR.$relative, $files, $tmp);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 상대 경로가 운영자 소유 디렉토리(`custom/`) 소속인지 판정합니다.
|
||
*
|
||
* @param string $relative 게시 원본 기준 상대 경로
|
||
* @return bool custom 소속이면 true
|
||
*/
|
||
private function isCustomAssetPath(string $relative): bool
|
||
{
|
||
$normalized = str_replace(DIRECTORY_SEPARATOR, '/', $relative);
|
||
|
||
return $normalized === CustomAssets::DIRECTORY
|
||
|| str_starts_with($normalized, CustomAssets::DIRECTORY.'/');
|
||
}
|
||
|
||
/**
|
||
* 확장 병합 번들 4종(modules/plugins × js/css)을 게시합니다.
|
||
*
|
||
* @param string $tmp tmp 디렉토리 절대 경로
|
||
* @param int $version 확장 캐시 버전
|
||
* @param array<string> $files 기록된 상대 경로 누적 (참조)
|
||
*/
|
||
private function publishBundles(string $tmp, int $version, array &$files): void
|
||
{
|
||
$map = ['module' => 'modules', 'plugin' => 'plugins'];
|
||
|
||
foreach ($map as $type => $plural) {
|
||
foreach (['js', 'css'] as $kind) {
|
||
$path = $this->bundleService->getBundleFilePath($type, $kind, $version);
|
||
|
||
if ($path === '' || ! is_file($path)) {
|
||
continue;
|
||
}
|
||
|
||
$this->copyFile(
|
||
$path,
|
||
$tmp.DIRECTORY_SEPARATOR.'bundles'.DIRECTORY_SEPARATOR."{$plural}.{$kind}",
|
||
$files,
|
||
$tmp
|
||
);
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 활성 모듈·플러그인의 운영자 소유 디렉토리(`custom/`)를 게시합니다.
|
||
*
|
||
* 모듈·플러그인의 빌드 산출물은 **병합 번들**로만 게시되는데, `custom/` 은 그 번들에
|
||
* 들어가지 않는다(운영자 파일은 번들보다 뒤에 따로 로드되어야 재정의가 성립한다).
|
||
* 그래서 게시하지 않으면 확장 자산 중 이것만 요청마다 PHP 를 거치고, 무엇보다
|
||
* CSS 내부 상대 `url()` 이 해석되지 않는다 — `?file=` 형태는 기준 URL 이
|
||
* `/api/modules/assets/` 라 `url('./font.woff2')` 가 그 디렉토리를 가리키고,
|
||
* 확장자 형태는 정적 최적화 서버가 먼저 가로챈다. 정적 확장자 URL 은 **public 아래
|
||
* 실제 파일일 때만** 200 이 되므로 게시가 유일한 방법이다 (템플릿과 같은 사유).
|
||
*
|
||
* **활성 확장만** 게시한다. 자산 서빙이 활성 확장에만 응답하므로, 비활성 확장의 파일을
|
||
* 게시해 봐야 아무도 참조하지 않는 사본이 버전 디렉토리마다 쌓일 뿐이다.
|
||
*
|
||
* @param string $tmp tmp 디렉토리 절대 경로
|
||
* @param array<string> $files 기록된 상대 경로 누적 (참조)
|
||
*/
|
||
private function publishExtensionCustomAssets(string $tmp, array &$files): void
|
||
{
|
||
// 활성 목록은 **레포지토리**에서 읽는다. 매니저(`getActiveModules()`)는 확장을
|
||
// 실제로 적재하는 부작용이 있어, 게시 중에 그 부작용을 끌어들이면 게시가 확장
|
||
// 부팅 상태에 좌우된다. 같은 메서드가 템플릿을 `templateRepository->getActive()`
|
||
// 로 세는 것과 대칭이다.
|
||
$sources = [
|
||
'modules' => $this->moduleRepository->getActiveModuleIdentifiers(),
|
||
'plugins' => $this->pluginRepository->getActivePluginIdentifiers(),
|
||
];
|
||
|
||
foreach ($sources as $root => $identifiers) {
|
||
foreach ($identifiers as $identifier) {
|
||
$identifier = (string) $identifier;
|
||
|
||
if (! preg_match(self::IDENTIFIER_PATTERN, $identifier)) {
|
||
Log::warning('정적 게시 제외 — 식별자 패턴 불일치', [
|
||
'type' => $root,
|
||
'identifier' => $identifier,
|
||
]);
|
||
|
||
continue;
|
||
}
|
||
|
||
$this->publishDistAssets(
|
||
base_path("{$root}/{$identifier}/".CustomAssets::DIRECTORY),
|
||
$tmp.DIRECTORY_SEPARATOR.$root.DIRECTORY_SEPARATOR.$identifier
|
||
.DIRECTORY_SEPARATOR.'assets'.DIRECTORY_SEPARATOR.CustomAssets::DIRECTORY,
|
||
$files,
|
||
$tmp,
|
||
excludeCustom: false
|
||
);
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 게시 대상 로케일을 열거합니다 — `/api/locales/active` 와 동일 소스
|
||
* (언어팩이 추가한 로케일 포함).
|
||
*
|
||
* @return array<string> 로케일 목록 (패턴 검증 통과분)
|
||
*/
|
||
private function publishableLocales(): array
|
||
{
|
||
$locales = $this->languagePackService->getActiveLocales();
|
||
|
||
return array_values(array_filter(
|
||
is_array($locales) ? $locales : [],
|
||
static fn ($locale) => is_string($locale) && preg_match(self::LOCALE_PATTERN, $locale)
|
||
));
|
||
}
|
||
|
||
/**
|
||
* JSON 파일을 API 와 동일 인코딩 옵션으로 기록합니다.
|
||
*
|
||
* @param string $absolutePath 기록 대상 절대 경로
|
||
* @param mixed $data 직렬화할 데이터
|
||
* @param array<string> $files 기록된 상대 경로 누적 (참조)
|
||
* @param string $tmp tmp 루트 (상대 경로 계산용)
|
||
*/
|
||
private function writeJson(string $absolutePath, mixed $data, array &$files, string $tmp): void
|
||
{
|
||
File::ensureDirectoryExists(dirname($absolutePath), 0775);
|
||
|
||
$json = json_encode($data, ResponseHelper::JSON_ENCODE_OPTIONS);
|
||
|
||
if ($json === false) {
|
||
throw new StaticCachePublishException("Failed to encode JSON payload: {$absolutePath}");
|
||
}
|
||
|
||
if (File::put($absolutePath, $json) === false) {
|
||
throw new StaticCachePublishException("Failed to write file: {$absolutePath}");
|
||
}
|
||
|
||
$files[] = $this->relativePath($absolutePath, $tmp);
|
||
}
|
||
|
||
/**
|
||
* 파일 1개를 복사합니다.
|
||
*
|
||
* @param string $source 원본 절대 경로
|
||
* @param string $target 대상 절대 경로
|
||
* @param array<string> $files 기록된 상대 경로 누적 (참조)
|
||
* @param string $tmp tmp 루트 (상대 경로 계산용)
|
||
*/
|
||
private function copyFile(string $source, string $target, array &$files, string $tmp): void
|
||
{
|
||
File::ensureDirectoryExists(dirname($target), 0775);
|
||
|
||
if (! File::copy($source, $target)) {
|
||
throw new StaticCachePublishException("Failed to copy file: {$source} -> {$target}");
|
||
}
|
||
|
||
$files[] = $this->relativePath($target, $tmp);
|
||
}
|
||
|
||
/**
|
||
* Apache 용 불변 캐시 헤더 + 압축 .htaccess 를 기록합니다.
|
||
*
|
||
* 정적 서빙은 Laravel 압축 미들웨어(GzipEncodeResponse)를 우회하므로 압축을
|
||
* 여기서 직접 선언한다 — 없으면 종전 API 대비 전송량 회귀다 (실측: lang/ko.json
|
||
* 524,915B 비압축). nginx 는 서버 기본(ETag/Last-Modified) 재검증으로 충분하며
|
||
* 권장 gzip/expires 스니펫은 규정 문서(§8)에 안내한다.
|
||
*
|
||
* @param string $tmp tmp 디렉토리 절대 경로
|
||
* @param array<string> $files 기록된 상대 경로 누적 (참조)
|
||
*/
|
||
private function writeHtaccess(string $tmp, array &$files): void
|
||
{
|
||
$content = <<<'HTACCESS'
|
||
<IfModule mod_headers.c>
|
||
Header set Cache-Control "public, max-age=31536000, immutable"
|
||
</IfModule>
|
||
<IfModule mod_deflate.c>
|
||
AddOutputFilterByType DEFLATE application/json application/javascript text/css image/svg+xml
|
||
</IfModule>
|
||
|
||
HTACCESS;
|
||
|
||
if (File::put($tmp.DIRECTORY_SEPARATOR.'.htaccess', $content) === false) {
|
||
throw new StaticCachePublishException('Failed to write .htaccess');
|
||
}
|
||
|
||
$files[] = '.htaccess';
|
||
}
|
||
|
||
/**
|
||
* 게시 완료 마커(manifest.json)를 기록합니다.
|
||
*
|
||
* @param string $finalDir 최종 버전 디렉토리 절대 경로
|
||
* @param int $version 확장 캐시 버전
|
||
* @param array<string> $files 게시된 상대 경로 목록
|
||
*/
|
||
private function writeManifest(string $finalDir, int $version, array $files): void
|
||
{
|
||
$manifest = [
|
||
'cache_version' => $version,
|
||
'published_at' => now()->toIso8601String(),
|
||
'files' => array_values($files),
|
||
];
|
||
|
||
$json = json_encode($manifest, ResponseHelper::JSON_ENCODE_OPTIONS);
|
||
|
||
if ($json === false || File::put($finalDir.DIRECTORY_SEPARATOR.self::MANIFEST_FILE, $json) === false) {
|
||
throw new StaticCachePublishException('Failed to write manifest');
|
||
}
|
||
}
|
||
|
||
/**
|
||
* tmp 루트 기준 상대 경로를 반환합니다.
|
||
*
|
||
* @param string $absolutePath 절대 경로
|
||
* @param string $tmp tmp 루트
|
||
* @return string 상대 경로 (구분자 `/` 정규화)
|
||
*/
|
||
private function relativePath(string $absolutePath, string $tmp): string
|
||
{
|
||
return str_replace('\\', '/', substr($absolutePath, strlen($tmp) + 1));
|
||
}
|
||
}
|