refactor(repo)!: 쓰지 않는 파일과 운영 인프라 파일을 지운다
문제: infra/ 43개 중 12개는 코드·테스트·workflow·스크립트 어디서도
읽지 않는다(httpclient·jpa·messaging·notification의 toxiproxy compose와
README). nginx 설정, Kubernetes PVC 인증 job, DB 역할 SQL 셋은 운영
인프라라 개발 repo에 둘 것이 아니다(소유자 결정 2026-11-07). release.yml
의 fileserver-pvc-certification job은 그 매니페스트 문자열만 grep했다.
고른 방법:
- 15개를 지운다.
- 운영 조건만 그 기능 문서에 한국어로 남긴다.
docs/fileserver/operations.md 「운영 환경이 지켜야 할 조건」(nginx
internal location·alias·X-Accel-Redirect 헤더 제거·스트리밍, PVC
ReadWriteOnce·fsGroup), storage-certification.md(인증 절차),
docs/jpa/security.md 「역할과 권한」·「서버 설정」(역할 SQL과
jpa/postgres README 내용), docs/messaging/security.md(인증서 SAN).
httpclient TLS README 내용은 docs/httpclient/security.md에 이미 있다.
- release.yml job과 needs 줄, fileserver-pr.yml·pr-adapters.yml의 지운
경로 필터를 지운다.
- fileserver 지원 표의 "Kubernetes ReadWriteOnce PVC — Limited" 행은
근거 job이 없어져 「주장하지 않음」으로 옮긴다.
버린 대안: 인프라 파일을 project-infra로 옮기기(설계 Q6). 그 repo는
특정 프로젝트용이라 범용 템플릿 파일을 받을 자리가 없다.
위험·한계: 지원 표에서 PVC 주장이 빠진다. 파생 서비스가 그 파일을
배포에 썼다면 병합이 지운다(B-50). 클러스터 인증은 이제 배포하는 쪽이
문서 절차로 한다.
검증(desktop, 트리 749a3328, ~/t1-layout-logs/):
- :composition:fileserver-platform:check :app-bootstrap:check
:app-bootstrap:documentContractTest rc=0 (repositoryContractTest,
FileserverDocumentationCoverageTest 실행)
- :verifyStrictLaneStages --dry-run rc=0
- scripts/verify-compose-profile-contracts.sh rc=0 (18 lane)
- check-work-docs.py, 상대 링크 검사 rc=0
Refs: design-docs repo-structure/01-backend-layout.md 4.4, 6.3
BREAKING CHANGE: infra/fileserver/nginx, infra/fileserver/kubernetes, infra/jpa, infra/httpclient, infra/messaging, infra/notification/toxiproxy와 release.yml fileserver-pvc-certification job이 없어진다. docs/upgrade/2026-11-maturity-review.md B-50.
This commit is contained in:
@@ -25,8 +25,6 @@ on:
|
||||
- 'docs/registries/env-keys.yaml'
|
||||
- 'src/Dockerfile'
|
||||
- 'docker-compose.yml'
|
||||
- 'infra/fileserver/nginx/**'
|
||||
- 'infra/fileserver/kubernetes/**'
|
||||
- 'infra/fileserver/nfs/**'
|
||||
- '.github/workflows/fileserver-pr.yml'
|
||||
# Every Gradle job here installs its toolchain through this composite action, so a change to
|
||||
|
||||
@@ -123,7 +123,6 @@ jobs:
|
||||
'^src/config/architecture/modules\.json$' \
|
||||
'^docs/jpa/' \
|
||||
'^docs/adr/ADR-JPA-' \
|
||||
'^infra/jpa/' \
|
||||
"${common}"
|
||||
|
||||
# The servlet system contract on both containers the template supports (Tomcat, Jetty). Real
|
||||
|
||||
@@ -326,27 +326,6 @@ jobs:
|
||||
:composition:fileserver-platform:test --tests '*FileserverDocumentationCoverageTest'
|
||||
--stacktrace
|
||||
|
||||
fileserver-pvc-certification:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 45
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
# This job checks the manifest, and only the manifest; it applies nothing to a cluster. The
|
||||
# cluster result comes from an operator running infra/fileserver/kubernetes/
|
||||
# pvc-certification-job.yaml and recording it in docs/fileserver/storage-certification.md,
|
||||
# where the absence of a cluster result is stated rather than hidden behind a green check.
|
||||
- name: Check the certification manifest still says what the claim depends on
|
||||
run: |
|
||||
set -euo pipefail
|
||||
manifest=infra/fileserver/kubernetes/pvc-certification-job.yaml
|
||||
test -f "$manifest"
|
||||
grep -q 'kind: PersistentVolumeClaim' "$manifest"
|
||||
grep -q 'kind: Job' "$manifest"
|
||||
# ReadWriteMany is explicitly not claimed; a manifest that quietly widened the access
|
||||
# mode would certify a topology the support matrix says is uncertified.
|
||||
grep -q 'ReadWriteOnce' "$manifest"
|
||||
! grep -q 'ReadWriteMany' "$manifest"
|
||||
|
||||
fileserver-sensitive-telemetry-scan:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
@@ -372,7 +351,6 @@ jobs:
|
||||
- jpa-registry-and-docs
|
||||
- fileserver-full-verification
|
||||
- fileserver-documentation-gate
|
||||
- fileserver-pvc-certification
|
||||
- fileserver-sensitive-telemetry-scan
|
||||
# Job-level, because a job that declares `permissions:` replaces the workflow set entirely: this
|
||||
# job and app-image-signing are the only ones that write anything anywhere, and
|
||||
|
||||
@@ -60,12 +60,10 @@ GitHub Actions 워크플로는 `kubectl apply`, `helm upgrade`, `argocd app sync
|
||||
| Argo CD Application 정의 | **없음.** GitOps 저장소에 둘 예정 |
|
||||
| CI에서의 클러스터 접근 | 없음 — 유일했던 `kubectl apply`는 제거됨 |
|
||||
|
||||
`release.yml`의 fileserver certification 잡(`fileserver-pvc-certification` 등, 예전
|
||||
`fileserver-certification.yml`)은 예외처럼 보이지만 아니다. PVC 매니페스트가 여전히 ReadWriteOnce를
|
||||
선언하는지 **파일만** 확인하고, 클러스터에는 아무것도 적용하지 않는다. 실제 클러스터에서의 인증은
|
||||
운영자가 `infra/fileserver/kubernetes/pvc-certification-job.yaml`을 직접 실행하고
|
||||
`docs/fileserver/storage-certification.md`에 기록한다. 잡 이름이 "release"가 아니라 "certification"인
|
||||
이유가 이것이다 — 이 잡은 릴리스하지 않는다.
|
||||
PVC 매니페스트와 그 파일을 검사하던 `release.yml` 잡(`fileserver-pvc-certification`)은 2026-11-07에
|
||||
지웠다(소유자 결정: Kubernetes·프록시 설정은 이 repo 밖). 클러스터 인증은 배포하는 쪽이
|
||||
`docs/fileserver/storage-certification.md` 절차로 하고, volume 조건은 `docs/fileserver/operations.md`
|
||||
「운영 환경이 지켜야 할 조건」에 있다.
|
||||
|
||||
## 규칙
|
||||
|
||||
|
||||
@@ -83,13 +83,13 @@ The volume was remounted somewhere the probe can no longer prove a required capa
|
||||
application refuses traffic rather than serving from storage it cannot publish to atomically.
|
||||
|
||||
```bash
|
||||
kubectl apply -f infra/fileserver/kubernetes/pvc-certification-job.yaml
|
||||
kubectl logs job/fileserver-pvc-certification
|
||||
# staging과 content가 같은 파일 저장소(같은 장치 번호)인지 pod 안에서 본다
|
||||
kubectl exec <pod> -- stat -c %d /var/lib/backend/files/staging /var/lib/backend/files/content
|
||||
```
|
||||
|
||||
Compare the printed tuple with the certified one in `docs/fileserver/storage-certification.md`. A
|
||||
mismatch in CSI driver, StorageClass, access mode, or mount options is the cause; the certification
|
||||
does not carry across it.
|
||||
`docs/fileserver/storage-certification.md`의 인증 절차로 지금 volume의 묶음(CSI driver, StorageClass,
|
||||
접근 모드, backend, mount 옵션)을 다시 적고, 인증한 묶음과 비교한다. 하나라도 다르면 그것이 원인이다.
|
||||
인증은 그 차이를 넘어 옮겨지지 않는다.
|
||||
|
||||
## Nginx delegation failure
|
||||
|
||||
@@ -97,9 +97,9 @@ does not carry across it.
|
||||
|
||||
The internal location is misconfigured, so the proxy cannot resolve the redirect it was handed.
|
||||
|
||||
프록시 설정의 내부 location(기본 `/__files/`)이 아래 「운영 환경이 지켜야 할 조건」을 지키는지 본다.
|
||||
|
||||
```bash
|
||||
# The internal prefix must resolve to the content root and must be marked `internal`.
|
||||
grep -A5 '__files' infra/fileserver/nginx/nginx.conf
|
||||
curl -s $ADMIN/internal/fileserver/capabilities | jq '.capabilities.delegatedDownload'
|
||||
```
|
||||
|
||||
@@ -110,6 +110,32 @@ slower but correct.
|
||||
app.fileserver-platform.nginx.enabled=false
|
||||
```
|
||||
|
||||
## 운영 환경이 지켜야 할 조건
|
||||
|
||||
이 repo는 프록시 설정 파일과 Kubernetes 매니페스트를 두지 않는다(2026-11-07 소유자 결정). 그 파일은 서비스를
|
||||
배포하는 쪽의 인프라 repo가 갖는다. 그 파일이 지켜야 할 조건은 아래다.
|
||||
|
||||
**프런트 프록시(nginx `X-Accel-Redirect` 위임)** — `app.fileserver-platform.nginx.enabled=true`일 때
|
||||
|
||||
1. 내부 location(`app.fileserver-platform.nginx.internal-prefix`, 기본 `/__files/`)은 `internal`이다. 클라이언트가
|
||||
그 경로를 직접 부르면 404이고 content 폴더에 닿지 않는다. 애플리케이션이 준 내부 redirect로만 닿는다.
|
||||
2. 그 location의 `alias`는 저장 루트의 content 폴더다(기본 `/var/lib/backend/files/content/`). 애플리케이션은
|
||||
절대 경로를 내보내지 않고 내부 접두사 아래 상대 URI만 내보낸다. 경로가 실제 위치가 되는 곳은 이 `alias`뿐이다.
|
||||
3. 앱으로 넘기는 요청에서 클라이언트가 보낸 `X-Accel-Redirect` 헤더를 지운다. 남기면 호출자가 임의의 내부
|
||||
객체를 가리킬 수 있다.
|
||||
4. 업로드는 스트리밍으로 넘긴다(`proxy_request_buffering off`, 본문 크기 제한은 애플리케이션이 정하므로 프록시는
|
||||
막지 않는다). 프록시가 큰 본문을 디스크에 버퍼링하면 쓰기가 두 번 일어난다.
|
||||
5. 내부 location 응답에 `X-Content-Type-Options: nosniff`를 붙이고, 앱이 정한 `Content-Disposition`·
|
||||
`Cache-Control`·`ETag`를 그대로 넘긴다. 올라온 내용이 자기 형식을 스스로 정하게 두지 않는다.
|
||||
|
||||
**Kubernetes 저장 volume**
|
||||
|
||||
1. PersistentVolumeClaim을 저장 루트(`/var/lib/backend/files`)에 마운트하고, 접근 모드는 `ReadWriteOnce`다.
|
||||
`ReadWriteMany`(여러 노드의 동시 쓰기)는 인증하지 않았다(`support-matrix.md`).
|
||||
2. pod `securityContext.fsGroup`을 이미지의 앱 그룹으로 둔다. 그래야 앱 계정이 volume에 쓸 수 있다.
|
||||
3. 그 volume이 `storage-certification.md`의 인증 항목(같은 파일 저장소, 원자적 rename, `O_EXCL` 생성)을
|
||||
통과해야 한다. 기동 때 `FileserverStartupValidator`도 같은 probe를 다시 돌린다.
|
||||
|
||||
## Cleanup backlog
|
||||
|
||||
**Signal** — `fileserver.cleanup{result="deferred"}` rising, or reclaimed bytes flat while deletes
|
||||
|
||||
@@ -19,12 +19,15 @@ certification that does not name all five is not transferable.
|
||||
|
||||
## Running the certification
|
||||
|
||||
```bash
|
||||
kubectl apply -f infra/fileserver/kubernetes/pvc-certification-job.yaml
|
||||
kubectl logs job/fileserver-pvc-certification
|
||||
```
|
||||
이 repo는 인증 job 매니페스트를 두지 않는다(2026-11-07 소유자 결정). 배포하는 쪽이 대상 volume을 저장
|
||||
루트(`/var/lib/backend/files`)에 마운트한 일회성 pod에서 아래를 차례로 확인한다.
|
||||
|
||||
The job writes a machine-readable result to the claim itself, carrying the full tuple:
|
||||
1. `staging`과 `content` 폴더를 만들고, `staging`의 파일을 `content`로 `mv`해 원자적 rename이 되는지 본다.
|
||||
2. 두 폴더의 장치 번호(`stat -c %d`)가 같은지 본다. 다르면 rename이 복사가 된다.
|
||||
3. `set -o noclobber` 상태에서 같은 파일을 두 번 만들어 `O_EXCL` 생성이 막히는지 본다.
|
||||
4. 결과와 함께 묶음(Kubernetes 버전, CSI driver, StorageClass, 접근 모드, backend, mount 옵션)을 기록한다.
|
||||
|
||||
결과는 묶음 전체를 담은 기계가 읽는 형식으로 그 volume에 남긴다:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -40,8 +43,7 @@ The job writes a machine-readable result to the claim itself, carrying the full
|
||||
}
|
||||
```
|
||||
|
||||
The job fails closed: a volume whose staging and content areas are on different stores is not
|
||||
certified, because its publish would silently degrade to a copy.
|
||||
2번이 실패하면 인증하지 않는다. staging과 content가 다른 저장소인 volume은 게시가 소리 없이 복사로 바뀐다.
|
||||
|
||||
## Network filesystems
|
||||
|
||||
|
||||
@@ -29,7 +29,6 @@ that does not exist, so a level can never outlive the test that justified it.
|
||||
| NFSv4 ambiguity handling | Beta | `fileserver-nfs-ambiguity` |
|
||||
| Large-file and slow-client performance | Beta | `fileserver-large-file-performance` |
|
||||
| Multi-instance writer lease | Beta | `fileserver-multi-instance-lease` |
|
||||
| Kubernetes ReadWriteOnce PVC | Limited | `fileserver-pvc-certification` (manifest checks in CI; cluster run is operator-driven) |
|
||||
| Nginx `X-Accel-Redirect` delegation | Limited | `fileserver-http-contract` |
|
||||
| Telemetry sensitive-data suppression | Stable | `fileserver-sensitive-telemetry-scan` |
|
||||
| Documentation and support-claim coverage | Stable | `fileserver-documentation-gate` |
|
||||
@@ -46,10 +45,10 @@ leaf puts `DispatcherServlet` on the classpath, so Boot resolves SERVLET.
|
||||
|
||||
These have no job, and therefore no claim:
|
||||
|
||||
- An automated Kubernetes cluster result. `fileserver-pvc-certification` validates the manifest on
|
||||
every release and applies it only when a release cluster is configured; without one it warns and
|
||||
records that nothing was certified. The cluster tuple is produced by an operator and read from
|
||||
[storage-certification.md](storage-certification.md).
|
||||
- Kubernetes PVC(ReadWriteOnce 포함). 이 repo는 클러스터 매니페스트와 그것을 검사하던 release job을
|
||||
2026-11-07에 지웠다. volume이 지켜야 할 조건은 [operations.md](operations.md) 「운영 환경이 지켜야 할
|
||||
조건」, 인증 절차는 [storage-certification.md](storage-certification.md)다. 클러스터 결과는 배포하는 쪽이
|
||||
만든다.
|
||||
|
||||
- Kubernetes ReadWriteMany PVC. Concurrent writers across nodes are not certified.
|
||||
- Windows NTFS as a production storage root. The filename policy strips the characters NTFS
|
||||
|
||||
@@ -100,7 +100,7 @@ Docker-dependent lanes fail closed rather than skipping, matching the existing
|
||||
| Hibernate ORM 7.4 is the Stable provider | Boot 4.0.0 resolves `org.hibernate.orm:hibernate-core:7.1.8.Final` | The *declared* Stable provider baseline of the design stays 7.4 in `HibernateProviderPolicy`; the runtime provider version is read from Hibernate itself and reported. The collection-fetch-pagination gate runs against whatever provider the BOM resolves, and `HibernateProviderPolicy.driftsFromDeclaredBaseline()` makes the difference visible instead of hiding it behind a green check. |
|
||||
| PostgreSQL 16·17·18 Stable matrix | This leaf's existing evidence image is `postgres:16-alpine` | `PostgreSqlVersion` declares exactly PG 16, 17, 18. The default lane runs the repository's existing 16 image; 17 and 18 are selected by `-Pjpa.matrix.versions=16,17,18`, and an unknown or empty selection is an error rather than a skip. |
|
||||
| `settings.gradle.kts` module registration | Fail-closed 19-leaf registry | No registry change: leaf identity, Gradle path, allowed dependencies, and runtime memberships are unchanged. |
|
||||
| `infra/jpa/{postgres,roles,toxiproxy}` | Repository already owns `infra/` | Created at the same repository-relative paths. |
|
||||
| `infra/jpa/{postgres,roles,toxiproxy}` | Repository already owns `infra/` | 2026-11-07에 지웠다(쓰는 곳이 없거나 운영 인프라 파일). 운영 DB 조건은 `docs/jpa/security.md`로 옮겼다. |
|
||||
| `docs/jpa/**`, `docs/adr/ADR-JPA-*`, `.github/workflows/jpa-*.yml` | Repository already owns `docs/` and `.github/workflows/` | Created at the same repository-relative paths. |
|
||||
| release blocking aggregate | `jpaReleaseQualification` (persistence-jpa `build.gradle`) over `config/jpa/release-registry.json`, run per PostgreSQL major by the `jpa-release-gate` job in `.github/workflows/release.yml` | The registry names the blocking lanes; Gradle defines how each lane runs; CI only schedules the matrix. | |
|
||||
| Per-task `git add` + `git commit` | `AGENTS.md`: commit policy is `human-only`; agents do not stage, commit, amend, or push | Implementation is delivered unstaged. This is the only plan step intentionally not executed, and it is recorded here. |
|
||||
|
||||
@@ -91,6 +91,6 @@ drop an index another instance was about to finish building.
|
||||
Startup refused because the runtime credential holds `CREATE`, or `search_path` contains an
|
||||
unapproved schema.
|
||||
|
||||
This is not a false positive to be worked around. Re-provision from
|
||||
`infra/jpa/roles/runtime-roles.sql`; the application's credential having DDL is the condition that
|
||||
makes every other schema guarantee unenforceable.
|
||||
This is not a false positive to be worked around. `docs/jpa/security.md` 「역할과 권한 — 운영 DB가
|
||||
갖춰야 할 것」대로 권한을 다시 맞춘다. 애플리케이션 자격 증명이 DDL을 가지면 다른 schema 보장을 하나도
|
||||
지킬 수 없다.
|
||||
|
||||
+35
-1
@@ -14,7 +14,41 @@ The separation is what makes "Flyway owns schema change" enforceable rather than
|
||||
the application's own credential cannot execute DDL, then no code path, no library, and no injected
|
||||
statement can alter the schema at runtime, regardless of what the application intended.
|
||||
|
||||
`infra/jpa/roles/runtime-roles.sql` provisions them.
|
||||
### 역할과 권한 — 운영 DB가 갖춰야 할 것
|
||||
|
||||
이 repo는 역할을 만드는 SQL 파일을 두지 않는다(2026-11-07 소유자 결정. 운영 DB 준비는 배포하는 쪽의
|
||||
일이다). 운영 DB는 아래 조건을 지켜야 한다. 기동 때 `PostgreSqlRuntimeRoleVerifier`가 그중 런타임 역할의
|
||||
`CREATE` 권한과 `search_path`를 다시 본다.
|
||||
|
||||
1. 애플리케이션 schema(예: `app`)는 migration 역할이 소유한다. 런타임 역할이 소유하지 않는다.
|
||||
2. `PUBLIC`에서 데이터베이스 권한 전체와 `public` schema의 `CREATE`를 거둔다. PostgreSQL 15 전에는
|
||||
`PUBLIC`이 `public` schema에 `CREATE`를 가져, 권한 없는 역할이 `search_path`로 진짜 객체를 가리는
|
||||
객체를 만들 수 있었다.
|
||||
3. 런타임 역할에는 `CONNECT`, 애플리케이션 schema의 `USAGE`, 그 schema 테이블의
|
||||
`SELECT`·`INSERT`·`UPDATE`·`DELETE`, sequence의 `USAGE`·`SELECT`만 준다.
|
||||
4. migration 역할이 앞으로 만들 테이블·sequence에도 같은 권한이 가도록 `ALTER DEFAULT PRIVILEGES`를
|
||||
건다. 빠뜨리면 새 테이블을 더한 첫 배포가 런타임 권한 오류로 실패한다.
|
||||
5. 런타임 역할에서 schema와 데이터베이스의 `CREATE`를 명시적으로 거둔다. 기동 검사가 보는 두 권한이다.
|
||||
6. 관리 역할(COPY·backfill·정비용)은 런타임 역할과 같은 행 권한을 갖되 schema를 소유하지 않는다. 요청
|
||||
경로는 이 역할을 쓰지 않는다.
|
||||
7. 런타임·관리 역할의 `search_path`를 `app, pg_catalog`처럼 고정한다.
|
||||
|
||||
비밀번호는 배포 환경의 비밀 저장소에서 넣는다. repo에 두지 않는다.
|
||||
|
||||
### 서버 설정 — 플랫폼의 보장이 기대는 것
|
||||
|
||||
계약 테스트는 자기 컨테이너를 띄우므로(`PostgreSqlContainerFactory`) 이 설정이 필요 없다. 운영 DB에서
|
||||
플랫폼의 보장이 성립하려면 아래 설정이 있어야 한다. 값은 출발점이다. 가장 느린 정상 쿼리를 재 보고 정한다.
|
||||
|
||||
| 설정 | 출발 값 | 왜 필요한가 |
|
||||
| --- | --- | --- |
|
||||
| `statement_timeout` | `30s` | 트랜잭션 안의 문장 하나가 요청보다 오래 사는 것을 막는 마지막 상한 |
|
||||
| `idle_in_transaction_session_timeout` | `60s` | 열어 둔 채 쉬는 트랜잭션이 잠금과 snapshot을 붙잡아 쓰기와 vacuum을 막는 시간을 줄인다 |
|
||||
| `lock_timeout` | `10s` | `PostgreSqlLockOptions`의 요청별 잠금 상한 아래에 까는 바닥 |
|
||||
| `max_connections` | 배포 수에 맞춤 | 모든 인스턴스의 pool 합과, `REQUIRES_NEW`가 두 번째 연결을 잡는 경우를 함께 견딘다 |
|
||||
| `default_transaction_isolation` | `read committed` | 바꾸면 격리 수준을 고르지 않은 모든 트랜잭션이 조용히 달라진다 |
|
||||
|
||||
확장(extension)은 필요 없다. JSONB, 배열, 범위, `SKIP LOCKED`, `ON CONFLICT`는 모두 PostgreSQL 본체 기능이다.
|
||||
|
||||
## Startup verification
|
||||
|
||||
|
||||
@@ -21,6 +21,10 @@ runtime이 admin 자격 증명을 아예 보유하지 않으므로, 침해된 ha
|
||||
- broker authentication 활성
|
||||
- topology auto-create 비활성
|
||||
|
||||
broker 인증서는 `subjectAltName`에 접속 이름을 가져야 한다. hostname verification은 SAN을 보므로, SAN이
|
||||
없는 인증서는 실패하는 것이 맞다. 검사를 끄지 않는다. 키와 인증서는 배포 환경의 PKI가 발급해 실행 때
|
||||
마운트하고, repo에 두지 않는다.
|
||||
|
||||
Kafka는 추가로 `enable.idempotence=true`, `acks=all`,
|
||||
`max.in.flight.requests.per.connection <= 5`, consumer auto-commit 금지.
|
||||
|
||||
|
||||
@@ -131,7 +131,8 @@
|
||||
|
||||
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|
||||
|---|---|---|---|---|
|
||||
| B-49 | 샘플 모듈 삭제: `src/sample-portfolio`, `src/Dockerfile.sample`, registry `sample-portfolio` 행, 루트 `build.gradle`의 샘플 태스크·단계(`sampleWebContractCheck`, `:sample-portfolio:*` 의존, strict lane 단계 `:sample-portfolio:check`), `ci-quality-gates.yml`의 `sample-portfolio` job, `SampleRuntimeDefaultsContractTest`, spotbugs 제외의 샘플 클래스. 샘플에만 있던 검사(OpenAPI 스냅숏 `openapiCheckSnapshot`, Date 헤더, 가상 스레드 MDC 전파)도 함께 없어졌다 | 샘플을 고쳐 쓰던 서비스: 병합 때 "수정 대 삭제" 충돌. 샘플을 이미 지운 서비스: 충돌 없음 | 샘플을 이미 지웠으면 할 일 없음. 고쳐 쓰고 있으면 자기 leaf로 옮기고 registry 행·빌드 줄을 자기 것으로 둔다. 위 검사가 필요하면 자기 기능 leaf에 둔다 | 커밋 「샘플 모듈을 지운다」 |
|
||||
| B-49 | 샘플 모듈 삭제: `src/sample-portfolio`, `src/Dockerfile.sample`, registry `sample-portfolio` 행, 루트 `build.gradle`의 샘플 태스크·단계(`sampleWebContractCheck`, `:sample-portfolio:*` 의존, strict lane 단계 `:sample-portfolio:check`), `ci-quality-gates.yml`의 `sample-portfolio` job, `SampleRuntimeDefaultsContractTest`, spotbugs 제외의 샘플 클래스. 샘플에만 있던 검사(OpenAPI 스냅숏 `openapiCheckSnapshot`, Date 헤더, 가상 스레드 MDC 전파)도 함께 없어졌다 | 샘플을 고쳐 쓰던 서비스: 병합 때 "수정 대 삭제" 충돌. 샘플을 이미 지운 서비스: 충돌 없음 | 샘플을 이미 지웠으면 할 일 없음. 고쳐 쓰고 있으면 자기 leaf로 옮기고 registry 행·빌드 줄을 자기 것으로 둔다. 위 검사가 필요하면 자기 기능 leaf에 둔다 | `ab5982e9` |
|
||||
| B-50 | `infra/`에서 15개 삭제. 쓰는 곳이 없던 12개(`infra/httpclient/**`, `infra/jpa/postgres/README.md`, `infra/jpa/toxiproxy/`, `infra/messaging/{kafka,postgres,toxiproxy,tls}/`, `infra/notification/toxiproxy/`)와 운영 인프라 셋(`infra/fileserver/nginx/nginx.conf`, `infra/fileserver/kubernetes/pvc-certification-job.yaml`, `infra/jpa/roles/runtime-roles.sql`). `release.yml`의 `fileserver-pvc-certification` job도 지웠고, fileserver 지원 표에서 "Kubernetes ReadWriteOnce PVC — Limited" 주장을 「주장하지 않음」으로 옮겼다 | 그 파일을 배포에 쓰던 서비스: 병합이 파일을 지운다. 고쳐 쓰던 서비스: "수정 대 삭제" 충돌 | 그 파일은 자기 인프라 repo로 옮긴다. 지켜야 할 조건은 `docs/fileserver/operations.md` 「운영 환경이 지켜야 할 조건」, `docs/fileserver/storage-certification.md`, `docs/jpa/security.md` 「역할과 권한」·「서버 설정」에 있다 | 커밋 「쓰지 않는 파일과 운영 인프라 파일을 지운다」 |
|
||||
|
||||
## 4. DB 마이그레이션
|
||||
|
||||
|
||||
@@ -74,6 +74,7 @@
|
||||
| 생성 명령 | JPA adapter를 만들지 않음(서비스 전용 persistence leaf가 기본), 생성된 쓰기 API는 역할 매핑 전 403 | 위임 | `1101` 15절(r2-10) |
|
||||
| `@SystemInvoked` | bean으로 등록돼 있으면 기동 실패, inbound adapter가 직접 부르지 못하게 ArchUnit | 위임 | `1103` 4절(RR-01-02) |
|
||||
| 시스템 호출 경로 | 사용자가 닿는 전송(web·GraphQL·gRPC·WebSocket)만 `@SystemInvoked`에 닿지 못한다. 메시지 소비자·스케줄러는 `@SystemCaller(reason)` 표시로 허용 | 위임 | `1103` 9.1절(RR-01-12), 10절 r5-b |
|
||||
| 인프라 실행 파일 | nginx 설정, Kubernetes PVC job, DB 역할 SQL은 이 repo에서 지우고, 기능이 운영 환경에 요구하는 조건만 그 기능 문서에 적는다. 아무도 쓰지 않는 `infra/` 파일도 지운다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.3절 |
|
||||
| 샘플 모듈 | `src/sample-portfolio`와 `src/Dockerfile.sample`을 폴더째 지운다. 역할은 옮기지 않는다. 샘플 안에만 있던 템플릿 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC)도 함께 지운다. 예시는 매뉴얼과 생성 명령 출력이 맡는다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.2절 |
|
||||
|
||||
### 2.3 계약·오류
|
||||
|
||||
@@ -14,8 +14,8 @@
|
||||
#
|
||||
# The volume is a named volume, not a tmpfs and not the read-only root: published content must
|
||||
# outlive the container that wrote it. Back it with real storage in any deployment that keeps files.
|
||||
# Kubernetes does the same job with a PersistentVolumeClaim and the pod's fsGroup
|
||||
# (infra/fileserver/kubernetes/pvc-certification-job.yaml).
|
||||
# Kubernetes does the same job with a PersistentVolumeClaim and the pod's fsGroup; the conditions
|
||||
# are in docs/fileserver/operations.md.
|
||||
#
|
||||
# Ownership. The application runs as the image's non-root `app` account (src/Dockerfile). Docker
|
||||
# seeds a fresh named volume's owner from the image directory at the mount point, and the image has
|
||||
|
||||
@@ -1,127 +0,0 @@
|
||||
# Storage certification job.
|
||||
#
|
||||
# A PersistentVolumeClaim is not a filesystem contract. Whether an atomic rename, a same-file-store
|
||||
# guarantee, or symlink refusal actually holds depends on the CSI driver, the StorageClass, the
|
||||
# access mode, the backend, and the mount options — so this job records all five alongside the probe
|
||||
# result. A certification without that tuple is not transferable to another cluster.
|
||||
#
|
||||
# The job writes a machine-readable result to the claim itself so the evidence lives with the volume
|
||||
# it describes.
|
||||
#
|
||||
# kubectl apply -f infra/fileserver/kubernetes/pvc-certification-job.yaml
|
||||
# kubectl logs job/fileserver-pvc-certification
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: PersistentVolumeClaim
|
||||
metadata:
|
||||
name: fileserver-certification
|
||||
labels:
|
||||
app.kubernetes.io/name: fileserver
|
||||
app.kubernetes.io/component: certification
|
||||
spec:
|
||||
accessModes:
|
||||
- ReadWriteOnce
|
||||
resources:
|
||||
requests:
|
||||
storage: 1Gi
|
||||
# Left unset on purpose: the certification is only meaningful for the class it actually ran on,
|
||||
# so the operator names it explicitly rather than inheriting a cluster default.
|
||||
storageClassName: ""
|
||||
---
|
||||
apiVersion: batch/v1
|
||||
kind: Job
|
||||
metadata:
|
||||
name: fileserver-pvc-certification
|
||||
labels:
|
||||
app.kubernetes.io/name: fileserver
|
||||
app.kubernetes.io/component: certification
|
||||
spec:
|
||||
backoffLimit: 0
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app.kubernetes.io/name: fileserver
|
||||
app.kubernetes.io/component: certification
|
||||
spec:
|
||||
restartPolicy: Never
|
||||
securityContext:
|
||||
runAsNonRoot: true
|
||||
runAsUser: 10001
|
||||
fsGroup: 10001
|
||||
containers:
|
||||
- name: certify
|
||||
image: eclipse-temurin:21-jdk
|
||||
env:
|
||||
- name: FILESERVER_STORAGE_ROOT
|
||||
value: /var/lib/backend/files
|
||||
- name: KUBERNETES_VERSION
|
||||
valueFrom:
|
||||
fieldRef:
|
||||
fieldPath: metadata.annotations['certification.fileserver/kubernetes-version']
|
||||
- name: CSI_DRIVER
|
||||
valueFrom:
|
||||
fieldRef:
|
||||
fieldPath: metadata.annotations['certification.fileserver/csi-driver']
|
||||
- name: STORAGE_CLASS
|
||||
valueFrom:
|
||||
fieldRef:
|
||||
fieldPath: metadata.annotations['certification.fileserver/storage-class']
|
||||
- name: ACCESS_MODE
|
||||
value: ReadWriteOnce
|
||||
command:
|
||||
- /bin/bash
|
||||
- -c
|
||||
- |
|
||||
set -euo pipefail
|
||||
ROOT="${FILESERVER_STORAGE_ROOT}"
|
||||
mkdir -p "${ROOT}/staging" "${ROOT}/content"
|
||||
|
||||
# Atomic rename within one file store is the property the publish path depends on.
|
||||
echo probe > "${ROOT}/staging/probe"
|
||||
if mv "${ROOT}/staging/probe" "${ROOT}/content/probe" 2>/dev/null; then
|
||||
ATOMIC_MOVE=true
|
||||
else
|
||||
ATOMIC_MOVE=false
|
||||
fi
|
||||
|
||||
# Same device means a rename is a metadata operation rather than a copy.
|
||||
STAGING_DEV=$(stat -c %d "${ROOT}/staging")
|
||||
CONTENT_DEV=$(stat -c %d "${ROOT}/content")
|
||||
[ "${STAGING_DEV}" = "${CONTENT_DEV}" ] && SAME_STORE=true || SAME_STORE=false
|
||||
|
||||
# O_EXCL create is what makes a publish create-only rather than an overwrite.
|
||||
if (set -o noclobber; echo x > "${ROOT}/content/excl") 2>/dev/null; then
|
||||
ATOMIC_CREATE=true
|
||||
else
|
||||
ATOMIC_CREATE=false
|
||||
fi
|
||||
|
||||
cat > "${ROOT}/certification-result.json" <<RESULT
|
||||
{
|
||||
"kubernetesVersion": "${KUBERNETES_VERSION:-unknown}",
|
||||
"csiDriver": "${CSI_DRIVER:-unknown}",
|
||||
"storageClass": "${STORAGE_CLASS:-unknown}",
|
||||
"accessMode": "${ACCESS_MODE}",
|
||||
"backend": "$(stat -f -c %T "${ROOT}")",
|
||||
"mountOptions": "$(findmnt -no OPTIONS --target "${ROOT}" || echo unknown)",
|
||||
"atomicMove": ${ATOMIC_MOVE},
|
||||
"sameFileStore": ${SAME_STORE},
|
||||
"atomicCreate": ${ATOMIC_CREATE}
|
||||
}
|
||||
RESULT
|
||||
cat "${ROOT}/certification-result.json"
|
||||
|
||||
# Fail closed: a volume that cannot publish atomically must not be certified silently.
|
||||
[ "${SAME_STORE}" = "true" ] || { echo "staging and content are on different stores"; exit 1; }
|
||||
volumeMounts:
|
||||
- name: storage
|
||||
mountPath: /var/lib/backend/files
|
||||
securityContext:
|
||||
allowPrivilegeEscalation: false
|
||||
readOnlyRootFilesystem: true
|
||||
capabilities:
|
||||
drop: ["ALL"]
|
||||
volumes:
|
||||
- name: storage
|
||||
persistentVolumeClaim:
|
||||
claimName: fileserver-certification
|
||||
@@ -1,67 +0,0 @@
|
||||
# Fileserver front-proxy configuration.
|
||||
#
|
||||
# The application authorizes every download and then hands the transfer to Nginx with
|
||||
# X-Accel-Redirect. Two properties make that safe, and both are enforced here rather than assumed:
|
||||
#
|
||||
# 1. /__files/ is `internal`, so it is reachable ONLY through an internal redirect the application
|
||||
# issued. A direct request from a client returns 404 and never touches the content root.
|
||||
# 2. The application never emits an absolute path. It emits a relative URI below /__files/, and
|
||||
# the alias below is the only place that prefix becomes a filesystem location.
|
||||
#
|
||||
# Keep `alias` in sync with the storage root's content directory. A mismatch is a startup
|
||||
# misconfiguration, not a runtime fallback: the application's startup validator checks that the
|
||||
# internal mapping was proven before it accepts traffic.
|
||||
|
||||
worker_processes auto;
|
||||
|
||||
events {
|
||||
worker_connections 4096;
|
||||
}
|
||||
|
||||
http {
|
||||
include mime.types;
|
||||
default_type application/octet-stream;
|
||||
|
||||
sendfile on;
|
||||
sendfile_max_chunk 2m;
|
||||
tcp_nopush on;
|
||||
keepalive_timeout 65;
|
||||
|
||||
# Uploads stream through to the application; buffering a large body to disk here would double
|
||||
# the write and defeat the streaming upload path.
|
||||
proxy_request_buffering off;
|
||||
client_max_body_size 0;
|
||||
|
||||
server {
|
||||
listen 8080;
|
||||
|
||||
# Public API. Everything, including download authorization, is decided by the application.
|
||||
location / {
|
||||
proxy_pass http://app:8081;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
|
||||
# The application must never see a client-supplied delegation header: it would let a
|
||||
# caller name an arbitrary internal object.
|
||||
proxy_set_header X-Accel-Redirect "";
|
||||
}
|
||||
|
||||
# Internal transfer location. Not reachable from outside; see property (1) above.
|
||||
location /__files/ {
|
||||
internal;
|
||||
alias /srv/files/content/;
|
||||
|
||||
sendfile on;
|
||||
sendfile_max_chunk 2m;
|
||||
|
||||
# Uploaded content is never trusted to describe itself.
|
||||
add_header X-Content-Type-Options nosniff always;
|
||||
add_header Content-Disposition $upstream_http_content_disposition always;
|
||||
add_header Cache-Control $upstream_http_cache_control always;
|
||||
add_header ETag $upstream_http_etag always;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,12 +0,0 @@
|
||||
# HTTP Client Platform — local test topology
|
||||
|
||||
The suites drive these dependencies through Testcontainers and in-process fixtures, so nothing here
|
||||
is required to run `./gradlew :adapter:outbound:httpclient:test`. These files exist for the nightly
|
||||
lane and for reproducing a failure locally with the same images and ports CI uses.
|
||||
|
||||
| Directory | Purpose | Used by |
|
||||
|---|---|---|
|
||||
| `toxiproxy/` | TCP fault injection (latency, reset, bandwidth) | `httpClientFailureInjectionTest` |
|
||||
| `tls/` | how the TLS and mTLS material is produced | TLS and mTLS suites |
|
||||
| `proxy/` | forward proxy with CONNECT and proxy authentication | proxy contract suite |
|
||||
| `oauth2/` | token endpoint behaviour under contention | OAuth2 suites |
|
||||
@@ -1,12 +0,0 @@
|
||||
# OAuth2 fixture
|
||||
|
||||
`OAuth2Fixture` exposes a token endpoint backed by the same deterministic fixture server as the rest
|
||||
of the suite.
|
||||
|
||||
It counts token requests, which is what makes design §20.3's single-flight guarantee provable rather
|
||||
than assumed: a hundred genuinely concurrent callers must produce exactly one token request. It can
|
||||
also issue rotating token values, so a stale cached token is detectable, and queue a failure status
|
||||
to exercise the refresh-failure path.
|
||||
|
||||
The token endpoint is configured as its own Named Client Profile, separate from the upstream it
|
||||
issues tokens for.
|
||||
@@ -1,12 +0,0 @@
|
||||
# Forward proxy fixture
|
||||
|
||||
`ProxyFixture` runs an in-process forward proxy so the proxy lane needs no external service.
|
||||
|
||||
| Factory | Behaviour |
|
||||
|---|---|
|
||||
| `ProxyFixture.openProxy()` | accepts CONNECT and tunnels to the target |
|
||||
| `ProxyFixture.authenticatingProxy(user, password)` | answers `407` until `Proxy-Authorization` matches |
|
||||
|
||||
The fixture records every request line and every `Proxy-Authorization` value it saw, which is what
|
||||
lets the suite prove design §24.3: proxy credentials never appear on the target request, and a proxy
|
||||
CONNECT failure is reported as `HttpProxyException` rather than as a target TLS failure.
|
||||
@@ -1,16 +0,0 @@
|
||||
# TLS fixtures
|
||||
|
||||
Certificates are generated **in process** by `TlsFixture`, not checked in. A committed private key
|
||||
is a private key that leaks, and design §21.2 forbids key material in the repository.
|
||||
|
||||
`TlsFixture` produces, from a throwaway CA created per test run:
|
||||
|
||||
| Fixture | Purpose |
|
||||
|---|---|
|
||||
| `TlsFixture.trusted()` | a server certificate valid for the loopback host |
|
||||
| `TlsFixture.hostnameMismatch()` | a certificate whose SAN does not match the connection host |
|
||||
| `TlsFixture.expired()` | an already-expired certificate |
|
||||
| `clientHandshake(true)` | client key material for the mTLS lane |
|
||||
|
||||
All three failure cases must classify as permanent (design §21.3) — never retried, never downgraded
|
||||
to plaintext.
|
||||
@@ -1,17 +0,0 @@
|
||||
# Fault-injection topology for the HTTP Client Platform failure suite (design §28.1, §28.3).
|
||||
#
|
||||
# The suite normally drives Toxiproxy through Testcontainers. This compose file exists for the
|
||||
# nightly lane and for reproducing a failure locally with the exact same image and ports.
|
||||
services:
|
||||
toxiproxy:
|
||||
image: ghcr.io/shopify/toxiproxy:2.9.0
|
||||
container_name: httpclient-toxiproxy
|
||||
ports:
|
||||
- "8474:8474" # control API
|
||||
- "18080:18080" # proxied upstream: plaintext
|
||||
- "18443:18443" # proxied upstream: TLS
|
||||
healthcheck:
|
||||
test: ["CMD", "/toxiproxy-cli", "list"]
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 10
|
||||
@@ -1,39 +0,0 @@
|
||||
# infra/jpa/postgres
|
||||
|
||||
Server-side settings the JPA platform's contracts assume, and why each one matters.
|
||||
|
||||
The contract suites start their own containers through
|
||||
`dev.caskeleton.adapter.outbound.persistence.testkit.postgresql.PostgreSqlContainerFactory`, so
|
||||
nothing here is needed to run them. This directory records what a *deployed* PostgreSQL has to look
|
||||
like for the platform's guarantees to hold, because several of them are server settings rather than
|
||||
application code.
|
||||
|
||||
## Settings the platform depends on
|
||||
|
||||
| Setting | Why the platform cares |
|
||||
|---|---|
|
||||
| `statement_timeout` | The last bound on a runaway statement. The platform sets transaction timeouts, but a single statement inside a transaction can still outlive the request that asked for it. |
|
||||
| `idle_in_transaction_session_timeout` | An idle open transaction holds its locks and its snapshot indefinitely, which blocks writers and prevents vacuum. This is what turns "someone left a transaction open" into a bounded incident. |
|
||||
| `lock_timeout` | A cluster-wide floor under the per-request lock bounds in `PostgreSqlLockOptions`. |
|
||||
| `max_connections` | The number `app.jpa-platform.datasource.maximum-pool-size` must be sized against — across every instance, and allowing for `REQUIRES_NEW` taking a second connection while pinning the first. |
|
||||
| `default_transaction_isolation` | Left at `read committed`. The platform selects `repeatable read` or `serializable` per transaction profile; changing the default would silently change every transaction that did not ask. |
|
||||
|
||||
## Suggested baseline
|
||||
|
||||
```conf
|
||||
statement_timeout = '30s'
|
||||
idle_in_transaction_session_timeout = '60s'
|
||||
lock_timeout = '10s'
|
||||
default_transaction_isolation = 'read committed'
|
||||
```
|
||||
|
||||
These are starting points, not recommendations: the right `statement_timeout` depends on the
|
||||
slowest legitimate query in the application, and setting it below that turns a working report into
|
||||
an error. Measure before pinning.
|
||||
|
||||
## What is deliberately not configured here
|
||||
|
||||
- **Roles.** Credential separation lives in [`../roles/runtime-roles.sql`](../roles/runtime-roles.sql).
|
||||
- **Schema.** Flyway owns it (design §31). Nothing in this directory creates a table.
|
||||
- **Extensions.** The platform's PostgreSQL support — JSONB, arrays, ranges, `SKIP LOCKED`,
|
||||
`ON CONFLICT` — is all core PostgreSQL. No extension is required, and none should be assumed.
|
||||
@@ -1,54 +0,0 @@
|
||||
-- Runtime / migration / admin credential separation for the JPA persistence platform.
|
||||
-- Design §36; enforced at startup by PostgreSqlRuntimeRoleVerifier + DatabaseRolePolicy.
|
||||
--
|
||||
-- The separation is what makes "Flyway owns schema change" enforceable rather than aspirational.
|
||||
-- If the application's own credential cannot execute DDL, then no code path, no library, and no
|
||||
-- injected statement can alter the schema at runtime — regardless of what the application intended.
|
||||
--
|
||||
-- Run as a superuser once per database. Replace the placeholder passwords with values from the
|
||||
-- deployment's secret store; they are intentionally not committed.
|
||||
|
||||
-- 1. The schema the application owns. Owned by the migration role, not the runtime role.
|
||||
create schema if not exists app authorization app_migration;
|
||||
|
||||
-- 2. Roles.
|
||||
-- app_migration : owns the schema, applies Flyway migrations. DDL.
|
||||
-- app_runtime : the application's credential. DML only, no DDL, no CREATE.
|
||||
-- app_admin : J4 operations — COPY, backfill, maintenance. Never used by request paths.
|
||||
create role app_migration login password 'REPLACE_FROM_SECRET_STORE';
|
||||
create role app_runtime login password 'REPLACE_FROM_SECRET_STORE';
|
||||
create role app_admin login password 'REPLACE_FROM_SECRET_STORE';
|
||||
|
||||
-- 3. Revoke the PUBLIC grants that make the checks in DatabaseRolePolicy necessary.
|
||||
-- Before PostgreSQL 15, PUBLIC held CREATE on the public schema — which is how an unprivileged
|
||||
-- role ends up able to plant an object that shadows a real one through search_path.
|
||||
revoke all on database current_database() from public;
|
||||
revoke create on schema public from public;
|
||||
|
||||
-- 4. Runtime: read and write rows in the application schema. Nothing else.
|
||||
grant connect on database current_database() to app_runtime;
|
||||
grant usage on schema app to app_runtime;
|
||||
grant select, insert, update, delete on all tables in schema app to app_runtime;
|
||||
grant usage, select on all sequences in schema app to app_runtime;
|
||||
|
||||
-- Tables created by future migrations must inherit the same grants, or the first deployment after
|
||||
-- a new table silently fails at runtime with a permission error.
|
||||
alter default privileges for role app_migration in schema app
|
||||
grant select, insert, update, delete on tables to app_runtime;
|
||||
alter default privileges for role app_migration in schema app
|
||||
grant usage, select on sequences to app_runtime;
|
||||
|
||||
-- 5. Explicitly deny the two privileges the startup verifier checks for.
|
||||
revoke create on schema app from app_runtime;
|
||||
revoke create on database current_database() from app_runtime;
|
||||
|
||||
-- 6. Admin: bulk operations under an audited identity, still without schema ownership.
|
||||
grant connect on database current_database() to app_admin;
|
||||
grant usage on schema app to app_admin;
|
||||
grant select, insert, update, delete on all tables in schema app to app_admin;
|
||||
alter default privileges for role app_migration in schema app
|
||||
grant select, insert, update, delete on tables to app_admin;
|
||||
|
||||
-- 7. Pin the runtime search_path so an unqualified name cannot resolve anywhere unexpected.
|
||||
alter role app_runtime set search_path = app, pg_catalog;
|
||||
alter role app_admin set search_path = app, pg_catalog;
|
||||
@@ -1,43 +0,0 @@
|
||||
# Commit-ambiguity failure injection for the JPA platform (design §39).
|
||||
#
|
||||
# The suite needs a proxy rather than a kill switch because the scenario that matters cannot be
|
||||
# produced any other way. Stopping the container, killing the process, or closing the client socket
|
||||
# all break *before* the server commits — the easy case, where the transaction rolled back and the
|
||||
# use case may simply be re-run. The hard case is a commit the server completed whose
|
||||
# acknowledgement never came back, and it only exists if you can cut the return path while leaving
|
||||
# the forward path intact.
|
||||
#
|
||||
# That is what CommitAmbiguityProxy does with a downstream-only toxic, and it is the one scenario
|
||||
# that distinguishes a platform that reports completion-unknown from one that retries a write which
|
||||
# already succeeded.
|
||||
#
|
||||
# Ordinary contract runs use Testcontainers and do not need this file; it exists for reproducing a
|
||||
# failure scenario by hand.
|
||||
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:16-alpine
|
||||
environment:
|
||||
POSTGRES_DB: jpa_failure
|
||||
POSTGRES_USER: jpa_failure
|
||||
POSTGRES_PASSWORD: jpa_failure
|
||||
# No published port: the suite must reach PostgreSQL only through the proxy, or the injected
|
||||
# fault can be bypassed by connecting directly and the test passes without testing anything.
|
||||
expose:
|
||||
- "5432"
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U jpa_failure -d jpa_failure"]
|
||||
interval: 2s
|
||||
timeout: 3s
|
||||
retries: 30
|
||||
|
||||
toxiproxy:
|
||||
image: ghcr.io/shopify/toxiproxy:2.11.0
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
ports:
|
||||
# 8474 is the control API the suite drives; 8666 is the proxied PostgreSQL port.
|
||||
- "8474:8474"
|
||||
- "8666:8666"
|
||||
command: ["-host", "0.0.0.0"]
|
||||
@@ -1,33 +0,0 @@
|
||||
# Kafka 4.3.x in KRaft mode.
|
||||
#
|
||||
# Single broker on purpose: this compose file exists to reproduce the platform's Stable profile
|
||||
# locally, not to model a production cluster. The settings below are the ones the profile guard
|
||||
# enforces, so a local run fails the same way a misconfigured deployment would.
|
||||
services:
|
||||
kafka:
|
||||
image: apache/kafka:4.3.0
|
||||
container_name: messaging-kafka
|
||||
ports:
|
||||
- "9092:9092"
|
||||
environment:
|
||||
KAFKA_NODE_ID: 1
|
||||
KAFKA_PROCESS_ROLES: broker,controller
|
||||
KAFKA_LISTENERS: PLAINTEXT://:9092,CONTROLLER://:9093
|
||||
KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
|
||||
KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
|
||||
KAFKA_CONTROLLER_QUORUM_VOTERS: 1@localhost:9093
|
||||
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
|
||||
# acks=all is only a durability guarantee when more than one replica must acknowledge.
|
||||
# With a single broker the platform still requires acks=all; min.insync.replicas is 1 here
|
||||
# and is expected to be 2 in any environment that claims replication evidence.
|
||||
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
|
||||
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
|
||||
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
|
||||
KAFKA_MIN_INSYNC_REPLICAS: 1
|
||||
# Topology is created by infrastructure, never by the application.
|
||||
KAFKA_AUTO_CREATE_TOPICS_ENABLE: "false"
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server localhost:9092 >/dev/null 2>&1"]
|
||||
interval: 5s
|
||||
timeout: 10s
|
||||
retries: 20
|
||||
@@ -1,27 +0,0 @@
|
||||
# PostgreSQL 16 for the Outbox and Inbox.
|
||||
#
|
||||
# logical replication stays enabled so a CDC relay can be tried against the same database the polling
|
||||
# relay uses. The repository ships no CDC relay (the Debezium mapping was removed on 2026-09-25).
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:16-alpine
|
||||
container_name: messaging-postgres
|
||||
ports:
|
||||
- "5432:5432"
|
||||
environment:
|
||||
POSTGRES_DB: messaging
|
||||
POSTGRES_USER: messaging
|
||||
POSTGRES_PASSWORD: messaging
|
||||
command:
|
||||
- "postgres"
|
||||
- "-c"
|
||||
- "wal_level=logical"
|
||||
- "-c"
|
||||
- "max_replication_slots=4"
|
||||
- "-c"
|
||||
- "max_wal_senders=4"
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U messaging -d messaging"]
|
||||
interval: 5s
|
||||
timeout: 5s
|
||||
retries: 20
|
||||
@@ -1,35 +0,0 @@
|
||||
# TLS material
|
||||
|
||||
Production profiles require TLS **and** hostname verification; `MessageSecurityValidator` fails
|
||||
startup without either.
|
||||
|
||||
No key material is committed here, and none should be. Certificates are issued by the deployment's
|
||||
own PKI and mounted at runtime; a keystore in a repository is a credential in a repository, and
|
||||
rotating it means a commit.
|
||||
|
||||
## Local development
|
||||
|
||||
The compose files in the sibling directories run plaintext listeners deliberately. They exist to
|
||||
reproduce the *messaging* semantics locally, not the transport security, and running them with
|
||||
`production: false` in the destination profile is what keeps the validator honest — a profile marked
|
||||
`production: true` against a plaintext broker must fail, and that is a test, not an inconvenience.
|
||||
|
||||
## Generating a local CA for TLS testing
|
||||
|
||||
```bash
|
||||
openssl req -x509 -newkey rsa:4096 -sha256 -days 30 -nodes \
|
||||
-keyout ca.key -out ca.crt -subj "/CN=messaging-local-ca"
|
||||
|
||||
openssl req -newkey rsa:4096 -nodes -keyout broker.key -out broker.csr \
|
||||
-subj "/CN=localhost"
|
||||
|
||||
openssl x509 -req -in broker.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
|
||||
-out broker.crt -days 30 -sha256 \
|
||||
-extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1")
|
||||
```
|
||||
|
||||
The `subjectAltName` is not optional. Hostname verification is required in production profiles, and
|
||||
a certificate without a SAN fails it — which is the correct outcome, not something to work around by
|
||||
disabling the check.
|
||||
|
||||
Generated files are ignored by `.gitignore` in this directory.
|
||||
@@ -1,18 +0,0 @@
|
||||
# Toxiproxy, for the failures that matter most.
|
||||
#
|
||||
# The platform's hardest guarantee is that a lost confirmation is reported as AMBIGUOUS rather than
|
||||
# guessed. A healthy broker will not lose one on request, so the chaos suite puts a proxy in front of
|
||||
# it and severs the connection after the record was accepted but before the acknowledgement arrives.
|
||||
services:
|
||||
toxiproxy:
|
||||
image: ghcr.io/shopify/toxiproxy:2.12.0
|
||||
container_name: messaging-toxiproxy
|
||||
ports:
|
||||
- "8474:8474" # control API
|
||||
- "19092:19092" # proxied Kafka
|
||||
- "15433:15433" # proxied PostgreSQL
|
||||
healthcheck:
|
||||
test: ["CMD", "/toxiproxy-cli", "list"]
|
||||
interval: 5s
|
||||
timeout: 5s
|
||||
retries: 20
|
||||
@@ -1,94 +0,0 @@
|
||||
# Toxiproxy fault injection for the notification delivery platform.
|
||||
#
|
||||
# Scope, stated up front: this is the *nightly and release* fault suite, not the PR gate. The PR
|
||||
# suite runs against a loopback socket harness in-process — deterministic, no Docker, no provider
|
||||
# sandbox — because a gate that needs infrastructure is a gate people learn to skip. What lives
|
||||
# here are the faults that harness cannot produce: real TCP behaviour under latency, bandwidth
|
||||
# starvation, and connection resets at a point the JVM's own socket layer decides.
|
||||
#
|
||||
# Usage:
|
||||
# docker compose -f infra/notification/toxiproxy/docker-compose.yml up -d
|
||||
# ./gradlew :adapter:outbound:notification:test -Dnotification.faultProxy=http://127.0.0.1:8474
|
||||
#
|
||||
# The proxies below front *stub* upstreams, never a provider's real API. Pointing a toxic proxy at
|
||||
# a live provider sends real notifications to real people from a test run, and adds a rate-limit
|
||||
# incident on an account the team shares.
|
||||
services:
|
||||
toxiproxy:
|
||||
image: ghcr.io/shopify/toxiproxy:2.11.0
|
||||
container_name: notification-toxiproxy
|
||||
ports:
|
||||
- "8474:8474" # control API
|
||||
- "18081:18081" # -> ses-stub
|
||||
- "18082:18082" # -> twilio-stub
|
||||
- "18083:18083" # -> push-stub (APNs / FCM / Web Push)
|
||||
networks: [notification-fault]
|
||||
healthcheck:
|
||||
test: ["CMD", "/toxiproxy-cli", "list"]
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 10
|
||||
|
||||
# Deterministic upstreams. Each returns the provider's success shape and nothing else; the
|
||||
# interesting behaviour is injected by the proxy in front of it, not by the stub.
|
||||
ses-stub:
|
||||
image: mendhak/http-https-echo:35
|
||||
environment:
|
||||
HTTP_PORT: "8080"
|
||||
networks: [notification-fault]
|
||||
|
||||
twilio-stub:
|
||||
image: mendhak/http-https-echo:35
|
||||
environment:
|
||||
HTTP_PORT: "8080"
|
||||
networks: [notification-fault]
|
||||
|
||||
push-stub:
|
||||
image: mendhak/http-https-echo:35
|
||||
environment:
|
||||
HTTP_PORT: "8080"
|
||||
networks: [notification-fault]
|
||||
|
||||
# Creates the proxies and the toxics once the control API is up. Kept as a job rather than a
|
||||
# README step so the topology is reproducible and reviewable rather than typed from memory.
|
||||
provision:
|
||||
image: ghcr.io/shopify/toxiproxy:2.11.0
|
||||
depends_on:
|
||||
toxiproxy:
|
||||
condition: service_healthy
|
||||
networks: [notification-fault]
|
||||
entrypoint:
|
||||
- /bin/sh
|
||||
- -c
|
||||
- |
|
||||
set -e
|
||||
CLI="/toxiproxy-cli -h toxiproxy:8474"
|
||||
$$CLI create -l 0.0.0.0:18081 -u ses-stub:8080 ses
|
||||
$$CLI create -l 0.0.0.0:18082 -u twilio-stub:8080 twilio
|
||||
$$CLI create -l 0.0.0.0:18083 -u push-stub:8080 push
|
||||
|
||||
# Response loss after the request was committed: the provider received and acted on the
|
||||
# message, and the answer never came back. This is the AMBIGUOUS case, and it is the one
|
||||
# fault no provider's documentation describes.
|
||||
$$CLI toxic add -t timeout -a timeout=0 -n response_loss --downstream --toxicity 0 ses
|
||||
$$CLI toxic add -t timeout -a timeout=0 -n response_loss --downstream --toxicity 0 twilio
|
||||
$$CLI toxic add -t timeout -a timeout=0 -n response_loss --downstream --toxicity 0 push
|
||||
|
||||
# Latency past the adapter's own timeout, to prove the timeout is the adapter's decision
|
||||
# rather than the socket's.
|
||||
$$CLI toxic add -t latency -a latency=8000 -n slow --toxicity 0 ses
|
||||
$$CLI toxic add -t latency -a latency=8000 -n slow --toxicity 0 twilio
|
||||
$$CLI toxic add -t latency -a latency=8000 -n slow --toxicity 0 push
|
||||
|
||||
# Partial write: the connection dies mid-body. Distinct from response loss, because the
|
||||
# provider never got a complete request and the attempt is genuinely retryable.
|
||||
$$CLI toxic add -t limit_data -a bytes=64 -n partial_write --upstream --toxicity 0 ses
|
||||
$$CLI toxic add -t limit_data -a bytes=64 -n partial_write --upstream --toxicity 0 twilio
|
||||
$$CLI toxic add -t limit_data -a bytes=64 -n partial_write --upstream --toxicity 0 push
|
||||
|
||||
echo "proxies ready; toxics are registered at toxicity=0 and enabled per test"
|
||||
$$CLI list
|
||||
|
||||
networks:
|
||||
notification-fault:
|
||||
driver: bridge
|
||||
@@ -59,7 +59,7 @@ volume을 붙인다.
|
||||
| 실행 환경 | 붙이는 방법 |
|
||||
| --- | --- |
|
||||
| Compose | `-f infra/fileserver/compose/docker-compose.fileserver.yml`을 더한다. `fileserver-data` named volume을 마운트하고, 앱보다 먼저 `fileserver-storage-init`이 앱 이미지 안에서 root로 한 번 돌아 volume 소유자를 이미지의 `app` 계정으로 바꾼다(0750). 새 volume, 재사용한 volume, bind mount 모두 같다 |
|
||||
| Kubernetes | PersistentVolumeClaim을 같은 경로에 마운트하고 pod `securityContext.fsGroup`을 앱 그룹으로 둔다(`infra/fileserver/kubernetes/pvc-certification-job.yaml`) |
|
||||
| Kubernetes | PersistentVolumeClaim을 같은 경로에 마운트하고 pod `securityContext.fsGroup`을 앱 그룹으로 둔다(조건: `docs/fileserver/operations.md` 「운영 환경이 지켜야 할 조건」) |
|
||||
| `docker run` | `-v <volume>:/var/lib/backend/files`. volume 소유자를 이미지의 `app` 계정으로 먼저 맞춘다 |
|
||||
|
||||
소유자가 맞지 않으면 모든 쓰기가 거부되고, 저장소 probe가 기동 때 `storage root is not writable`로
|
||||
|
||||
Reference in New Issue
Block a user