fix(core,extensions): 확장 쓰기 경로 공통화 · HTMLPurifier 정의 캐시 storage 이전
https://github.com/gnuboard/g7/issues/125 — 상품 상세설명을 HTML 로 저장할 때 HTMLPurifier 가 모듈 vendor 폴더 안에 정의 캐시를 만들려다 실패해 저장이 매번 500 으로 끝나던 문제를 고친다. vendor 를 읽기 전용으로 두는 표준 배포에서 그 쓰기는 예외가 아니라 PHP 경고로 나오고 Laravel 이 이를 ErrorException 으로 승격시킨다. 캐시는 설정 해시당 1회만 기록되므로 캐시가 영영 생기지 않아 재시도해도 같은 결과였다. 캐시 경로를 storage 아래로 옮기고, 그 경로마저 확보하지 못하면 캐시만 끄고 정화는 그대로 수행한다 — 캐시는 성능 장치이고 정화는 보안 장치라, 전자의 실패가 후자를 건너뛰게 만들면 안 된다. 저장은 성공하므로 운영자에게 도달하는 흔적이 로그 하나뿐이라 error 수준으로 남긴다 (출하 기본 로그 수준이 error 라 warning 은 기본 설치 상태에서 파일에 남지 않는다). 그 과정에서 갈라져 있던 두 축을 코어 한 곳으로 모은다. - 쓰기 디렉토리 확보: 억제 생성·chmod·setgid·소유권 상속·쓰기 판정 절차가 정적 게시와 정의 캐시 두 곳에 서로 다른 하드닝으로 복제돼 있었다(억제 mkdir·setgid·clearstatcache 가 사본마다 한쪽씩 빠져 있었다). FilePermissionHelper 의 ensureWritableDirectory 와 hardenDirectory 로 통합하고, 실패 사유는 out 파라미터로 올려 정책(조용한 성능 저하 대 시끄러운 실패)은 호출부가 정하게 둔다. - 확장 저장 경로: storage_path('app/modules/…') 손조립이 30곳에 흩어져 있어 테스트 격리 분기를 넣으려면 사본마다 복제해야 했고, 한 곳만 빠뜨려도 그 확장의 테스트가 운영 설정 파일을 덮어쓴다. 디스크 root 를 단일 출처로 읽는 ExtensionStoragePath 로 전환하고 테스트 분기는 config/filesystems.php 한 줄에서 끝낸다. 함께 고친 것 - 테스트가 운영 라우트 캐시로 부팅해 확장 allowlist 가 라우트 축에서 통째로 무력화되던 문제. 삭제가 아니라 경로를 돌린다 — 라우트 캐시는 확장 작업 전까지 재생성되지 않아, 삭제하면 운영 사이트가 그때까지 라우트 파일 스캔 경로로 떨어진다. - PHPUnit 프로세스가 확장 vendor 의 제3자 composer 패키지를 오토로드하지 않아 그 패키지를 쓰는 코드 경로가 통째로 테스트 불가였던 문제. 확장 자신의 오토로더를 그대로 쓰면 활성 디렉토리가 _bundled 를 이기고 base path 유추까지 깨지므로, 생성된 맵에서 제3자 항목만 골라 별도 로더로 등록한다. - 게시 폴더가 setgid 를 갖지 않아, 명령줄과 웹이 번갈아 만든 하위 폴더를 다른 쪽이 쓰지 못하던 문제. - 관리자 템플릿이 HTML 정화 라이브러리를 직접 지정하지 않아 전이 의존으로 딸려온 구버전이 쓰이던 문제. 동반 산출물 - 규정 표(·AGENTS.md) 6행 + storage-driver/service-repository/testing-guide 문서 - audit 룰 2종 + coverage 6항목. 저장소가 이미 전량 전환돼 전수 실행이 공허 통과하므로 판정식은 픽스처 36건이 잠근다 - INSTALL.md 에 설치 후 파일 권한 절 추가 (vendor 쓰기 권한 불요를 명시)
This commit is contained in:
1 parent
fc27a6edf6
commit
85e266d361
88 files changed
+1913
-332
No files matched your search
@@ -501,6 +501,26 @@ public function updateUser(User $user, array $data): User
|
||||
|
||||
> 상세: [validation.md](validation.md) "계층 리소스"·"보안 게이트 대칭성"
|
||||
|
||||
### 서비스가 제3자 라이브러리를 붙일 때
|
||||
|
||||
그 라이브러리가 디스크에 무엇을 어디에 쓰는지는 **서비스가 책임진다.** 제3자 라이브러리는 캐시·임시파일 경로를 설정하지 않으면 자기 설치 폴더(vendor 안)나 현재 작업 디렉토리에 쓰는데, 배포본의 vendor 를 읽기 전용으로 두는 서버에서는 그 쓰기가 PHP 경고를 내고 Laravel 이 이를 `ErrorException` 으로 승격시켜 요청이 500 으로 끝난다.
|
||||
|
||||
```
|
||||
필수: 경로는 `ExtensionStoragePath::module($identifier, 'cache/…')` 로 얻는다
|
||||
(디스크 root 단일 출처 — 테스트 분기를 서비스가 들고 있지 않는다)
|
||||
필수: 확보는 `FilePermissionHelper::ensureWritableDirectory($path, $mode, $failure)` 에 맡긴다
|
||||
(억제된 생성 + umask 무력화 chmod + POSIX setgid + 소유권 상속 + 쓰기 판정을 한 번에)
|
||||
필수: 확보 실패 시 캐시만 끄고 본래 기능은 계속 수행 + `error` 수준 통지 1회 기록
|
||||
(출하 기본 로그 수준이 `error` 라 `warning` 은 기본 설치 상태에서 기록되지 않는다)
|
||||
필수: 통지에 `$failure['reason']` 을 함께 싣는다 (사유마다 운영자가 고칠 대상이 다르다)
|
||||
금지: 경로를 `storage_path('app/modules/…')` 로 직접 조립하는 것
|
||||
금지: 확보 절차(생성·chmod·setgid·판정)를 서비스가 자기 안에 복사하는 것
|
||||
금지: 캐시 확보 실패를 그대로 500 으로 흘리는 것
|
||||
금지: 폴백에서 정화·검증 자체를 건너뛰는 것 (캐시는 성능 장치, 정화는 보안 장치)
|
||||
```
|
||||
|
||||
> 상세: [storage-driver.md](../extension/storage-driver.md) "제3자 라이브러리에 절대 경로를 넘길 때"
|
||||
|
||||
---
|
||||
|
||||
## 트랜잭션 및 관계 삭제 패턴
|
||||
|
||||
@@ -968,6 +968,36 @@ $basePath = $this->storage->getBasePath('images');
|
||||
// → /path/to/g7/storage/app/modules/sirsoft-ecommerce/images
|
||||
```
|
||||
|
||||
#### 제3자 라이브러리에 절대 경로를 넘길 때
|
||||
|
||||
제3자 라이브러리(HTML 정화기, PDF 생성기, 이미지 처리기 등)는 캐시·임시파일 경로를 설정하지 않으면 **자기 설치 폴더**(vendor 안)나 현재 작업 디렉토리에 쓴다. 표준 Laravel 배포는 웹서버에 `storage/` 와 `bootstrap/cache` 만 쓰기 권한을 주므로 그 쓰기는 실패하는데, 실패가 예외가 아니라 PHP 경고라 Laravel `HandleExceptions` 가 `ErrorException` 으로 승격시켜 **요청이 500 으로 끝난다**. 설정 해시당 1회만 기록하는 라이브러리라면 캐시가 영영 생기지 않아 매 요청이 같은 실패를 반복한다. 개발 머신에서는 vendor 가 쓰기 가능해 한 번 성공하고 끝나므로 재현되지 않는다.
|
||||
|
||||
`cache` 카테고리의 절대 경로를 명시적으로 넘긴다.
|
||||
|
||||
```php
|
||||
$cacheDir = ExtensionStoragePath::module('sirsoft-ecommerce', 'cache/htmlpurifier');
|
||||
|
||||
if (! FilePermissionHelper::ensureWritableDirectory($cacheDir, 0775, $failure)) {
|
||||
// 캐시만 끄고 정화는 그대로 수행한다 (아래 (c))
|
||||
}
|
||||
|
||||
$config = \HTMLPurifier_Config::createDefault();
|
||||
$config->set('Cache.SerializerPath', $cacheDir);
|
||||
$config->set('Cache.SerializerPermissions', 0775);
|
||||
```
|
||||
|
||||
세 가지 규율을 함께 지킨다.
|
||||
|
||||
**(a) 디렉토리를 먼저 만든다.** 경로 해석기는 경로를 계산할 뿐 만들지 않고, 라이브러리도 대개 지정한 base 아래의 **하위** 디렉토리만 만든다. base 가 없으면 경고 한 줄을 내고 끝나므로, 경로만 지정하면 실패 지점이 "vendor 쓰기 실패" 에서 "base 없음 실패" 로 옮겨갈 뿐이다.
|
||||
|
||||
확보는 코어 프리미티브 `FilePermissionHelper::ensureWritableDirectory($path, $mode, $failure)` 가 맡는다. 이 프리미티브는 **예외도 PHP 경고도 내지 않고** `bool` 을 돌려준다 — `File::ensureDirectoryExists()` 는 `mkdir()` 을 억제 없이 부르므로 생성 실패가 `E_WARNING` 으로 나오고 Laravel 이 `ErrorException` 으로 승격시켜, 막으려던 500 이 다른 줄에서 그대로 난다. 직접 조립하지 않는다.
|
||||
|
||||
**(b) 권한 정합화는 프리미티브가 함께 수행한다.** 생성 API 의 mode 인자는 umask 로 깎이므로 명시 `chmod` 를 재적용하고, POSIX 에서는 setgid 도 함께 세운다 — 새 디렉토리의 그룹은 생성 프로세스의 egid 이므로, setgid 가 없으면 스케줄러(CLI)가 먼저 만든 하위 디렉토리를 웹 프로세스가 쓰지 못한다. 부모 소유권 상속까지 한 곳에 있으므로 호출부가 이 셋을 각자 복사하지 않는다. 이미 존재하는 디렉토리만 정합화하려면 `FilePermissionHelper::hardenDirectory($path, $mode)` 를 쓴다.
|
||||
|
||||
**(c) 확보 실패는 기능 실패가 아니다.** 프리미티브가 `false` 와 함께 사유(`occupied_by_file` / `ancestor_not_writable` / `create_failed` / `not_writable`)를 돌려주므로 통지에 그 사유를 싣는다 — 사유마다 운영자가 고쳐야 할 대상이 다르다. 디렉토리가 이미 있는데 쓰기 불가라면 요청 경로에서 권한과 싸우지 않는다. 캐시만 끄고(`Cache.DefinitionImpl = null` 같은 라이브러리별 비활성 스위치) 본래 기능은 계속 수행하며, 통지는 프로세스당 1회만 남긴다. 그 통지는 `error` 수준으로 남긴다 — 출하 기본 로그 수준이 `error` 라 `warning` 으로 남기면 기본 설치 상태에서 파일에 기록되지 않고, 기능은 성공하므로 운영자에게 도달하는 흔적이 그 통지 하나뿐이다. **정화·검증 자체를 건너뛰는 폴백은 금지한다** — 캐시는 성능 장치이고 정화는 보안 장치라, 캐시 실패가 보안 장치를 건너뛰게 만들어서는 안 된다.
|
||||
|
||||
**디스크 주의**: 경로를 `getBasePath('cache')` 로 얻지 말고 `App\Support\ExtensionStoragePath::module($identifier, 'cache/…')` 로 얻는다. 이 해석기는 `modules`/`plugins` 디스크의 root(`config/filesystems.php`)를 단일 출처로 삼아 로컬 절대 경로를 조립하며, 그 root 가 테스트 환경을 인지하므로 확장이 `app()->runningUnitTests()` 분기를 자기 안에 복사할 필요가 없다. `getBasePath()` 는 `Storage::disk()->path()` 위임이라 카테고리 디스크가 비로컬(S3 등)로 오버라이드되면 파일시스템 경로가 아니게 되고, 그러면 라이브러리가 그 값을 상대경로로 보고 현재 작업 디렉토리 기준으로 해석해 **조용히 엉뚱한 곳에 쓴다**. 대부분의 정의 캐시는 `file_put_contents` 로 쓰는 로컬 전용 장치다. 두 경로는 기본 설정에서 바이트 단위로 동일하므로 `cache` 카테고리 규약은 레이아웃 차원에서 그대로 지켜진다.
|
||||
|
||||
---
|
||||
|
||||
### getDisk()
|
||||
|
||||
@@ -73,6 +73,31 @@ powershell -Command "npm run test:run"
|
||||
2. `_bundled` src/ → PSR-4 prepend 등록 (활성 디렉토리보다 우선 검색)
|
||||
3. `autoload-extensions.php` → 이미 로드된 _bundled 항목은 스킵
|
||||
4. Manager/RouteServiceProvider → `class_exists` 가드로 중복 선언 방지
|
||||
5. 확장 `vendor/` → 제3자 composer 패키지만 골라 별도 로더로 등록
|
||||
|
||||
### 확장의 제3자 composer 패키지
|
||||
|
||||
확장이 자기 `composer.json` 으로 들여온 제3자 패키지(예: HTML 정화 라이브러리)는 `tests/bootstrap.php`
|
||||
가 등록합니다. 확장별 테스트 베이스 클래스에서 같은 일을 다시 하지 않습니다 — 규칙이 두 곳으로
|
||||
갈라지면 한쪽만 고쳐져 조용히 어긋납니다.
|
||||
|
||||
```
|
||||
금지: 확장 vendor 의 autoload.php 를 그대로 require
|
||||
필수: 생성된 맵에서 제3자 항목만 골라 vendorDir 없는 로더로 등록
|
||||
```
|
||||
|
||||
그 오토로더를 그대로 쓰면 두 가지가 오류 없이 깨집니다.
|
||||
|
||||
1. 확장 **자신의** PSR-4 와 files 를 활성 디렉토리로 매핑하고 자신을 prepend 로 걸어, 위 2번의
|
||||
`_bundled` 등록을 이깁니다. 테스트가 `_bundled` 가 아니라 활성 디렉토리 사본을 검증하게 되어
|
||||
"`_bundled` 에서만 작업한다" 는 규율이 조용히 깨집니다.
|
||||
2. Composer 로더는 `vendorDir` 를 가지면 등록 로더 목록의 맨 앞에 자신을 넣는데, 테스트용 앱
|
||||
생성이 그 첫 항목에서 base path 를 유추합니다. 이후 테스트의 앱 부팅이 확장 디렉토리에서
|
||||
`bootstrap/app.php` 를 찾다 실패합니다. (운영 진입점은 base path 를 명시 전달하므로 영향이 없습니다.)
|
||||
|
||||
이 결손은 그 패키지를 쓰는 코드 경로를 아무도 테스트하지 않는 동안 드러나지 않습니다. 확장에
|
||||
제3자 패키지를 추가하면 그 패키지를 실제로 로드하는 테스트를 함께 두고, 로드 실패를 skip 이 아니라
|
||||
단언 실패로 드러냅니다.
|
||||
|
||||
### 주의사항
|
||||
|
||||
|
||||
Reference in new issue
Block a user