feat: jpa, messaging, notification, mongo, graphql 어댑터터 리펙토링
This commit is contained in:
DongHyeonka
@@ -16,7 +16,7 @@ readonly EXPECTED_GUARDED_GRADLE_IF="\${{ always() && steps.gradle-wrapper-valid
|
||||
# Replace this entire sorted array in the same reviewed change. Never refresh a single digest
|
||||
# merely to make this verifier pass.
|
||||
readonly EXPECTED_WORKFLOW_LOCK=(
|
||||
'a5986c6d865e28d6160dc09c513c430c9d9c38d154c67423cb34448cb1e9863c .github/workflows/ci-quality-gates.yml'
|
||||
'e27d981f43815294e47470e51f61671ee7047794e2a638d1b71a91ee957a18c6 .github/workflows/ci-quality-gates.yml'
|
||||
'59de260a70c2c0a0d686d97035a189dc0567395977dfa18758f1a2d89d15a00d .github/workflows/dependency-vulnerability.yml'
|
||||
'1b3220c922f954500f727c6a799b24e4962915845b9248e8e496e5050e829f28 .github/workflows/fileserver-nightly.yml'
|
||||
'26812e16b8d6e4472543ddd49c7b16ee6b7697834ddbb653fa0424befd71c544 .github/workflows/fileserver-pr.yml'
|
||||
|
||||
@@ -48,6 +48,14 @@ jobs:
|
||||
- name: Check quality, public paths, and dependency locks
|
||||
working-directory: src
|
||||
run: ./gradlew check verifyPublicPathSnapshot verifyDependencyLocks --warning-mode=fail --no-daemon --stacktrace
|
||||
# Named as its own step because nothing else runs it: `check` does not depend on
|
||||
# graphqlStableTest, so the lane's required-class guard — the check that its module-boundary
|
||||
# suite has not silently stopped being discovered — protected nothing in CI. A separate step
|
||||
# keeps the aggregate invocation below byte-identical, which ConditionalTransportQualification
|
||||
# ContractTest asserts on, and the two tasks do not overlap.
|
||||
- name: Qualify the GraphQL Stable lane
|
||||
working-directory: src
|
||||
run: ./gradlew :adapter:inbound:graphql:graphqlStableTest --no-daemon --stacktrace
|
||||
- name: Qualify opt-in inbound transports without skips
|
||||
working-directory: src
|
||||
run: ./gradlew conditionalTransportQualification --no-daemon --stacktrace
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
.vscode/
|
||||
src/**/bin/
|
||||
.claude/
|
||||
|
||||
# Operator input, not a build input. The examples beside it are the tracked contract;
|
||||
# verifyEnvKeys reads the registry, the profile YAMLs and .env.example, never a real one.
|
||||
src/.env*
|
||||
!src/.env.example
|
||||
!src/.env.local.example
|
||||
|
||||
# Written per run by the runtime-smoke wrapper; never committed.
|
||||
src/.env.lane
|
||||
|
||||
+41
-1
@@ -18,11 +18,30 @@ services:
|
||||
app:
|
||||
# Relax read-only constraint for local development.
|
||||
read_only: false
|
||||
tmpfs: [] # no tmpfs in dev; rely on normal writable rootfs
|
||||
# `!override`, not a plain empty list. An empty sequence merges with the base sequence rather
|
||||
# than replacing it, so the base's /var/tmp/heap tmpfs survived and collided with the bind mount
|
||||
# below — Compose refuses to have the same target twice and will not silently pick one. That is
|
||||
# the right refusal: a heap dump written into a tmpfs dies with the container that produced it,
|
||||
# which is the one moment somebody wants the file.
|
||||
#
|
||||
# `!override` needs Compose >= 2.24.4. Whether the collision is actually gone is checked in the
|
||||
# merged model rather than assumed from this line.
|
||||
tmpfs: !override []
|
||||
# More memory for dev profiling / heap dumps.
|
||||
mem_limit: 1g
|
||||
memswap_limit: 1g
|
||||
environment:
|
||||
# Explicit, not inherited. A Compose profile selects services; it says nothing about which
|
||||
# environment the application believes it is in, and the two drifting is how a dev stack ends
|
||||
# up running local's settings.
|
||||
SPRING_PROFILES_ACTIVE: "dev"
|
||||
# The datasource address, owned here like the local and prod-smoke overlays own theirs. It was
|
||||
# the only one of the three missing, and the gap was invisible while the qualification wrapper
|
||||
# supplied a URL to every lane: the dev stack ran on a value that came from the test harness
|
||||
# rather than from the file that describes the dev environment. With the wrapper no longer
|
||||
# setting it — it was overriding prod's sslmode=verify-full URL — dev had none at all and
|
||||
# Flyway was handed the literal string "${APP_DATASOURCE_URL}".
|
||||
APP_DATASOURCE_URL: "jdbc:postgresql://db:5432/${POSTGRES_DB:-ca_skeleton}"
|
||||
TZ: "UTC"
|
||||
LANG: "C.UTF-8"
|
||||
LC_ALL: "C.UTF-8"
|
||||
@@ -53,9 +72,30 @@ services:
|
||||
# Do not restart automatically so crash loops stay visible.
|
||||
restart: "no"
|
||||
# Optional: mount heap dump directory to host for dev analysis.
|
||||
# The base declares /var/tmp/heap as a tmpfs, which is right for an ephemeral runtime and wrong
|
||||
# for dev: a heap dump written into a tmpfs dies with the container that produced it, which is
|
||||
# the one moment somebody wants the file. Compose refuses to have both, and correctly — it will
|
||||
# not silently pick one — so the tmpfs list is replaced rather than appended to.
|
||||
#
|
||||
# `!override` needs Compose >= 2.24.4. An empty sequence is not assumed to delete the base
|
||||
# sequence by itself; scripts/verify-compose-profile-contracts.sh checks mount-target uniqueness
|
||||
# in the merged model, which is what actually proves the collision is gone.
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./tmp/heap-dumps
|
||||
target: /var/tmp/heap
|
||||
bind:
|
||||
create_host_path: true
|
||||
# The same network the shared infrastructure lives on. The local overlay joins it and the dev
|
||||
# overlay did not, so a dev lane that started PostgreSQL beside the application put the two on
|
||||
# different networks: `UnknownHostException: db`, from a container that was running and healthy
|
||||
# a metre away. Compose puts a service with no `networks:` on `default`, which is a network of
|
||||
# its own making — so the omission reads as a working stack until something has to resolve a
|
||||
# name across it.
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
|
||||
networks:
|
||||
# Defined in docker-compose.infra.yml, where the services that share it live.
|
||||
caskeleton-infra:
|
||||
external: false
|
||||
|
||||
@@ -0,0 +1,472 @@
|
||||
# =============================================================================
|
||||
# Shared infrastructure, owned here and nowhere else.
|
||||
#
|
||||
# Environment overlays (local, dev, prod-smoke) describe how the application runs. This file
|
||||
# describes what it runs against. Keeping the two apart is why `local` could stop meaning "the app
|
||||
# plus a database" and start meaning "the app, with whichever services the lane asked for".
|
||||
#
|
||||
# Every service carries a Compose profile, so nothing here starts unless a lane names it. A profile
|
||||
# selects services; it never implies a Spring profile. The lane definitions live in
|
||||
# src/config/runtime/compose-profile-contracts.json, and scripts/verify-compose-profile-contracts.sh
|
||||
# checks this file against them.
|
||||
# =============================================================================
|
||||
|
||||
services:
|
||||
# ---- PostgreSQL --------------------------------------------------------------
|
||||
db:
|
||||
profiles:
|
||||
- local-jpa
|
||||
- local-messaging-outbox
|
||||
- local-notification-ingest
|
||||
- local-notification-serving
|
||||
- local-notification-handoff
|
||||
- shared-infra
|
||||
- prod-smoke
|
||||
- all-adapters
|
||||
image: postgres:16-alpine
|
||||
environment:
|
||||
POSTGRES_DB: "${POSTGRES_DB:-ca_skeleton}"
|
||||
POSTGRES_USER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
|
||||
POSTGRES_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
|
||||
TZ: "UTC"
|
||||
volumes:
|
||||
- type: volume
|
||||
source: caskeleton-db-data
|
||||
target: /var/lib/postgresql/data
|
||||
ports:
|
||||
- "127.0.0.1:5433:5432"
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test:
|
||||
[
|
||||
"CMD-SHELL",
|
||||
"pg_isready -U ${APP_DATASOURCE_USERNAME:-ca_skeleton} -d ${POSTGRES_DB:-ca_skeleton}",
|
||||
]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 30s
|
||||
|
||||
# ---- MongoDB -----------------------------------------------------------------
|
||||
# A replica set of one. Single-node is still a replica set: transactions and change streams need
|
||||
# one, and a standalone mongod that "works for reads" is a deployment that discovers the
|
||||
# difference at the first transaction.
|
||||
mongo:
|
||||
profiles:
|
||||
- local-mongo
|
||||
- all-adapters
|
||||
image: mongo:7
|
||||
command: ["mongod", "--replSet", "rs0", "--bind_ip_all"]
|
||||
volumes:
|
||||
- type: volume
|
||||
source: caskeleton-mongo-data
|
||||
target: /data/db
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 10
|
||||
start_period: 20s
|
||||
|
||||
mongo-rs-init:
|
||||
profiles:
|
||||
- local-mongo
|
||||
- all-adapters
|
||||
image: mongo:7
|
||||
depends_on:
|
||||
mongo:
|
||||
condition: service_healthy
|
||||
# Idempotent: rs.initiate() on an already-initiated set returns an error this swallows, so the
|
||||
# lane can be re-run against a surviving volume without a manual reset.
|
||||
command:
|
||||
- mongosh
|
||||
- --host
|
||||
- mongo
|
||||
- --quiet
|
||||
- --eval
|
||||
- >-
|
||||
try { rs.initiate({_id:'rs0',members:[{_id:0,host:'mongo:27017'}]}) }
|
||||
catch (e) { if (!/already initialized/i.test(e.message)) { throw e } }
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
# ---- Kafka -------------------------------------------------------------------
|
||||
kafka:
|
||||
profiles:
|
||||
- local-messaging
|
||||
- local-messaging-outbox
|
||||
- all-adapters
|
||||
image: apache/kafka:3.8.0
|
||||
environment:
|
||||
KAFKA_NODE_ID: "1"
|
||||
KAFKA_PROCESS_ROLES: "broker,controller"
|
||||
KAFKA_LISTENERS: "PLAINTEXT://:9092,CONTROLLER://:9093"
|
||||
KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT://kafka:9092"
|
||||
KAFKA_CONTROLLER_QUORUM_VOTERS: "1@kafka:9093"
|
||||
KAFKA_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
|
||||
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT"
|
||||
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "1"
|
||||
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: "1"
|
||||
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: "1"
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test:
|
||||
["CMD-SHELL", "/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server kafka:9092"]
|
||||
interval: 10s
|
||||
timeout: 10s
|
||||
retries: 12
|
||||
start_period: 30s
|
||||
|
||||
# ---- Mailpit — the reference SMTP provider for notification serving ----------
|
||||
mailpit:
|
||||
profiles:
|
||||
- local-notification-serving
|
||||
- local-notification-handoff
|
||||
- all-adapters
|
||||
image: axllent/mailpit:v1.21
|
||||
environment:
|
||||
MP_SMTP_AUTH_ACCEPT_ANY: "1"
|
||||
# MP_SMTP_AUTH_ALLOW_INSECURE is deliberately absent, and Mailpit refuses to start with both:
|
||||
# "TLS cannot be required with --smtp-auth-allow-insecure". It existed to permit credentials
|
||||
# over a plaintext connection, which is exactly what requiring STARTTLS removes the need for —
|
||||
# any AUTH now happens inside the TLS session.
|
||||
# STARTTLS, required. Not a hardening extra: SmtpProviderProperties.TlsMode has two members and
|
||||
# neither is plaintext, so the platform cannot describe an unencrypted relay at all. A lane that
|
||||
# wanted a plaintext Mailpit would be asking for a transport the type refuses to express, and
|
||||
# the honest way to satisfy it is to give the relay a certificate.
|
||||
MP_SMTP_TLS_CERT: /run/mailpit-tls/server.crt
|
||||
MP_SMTP_TLS_KEY: /run/mailpit-tls/server.key
|
||||
MP_SMTP_REQUIRE_STARTTLS: "true"
|
||||
volumes:
|
||||
# Generated per run by the qualification wrapper for the host name `mailpit`, and removed on
|
||||
# teardown, exactly like the PostgreSQL lane certificate. A committed test certificate is a
|
||||
# private key in Git.
|
||||
- type: bind
|
||||
source: ./infra/mailpit/tls
|
||||
target: /run/mailpit-tls
|
||||
read_only: true
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test: ["CMD", "/mailpit", "readyz"]
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 12
|
||||
start_period: 5s
|
||||
|
||||
# ---- MinIO -------------------------------------------------------------------
|
||||
minio:
|
||||
profiles:
|
||||
- shared-infra
|
||||
- prod-smoke
|
||||
image: minio/minio:RELEASE.2024-09-13T20-26-02Z
|
||||
command: ["server", "/data"]
|
||||
environment:
|
||||
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
|
||||
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
|
||||
volumes:
|
||||
- type: volume
|
||||
source: caskeleton-minio-data
|
||||
target: /data
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test: ["CMD", "mc", "ready", "local"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 10
|
||||
start_period: 10s
|
||||
|
||||
# Bucket and policy bootstrap. Not a substitute for the round trip: creating a bucket proves the
|
||||
# server accepts an admin command, not that an object survives being written and read back.
|
||||
minio-init:
|
||||
profiles:
|
||||
- shared-infra
|
||||
- prod-smoke
|
||||
image: minio/mc:RELEASE.2024-09-16T17-43-14Z
|
||||
depends_on:
|
||||
minio:
|
||||
condition: service_healthy
|
||||
entrypoint: ["/bin/sh", "/opt/minio/bucket-bootstrap.sh"]
|
||||
environment:
|
||||
MINIO_ENDPOINT: "http://minio:9000"
|
||||
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
|
||||
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
|
||||
MINIO_BUCKET: "${MINIO_BUCKET:-ca-skeleton-objects}"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/minio/init
|
||||
target: /opt/minio
|
||||
read_only: true
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
# ---- Keycloak ----------------------------------------------------------------
|
||||
keycloak:
|
||||
profiles:
|
||||
- local-graphql
|
||||
- local-notification-ingest
|
||||
- local-notification-serving
|
||||
- local-notification-handoff
|
||||
- shared-infra
|
||||
- prod-smoke
|
||||
- all-adapters
|
||||
image: quay.io/keycloak/keycloak:26.0
|
||||
# The wrapper reads the client secret from a mounted file and execs kc.sh. The realm artifact
|
||||
# carries only a ${...} reference, so no secret value is in Git, in the rendered config, or on a
|
||||
# command line.
|
||||
entrypoint: ["/bin/bash", "/opt/keycloak-entrypoint/entrypoint.sh"]
|
||||
environment:
|
||||
KC_BOOTSTRAP_ADMIN_USERNAME: "${KEYCLOAK_ADMIN:-admin}"
|
||||
KC_BOOTSTRAP_ADMIN_PASSWORD: "${KEYCLOAK_ADMIN_PASSWORD:-admin}"
|
||||
KC_HEALTH_ENABLED: "true"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/keycloak/entrypoint.sh
|
||||
target: /opt/keycloak-entrypoint/entrypoint.sh
|
||||
read_only: true
|
||||
- type: bind
|
||||
source: ./infra/keycloak/realms
|
||||
target: /opt/keycloak/data/import
|
||||
read_only: true
|
||||
secrets:
|
||||
- keycloak-graphql-smoke-client-secret
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
healthcheck:
|
||||
test:
|
||||
- "CMD-SHELL"
|
||||
- "exec 3<>/dev/tcp/127.0.0.1/9000 && echo -e 'GET /health/ready HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3 && cat <&3 | grep -q '\"status\": \"UP\"'"
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 20
|
||||
start_period: 30s
|
||||
|
||||
# ---- Capability schema streams ------------------------------------------------
|
||||
# Two pre-start one-shots, in this order, because a capability stream is an operator sequence
|
||||
# rather than a property.
|
||||
#
|
||||
# Install: each stream under db/migration/jpa keeps its own Flyway history table — they all declare
|
||||
# a V1, so one Flyway pointed at all of them fails outright — and each registers itself
|
||||
# INSTALLED_INACTIVE.
|
||||
#
|
||||
# Promote: an operator sanctions the installed schema, and the application refuses to start until
|
||||
# that has happened. That is the fail-closed half of the same design, so it cannot be folded into
|
||||
# the install step without making "the tables exist" and "this is sanctioned" the same event.
|
||||
#
|
||||
# They are also two images because they must be: flyway/flyway ships no psql, so the promotion
|
||||
# could not have run in the migration container at all.
|
||||
#
|
||||
# Both run before `up`, not with the smoke clients after it — the application is what they are a
|
||||
# precondition for. The lane contract's preStartServices carries that ordering.
|
||||
db-migrate-capabilities:
|
||||
profiles:
|
||||
- local-notification-ingest
|
||||
- local-notification-serving
|
||||
- local-notification-handoff
|
||||
- all-adapters
|
||||
image: flyway/flyway:11.1.0
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy
|
||||
entrypoint: ["/bin/sh", "/opt/capability-streams/apply-capability-streams.sh"]
|
||||
environment:
|
||||
PGHOST: "db"
|
||||
PGUSER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
|
||||
PGPASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
|
||||
PGDATABASE: "${POSTGRES_DB:-ca_skeleton}"
|
||||
CAPABILITY_STREAMS: "${CAPABILITY_STREAMS:-}"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/postgres/apply-capability-streams.sh
|
||||
target: /opt/capability-streams/apply-capability-streams.sh
|
||||
read_only: true
|
||||
# The whole migration tree, not just db/migration/jpa: the application's own postgresql stream
|
||||
# has to be installed first, or the capability tables arrive in a schema whose flyway_schema_history
|
||||
# does not exist yet and the application refuses to start — which is its baseline-on-migrate: false
|
||||
# policy working as designed.
|
||||
- type: bind
|
||||
source: ./src/adapter/outbound/persistence-jpa/src/main/resources/db/migration
|
||||
target: /flyway/sql
|
||||
read_only: true
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
db-promote-capabilities:
|
||||
profiles:
|
||||
- local-notification-ingest
|
||||
- local-notification-serving
|
||||
- local-notification-handoff
|
||||
- all-adapters
|
||||
image: postgres:16-alpine
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy
|
||||
entrypoint: ["/bin/sh", "/opt/capability-streams/promote-capability-streams.sh"]
|
||||
environment:
|
||||
PGHOST: "db"
|
||||
PGUSER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
|
||||
PGPASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
|
||||
PGDATABASE: "${POSTGRES_DB:-ca_skeleton}"
|
||||
CAPABILITY_STREAMS: "${CAPABILITY_STREAMS:-}"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/postgres/promote-capability-streams.sh
|
||||
target: /opt/capability-streams/promote-capability-streams.sh
|
||||
read_only: true
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
# ---- One-shot smoke clients --------------------------------------------------
|
||||
# Never `up --wait` targets. Each is run with `run --rm` and must exit zero; a missing, skipped or
|
||||
# non-zero one fails its lane rather than being treated as "not applicable".
|
||||
auth-smoke:
|
||||
profiles:
|
||||
- local-graphql
|
||||
- shared-infra
|
||||
- prod-smoke
|
||||
- all-adapters
|
||||
image: curlimages/curl:8.10.1
|
||||
depends_on:
|
||||
keycloak:
|
||||
condition: service_healthy
|
||||
# The client secret is written on the host at mode 0600 by the qualification wrapper and mounted
|
||||
# in. The Keycloak image happens to run as the same uid the wrapper writes as; this image runs as
|
||||
# uid 100, so it read "Permission denied" and the lane failed on the smoke client rather than on
|
||||
# anything it was checking. Compose ignores the secret's uid/gid/mode options outside swarm, so
|
||||
# the container reads it as root instead. The two alternatives are both worse: loosening the host
|
||||
# file to world-readable leaves a credential readable by every process on the machine, and passing
|
||||
# the value as an environment variable puts it in `docker compose config` output and in ps.
|
||||
user: "0:0"
|
||||
entrypoint: ["/bin/sh", "/opt/auth-smoke/auth-smoke.sh"]
|
||||
environment:
|
||||
# The same issuer URL the application is given. A token obtained from one URL and validated
|
||||
# against another proves nothing, and localhost means a different host inside each container.
|
||||
KEYCLOAK_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
|
||||
KEYCLOAK_CLIENT_ID: "ca-skeleton-api"
|
||||
APP_BASE_URL: "http://app:8080"
|
||||
# Supplied per runtime, because the same endpoint has two addresses: application-local.yml
|
||||
# pins presentation.api-base-path to /api and the shipped default is /v1. The qualification
|
||||
# wrapper exports the value that matches the lane's Spring runtime.
|
||||
APP_HEALTH_PATH: "${APP_HEALTH_PATH:-/v1/healthcheck}"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/keycloak/smoke
|
||||
target: /opt/auth-smoke
|
||||
read_only: true
|
||||
secrets:
|
||||
- keycloak-graphql-smoke-client-secret
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
# The server image, not the mc client image: minio/mc ships no sed, grep or cmp, and the round-trip
|
||||
# client needs a digest tool. See infra/minio/smoke/object-storage-smoke.sh for how that went
|
||||
# unnoticed. The lane already pulls this image for the server itself.
|
||||
object-storage-smoke:
|
||||
profiles:
|
||||
- shared-infra
|
||||
- prod-smoke
|
||||
image: minio/minio:RELEASE.2024-09-13T20-26-02Z
|
||||
depends_on:
|
||||
minio-init:
|
||||
condition: service_completed_successfully
|
||||
entrypoint: ["/bin/sh", "/opt/minio-smoke/object-storage-smoke.sh"]
|
||||
environment:
|
||||
MINIO_ENDPOINT: "http://minio:9000"
|
||||
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
|
||||
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
|
||||
MINIO_BUCKET: "${MINIO_BUCKET:-ca-skeleton-objects}"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/minio/smoke
|
||||
target: /opt/minio-smoke
|
||||
read_only: true
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
notification-smoke:
|
||||
profiles:
|
||||
- local-notification-ingest
|
||||
- local-notification-serving
|
||||
- local-notification-handoff
|
||||
- all-adapters
|
||||
image: curlimages/curl:8.10.1
|
||||
depends_on:
|
||||
keycloak:
|
||||
condition: service_healthy
|
||||
# uid 0 for the same reason auth-smoke uses it: the mounted client secret is mode 0600 on the
|
||||
# host and this image otherwise runs as uid 100, which reads "Permission denied". The lane then
|
||||
# fails on the smoke client rather than on anything it was checking.
|
||||
user: "0:0"
|
||||
entrypoint: ["/bin/sh", "/opt/notification-smoke/notification-smoke.sh"]
|
||||
environment:
|
||||
APP_BASE_URL: "http://app:8080"
|
||||
MAILPIT_BASE_URL: "http://mailpit:8025"
|
||||
# ingest | serving | handoff-verify — which phase of the lane this invocation is.
|
||||
#
|
||||
# No default, deliberately. It defaulted to `ingest`, and local-notification-serving therefore
|
||||
# ran the ingest assertions — "accepted, and nothing was delivered" — against an application in
|
||||
# SERVING mode. The lane passed while testing the opposite of what it is named for, and would
|
||||
# have kept passing for as long as the check happened to run before the dispatch worker. An
|
||||
# unset value now renders empty and the client refuses it.
|
||||
# `:-` and not a value: an explicit empty default keeps Compose from warning about an unset
|
||||
# variable on every lane that never runs this client, while still rendering empty so the
|
||||
# client refuses it.
|
||||
NOTIFICATION_SMOKE_PHASE: "${NOTIFICATION_SMOKE_PHASE:-}"
|
||||
# Submission and template publication are authenticated like every other non-public path, so
|
||||
# this client obtains a token the same way auth-smoke does — client credentials against the
|
||||
# same issuer URL the application validates against.
|
||||
APP_BASE_PATH: "${APP_BASE_PATH:-/api}"
|
||||
KEYCLOAK_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
|
||||
KEYCLOAK_CLIENT_ID: "ca-skeleton-api"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/notification/smoke
|
||||
target: /opt/notification-smoke
|
||||
read_only: true
|
||||
# The handoff lane runs this client twice in one project and the second run needs the request
|
||||
# id the first accepted, so the state lives in a named volume that outlives a `run --rm`
|
||||
# container and is removed with the project by the teardown's --volumes.
|
||||
#
|
||||
# Its own path, not a subdirectory of the script mount above: a volume nested inside a
|
||||
# read-only bind cannot be created, because the runtime has to mkdir the mountpoint in a
|
||||
# filesystem it was just told is read-only.
|
||||
- type: volume
|
||||
source: caskeleton-notification-smoke-state
|
||||
target: /opt/notification-smoke-state
|
||||
secrets:
|
||||
- keycloak-graphql-smoke-client-secret
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
restart: "no"
|
||||
|
||||
networks:
|
||||
caskeleton-infra:
|
||||
driver: bridge
|
||||
|
||||
volumes:
|
||||
caskeleton-notification-smoke-state:
|
||||
driver: local
|
||||
caskeleton-db-data:
|
||||
driver: local
|
||||
caskeleton-mongo-data:
|
||||
driver: local
|
||||
caskeleton-minio-data:
|
||||
driver: local
|
||||
|
||||
secrets:
|
||||
# Written per run at mode 0600 by the qualification wrapper and removed on teardown. The realm
|
||||
# artifact references it by name; the value never reaches Git, a rendered config, a command line,
|
||||
# or an evidence file.
|
||||
keycloak-graphql-smoke-client-secret:
|
||||
file: ./infra/keycloak/secrets/graphql-smoke-client-secret
|
||||
+19
-49
@@ -5,8 +5,11 @@
|
||||
# docker compose -f docker-compose.yml -f docker-compose.local.yml up
|
||||
#
|
||||
# Local intent:
|
||||
# - Starts a local PostgreSQL database for integration testing without Testcontainers.
|
||||
# - Wires the app environment to point at the local DB.
|
||||
# - Wires the app environment to point at the shared `db` service, which lives in
|
||||
# docker-compose.infra.yml and starts only for lanes whose Compose profile names it.
|
||||
# - Declares no depends_on: a depends_on aimed at a profiled service makes every lane that does
|
||||
# not enable that profile fail to render at all, and ordering is the runtime-smoke wrapper's
|
||||
# job — it knows which services a lane actually starts.
|
||||
# - Keeps read-only filesystem and memory limits from the base compose.
|
||||
# - Publishes the DB on the loopback interface only, so a host-side run
|
||||
# (`./gradlew :app-bootstrap:bootRun`, IDE) reaches the same database the
|
||||
@@ -15,10 +18,19 @@
|
||||
|
||||
services:
|
||||
app:
|
||||
# Optional, because src/.env is operator input and a fresh clone does not have one. Before this
|
||||
# was marked optional, untracking that file made `docker compose config` fail outright on a
|
||||
# clone — the environment override that exists for convenience became a hard prerequisite for
|
||||
# rendering the stack at all. The tracked contract is src/.env.example; copy it.
|
||||
env_file:
|
||||
- ./src/.env
|
||||
- path: ./src/.env
|
||||
required: false
|
||||
# Wire the app to the local Postgres service on the internal network.
|
||||
environment:
|
||||
# Explicit, not inherited. A Compose profile selects services; it says nothing about which
|
||||
# environment the application believes it is in, and the two drifting is how a dev stack ends
|
||||
# up running local's settings.
|
||||
SPRING_PROFILES_ACTIVE: "local"
|
||||
TZ: "UTC"
|
||||
LANG: "C.UTF-8"
|
||||
LC_ALL: "C.UTF-8"
|
||||
@@ -30,9 +42,6 @@ services:
|
||||
APP_DATASOURCE_URL: "jdbc:postgresql://db:5432/${POSTGRES_DB:-ca_skeleton}"
|
||||
APP_DATASOURCE_USERNAME: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
|
||||
APP_DATASOURCE_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy
|
||||
healthcheck:
|
||||
test:
|
||||
- "CMD"
|
||||
@@ -46,49 +55,10 @@ services:
|
||||
start_period: 20s
|
||||
retries: 12
|
||||
networks:
|
||||
- caskeleton-local
|
||||
|
||||
db:
|
||||
image: postgres:16-alpine
|
||||
environment:
|
||||
POSTGRES_DB: "${POSTGRES_DB:-ca_skeleton}"
|
||||
POSTGRES_USER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
|
||||
POSTGRES_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
|
||||
TZ: "UTC"
|
||||
# Persist data between restarts; remove the volume to start fresh.
|
||||
volumes:
|
||||
- type: volume
|
||||
source: caskeleton-db-data
|
||||
target: /var/lib/postgresql/data
|
||||
# The containerised app reaches this over the internal network and needs no host port. A
|
||||
# host-side run does: src/.env is the dotenv source bootRun reads, and its committed
|
||||
# APP_DATASOURCE_URL is jdbc:postgresql://localhost:5433/ca_skeleton. With the port unpublished
|
||||
# that default named an address nothing in the repository provisioned, so every bootRun died in
|
||||
# the startup migration phase with a connection refusal.
|
||||
#
|
||||
# Bound to 127.0.0.1, never 0.0.0.0: the database is reachable from this machine and from
|
||||
# nowhere else on the network. Host 5433 (not 5432) so a PostgreSQL already installed on the
|
||||
# host keeps its conventional port.
|
||||
ports:
|
||||
- "127.0.0.1:5433:5432"
|
||||
networks:
|
||||
- caskeleton-local
|
||||
healthcheck:
|
||||
test:
|
||||
[
|
||||
"CMD-SHELL",
|
||||
"pg_isready -U ${APP_DATASOURCE_USERNAME:-ca_skeleton} -d ${POSTGRES_DB:-ca_skeleton}",
|
||||
]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 30s
|
||||
restart: unless-stopped
|
||||
- caskeleton-infra
|
||||
|
||||
networks:
|
||||
caskeleton-local:
|
||||
driver: bridge
|
||||
# Defined in docker-compose.infra.yml, where the services that share it live.
|
||||
caskeleton-infra:
|
||||
external: false
|
||||
|
||||
volumes:
|
||||
caskeleton-db-data:
|
||||
driver: local
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
# =============================================================================
|
||||
# prod-smoke — a production-shaped runtime, for evidence, on a laptop.
|
||||
#
|
||||
# Not "production Compose". What it is for is proving that the prod profile's fail-closed validators
|
||||
# can be satisfied at all: TLS on the JDBC URL, a schema Flyway owns, JSON logging, secret
|
||||
# references rather than values. A prod lane that only ever gets as far as `config` proves the file
|
||||
# parses, which was never the thing in doubt.
|
||||
#
|
||||
# The credentials here are generated per run by the lane wrapper. Nothing local is reused: a
|
||||
# prod-smoke that borrows the local MinIO password is a prod-smoke that tests the local setup.
|
||||
# =============================================================================
|
||||
|
||||
services:
|
||||
app:
|
||||
environment:
|
||||
# Explicit, not inherited. A Compose profile selects services and says nothing about which
|
||||
# environment the application believes it is in.
|
||||
SPRING_PROFILES_ACTIVE: "prod"
|
||||
TZ: "UTC"
|
||||
# verify-full, which is the point: PostgreSqlTransportSecurityValidator refuses anything less,
|
||||
# and that refusal is the behaviour this lane exists to satisfy rather than bypass.
|
||||
APP_DATASOURCE_URL: "jdbc:postgresql://db:5432/${POSTGRES_DB:-ca_skeleton}?sslmode=verify-full&sslrootcert=/run/secrets/postgres-ca"
|
||||
APP_DATASOURCE_USERNAME: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
|
||||
# The password is deliberately absent here. An `environment:` entry beats `env_file:`, so
|
||||
# declaring it as "${APP_DATASOURCE_PASSWORD:-}" read the host shell rather than the lane's
|
||||
# generated file and injected an empty string — which the prod env validator then refused, for
|
||||
# the right reason, about a value the lane had actually supplied.
|
||||
APP_DATASOURCE_DDL_AUTO: "validate"
|
||||
APP_LOG_JSON_ENABLED: "true"
|
||||
APP_SECURITY_JWT_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
|
||||
APP_SECURITY_JWT_AUDIENCE: "ca-skeleton-api"
|
||||
networks:
|
||||
- caskeleton-infra
|
||||
|
||||
networks:
|
||||
caskeleton-infra:
|
||||
external: false
|
||||
@@ -0,0 +1,50 @@
|
||||
# =============================================================================
|
||||
# Database transport security, for the lanes whose runtime requires it.
|
||||
#
|
||||
# The prod runtime connects with `sslmode=verify-full` and an explicit `sslrootcert`. That is not a
|
||||
# lane setting to relax: a prod smoke test against a database with TLS disabled is a smoke test of a
|
||||
# configuration production never runs, and the one failure mode it would hide — the certificate
|
||||
# chain or the host name not checking out — is the one that only ever appears in production.
|
||||
#
|
||||
# So the lane brings a real certificate instead. The qualification wrapper generates a CA and a
|
||||
# server certificate for the host name `db` per run, at mode 0600, and removes both on teardown; the
|
||||
# realm-secret pattern, applied to a keypair. Nothing here is committed: infra/postgres/tls holds
|
||||
# only a .gitignore.
|
||||
#
|
||||
# `verify-full` is deliberate rather than `verify-ca`. `verify-ca` proves the certificate was issued
|
||||
# by the expected authority and says nothing about who presented it, so it does not detect a
|
||||
# redirected connection — which is most of what transport security is for.
|
||||
# =============================================================================
|
||||
|
||||
services:
|
||||
db:
|
||||
# Runs as root just long enough to install the key where postgres can read it, then hands over
|
||||
# to the official entrypoint. See infra/postgres/entrypoint.sh for why a bind mount cannot do it.
|
||||
entrypoint: ["/bin/sh", "/opt/postgres-entrypoint/entrypoint.sh"]
|
||||
command:
|
||||
- "postgres"
|
||||
- "-c"
|
||||
- "ssl=on"
|
||||
- "-c"
|
||||
- "ssl_cert_file=/etc/postgresql-tls/server.crt"
|
||||
- "-c"
|
||||
- "ssl_key_file=/etc/postgresql-tls/server.key"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/postgres/entrypoint.sh
|
||||
target: /opt/postgres-entrypoint/entrypoint.sh
|
||||
read_only: true
|
||||
- type: bind
|
||||
source: ./infra/postgres/tls
|
||||
target: /opt/postgres-tls
|
||||
read_only: true
|
||||
|
||||
app:
|
||||
# The certificate authority the JDBC URL names in `sslrootcert`. A public certificate, so it
|
||||
# carries no mode problem — the private half never leaves the database container's filesystem.
|
||||
secrets:
|
||||
- postgres-ca
|
||||
|
||||
secrets:
|
||||
postgres-ca:
|
||||
file: ./infra/postgres/tls/ca.crt
|
||||
@@ -34,6 +34,14 @@ services:
|
||||
GIT_SHA: "${GIT_SHA:-0000000}"
|
||||
SOURCE_URL: "${SOURCE_URL:-https://example.invalid/ca-tmpl}"
|
||||
image: caskeleton:${BUILD_VERSION:-0.0.1_local_0000000}
|
||||
# Generated per run by scripts/run-compose-runtime-smoke.sh and removed on teardown. Seven values
|
||||
# have no inline default on purpose — the datasource address and credential, the application
|
||||
# name, and the JWT issuer and audience — so a lane has to supply them, and a lane that borrowed
|
||||
# the developer's own src/.env would be reproducible only on that developer's machine. Optional,
|
||||
# so an ordinary `docker compose up` is unaffected.
|
||||
env_file:
|
||||
- path: ./src/.env.lane
|
||||
required: false
|
||||
ports:
|
||||
- "${APP_SERVER_PORT:-8080}:8080"
|
||||
- "9001:9001"
|
||||
|
||||
@@ -0,0 +1,54 @@
|
||||
# docs
|
||||
|
||||
저장소의 모든 문서는 이 디렉터리 아래에 있다. 어떤 문서를 어디에 두는지가 유일한 규칙이고,
|
||||
파일 목록은 디렉터리를 직접 읽는다. 개수를 여기에 적으면 다음 문서가 추가되는 순간 틀린 글이 된다.
|
||||
|
||||
## 어댑터별 운영 문서
|
||||
|
||||
각 어댑터의 지원 범위, 설정, 보안, 운영, 마이그레이션 문서다. 코드와 함께 갱신되어야 하는 문서이고,
|
||||
`docs/httpclient/` 는 `scripts/verify-httpclient-docs.py` 가 코드에서 뽑은 이름과 대조한다.
|
||||
|
||||
| 디렉터리 | 대상 |
|
||||
| --- | --- |
|
||||
| `fileserver/` | 파일 서버 어댑터 |
|
||||
| `httpclient/` | HTTP 클라이언트 플랫폼 |
|
||||
| `jpa/` | JPA·PostgreSQL 영속성 |
|
||||
| `messaging/` | 메시징 어댑터 |
|
||||
| `mongodb/` | MongoDB 문서 영속성 (`advanced/`, `runbooks/` 포함) |
|
||||
| `notification/` | 알림 전달 플랫폼 (`adr/` 포함) |
|
||||
| `redis/` | Redis 캐시·세션 |
|
||||
|
||||
## 횡단 문서
|
||||
|
||||
| 디렉터리 | 대상 |
|
||||
| --- | --- |
|
||||
| `adr/` | 아키텍처 결정 기록 |
|
||||
| `architecture/` | 공개 API 표면 스냅숏 |
|
||||
| `evidence/` | 작업 단계별 증거·체크포인트 |
|
||||
| `registries/` | env 키·에러 코드·메트릭·헤더 등 레지스트리 SSOT |
|
||||
| `reviews/` | 모듈 코드 리뷰 결과 |
|
||||
| `runbooks/` | 장애 코드별 대응 런북 (`template.md` 기준) |
|
||||
| `security/` | 공개 경로 스냅숏 |
|
||||
|
||||
## 설계와 계획
|
||||
|
||||
| 디렉터리 | 대상 |
|
||||
| --- | --- |
|
||||
| `superpowers/specs/` | 설계서. `YYYY-MM-DD-<주제>-design.md` |
|
||||
| `superpowers/plans/` | 구현·확장 계획서. `YYYY-MM-DD-<주제>-plan.md` |
|
||||
| `superpowers/packages/` | 외부에서 납품된 설계 패키지의 README와 정적 검증 결과 |
|
||||
|
||||
`superpowers/packages/<어댑터>/` 는 설계서가 처음 전달됐을 때의 안내와 `VALIDATION.md` 검증 이력을
|
||||
남긴 기록 보관소다. 설계서·계획서 본문은 전부 `specs/` 와 `plans/` 에 있으므로 이 디렉터리에서
|
||||
문서를 찾을 필요는 없다. 각 README 상단의 보존 안내가 무엇이 옮겨졌고 무엇이 제거됐는지 밝힌다.
|
||||
|
||||
계획서 본문에는 당시 계획한 경로와 명령이 그대로 남아 있다. 그중 일부는 실제 구현에서 다른 위치로
|
||||
조정됐고, 저장소에 어떻게 대응시켰는지는 각 어댑터의 `repository-adaptation.md` 또는
|
||||
`module-mapping.md` 가 기록한다. 계획서를 사후에 고치지 않는 이유는 그렇게 하면 계획의 기록이 아니라
|
||||
결과를 계획처럼 보이게 만든 글이 되기 때문이다.
|
||||
|
||||
## 여기에 없는 것
|
||||
|
||||
- 실행되는 검증 스크립트는 문서가 아니다. `scripts/` 와 `.github/scripts/` 에 있다.
|
||||
- 모듈 레지스트리·Gradle 정책은 `src/config/architecture/modules.json` 과 `src/build.gradle` 이 소유한다.
|
||||
- 각 모듈의 지역 규칙은 해당 모듈의 `src/**/CLAUDE.md` 가 소유한다.
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- **Status:** Accepted
|
||||
- **Date:** 2026-08-13
|
||||
- **Design source:** `mongodb-superpowers-package/.../2026-08-11-mongodb-document-persistence-platform-design.md` §1, §2 (D-01, D-04, D-05), §5, §6
|
||||
- **Design source:** `docs/superpowers/specs/2026-08-11-mongodb-document-persistence-platform-design.md` §1, §2 (D-01, D-04, D-05), §5, §6
|
||||
|
||||
## Context
|
||||
|
||||
|
||||
@@ -74,6 +74,7 @@ where encryption and sharding are both expensive to reverse.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
bash scripts/verify-mongodb-advanced.sh
|
||||
```
|
||||
`scripts/verify-mongodb-advanced.sh` enforced this ADR until it was removed on 2026-08-15. The
|
||||
promotion evidence categories this ADR requires are therefore no longer checked by any automated
|
||||
gate; they are a review obligation until one is rebuilt. See `docs/mongodb/repository-adaptation.md`
|
||||
§5 for the Gradle lanes the script wrapped.
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
# split into capability artifacts.
|
||||
# Update only after review with:
|
||||
# ./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange
|
||||
# types: 391
|
||||
# types: 395
|
||||
dev.caskeleton.adapter.inbound.graphql.HealthGraphqlController
|
||||
dev.caskeleton.adapter.inbound.graphql.advanced.admin.GraphQlAdminPrincipal
|
||||
dev.caskeleton.adapter.inbound.graphql.advanced.admin.GraphQlPersistedOperationAdminAuthorization
|
||||
@@ -84,7 +84,7 @@ dev.caskeleton.adapter.inbound.graphql.advanced.persisted.OperationalStoreGraphQ
|
||||
dev.caskeleton.adapter.inbound.graphql.advanced.release.GraphQlAdvancedCompatibilityMatrix
|
||||
dev.caskeleton.adapter.inbound.graphql.advanced.release.GraphQlAdvancedPromotionDecision
|
||||
dev.caskeleton.adapter.inbound.graphql.advanced.release.GraphQlAdvancedReleaseEvidence
|
||||
dev.caskeleton.adapter.inbound.graphql.advanced.release.GraphQlAdvancedReleaseFailure
|
||||
dev.caskeleton.adapter.inbound.graphql.advanced.release.GraphQlAdvancedReleaseException
|
||||
dev.caskeleton.adapter.inbound.graphql.advanced.release.GraphQlAdvancedReleaseGate
|
||||
dev.caskeleton.adapter.inbound.graphql.advanced.release.GraphQlAdvancedRunbookIndex
|
||||
dev.caskeleton.adapter.inbound.graphql.advanced.release.GraphQlAdvancedSoakScenario
|
||||
@@ -137,7 +137,7 @@ dev.caskeleton.adapter.inbound.graphql.advanced.websocket.GraphQlWebSocketConnec
|
||||
dev.caskeleton.adapter.inbound.graphql.advanced.websocket.GraphQlWebSocketLifecycle
|
||||
dev.caskeleton.adapter.inbound.graphql.advanced.websocket.GraphQlWebSocketProperties
|
||||
dev.caskeleton.adapter.inbound.graphql.advanced.websocket.GraphQlWebSocketProtocol
|
||||
dev.caskeleton.adapter.inbound.graphql.advanced.websocket.GraphQlWebSocketProtocolError
|
||||
dev.caskeleton.adapter.inbound.graphql.advanced.websocket.GraphQlWebSocketProtocolException
|
||||
dev.caskeleton.adapter.inbound.graphql.api.GraphQlClientProfile
|
||||
dev.caskeleton.adapter.inbound.graphql.api.GraphQlClientProfileName
|
||||
dev.caskeleton.adapter.inbound.graphql.api.GraphQlOperationId
|
||||
@@ -152,14 +152,18 @@ dev.caskeleton.adapter.inbound.graphql.architecture.GraphQlResolverBoundaryRules
|
||||
dev.caskeleton.adapter.inbound.graphql.architecture.GraphQlReturnTypePolicy
|
||||
dev.caskeleton.adapter.inbound.graphql.architecture.GraphQlTransportTypeRules
|
||||
dev.caskeleton.adapter.inbound.graphql.architecture.GraphQlTypeGraph
|
||||
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlActivationEnvironmentPostProcessor
|
||||
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlDeploymentMode
|
||||
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlOffAutoConfigurationImportFilter
|
||||
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformActuatorEndpoint
|
||||
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformAutoConfiguration
|
||||
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformConfigurationException
|
||||
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformConfigurationReport
|
||||
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformEnvironment
|
||||
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformProperties
|
||||
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformRuntime
|
||||
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformSettings
|
||||
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlPlatformStartupValidator
|
||||
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlRetiredSafetyAxis
|
||||
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlRootAutoConfiguration
|
||||
dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlRuntimeTransport
|
||||
dev.caskeleton.adapter.inbound.graphql.compat.GraphQlChangeKind
|
||||
dev.caskeleton.adapter.inbound.graphql.compat.GraphQlClientOwnerApproval
|
||||
@@ -195,8 +199,8 @@ dev.caskeleton.adapter.inbound.graphql.cost.GraphQlResponseNodeCounter
|
||||
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlRuntimeBudget
|
||||
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlRuntimeBudgetExceededException
|
||||
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlRuntimeBudgetTracker
|
||||
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlStructuralLimitException
|
||||
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlStructuralLimitPolicy
|
||||
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlStructuralLimitViolation
|
||||
dev.caskeleton.adapter.inbound.graphql.cost.GraphQlStructuralLimits
|
||||
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchChunker
|
||||
dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchContext
|
||||
@@ -333,7 +337,7 @@ dev.caskeleton.adapter.inbound.graphql.release.GraphQlCompatibilityMatrix
|
||||
dev.caskeleton.adapter.inbound.graphql.release.GraphQlFaultScenario
|
||||
dev.caskeleton.adapter.inbound.graphql.release.GraphQlPerformanceScenario
|
||||
dev.caskeleton.adapter.inbound.graphql.release.GraphQlReleaseEvidence
|
||||
dev.caskeleton.adapter.inbound.graphql.release.GraphQlReleaseFailure
|
||||
dev.caskeleton.adapter.inbound.graphql.release.GraphQlReleaseException
|
||||
dev.caskeleton.adapter.inbound.graphql.release.GraphQlReleaseGate
|
||||
dev.caskeleton.adapter.inbound.graphql.release.GraphQlReleaseOverride
|
||||
dev.caskeleton.adapter.inbound.graphql.release.GraphQlReleaseReportWriter
|
||||
|
||||
@@ -5,10 +5,11 @@
|
||||
# root yet.
|
||||
# Update only after review with:
|
||||
# ./gradlew :adapter:outbound:persistence-mongo:updateMongoApiSurface -PapproveMongoApiSurfaceChange
|
||||
# types: 341
|
||||
# types: 343
|
||||
dev.caskeleton.adapter.outbound.mongo.MongoOptInAutoConfigurationImportFilter
|
||||
dev.caskeleton.adapter.outbound.mongo.MongoPersistenceConfig
|
||||
dev.caskeleton.adapter.outbound.mongo.MongoPersistenceProperties
|
||||
dev.caskeleton.adapter.outbound.mongo.MongoPersistenceSettings
|
||||
dev.caskeleton.adapter.outbound.mongo.MongoRootAutoConfiguration
|
||||
dev.caskeleton.adapter.outbound.mongo.advanced.MongoAdvancedCapabilityFlags
|
||||
dev.caskeleton.adapter.outbound.mongo.advanced.MongoAdvancedCapabilityGuard
|
||||
dev.caskeleton.adapter.outbound.mongo.advanced.MongoAdvancedEntryPoint
|
||||
@@ -16,7 +17,7 @@ dev.caskeleton.adapter.outbound.mongo.advanced.MongoAdvancedPolicy
|
||||
dev.caskeleton.adapter.outbound.mongo.advanced.MongoAdvancedPromotionEvidence
|
||||
dev.caskeleton.adapter.outbound.mongo.advanced.MongoAdvancedPromotionGate
|
||||
dev.caskeleton.adapter.outbound.mongo.advanced.autoconfigure.MongoAdvancedConfiguration
|
||||
dev.caskeleton.adapter.outbound.mongo.advanced.autoconfigure.MongoAdvancedProperties
|
||||
dev.caskeleton.adapter.outbound.mongo.advanced.autoconfigure.MongoAdvancedSettings
|
||||
dev.caskeleton.adapter.outbound.mongo.advanced.bridge.MongoBridgeCheckpointPolicy
|
||||
dev.caskeleton.adapter.outbound.mongo.advanced.bridge.MongoBridgeOutboxPolicy
|
||||
dev.caskeleton.adapter.outbound.mongo.advanced.bridge.MongoChangeMessagingBridge
|
||||
@@ -143,7 +144,7 @@ dev.caskeleton.adapter.outbound.mongo.autoconfigure.MongoClientGenerationRegistr
|
||||
dev.caskeleton.adapter.outbound.mongo.autoconfigure.MongoDriverObservabilityAutoConfiguration
|
||||
dev.caskeleton.adapter.outbound.mongo.autoconfigure.MongoPlatformAutoConfiguration
|
||||
dev.caskeleton.adapter.outbound.mongo.autoconfigure.MongoPlatformHealthIndicator
|
||||
dev.caskeleton.adapter.outbound.mongo.autoconfigure.MongoPlatformProperties
|
||||
dev.caskeleton.adapter.outbound.mongo.autoconfigure.MongoPlatformSettings
|
||||
dev.caskeleton.adapter.outbound.mongo.autoconfigure.MongoProfileProperties
|
||||
dev.caskeleton.adapter.outbound.mongo.autoconfigure.MongoStableReleaseEvidence
|
||||
dev.caskeleton.adapter.outbound.mongo.autoconfigure.MongoStableReleaseGate
|
||||
@@ -166,6 +167,7 @@ dev.caskeleton.adapter.outbound.mongo.changestream.recovery.MongoChangeHistoryLo
|
||||
dev.caskeleton.adapter.outbound.mongo.changestream.recovery.MongoChangeStreamRecoveryDecision
|
||||
dev.caskeleton.adapter.outbound.mongo.changestream.recovery.MongoChangeStreamRecoveryPolicy
|
||||
dev.caskeleton.adapter.outbound.mongo.changestream.recovery.MongoInvalidateRecovery
|
||||
dev.caskeleton.adapter.outbound.mongo.client.MongoClientSettingsFactory
|
||||
dev.caskeleton.adapter.outbound.mongo.failure.DefaultMongoFailureClassifier
|
||||
dev.caskeleton.adapter.outbound.mongo.failure.DefaultMongoFailureTranslator
|
||||
dev.caskeleton.adapter.outbound.mongo.failure.MongoDriverFailureView
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# HTTP Client Platform — Repository Adaptation Contract
|
||||
|
||||
**Design source:** `httpclient-superpowers-package/docs/superpowers/specs/2026-08-08-httpclient-platform-design.md`
|
||||
**Plan source:** `httpclient-superpowers-package/docs/superpowers/plans/2026-08-08-httpclient-platform-implementation-plan.md`
|
||||
**Design source:** `docs/superpowers/specs/2026-08-08-httpclient-platform-design.md`
|
||||
**Plan source:** `docs/superpowers/plans/2026-08-08-httpclient-platform-implementation-plan.md`
|
||||
|
||||
The design package states its own adaptation rule:
|
||||
|
||||
|
||||
@@ -1,11 +1,8 @@
|
||||
# JPA Relational Persistence Platform — Repository Adaptation Contract
|
||||
|
||||
**Design source:** `jpa-superpowers-package/docs/superpowers/specs/2026-08-11-jpa-persistence-platform-design.md`
|
||||
(copied to `docs/superpowers/specs/`)
|
||||
**Stable plan source:** `jpa-superpowers-package/docs/superpowers/plans/2026-08-11-jpa-persistence-platform-implementation-plan.md`
|
||||
(copied to `docs/superpowers/plans/`)
|
||||
**Experimental plan source:** `jpa-superpowers-package/docs/superpowers/plans/2026-08-11-jpa-persistence-experimental-expansion-plan.md`
|
||||
(copied to `docs/superpowers/plans/`)
|
||||
**Design source:** `docs/superpowers/specs/2026-08-11-jpa-persistence-platform-design.md`
|
||||
**Stable plan source:** `docs/superpowers/plans/2026-08-11-jpa-persistence-platform-implementation-plan.md`
|
||||
**Experimental plan source:** `docs/superpowers/plans/2026-08-11-jpa-persistence-experimental-expansion-plan.md`
|
||||
|
||||
The design package states its own adaptation rule (§3.2): the assumed package paths and Gradle
|
||||
structure are explicit implementation *assumptions* made because the real Backend Skeleton
|
||||
|
||||
@@ -11,7 +11,7 @@
|
||||
| Topology | A real sharded cluster. A replica set cannot exercise routing. |
|
||||
| Server | MongoDB 7.0 or 8.0. |
|
||||
| Privilege | `MongoPrincipalRole.SHARD_ADMIN` for the admin plane; the application role is unchanged. |
|
||||
| Gate | `mongoShardedTest` lane with `MongoShardingContractSuite`. |
|
||||
| Gate | **Not promoted.** No `mongoShardedTest` lane is registered, and a sharded cluster is not an environment this repository stands up. Listed under `experimental_contracts` in `src/config/mongodb/release-contracts.json`; promoting it needs the lane, its required class, and protected-environment evidence to exist first. |
|
||||
|
||||
## Shard key
|
||||
|
||||
|
||||
@@ -1,6 +1,10 @@
|
||||
# Advanced capability sign-off
|
||||
|
||||
`scripts/verify-mongodb-advanced.sh` treats a file in this directory as the evidence that a review
|
||||
> **2026-08-15:** `scripts/verify-mongodb-advanced.sh` was removed, so nothing reads this directory
|
||||
> automatically any more. The files below are still the record that a review happened, but a missing
|
||||
> one no longer fails anything — a human has to check for it during promotion.
|
||||
|
||||
`scripts/verify-mongodb-advanced.sh` treated a file in this directory as the evidence that a review
|
||||
happened:
|
||||
|
||||
- `security.md` — per-capability privilege review, naming the roles granted and by whom.
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# MongoDB Document Persistence Platform — Repository Adaptation Contract
|
||||
|
||||
**Design source:** `mongodb-superpowers-package/docs/superpowers/specs/2026-08-11-mongodb-document-persistence-platform-design.md`
|
||||
**Stable plan:** `mongodb-superpowers-package/docs/superpowers/plans/2026-08-11-mongodb-document-persistence-platform-implementation-plan.md`
|
||||
**Advanced plan:** `mongodb-superpowers-package/docs/superpowers/plans/2026-08-11-mongodb-advanced-capabilities-expansion-plan.md`
|
||||
**Design source:** `docs/superpowers/specs/2026-08-11-mongodb-document-persistence-platform-design.md`
|
||||
**Stable plan:** `docs/superpowers/plans/2026-08-11-mongodb-document-persistence-platform-implementation-plan.md`
|
||||
**Advanced plan:** `docs/superpowers/plans/2026-08-11-mongodb-advanced-capabilities-expansion-plan.md`
|
||||
|
||||
The design package declares its own module root (`modules/mongodb`) and root package
|
||||
(`io.backend.skeleton.mongodb`) as *implementation assumptions*, not as contract. This file is the
|
||||
@@ -96,7 +96,7 @@ otherwise. Being on the classpath is not being enabled.
|
||||
| `mongodb-migration-flamingock` depends on Flamingock | Adding an unvetted external dependency is out of scope for this task, and the design itself requires the public contract not to depend on Flamingock types | The adapter is provider-neutral: it consumes a platform-owned `FlamingockChangeUnitView`. Wiring an actual Flamingock distribution is a one-file change behind that view. |
|
||||
| Testkit as its own Gradle module | The design forbids production modules depending on the testkit | A dedicated `testkit` source set whose output is on the test compile/runtime classpaths only. ArchUnit rule `productionNeverDependsOnTestkit` enforces the direction. |
|
||||
| Per-task `git commit` | `AGENTS.md`: commit policy is `human-only` | Implementation is delivered unstaged; commits are the human's action. This is the only plan step intentionally not executed, and it is recorded here. |
|
||||
| `docs/mongodb/**`, `scripts/verify-mongodb-*.sh` | Repository already owns `docs/` and `scripts/` | Created at the same repository-relative paths. |
|
||||
| `docs/mongodb/**`, `scripts/verify-mongodb-*.sh` | Repository already owns `docs/` and `scripts/` | Created at the same repository-relative paths. The two gate scripts were later removed (2026-08-15); see §5. |
|
||||
|
||||
## 4. What is unchanged from the design
|
||||
|
||||
@@ -124,9 +124,21 @@ otherwise. Being on the classpath is not being enabled.
|
||||
|
||||
## 5. Verification
|
||||
|
||||
The two release-gate scripts (`scripts/verify-mongodb-platform.sh` and
|
||||
`scripts/verify-mongodb-advanced.sh`) were removed on 2026-08-15. They wrapped the Gradle lanes below
|
||||
and added two things Gradle does not do on its own: a lane that executed zero tests was reported as a
|
||||
failure rather than counted as a pass, and a `promotion.json` recording the commit, server image and
|
||||
contract-manifest hash. Neither exists until something replaces it, so a green run of the commands
|
||||
below is weaker evidence than the gate was.
|
||||
|
||||
From `src/`:
|
||||
|
||||
```bash
|
||||
bash scripts/verify-mongodb-platform.sh # Stable gate
|
||||
bash scripts/verify-mongodb-advanced.sh # Advanced gate (opt-in lanes)
|
||||
./gradlew :adapter:outbound:persistence-mongo:check --console=plain
|
||||
./gradlew verifyCleanArchitectureDependencies --console=plain
|
||||
./gradlew :app-bootstrap:test --tests '*CleanArchitectureTest' --console=plain
|
||||
```
|
||||
|
||||
Both scripts run from the repository root and delegate to `src/gradlew`.
|
||||
The container-backed lanes the gate ran behind `MONGODB_DOCKER=1` — `mongoCompatibilityTest`,
|
||||
`mongoMigrationTest`, `mongoSecurityIntegrationTest`, `mongoReplicaSetTest`, `mongoFailoverTest`,
|
||||
`mongoPerformanceTest` — are now invoked by name or not at all.
|
||||
|
||||
@@ -0,0 +1,116 @@
|
||||
# Notification payload at rest — threat model and decision (NTF-INT-007)
|
||||
|
||||
Wave 2 Task D6 offers two branches and requires that one be chosen and implemented fully:
|
||||
|
||||
- **(a) encryption** — a codec/port, ciphertext envelope, key id, rotation and history, row migration,
|
||||
and a decryption-failure contract;
|
||||
- **(b) restriction** — this document plus a static restriction proving the variable types cannot
|
||||
carry sensitive values.
|
||||
|
||||
The plan recommends (b) **"if and only if the variable types can genuinely be restricted to
|
||||
non-sensitive values"**. They cannot. This document records why, what that leaves, and when the
|
||||
remaining branch lands.
|
||||
|
||||
## What is stored, and where
|
||||
|
||||
`CanonicalNotificationPlanWriter.request(...)` puts `encoded.variablesPayload()` into
|
||||
`NotificationRequestRecord` verbatim. `JpaNotificationRequestStore` writes that record to
|
||||
`notification_request.variables_payload` with no transformation. There is no encryption anywhere on
|
||||
this path.
|
||||
|
||||
## Why the restriction branch is unavailable
|
||||
|
||||
Template variables are a closed algebra — `NotificationVariable` permits `TextValue`, `NumberValue`,
|
||||
`BooleanValue`, `NullValue`, `ListValue`, `ObjectValue` — which is a real improvement over the
|
||||
`Map<String, Object>` it replaced. But `TextValue` holds an arbitrary UTF-8 string of up to 8 KiB,
|
||||
and that is not an oversight to be tightened: **the variables are the recipient-specific content of
|
||||
the message**. A password-reset code, an order total, a delivery address, a patient's appointment
|
||||
time — those are what a notification is for.
|
||||
|
||||
A restriction to "non-sensitive values" would therefore be one of two things, and both are worse
|
||||
than the problem:
|
||||
|
||||
- **unenforceable** — a comment saying callers should not put sensitive data in a field designed to
|
||||
carry the message's content, which is a policy no type checks and no reviewer can see violated;
|
||||
- **enforced and useless** — a type that refuses free text, which does not restrict the capability so
|
||||
much as delete it.
|
||||
|
||||
The precondition on the plan's recommendation is false. Branch (b) is not available.
|
||||
|
||||
> **Status: branch (a) implemented at the storage boundary.** `NotificationPayloadProtection` is the
|
||||
> application-owned port, `AesGcmNotificationPayloadProtection` the AES-GCM implementation, and
|
||||
> `NotificationRecordMapper` applies it — as a **required** constructor argument, so a composition
|
||||
> cannot assemble the notification stores while leaving the payload in plaintext. What remains before
|
||||
> the facade can be imported is the row migration for any deployment that already has plaintext rows,
|
||||
> and the `local-notification-*` lanes. The analysis below is kept as written, because it is what the
|
||||
> decision rests on.
|
||||
|
||||
## Decision: branch (a), landing with the persistence wiring
|
||||
|
||||
Encryption is therefore the required branch. Its scope is unchanged from the plan: a codec behind an
|
||||
application port, a ciphertext envelope carrying its key id, key rotation with history so an old row
|
||||
stays readable, a migration for existing rows, and an explicit contract for what a decryption failure
|
||||
does to a request.
|
||||
|
||||
**It lands in the change unit that makes the write path reachable, and not before.** The reason is a
|
||||
fact the spec did not have: `NotificationJpaPersistenceFacade`, which assembles
|
||||
`JpaNotificationRequestStore`, is imported by nothing. The composition root's component scan excludes
|
||||
the persistence package by design, and no configuration imports the facade — so the notification
|
||||
capability has **no JPA persistence at all**, and no deployment currently writes this payload
|
||||
anywhere. The defect is real in the code and latent in the runtime.
|
||||
|
||||
Designing key rotation and a row migration for rows that no deployment produces would be building the
|
||||
migration before the table. Worse, it would settle the envelope's shape before the store that has to
|
||||
read it is wired, which is the order that produces an envelope the store cannot use.
|
||||
|
||||
**One correction, learned by trying it.** This section said the envelope "lands with the wiring".
|
||||
Wiring the facade first — to register the SMTP assembler — made
|
||||
`NotificationPayloadAtRestContractTest` fail on the case asserting the write path is reachable from
|
||||
no composition, which is exactly what that case is for. The wave forbids connecting wiring over a
|
||||
known security finding on a runtime path, so the wiring was reverted and the envelope built first.
|
||||
The honest ordering is **envelope before or with the wiring, never after**, and the contract test now
|
||||
enforces it by failing on the wiring alone.
|
||||
|
||||
### The envelope, and why it has a key id
|
||||
|
||||
```
|
||||
byte version always 1
|
||||
byte keyIdLength 1..255 UTF-8 bytes
|
||||
byte[] keyId
|
||||
byte[12] nonce
|
||||
byte[] ciphertext + GCM tag
|
||||
```
|
||||
|
||||
The key id is the reason there is a format at all. This repository's callback protection stores nonce
|
||||
and ciphertext and nothing else, so the day the active key changes, every row written under the
|
||||
previous one becomes unreadable and nothing in the row can say which key it needed — that is not a
|
||||
rotation story with a gap in it, it is the absence of one. `SecretMaterialProvider` already exposes
|
||||
`keyById`, so reading the id back and asking for that specific key makes rotation a change of default
|
||||
rather than a data migration. The version byte costs one byte and is what allows the format to change
|
||||
at all.
|
||||
|
||||
The header is passed as **AAD**, not merely prefixed: without that, the key id is attacker-editable
|
||||
and an envelope could be redirected at a key of the attacker's choosing.
|
||||
|
||||
A failed decryption throws `NotificationPayloadUnreadableException` rather than returning empty. A
|
||||
caller handed an empty payload renders every variable as nothing and sends "Hello , your code is " to
|
||||
a real person — the failure delivered instead of reported. All three causes (unknown key, wrong key,
|
||||
modified ciphertext) collapse into one message, because telling them apart tells an attacker which of
|
||||
the three they achieved.
|
||||
|
||||
## What must not be done instead
|
||||
|
||||
**Requiring `PAYLOAD_ENCRYPTION` in `INGEST_ONLY` is not a fix.** That secret is consumed by exactly
|
||||
one thing — `AesGcmCallbackPayloadProtection`, which protects raw callback bodies — and by nothing on
|
||||
the accept path. Demanding it would make a deployment supply a key that protects nothing while the
|
||||
payload it appears to be about stays in plaintext. The repository already has one defect of that
|
||||
exact shape: `backend.graphql.cursor.key-ids`, which production refuses to start without and which no
|
||||
code signs a cursor with (GQL-INT-003). Adding a second would make the pattern a habit.
|
||||
|
||||
## Consequence
|
||||
|
||||
Notification is **not promoted to Stable**, per the index's scope boundaries, until branch (a) is
|
||||
complete. The three notification Compose lanes stay non-blocking. `NotificationPayloadAtRestContractTest`
|
||||
holds every fact this decision rests on, so the decision expires automatically if any of them stops
|
||||
being true — in particular, the assertion that no encryption sits on the accept path fails the moment
|
||||
somebody adds one, which is the change this document is waiting for.
|
||||
@@ -15,7 +15,7 @@ when this page, the YAML tree and `docs/registries/env-keys.yaml` disagree.
|
||||
| Property | Environment variable | Default | Meaning |
|
||||
|---|---|---|---|
|
||||
| `enabled` | `APP_NOTIFICATION_PLATFORM_ENABLED` | `false` | Binds nothing at all while false: no runtime, no schema check, no scheduler thread, no secret required |
|
||||
| `mode` | `APP_NOTIFICATION_PLATFORM_MODE` | `SERVING` | `SERVING` refuses to start without a working provider; `ACCEPT_ONLY` stores requests and does not dispatch |
|
||||
| `mode` | `APP_NOTIFICATION_PLATFORM_MODE` | `SERVING` | `SERVING` refuses to start without a working provider; `INGEST_ONLY` stores requests and does not dispatch |
|
||||
|
||||
## Dispatch
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Notification Delivery Platform — module mapping
|
||||
|
||||
> Source design: `notification-superpowers-package/docs/superpowers/specs/2026-08-10-notification-platform-design.md`
|
||||
> Source design: `docs/superpowers/specs/2026-08-10-notification-platform-design.md`
|
||||
>
|
||||
> Source plan: `notification-superpowers-package/docs/superpowers/plans/2026-08-10-notification-platform-implementation-plan.md`
|
||||
> Source plan: `docs/superpowers/plans/2026-08-10-notification-platform-implementation-plan.md`
|
||||
|
||||
## Why a mapping exists
|
||||
|
||||
|
||||
+588
-11
@@ -20,12 +20,15 @@ env_keys:
|
||||
# === Profile / Identity (feature-env-driven-runtime-configuration) ===
|
||||
|
||||
- name: SPRING_PROFILES_ACTIVE
|
||||
# source: feature-env-driven-runtime-configuration D6 (2026-06-06)
|
||||
# Profile selector is Spring-native and sole (APP_PROFILE was dropped). Unset
|
||||
# -> local fallback in application.yml for early Boot profile binding.
|
||||
type: csv_list
|
||||
default: local
|
||||
allowed_values: [local, dev, staging, prod, sample]
|
||||
# source: feature-env-driven-runtime-configuration D6 (2026-06-06), amended by
|
||||
# five-adapter-runtime-remediation §7.1. Profile selector is Spring-native and sole
|
||||
# (APP_PROFILE was dropped). Exactly one value, not a CSV list: two environments cannot both
|
||||
# have their safety rules apply, and whichever lost did so silently.
|
||||
type: enum
|
||||
# No default. A profile that is guessed is a deployment nobody chose: a jar started
|
||||
# with none used to become local, which before persistence was gated also meant an
|
||||
# in-memory database that loses every write on restart.
|
||||
allowed_values: [local, dev, prod]
|
||||
classification: public-config
|
||||
required: true
|
||||
reload_policy: restart-only
|
||||
@@ -389,14 +392,19 @@ env_keys:
|
||||
- name: APP_DATASOURCE_CONNECTION_TIMEOUT
|
||||
# source: feature-env-driven-runtime-configuration "datasource/pool env"
|
||||
# + feature-persistence-failure-baseline "Hikari Alert Threshold: pool wait p99 > 100ms"
|
||||
type: duration
|
||||
default: 5s
|
||||
# unit: milliseconds. It feeds spring.datasource.hikari.connection-timeout, which binds onto
|
||||
# HikariConfig#setConnectionTimeout(long) — a duration shorthand such as "5s" does not bind and
|
||||
# fails the boot. This row said `duration` / `5s`, application.yml copied that default, and
|
||||
# every prod and dev deployment refused to start; five-adapter-runtime-remediation Wave 2 found
|
||||
# it in the prod-smoke lane. Corrected to what the property actually accepts.
|
||||
type: integer
|
||||
default: 5000
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: feature-env-driven-runtime-configuration
|
||||
validation: spring_duration_shorthand
|
||||
validation: positive_integer_milliseconds
|
||||
compatibility_impact: behavior-change
|
||||
required_test: env-contract:connection-timeout-set
|
||||
|
||||
@@ -4250,6 +4258,117 @@ env_keys:
|
||||
# default. Every key carries an inline default so a deployment that leaves the platform off
|
||||
# supplies nothing. Reference: docs/notification/configuration.md.
|
||||
|
||||
- name: APP_PERSISTENCE_JPA_ENABLED
|
||||
# source: five-adapter-runtime-remediation §5.1 — master switch for relational persistence.
|
||||
# false means no DataSource, no entity scan, no repositories, no Hibernate, no Flyway and no DB
|
||||
# health contributor; the old app.jpa-platform.enabled gated three add-on beans while reading
|
||||
# like this one and defaulting to on.
|
||||
type: boolean
|
||||
default: false
|
||||
allowed_values: [true, false]
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-five-adapter-activation
|
||||
validation: boolean
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:persistence-jpa-disabled-safe
|
||||
- name: APP_PERSISTENCE_MONGO_ENABLED
|
||||
# source: five-adapter-runtime-remediation §5.1 — master switch for MongoDB persistence.
|
||||
type: boolean
|
||||
default: false
|
||||
allowed_values: [true, false]
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-five-adapter-activation
|
||||
validation: boolean
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:persistence-mongo-disabled-safe
|
||||
- name: APP_PERSISTENCE_MONGO_ACTIVE_PROFILE
|
||||
# source: five-adapter-runtime-remediation §5.1 — selects exactly one Mongo profile. The runtime
|
||||
# builds one sync client and one pool; a profile present in the map but not selected has neither
|
||||
# its secret resolved nor a client created.
|
||||
type: string
|
||||
default: ""
|
||||
classification: public-config
|
||||
required: false
|
||||
required_when: APP_PERSISTENCE_MONGO_ENABLED=true
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-five-adapter-activation
|
||||
validation: nonblank-when-required
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:persistence-mongo-active-profile
|
||||
- name: APP_MESSAGING_ENABLED
|
||||
# source: five-adapter-runtime-remediation §5.1 — master switch for broker publication.
|
||||
# APP_MESSAGING_BROKER selects which transport and is no longer the de-facto switch.
|
||||
type: boolean
|
||||
default: false
|
||||
allowed_values: [true, false]
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-five-adapter-activation
|
||||
validation: boolean
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:messaging-disabled-safe
|
||||
- name: APP_GRAPHQL_ENABLED
|
||||
# source: five-adapter-runtime-remediation §5.1 — master switch for the GraphQL transport.
|
||||
# false publishes no /graphql route, including the one Spring GraphQL would publish by itself.
|
||||
type: boolean
|
||||
default: false
|
||||
allowed_values: [true, false]
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-five-adapter-activation
|
||||
validation: boolean
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:graphql-disabled-safe
|
||||
- name: APP_GRAPHQL_DEPLOYMENT_MODE
|
||||
# source: five-adapter-runtime-remediation §5.1 / GQL-INT-002 — replaces backend.graphql.production
|
||||
# and backend.graphql.environment, which defaulted to production=false with
|
||||
# environment=PRODUCTION_PUBLIC and let anonymous-principal and allow-by-default authorization
|
||||
# read one axis while the other claimed production.
|
||||
type: enum
|
||||
default: ""
|
||||
allowed_values: [LOCAL, DEV, PRODUCTION_INTERNAL, PRODUCTION_PUBLIC]
|
||||
classification: public-config
|
||||
required: false
|
||||
required_when: APP_GRAPHQL_ENABLED=true
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-five-adapter-activation
|
||||
validation: enum
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:graphql-deployment-mode
|
||||
- name: APP_OUTBOX_ENABLED
|
||||
# source: five-adapter-runtime-remediation §6.1 JPA-INT-004 — the outbox capability switch.
|
||||
# relay-enabled below only starts the scheduler; conflating the two meant a relay-off deployment
|
||||
# still assembled outbox metrics over a store port a database-less runtime does not have.
|
||||
type: boolean
|
||||
default: false
|
||||
allowed_values: [true, false]
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-five-adapter-activation
|
||||
validation: boolean
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:outbox-capability-disabled-safe
|
||||
- name: APP_OUTBOX_RELAY_ENABLED
|
||||
# source: five-adapter-runtime-remediation §6.3 MSG-INT-001 — starts the relay scheduler.
|
||||
# Requires APP_OUTBOX_ENABLED, APP_PERSISTENCE_JPA_ENABLED and APP_MESSAGING_ENABLED with a
|
||||
# broker; the shipped default was true beside a blank broker, which refused every startup.
|
||||
type: boolean
|
||||
default: false
|
||||
allowed_values: [true, false]
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-five-adapter-activation
|
||||
validation: boolean
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:outbox-relay-dependency
|
||||
- name: APP_NOTIFICATION_PLATFORM_ENABLED
|
||||
# source: NTF-025 — master switch for the notification delivery platform; false binds nothing at all
|
||||
type: boolean
|
||||
@@ -4263,11 +4382,469 @@ env_keys:
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-platform-disabled-safe
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY
|
||||
# source: NTF-INT-007 — Encrypts recipient contact points at rest — addresses and phone numbers.
|
||||
# Full row owned by secrets-classification.yaml. Bound by
|
||||
# ca-skeleton.notification.platform.secrets.contact-encryption-key; the platform decodes it at startup and
|
||||
# refuses to boot if it is blank, shorter than 32 bytes, or equal to another purpose's key.
|
||||
type: string
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: secret
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: base64_at_least_32_bytes_and_distinct_per_purpose
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-secret-material-required
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY
|
||||
# source: NTF-INT-007 — Blind index over contact points, so a lookup never needs the plaintext.
|
||||
# Full row owned by secrets-classification.yaml. Bound by
|
||||
# ca-skeleton.notification.platform.secrets.contact-lookup-hmac-key; the platform decodes it at startup and
|
||||
# refuses to boot if it is blank, shorter than 32 bytes, or equal to another purpose's key.
|
||||
type: string
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: secret
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: base64_at_least_32_bytes_and_distinct_per_purpose
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-secret-material-required
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY
|
||||
# source: NTF-INT-007 — Signs the callback URLs a provider posts delivery outcomes back to.
|
||||
# Full row owned by secrets-classification.yaml. Bound by
|
||||
# ca-skeleton.notification.platform.secrets.callback-signing-key; the platform decodes it at startup and
|
||||
# refuses to boot if it is blank, shorter than 32 bytes, or equal to another purpose's key.
|
||||
type: string
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: secret
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: base64_at_least_32_bytes_and_distinct_per_purpose
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-secret-material-required
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY
|
||||
# source: NTF-INT-007 — Encrypts stored provider credentials, which are themselves secrets.
|
||||
# Full row owned by secrets-classification.yaml. Bound by
|
||||
# ca-skeleton.notification.platform.secrets.provider-credential-key; the platform decodes it at startup and
|
||||
# refuses to boot if it is blank, shorter than 32 bytes, or equal to another purpose's key.
|
||||
type: string
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: secret
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: base64_at_least_32_bytes_and_distinct_per_purpose
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-secret-material-required
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY
|
||||
# source: NTF-INT-007 — Encrypts notification variables and retained callback bodies at rest.
|
||||
# Full row owned by secrets-classification.yaml. Bound by
|
||||
# ca-skeleton.notification.platform.secrets.payload-encryption-key; the platform decodes it at startup and
|
||||
# refuses to boot if it is blank, shorter than 32 bytes, or equal to another purpose's key.
|
||||
type: string
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: secret
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: base64_at_least_32_bytes_and_distinct_per_purpose
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-secret-material-required
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY
|
||||
# source: NTF-INT-007 — Signs Web Push requests; the browser push service rejects anything else.
|
||||
# Full row owned by secrets-classification.yaml. Bound by
|
||||
# ca-skeleton.notification.platform.secrets.vapid-signing-key; the platform decodes it at startup and
|
||||
# refuses to boot if it is blank, shorter than 32 bytes, or equal to another purpose's key.
|
||||
type: string
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: secret
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: base64_at_least_32_bytes_and_distinct_per_purpose
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-secret-material-required
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY
|
||||
# source: NTF-INT-007 — Keyed hash of provider request ids, which are provider-side identifiers.
|
||||
# Full row owned by secrets-classification.yaml. Bound by
|
||||
# ca-skeleton.notification.platform.secrets.provider-request-lookup-hmac-key; the platform decodes it at startup and
|
||||
# refuses to boot if it is blank, shorter than 32 bytes, or equal to another purpose's key.
|
||||
type: string
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: secret
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: base64_at_least_32_bytes_and_distinct_per_purpose
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-secret-material-required
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY
|
||||
# source: NTF-INT-007 — Keyed fingerprint of callback bodies, used to detect replays.
|
||||
# Full row owned by secrets-classification.yaml. Bound by
|
||||
# ca-skeleton.notification.platform.secrets.callback-fingerprint-hmac-key; the platform decodes it at startup and
|
||||
# refuses to boot if it is blank, shorter than 32 bytes, or equal to another purpose's key.
|
||||
type: string
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: secret
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: base64_at_least_32_bytes_and_distinct_per_purpose
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-secret-material-required
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY_ID
|
||||
# source: NTF-INT-007 — the id written into every envelope the CONTACT_ENCRYPTION key produces.
|
||||
# An identifier, not key material, so it is public-config; the material itself is the
|
||||
# APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY row above. Bound into
|
||||
# ca-skeleton.notification.platform.secrets.active-key-ids.CONTACT_ENCRYPTION.
|
||||
type: string
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: non_blank_when_platform_enabled
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-secret-material-required
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY_ID
|
||||
# source: NTF-INT-007 — the id written into every envelope the CONTACT_LOOKUP_HMAC key produces.
|
||||
# An identifier, not key material, so it is public-config; the material itself is the
|
||||
# APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY row above. Bound into
|
||||
# ca-skeleton.notification.platform.secrets.active-key-ids.CONTACT_LOOKUP_HMAC.
|
||||
type: string
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: non_blank_when_platform_enabled
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-secret-material-required
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY_ID
|
||||
# source: NTF-INT-007 — the id written into every envelope the CALLBACK_SIGNING key produces.
|
||||
# An identifier, not key material, so it is public-config; the material itself is the
|
||||
# APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY row above. Bound into
|
||||
# ca-skeleton.notification.platform.secrets.active-key-ids.CALLBACK_SIGNING.
|
||||
type: string
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: non_blank_when_platform_enabled
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-secret-material-required
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY_ID
|
||||
# source: NTF-INT-007 — the id written into every envelope the PROVIDER_CREDENTIAL key produces.
|
||||
# An identifier, not key material, so it is public-config; the material itself is the
|
||||
# APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY row above. Bound into
|
||||
# ca-skeleton.notification.platform.secrets.active-key-ids.PROVIDER_CREDENTIAL.
|
||||
type: string
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: non_blank_when_platform_enabled
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-secret-material-required
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY_ID
|
||||
# source: NTF-INT-007 — the id written into every envelope the PAYLOAD_ENCRYPTION key produces.
|
||||
# An identifier, not key material, so it is public-config; the material itself is the
|
||||
# APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY row above. Bound into
|
||||
# ca-skeleton.notification.platform.secrets.active-key-ids.PAYLOAD_ENCRYPTION.
|
||||
type: string
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: non_blank_when_platform_enabled
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-secret-material-required
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY_ID
|
||||
# source: NTF-INT-007 — the id written into every envelope the VAPID_SIGNING key produces.
|
||||
# An identifier, not key material, so it is public-config; the material itself is the
|
||||
# APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY row above. Bound into
|
||||
# ca-skeleton.notification.platform.secrets.active-key-ids.VAPID_SIGNING.
|
||||
type: string
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: non_blank_when_platform_enabled
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-secret-material-required
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY_ID
|
||||
# source: NTF-INT-007 — the id written into every envelope the PROVIDER_REQUEST_LOOKUP_HMAC key produces.
|
||||
# An identifier, not key material, so it is public-config; the material itself is the
|
||||
# APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY row above. Bound into
|
||||
# ca-skeleton.notification.platform.secrets.active-key-ids.PROVIDER_REQUEST_LOOKUP_HMAC.
|
||||
type: string
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: non_blank_when_platform_enabled
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-secret-material-required
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY_ID
|
||||
# source: NTF-INT-007 — the id written into every envelope the CALLBACK_FINGERPRINT_HMAC key produces.
|
||||
# An identifier, not key material, so it is public-config; the material itself is the
|
||||
# APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY row above. Bound into
|
||||
# ca-skeleton.notification.platform.secrets.active-key-ids.CALLBACK_FINGERPRINT_HMAC.
|
||||
type: string
|
||||
default: null
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: non_blank_when_platform_enabled
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-secret-material-required
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_SMTP_ENABLED
|
||||
# source: NTF-INT-001 — master switch of the shipped SMTP provider profile; false means assembly skips it entirely.
|
||||
type: boolean
|
||||
default: false
|
||||
allowed_values: [true, false]
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: boolean
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-smtp-provider-assembled
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_SMTP_PRIMARY
|
||||
# source: NTF-INT-001 — whether this profile is the primary route for EMAIL; exactly one primary per channel.
|
||||
type: boolean
|
||||
default: true
|
||||
allowed_values: [true, false]
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: boolean
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-smtp-provider-assembled
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_SMTP_ENVIRONMENT
|
||||
# source: NTF-INT-001 — the profile's declared environment, carried on every dispatch record.
|
||||
type: string
|
||||
default: local
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: non_blank
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-smtp-provider-assembled
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_SMTP_CREDENTIAL_PROFILE
|
||||
# source: NTF-INT-001 — the credential profile the relay's credentials are resolved through.
|
||||
type: string
|
||||
default: default
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: non_blank
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-smtp-provider-assembled
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_SMTP_TIMEOUT
|
||||
# source: NTF-INT-001 — per-attempt provider timeout for this profile.
|
||||
type: duration
|
||||
default: 10s
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: duration_spring_shorthand
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-smtp-provider-assembled
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_SMTP_MAX_CONCURRENCY
|
||||
# source: NTF-INT-001 — how many attempts this profile may have in flight.
|
||||
type: int
|
||||
default: 4
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: positive_int
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-smtp-provider-assembled
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_SMTP_RATE_PER_SECOND
|
||||
# source: NTF-INT-001 — the profile's attempt rate limit.
|
||||
type: int
|
||||
default: 10
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: positive_int
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-smtp-provider-assembled
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_SMTP_TLS_MODE
|
||||
# source: NTF-INT-001 — transport security of the SMTP session; the type has no plaintext member.
|
||||
type: enum
|
||||
default: STARTTLS_REQUIRED
|
||||
allowed_values: [STARTTLS_REQUIRED, IMPLICIT_TLS]
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: enum_in_allowed_values
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-smtp-provider-assembled
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_SMTP_SENDER_IDENTITY
|
||||
# source: NTF-INT-001 — the envelope sender every message is sent as.
|
||||
type: string
|
||||
default: no-reply@example.invalid
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: email_address
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-smtp-provider-assembled
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_SMTP_CONNECT_TIMEOUT
|
||||
# source: NTF-INT-001 — how long a connection attempt to the relay may take.
|
||||
type: duration
|
||||
default: 5s
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: duration_spring_shorthand
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-smtp-provider-assembled
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_SMTP_READ_TIMEOUT
|
||||
# source: NTF-INT-001 — how long a relay reply may take.
|
||||
type: duration
|
||||
default: 10s
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: duration_spring_shorthand
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-smtp-provider-assembled
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_SMTP_WRITE_TIMEOUT
|
||||
# source: NTF-INT-001 — how long a write to the relay may take.
|
||||
type: duration
|
||||
default: 10s
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: duration_spring_shorthand
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-smtp-provider-assembled
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY
|
||||
# source: NTF-INT-001 — size of the bounded executor SMTP sends run on.
|
||||
type: int
|
||||
default: 4
|
||||
allowed_values: null
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: worktree-notification-platform
|
||||
validation: positive_int
|
||||
compatibility_impact: behavior-change
|
||||
required_test: adapter-contract:notification-smtp-provider-assembled
|
||||
|
||||
- name: APP_OPENAPI_DOCS_ENABLED
|
||||
# source: five-adapter-runtime-remediation §9 — whether /v3/api-docs is served; application-prod.yml pins it false. Stated rather than defaulted because
|
||||
# SpringDoc warns on every startup until a deployment decides, and a warning on every start is
|
||||
# one nobody reads.
|
||||
type: boolean
|
||||
default: true
|
||||
allowed_values: [true, false]
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: main
|
||||
validation: boolean
|
||||
compatibility_impact: behavior-change
|
||||
required_test: env-contract:openapi-exposure-decided
|
||||
|
||||
- name: APP_OPENAPI_UI_ENABLED
|
||||
# source: five-adapter-runtime-remediation §9 — whether the Swagger UI is served; application-prod.yml pins it false. Stated rather than defaulted because
|
||||
# SpringDoc warns on every startup until a deployment decides, and a warning on every start is
|
||||
# one nobody reads.
|
||||
type: boolean
|
||||
default: true
|
||||
allowed_values: [true, false]
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
owner_branch: main
|
||||
validation: boolean
|
||||
compatibility_impact: behavior-change
|
||||
required_test: env-contract:openapi-exposure-decided
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_MODE
|
||||
# source: NTF-025 — SERVING refuses to start without a working provider; ACCEPT_ONLY stores and does not dispatch
|
||||
# source: NTF-025 — SERVING refuses to start without a working provider; INGEST_ONLY stores and does not dispatch.
|
||||
# The constant is INGEST_ONLY. This row said ACCEPT_ONLY, a name NotificationPlatformMode has
|
||||
# never had, so an operator following the registry got a binding failure naming a value the
|
||||
# documentation does not mention. NotificationModeSsotTest derives the list below from the enum.
|
||||
type: enum
|
||||
default: SERVING
|
||||
allowed_values: [SERVING, ACCEPT_ONLY]
|
||||
allowed_values: [SERVING, INGEST_ONLY]
|
||||
classification: public-config
|
||||
required: false
|
||||
reload_policy: restart-only
|
||||
|
||||
@@ -226,6 +226,134 @@ secrets:
|
||||
|
||||
# === Tier 2: sensitive-config (token-bearing URL or id with exposure restriction) ===
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY
|
||||
# Encrypts recipient contact points at rest — addresses and phone numbers.
|
||||
# One of eight purpose-scoped keys. They must all differ: a single key reused across purposes
|
||||
# means a compromise of any one of them is a compromise of all eight, and the platform enforces
|
||||
# the distinction at startup rather than trusting the deployment to have noticed.
|
||||
classification: secret
|
||||
source: secret-manager
|
||||
rotation_policy: dual-read-restart-only
|
||||
prod_default: null
|
||||
required_when: ca-skeleton.notification.platform.enabled=true
|
||||
dev_sentinel_prefix: __LOCAL_DEV_
|
||||
owner_branch: worktree-notification-platform
|
||||
masking_rule: full
|
||||
compatibility_impact: behavior-change
|
||||
required_test: secrets-contract:notification-contact-encryption-no-leak
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY
|
||||
# Blind index over contact points, so a lookup never needs the plaintext.
|
||||
# One of eight purpose-scoped keys. They must all differ: a single key reused across purposes
|
||||
# means a compromise of any one of them is a compromise of all eight, and the platform enforces
|
||||
# the distinction at startup rather than trusting the deployment to have noticed.
|
||||
classification: secret
|
||||
source: secret-manager
|
||||
rotation_policy: dual-read-restart-only
|
||||
prod_default: null
|
||||
required_when: ca-skeleton.notification.platform.enabled=true
|
||||
dev_sentinel_prefix: __LOCAL_DEV_
|
||||
owner_branch: worktree-notification-platform
|
||||
masking_rule: full
|
||||
compatibility_impact: behavior-change
|
||||
required_test: secrets-contract:notification-contact-lookup-hmac-no-leak
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY
|
||||
# Signs the callback URLs a provider posts delivery outcomes back to.
|
||||
# One of eight purpose-scoped keys. They must all differ: a single key reused across purposes
|
||||
# means a compromise of any one of them is a compromise of all eight, and the platform enforces
|
||||
# the distinction at startup rather than trusting the deployment to have noticed.
|
||||
classification: secret
|
||||
source: secret-manager
|
||||
rotation_policy: dual-read-restart-only
|
||||
prod_default: null
|
||||
required_when: ca-skeleton.notification.platform.enabled=true
|
||||
dev_sentinel_prefix: __LOCAL_DEV_
|
||||
owner_branch: worktree-notification-platform
|
||||
masking_rule: full
|
||||
compatibility_impact: behavior-change
|
||||
required_test: secrets-contract:notification-callback-signing-no-leak
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY
|
||||
# Encrypts stored provider credentials, which are themselves secrets.
|
||||
# One of eight purpose-scoped keys. They must all differ: a single key reused across purposes
|
||||
# means a compromise of any one of them is a compromise of all eight, and the platform enforces
|
||||
# the distinction at startup rather than trusting the deployment to have noticed.
|
||||
classification: secret
|
||||
source: secret-manager
|
||||
rotation_policy: dual-read-restart-only
|
||||
prod_default: null
|
||||
required_when: ca-skeleton.notification.platform.enabled=true
|
||||
dev_sentinel_prefix: __LOCAL_DEV_
|
||||
owner_branch: worktree-notification-platform
|
||||
masking_rule: full
|
||||
compatibility_impact: behavior-change
|
||||
required_test: secrets-contract:notification-provider-credential-no-leak
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY
|
||||
# Encrypts notification variables and retained callback bodies at rest.
|
||||
# One of eight purpose-scoped keys. They must all differ: a single key reused across purposes
|
||||
# means a compromise of any one of them is a compromise of all eight, and the platform enforces
|
||||
# the distinction at startup rather than trusting the deployment to have noticed.
|
||||
classification: secret
|
||||
source: secret-manager
|
||||
rotation_policy: dual-read-restart-only
|
||||
prod_default: null
|
||||
required_when: ca-skeleton.notification.platform.enabled=true
|
||||
dev_sentinel_prefix: __LOCAL_DEV_
|
||||
owner_branch: worktree-notification-platform
|
||||
masking_rule: full
|
||||
compatibility_impact: behavior-change
|
||||
required_test: secrets-contract:notification-payload-encryption-no-leak
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY
|
||||
# Signs Web Push requests; the browser push service rejects anything else.
|
||||
# One of eight purpose-scoped keys. They must all differ: a single key reused across purposes
|
||||
# means a compromise of any one of them is a compromise of all eight, and the platform enforces
|
||||
# the distinction at startup rather than trusting the deployment to have noticed.
|
||||
classification: secret
|
||||
source: secret-manager
|
||||
rotation_policy: dual-read-restart-only
|
||||
prod_default: null
|
||||
required_when: ca-skeleton.notification.platform.enabled=true
|
||||
dev_sentinel_prefix: __LOCAL_DEV_
|
||||
owner_branch: worktree-notification-platform
|
||||
masking_rule: full
|
||||
compatibility_impact: behavior-change
|
||||
required_test: secrets-contract:notification-vapid-signing-no-leak
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY
|
||||
# Keyed hash of provider request ids, which are provider-side identifiers.
|
||||
# One of eight purpose-scoped keys. They must all differ: a single key reused across purposes
|
||||
# means a compromise of any one of them is a compromise of all eight, and the platform enforces
|
||||
# the distinction at startup rather than trusting the deployment to have noticed.
|
||||
classification: secret
|
||||
source: secret-manager
|
||||
rotation_policy: dual-read-restart-only
|
||||
prod_default: null
|
||||
required_when: ca-skeleton.notification.platform.enabled=true
|
||||
dev_sentinel_prefix: __LOCAL_DEV_
|
||||
owner_branch: worktree-notification-platform
|
||||
masking_rule: full
|
||||
compatibility_impact: behavior-change
|
||||
required_test: secrets-contract:notification-provider-request-lookup-hmac-no-leak
|
||||
|
||||
- name: APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY
|
||||
# Keyed fingerprint of callback bodies, used to detect replays.
|
||||
# One of eight purpose-scoped keys. They must all differ: a single key reused across purposes
|
||||
# means a compromise of any one of them is a compromise of all eight, and the platform enforces
|
||||
# the distinction at startup rather than trusting the deployment to have noticed.
|
||||
classification: secret
|
||||
source: secret-manager
|
||||
rotation_policy: dual-read-restart-only
|
||||
prod_default: null
|
||||
required_when: ca-skeleton.notification.platform.enabled=true
|
||||
dev_sentinel_prefix: __LOCAL_DEV_
|
||||
owner_branch: worktree-notification-platform
|
||||
masking_rule: full
|
||||
compatibility_impact: behavior-change
|
||||
required_test: secrets-contract:notification-callback-fingerprint-hmac-no-leak
|
||||
|
||||
- name: APP_NOTIFICATION_SLACK_WEBHOOK_URL
|
||||
# source: feature-integration-adapter-templates 2026-05-22
|
||||
# "Slack | disabled optional module | notification failure policy"
|
||||
|
||||
+5
@@ -1,3 +1,8 @@
|
||||
> **보존 안내** — 이 파일은 저장소 루트 `fileserver-superpowers-package/` 에 있던 납품 패키지의 README다.
|
||||
> 2026-08-15 문서 정리에서 설계서·계획서는 `docs/superpowers/specs/` 와 `docs/superpowers/plans/` 로 통합했고,
|
||||
> 실행 불가 상태였던 `validate_fileserver_docs.py` 는 제거했다.
|
||||
> 아래 본문은 납품 시점의 기록이므로 제거된 파일을 가리키는 문장은 더 이상 유효하지 않다.
|
||||
|
||||
# Fileserver Superpowers Package
|
||||
|
||||
## 포함 파일
|
||||
@@ -1,3 +1,8 @@
|
||||
> **보존 안내** — 이 파일은 저장소 루트 `graphql-superpowers-package/` 에 있던 납품 패키지의 README다.
|
||||
> 2026-08-15 문서 정리에서 설계서·계획서는 `docs/superpowers/specs/` 와 `docs/superpowers/plans/` 로 통합했고,
|
||||
> `validate_graphql_docs.py` 와 `MANIFEST.sha256` 은 제거했다.
|
||||
> 아래 본문은 납품 시점의 기록이므로 제거된 파일을 가리키는 문장은 더 이상 유효하지 않다.
|
||||
|
||||
# GraphQL Superpowers 설계 패키지
|
||||
|
||||
이 패키지는 `GraphQL API 실행 플랫폼 심층 리서치`를 구현 기준선으로 변환한 설계서와 실행 계획서다.
|
||||
+5
@@ -1,3 +1,8 @@
|
||||
> **보존 안내** — 이 파일은 저장소 루트 `httpclient-superpowers-package/` 에 있던 납품 패키지의 README다.
|
||||
> 2026-08-15 문서 정리에서 설계서·계획서는 `docs/superpowers/specs/` 와 `docs/superpowers/plans/` 로 통합했고,
|
||||
> 실행 불가 상태였던 `validate_httpclient_docs.py` 는 제거했다.
|
||||
> 아래 본문은 납품 시점의 기록이므로 제거된 파일을 가리키는 문장은 더 이상 유효하지 않다.
|
||||
|
||||
# HTTP Client Superpowers 설계 패키지
|
||||
|
||||
이 패키지는 `Java/Spring 외부 HTTP Client 플랫폼 설계 심층 리서치`를 기반으로 작성한 설계서와 구현 계획서다.
|
||||
@@ -1,3 +1,8 @@
|
||||
> **보존 안내** — 이 파일은 저장소 루트 `jpa-superpowers-package/` 에 있던 납품 패키지의 README다.
|
||||
> 2026-08-15 문서 정리에서 설계서·계획서는 `docs/superpowers/specs/` 와 `docs/superpowers/plans/` 로 통합했고,
|
||||
> `validate_jpa_docs.py` 와 `MANIFEST.sha256` 은 제거했다.
|
||||
> 아래 본문은 납품 시점의 기록이므로 제거된 파일을 가리키는 문장은 더 이상 유효하지 않다.
|
||||
|
||||
# JPA 관계형 영속성 플랫폼 Superpowers 패키지
|
||||
|
||||
이 패키지는 Java/Spring Backend Skeleton의 JPA 관계형 영속성 플랫폼을 구현하기 위한 설계서, Stable 구현 계획서, Experimental 확장 계획서와 정적 검증 도구를 포함한다.
|
||||
+5
@@ -1,3 +1,8 @@
|
||||
> **보존 안내** — 이 파일은 저장소 루트 `messaging-superpowers-package/` 에 있던 납품 패키지의 README다.
|
||||
> 2026-08-15 문서 정리에서 설계서·계획서는 `docs/superpowers/specs/` 와 `docs/superpowers/plans/` 로 통합했고,
|
||||
> `validate_messaging_docs.py` 와 `MANIFEST.sha256` 은 제거했다.
|
||||
> 아래 본문은 납품 시점의 기록이므로 제거된 파일을 가리키는 문장은 더 이상 유효하지 않다.
|
||||
|
||||
# Messaging Platform Superpowers Package
|
||||
|
||||
이 패키지는 `Java/Spring Messaging 플랫폼 심층 리서치`를 구현 기준으로 변환한 설계서와 구현 계획서다.
|
||||
@@ -1,3 +1,8 @@
|
||||
> **보존 안내** — 이 파일은 저장소 루트 `mongodb-superpowers-package/` 에 있던 납품 패키지의 README다.
|
||||
> 2026-08-15 문서 정리에서 설계서·계획서는 `docs/superpowers/specs/` 와 `docs/superpowers/plans/` 로 통합했고,
|
||||
> `validate_mongodb_docs.py` 와 `MANIFEST.sha256` 은 제거했다.
|
||||
> 아래 본문은 납품 시점의 기록이므로 제거된 파일을 가리키는 문장은 더 이상 유효하지 않다.
|
||||
|
||||
# MongoDB Superpowers 문서 패키지
|
||||
|
||||
이 패키지는 첨부된 `MongoDB 문서 영속성 플랫폼 심층 리서치`를 요구사항 원본으로 사용해 작성한 설계서와 구현 계획서다.
|
||||
+5
@@ -1,3 +1,8 @@
|
||||
> **보존 안내** — 이 파일은 저장소 루트 `notification-superpowers-package/` 에 있던 납품 패키지의 README다.
|
||||
> 2026-08-15 문서 정리에서 설계서·계획서는 `docs/superpowers/specs/` 와 `docs/superpowers/plans/` 로 통합했고,
|
||||
> 실행 불가 상태였던 `validate_notification_docs.py` 와 `MANIFEST.sha256` 은 제거했다.
|
||||
> 아래 본문은 납품 시점의 기록이므로 제거된 파일을 가리키는 문장은 더 이상 유효하지 않다.
|
||||
|
||||
# Notification Delivery Platform Superpowers Package
|
||||
|
||||
이 패키지는 Backend Skeleton의 `notification` 기술 모듈을 구현하기 위한 설계서와 TDD 구현 계획서다.
|
||||
@@ -1,3 +1,8 @@
|
||||
> **보존 안내** — 이 파일은 저장소 루트 `redis-superpowers-package/` 에 있던 납품 패키지의 README다.
|
||||
> 2026-08-15 문서 정리에서 설계서·계획서는 `docs/superpowers/specs/` 와 `docs/superpowers/plans/` 로 통합했고,
|
||||
> 이 패키지에는 검증 스크립트가 없었다.
|
||||
> 아래 본문은 납품 시점의 기록이므로 제거된 파일을 가리키는 문장은 더 이상 유효하지 않다.
|
||||
|
||||
# Redis Wrapper 및 Typed API 설계 패키지
|
||||
|
||||
이 패키지는 Spring 기반 Backend Skeleton에서 Redis 자료구조와 명령을 폭넓게 제공하기 위한 설계서와 구현 계획서다.
|
||||
@@ -0,0 +1,281 @@
|
||||
# Five-Adapter Runtime Remediation — Plan Index
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
|
||||
> (recommended) or superpowers:executing-plans to implement the wave plans task-by-task. Steps use
|
||||
> checkbox (`- [ ]`) syntax for tracking. **Read this index first** — its Global Constraints section
|
||||
> is implicitly part of every task in every wave plan.
|
||||
|
||||
**Goal:** Ship a single `app-bootstrap` bootJar that carries the MongoDB, Messaging, Notification,
|
||||
JPA, and GraphQL runtime facades on one classpath, each governed by an explicit master env switch
|
||||
that defaults to `false`, with `false` meaning zero beans/sockets/threads/endpoints and `true`
|
||||
meaning startup-time fail-closed dependency validation.
|
||||
|
||||
**Architecture:** One activation authority per adapter. Each of the five adapters gets exactly one
|
||||
master-gated root auto-configuration registered in `AutoConfiguration.imports`; that root owns the
|
||||
master condition and imports every child configuration. The composition root's broad component scan
|
||||
and `@ConfigurationPropertiesScan` are narrowed so a leaf's stereotypes and
|
||||
`@ConfigurationProperties` cannot be discovered outside its root. Vendor Spring Boot
|
||||
auto-configuration (JPA/Flyway/Hikari, Mongo, GraphQL, Kafka/Rabbit) is blocked in the off state by
|
||||
`AutoConfigurationImportFilter`s, following the mechanism `MongoOptInAutoConfigurationImportFilter`
|
||||
already establishes. Subordinate capabilities that consume an adapter (outbox relay, JDBC
|
||||
idempotency, distributed lock, notification store, DB readiness) are computed from the same
|
||||
dependency closure and fail closed at startup rather than at first request.
|
||||
|
||||
**Tech Stack:** Java 21, Spring Boot 4.0.0, Gradle 9.0.0 (multi-module, `src/` as the Gradle root),
|
||||
JUnit 5 + AssertJ, ArchUnit 1.3.0, Testcontainers, Flyway, PostgreSQL 16–18, MongoDB, Kafka/RabbitMQ,
|
||||
Keycloak, MinIO, Docker Compose 5.4.0 (spec floor: 2.24.4).
|
||||
|
||||
**Spec:** [`docs/superpowers/specs/2026-08-15-five-adapter-runtime-remediation-review-design.md`](../specs/2026-08-15-five-adapter-runtime-remediation-review-design.md)
|
||||
|
||||
---
|
||||
|
||||
## Baseline facts verified at HEAD `2f5d2fc`
|
||||
|
||||
These were re-verified in this repository before the plans were written. Every wave argues from
|
||||
them; do not re-derive them from the spec's prose.
|
||||
|
||||
| Fact | Evidence |
|
||||
| --- | --- |
|
||||
| Registry has 44 modules; `adapter-outbound-persistence-mongo` has `allowed_dependencies: []` and `runtime_memberships: []` | `src/config/architecture/modules.json` |
|
||||
| `adapter-inbound-graphql` has `runtime_memberships: []` | same |
|
||||
| All 24 `messaging-*` leaves have `runtime_memberships: []` | same |
|
||||
| `app-bootstrap.allowed_dependencies` has 12 entries and lists neither mongo, graphql, nor any `messaging-*` platform leaf | same |
|
||||
| `CaSkeletonApplication` already excludes `dev\.caskeleton\.bootstrap\.autoconfigure\..*` from its component scan, but its `@ConfigurationPropertiesScan` has **no** such exclusion | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/CaSkeletonApplication.java:29-53,66-68` |
|
||||
| `app-bootstrap` registers 3 auto-configurations: fileserver, httpclient, jpa | `src/app-bootstrap/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` |
|
||||
| The JPA platform auto-configuration lives in **`app-bootstrap`**, not in the JPA leaf | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/jpa/JpaPlatformRuntimeAutoConfiguration.java` |
|
||||
| Mongo registers 2 auto-configurations with no master-gated single root | `src/adapter/outbound/persistence-mongo/src/main/resources/META-INF/spring/...imports` |
|
||||
| Messaging starter registers 5 independent auto-configurations, none master-gated | `src/messaging/messaging-spring-boot-starter/src/main/resources/META-INF/spring/...imports` |
|
||||
| `spring.profiles.active: ${SPRING_PROFILES_ACTIVE:local}` — profileless boots as local | `src/app-bootstrap/src/main/resources/application.yml:22-24` |
|
||||
| `ca-skeleton.outbox.relay-enabled: true` is the shipped default | `src/app-bootstrap/src/main/resources/application.yml:539` |
|
||||
| `APP_IDEMPOTENCY_PROVIDER` default is `jdbc` | `src/app-bootstrap/src/main/resources/application.yml:352` |
|
||||
| `management.endpoint.health.group.readiness.include: readinessState,db` is static, with `validate-group-membership: true` | `src/app-bootstrap/src/main/resources/application.yml:248,278` |
|
||||
| `src/.env` is **git-tracked**; no `.env.example` and no `.env.local.example` exist | `git ls-files \| grep '\.env'` |
|
||||
| `logback-spring.xml` reads `SPRING_PROFILES_ACTIVE` with `defaultValue="local"`, independent of the real active profile | `src/app-bootstrap/src/main/resources/logback-spring.xml:8-9` |
|
||||
| `scripts/` holds only 3 files; there is no compose verification or runtime-smoke script | `ls scripts/` |
|
||||
| `infra/` has no `keycloak/` or `minio/` directory | `find infra -maxdepth 2 -type d` |
|
||||
| Full `test` fails on exactly one test with two offenders | reproduced below |
|
||||
|
||||
### The one reproduced red test
|
||||
|
||||
```
|
||||
$ cd src && ./gradlew :messaging:messaging-observability:test \
|
||||
--tests '*SecretLeakStaticScanTest*' --console=plain --no-daemon
|
||||
|
||||
SecretLeakStaticScanTest > noSensitiveIdentifierIsConcatenatedIntoAString() FAILED
|
||||
java.lang.AssertionError: [a concatenated secret never reaches the redactor, so it must not be written at all]
|
||||
Expecting empty but was: ["KafkaSecurityConfigurer.java:104 + oauth.credentialId());",
|
||||
"InMemoryAdminOperationJournal.java:110 existing.leaseToken() + 1,"]
|
||||
```
|
||||
|
||||
Root cause, confirmed by reading the scanner: `CONCATENATION_OPERAND` captures a method call
|
||||
*including* its trailing `()`
|
||||
(`src/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/SecretLeakStaticScanTest.java:39-42`),
|
||||
but `DESCRIBES_RATHER_THAN_REVEALS` anchors its safe suffixes with `$`
|
||||
(same file, `:47-49`). So `tail` is the string `credentialId()`, the `$` anchor never matches `Id`,
|
||||
and the safe-suffix exemption is dead for every method call. The second offender,
|
||||
`existing.leaseToken() + 1`, is numeric fencing — an integer increment, which cannot concatenate at
|
||||
all — and needs a separate exemption for numeric operands.
|
||||
|
||||
### Environment capabilities confirmed
|
||||
|
||||
| Tool | Version | Consequence |
|
||||
| --- | --- | --- |
|
||||
| Docker Engine | 29.7.2 | Wave 3 Compose lanes are executable here |
|
||||
| Docker Compose | 5.4.0 | above the spec's 2.24.4 floor, so `!override` merge semantics are available |
|
||||
| JDK | 21.0.11 | matches the toolchain |
|
||||
|
||||
---
|
||||
|
||||
## Global Constraints
|
||||
|
||||
Every task in every wave plan implicitly includes this section.
|
||||
|
||||
**Repository policy**
|
||||
|
||||
- Commit policy is `human-only`. Agents do **not** run `git add`, `git commit`, `git amend`, or
|
||||
`git push`. Where a wave task says "Commit", it means: stop, report the staged-file list and the
|
||||
proposed message to the human, and let them commit. (`AGENTS.md:65`)
|
||||
- The eight HARD-STOP conditions in `AGENTS.md:17-24` outrank every instruction in these plans.
|
||||
- `src/config/architecture/modules.json` is the only source of a leaf's Gradle path, allowed
|
||||
dependency edges, and runtime memberships. Never infer them from a document.
|
||||
- Focused tests are derived as `./gradlew <gradle_path>:test --console=plain`, read from that
|
||||
registry.
|
||||
- Non-trivial work ends with an LLM Wiki capture at
|
||||
`/home/donghyeon/workspace/ai-tool/llm-wiki-private/raw/branch-notes/<branch-name>.md`
|
||||
(`AGENTS.md:79-90`).
|
||||
- All Gradle commands run from `src/`, which is the Gradle root.
|
||||
|
||||
**Activation contract (spec §5.1) — exact values, copied verbatim**
|
||||
|
||||
| Adapter | canonical env | Spring property | default |
|
||||
| --- | --- | --- | --- |
|
||||
| JPA | `APP_PERSISTENCE_JPA_ENABLED` | `ca-skeleton.persistence-jpa.enabled` | `false` |
|
||||
| MongoDB | `APP_PERSISTENCE_MONGO_ENABLED` | `ca-skeleton.persistence-mongo.enabled` | `false` |
|
||||
| Messaging | `APP_MESSAGING_ENABLED` | `app.messaging.enabled` | `false` |
|
||||
| Notification | `APP_NOTIFICATION_PLATFORM_ENABLED` | `ca-skeleton.notification.platform.enabled` | `false` |
|
||||
| GraphQL | `APP_GRAPHQL_ENABLED` | `backend.graphql.enabled` | `false` |
|
||||
|
||||
Subordinate selectors registered alongside them:
|
||||
|
||||
| env | Spring property | contract |
|
||||
| --- | --- | --- |
|
||||
| `APP_PERSISTENCE_MONGO_ACTIVE_PROFILE` | `ca-skeleton.persistence-mongo.active-profile` | required non-blank when Mongo is on; selects exactly one profile |
|
||||
| `APP_GRAPHQL_DEPLOYMENT_MODE` | `backend.graphql.deployment-mode` | required when GraphQL is on; one of `LOCAL`, `DEV`, `PRODUCTION_INTERNAL`, `PRODUCTION_PUBLIC` |
|
||||
|
||||
GraphQL deployment mode is constrained by the runtime environment:
|
||||
|
||||
| runtime environment | permitted GraphQL mode |
|
||||
| --- | --- |
|
||||
| `local` | `LOCAL` |
|
||||
| `dev` | `DEV` |
|
||||
| `prod` | exactly one operator-named value of `PRODUCTION_INTERNAL` or `PRODUCTION_PUBLIC` |
|
||||
|
||||
`TEST` is test-source only. `STAGING` is not permitted in a shipped env key until a `stage` runtime
|
||||
environment exists.
|
||||
|
||||
**Master scalar parsing rule (spec §5.1)**
|
||||
|
||||
Master scalars are parsed *before* any detail `@ConfigurationProperties` binds, and strictly:
|
||||
|
||||
- unset ⇒ `false`;
|
||||
- the only accepted raw values are `true` and `false`, case-insensitive, with no surrounding
|
||||
whitespace;
|
||||
- `yes`, `1`, `on`, empty string, and any typo are a **configuration error**, never a silent off;
|
||||
- canonical and legacy key both present ⇒ rejected as ambiguity, even when the values agree;
|
||||
- legacy key alone ⇒ migration error that names the replacement key.
|
||||
|
||||
The early validator must not bind the detail namespace, or it breaks the off invariant it exists to
|
||||
protect.
|
||||
|
||||
**Off invariant (spec §5.2) — the acceptance shape for every "off" test**
|
||||
|
||||
With its master switch `false`, an adapter must satisfy all of the following in a
|
||||
**full-context** test:
|
||||
|
||||
1. its detail `@ConfigurationProperties` are neither bound nor validated;
|
||||
2. it owns zero production beans;
|
||||
3. no socket, client, connection pool, session, executor, scheduler, or watcher is created;
|
||||
4. JPA-off additionally means zero `DataSource`/`HikariDataSource`, zero `EntityManagerFactory`,
|
||||
zero Flyway, and zero DB health/metrics beans;
|
||||
5. no migration and no schema validation runs;
|
||||
6. no health contributor and no actuator detail is registered;
|
||||
7. for an inbound adapter, no route, schema, or controller is exposed;
|
||||
8. an invalid detail setting left in the environment does not block startup;
|
||||
9. where the application requires a port bean unconditionally, the disabled sentinel is supplied by
|
||||
the **composition root**, not by the adapter, and fails fast with `ADAPTER_DISABLED` when called.
|
||||
|
||||
This is implemented by **structural gating** — one root auto-configuration owning the master
|
||||
condition and importing children — never by repeating `@ConditionalOnProperty` on each bean.
|
||||
|
||||
**Profile cardinality (spec §7.1)**
|
||||
|
||||
A deployable runtime has exactly one environment profile. `SPRING_PROFILES_ACTIVE` becomes an enum
|
||||
`local|dev|prod` with **no default**. Missing, blank, unknown, and multi-value (`local,prod`) are all
|
||||
startup failures. Feature selection is never expressed as a supplementary Spring profile — that is
|
||||
what the five master switches are for. The `test` profile is test-source only; a release artifact
|
||||
booting under `test` is rejected.
|
||||
|
||||
**Evidence rules**
|
||||
|
||||
- A finding is not closed by an auto-configuration existing; it is closed by a test that exercises
|
||||
the real path.
|
||||
- Class-existence assertions and test-only Basic Auth never count as release evidence.
|
||||
- Secret values must not appear in Git, rendered config, command lines, JUnit XML, or evidence
|
||||
artifacts.
|
||||
- A blocking lane that discovers zero tests, skips a test, or reads a stale XML fails.
|
||||
- Never claim "complete" / "all passing" / "production-ready" without the corresponding command
|
||||
output. Use `superpowers:verification-before-completion`.
|
||||
|
||||
**Compose contract (spec §7.2)**
|
||||
|
||||
- Minimum Docker Compose version pinned at `2.24.4` in docs and CI.
|
||||
- `config/runtime/compose-profile-contracts.json` is the SSOT for lane → profile → file stack →
|
||||
Spring runtime → exact sorted service set.
|
||||
- `scripts/verify-compose-profile-contracts.sh` is the only static entry point;
|
||||
`scripts/run-compose-runtime-smoke.sh` is the only dynamic entry point. CI must not inline
|
||||
fragments of either.
|
||||
|
||||
---
|
||||
|
||||
## Wave map
|
||||
|
||||
Each wave is a separate plan that produces working, testable software on its own. Execute them in
|
||||
order; a wave's exit criterion is the entry criterion of the next.
|
||||
|
||||
| Wave | Plan | Delivers | Exit criterion |
|
||||
| --- | --- | --- | --- |
|
||||
| 0 | [wave0-red-baseline](2026-08-15-wave0-red-baseline.md) | Characterization tests that pin every current defect as an explicit, named red | Every spec §2 failure is reproduced by a test that fails for the documented reason |
|
||||
| 1 | [wave1-activation-ssot](2026-08-15-wave1-activation-ssot.md) | Five canonical switches, structural gating, classpath/registry alignment, dependency closure validators | `all-off` boots on `local`, `dev`, and `prod` with no external infrastructure |
|
||||
| 2 | [wave2-module-on-path](2026-08-15-wave2-module-on-path.md) | Per-adapter on-path blockers closed (JPA-INT-001..4, MNG-INT-001..5, MSG-INT-001..5, NTF-INT-001..7, GQL-INT-001..4) | Each adapter's one-on lane passes against real infrastructure |
|
||||
| 3 | [wave3-environment-and-infra](2026-08-15-wave3-environment-and-infra.md) | Env-source separation, profileless fail-closed, Compose contract SSOT + both scripts, Keycloak realm, MinIO round trip | The full Compose lane matrix passes zero-skip with evidence |
|
||||
| 4 | [wave4-warning-zero](2026-08-15-wave4-warning-zero.md) | MeterFilter ordering, BeanPostProcessor early-instantiation removal, Flyway warning root cause, IDE suppression narrowing, log/profile agreement | `local`, `dev`, `prod` startup logs contain zero WARN and zero ERROR, with an empty allowlist |
|
||||
| 5 | [wave5-gradle-build-logic](2026-08-15-wave5-gradle-build-logic.md) | `build-logic` included build with eight TestKit-tested convention plugins; duplicated source-set/lane/API-surface machinery removed | Task graph, dependency graph, test selection, and evidence output are byte-identical to the Wave 4 baseline |
|
||||
| 6 | [wave6-final-qualification](2026-08-15-wave6-final-qualification.md) | Full `clean check`, the activation matrix, every environment smoke, doc/metadata drift checks, Wiki capture | Every Definition-of-Done checkbox in spec §13 is ticked with attached evidence |
|
||||
|
||||
### Design patterns (spec §8) — where each one lands
|
||||
|
||||
Spec §8 is a constraint on *how* the waves are built, not a deliverable of its own. It is mapped here
|
||||
so no executor treats it as unassigned.
|
||||
|
||||
| Pattern to apply | Where |
|
||||
| --- | --- |
|
||||
| Conditional auto-configuration as a plugin boundary — one root condition owns the whole adapter graph | Wave 1 Tasks 4–8 |
|
||||
| Strategy + registry — provider selection is a closed descriptor plus a real implementation registry; unknown or duplicate rejected at startup | Wave 2 C4 (broker), D2 (notification provider) |
|
||||
| Factory / Builder — one factory composes secret, TLS, pool, and lifecycle together | Wave 2 B2 (Mongo client), C3 (broker client), D2 (provider) |
|
||||
| State machine + fencing — durable transitions guarded by owner/fencing token and DB compare-and-set | Wave 2 D5 (notification delivery), C2/C3 (outbox, settlement) |
|
||||
| Typed settings + validator — no scattered `@Value`, no duplicate namespace; validate the resolved runtime object | Wave 2 A1 (resolved `DataSource`), Wave 1 Task 10 |
|
||||
| Decorator — metrics, redaction, retry only at boundaries, never altering core behaviour | Wave 4 Task 1 |
|
||||
|
||||
| Pattern to avoid | Enforced by |
|
||||
| --- | --- |
|
||||
| The same `@ConditionalOnProperty` copied onto every adapter bean | Wave 1's structural gating; index §Off invariant closing paragraph |
|
||||
| A plain factory named `...AutoConfiguration` mixed with real auto-configuration | Wave 1 Tasks 4–8 convert imported factories to `@Configuration` |
|
||||
| `ObjectProvider` absence silently becoming a no-op, hiding missing production wiring | Wave 2 C3 (no fake sender), D2 (no assembler ⇒ capability stays off) |
|
||||
| `@Primary` resolving a JPA/Mongo implementation clash by accident | Wave 1 Task 10's ambiguity rejection |
|
||||
| A fake or in-memory implementation offered as a production runtime fallback | Wave 2 Global Constraints ("No fake in production") |
|
||||
| One over-general DSL merging release matrices whose provider meanings differ | Wave 5 Global Constraints |
|
||||
| Moving `build.gradle` content into `apply from:` files while leaving the duplicated model | Wave 5 Task 9 exit criteria |
|
||||
|
||||
The aim is not more patterns. It is one activation authority, one publication authority, one settings
|
||||
SSOT, and a real execution path.
|
||||
|
||||
### Dependency ordering rationale
|
||||
|
||||
Wave 5 is deliberately last-but-one and never shares a diff with runtime changes: moving build logic
|
||||
on top of a red or unverified baseline produces a task graph that looks green because a task
|
||||
silently stopped existing (spec §14). Wave 3 depends on Wave 1 because a Compose lane cannot assert
|
||||
an activation report that does not exist yet. Wave 2's per-module fixes depend on Wave 1's single
|
||||
activation authority, or each module invents its own.
|
||||
|
||||
---
|
||||
|
||||
## Scope boundaries carried from spec §14
|
||||
|
||||
These plans approve **an assemblable artifact that is off by default**. They do not approve every
|
||||
internal algorithm of the five platforms as production-ready. The following stay explicitly out of
|
||||
scope and must not be silently promoted:
|
||||
|
||||
- Mongo **reactive** support — the reactive starter/auto-configuration is removed from the
|
||||
production runtime or blocked even when the master is on. Not listed as supported.
|
||||
- Mongo **change streams** — `experimental`, always `false`, zero beans and zero threads. A
|
||||
replica-set qualification observing that the server *could* support change streams is not evidence
|
||||
of shipped support.
|
||||
- Mongo **transactions** — a typed subordinate switch defaulting to `false`; when on, the real
|
||||
replica-set capability of the data-plane credential is verified.
|
||||
- `mongoShardedTest`, `mongoAtlasTest`, `mongoKmsTest` — the Mongo release registry points at tasks
|
||||
and classes that **do not exist**. Either implement them with protected-environment evidence, or
|
||||
remove their Stable blocking claim and demote them to explicit experimental/conditional promotion.
|
||||
A green release manifest naming a task that does not exist is not permitted.
|
||||
- Notification at-rest payload sensitivity (NTF-INT-007) — Notification is not promoted to Stable
|
||||
until either application-level encryption is implemented end to end (codec/port, ciphertext
|
||||
envelope, key ID, rotation/history, row migration, decryption failure contract) or a written
|
||||
threat model justifies restricted variable types plus storage-level encryption. Plaintext storage
|
||||
is not approved by default.
|
||||
- Object storage inclusion in the `app-bootstrap` runtime is a **separate** decision from the five
|
||||
master switches. If it is not included, the MinIO smoke client is a release fixture only, never a
|
||||
production bean.
|
||||
- Fileserver internals are not redesigned. Only the composition consumers that break `all-off` are
|
||||
gated or turned into dependency errors; module hardening stays a separate spec.
|
||||
|
||||
Each wave plan restates the boundary that applies to it, so an executor reading one plan in
|
||||
isolation cannot promote something this index excluded.
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,612 @@
|
||||
# Wave 2 — Module On-Path Blockers Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
|
||||
> (recommended) or superpowers:executing-plans. Steps use checkbox (`- [ ]`) syntax.
|
||||
> **Read [`2026-08-15-five-adapter-runtime-remediation-index.md`](2026-08-15-five-adapter-runtime-remediation-index.md)
|
||||
> first.**
|
||||
> **Entry criterion:** Wave 1 complete — all-off boots on `local`, `dev`, and `prod`, and every
|
||||
> `FiveAdapterOffInventoryTest` case is green.
|
||||
|
||||
**Goal:** Close every per-module blocker that stands between "the switch turns it on" and "the thing
|
||||
it turns on actually works against real infrastructure", for all five adapters.
|
||||
|
||||
**Architecture:** Wave 1 decided whether a bean exists; Wave 2 decides what it does. Each adapter
|
||||
gets one publication/settings/assembly authority to match the one activation authority it now has:
|
||||
JPA validates the *resolved* `DataSource` rather than a parallel property namespace; Mongo builds
|
||||
exactly one sync client from the active profile's credential; Messaging replaces the fake sender with
|
||||
a real transport bridge and gains its Stable facade membership only in the change that proves a live
|
||||
broker round trip; Notification gains production provider assemblers and a frozen-route ingest
|
||||
contract; GraphQL collapses its two contradictory safety axes into one deployment mode carried
|
||||
through the real request path.
|
||||
|
||||
**Tech Stack:** Testcontainers (PostgreSQL 16/17/18, MongoDB replica set, Kafka, RabbitMQ, Mailpit),
|
||||
Spring GraphQL, Spring Security OAuth2 resource server, Flyway, Micrometer.
|
||||
|
||||
**Spec:** [`2026-08-15-five-adapter-runtime-remediation-review-design.md`](../specs/2026-08-15-five-adapter-runtime-remediation-review-design.md)
|
||||
(§6 in full, §11 Wave 2, §12.2, §12.3)
|
||||
|
||||
---
|
||||
|
||||
## Global Constraints
|
||||
|
||||
Inherited from the index. Wave 2 adds:
|
||||
|
||||
- **Membership is earned, never granted in advance.** A Stable facade gains `runtime_memberships`
|
||||
and an `app-bootstrap` dependency **in the same change unit that proves it works against real
|
||||
infrastructure**. Wiring first and qualifying later ships a known-broken path.
|
||||
- **No fake in production.** A fixture, in-memory implementation, or test double must not be
|
||||
reachable from a production runtime path. Where the production implementation is absent, the
|
||||
capability stays off and its promotion claim is removed from the registry.
|
||||
- **Each finding is re-reproduced at current HEAD before it is fixed.** The five detailed module
|
||||
reviews below remain authoritative inputs, but they were written against a different HEAD; do not
|
||||
copy a failure forward without reproducing it.
|
||||
- `docs/reviews/2026-08-14-mongodb-module-code-review.md`
|
||||
- `docs/reviews/2026-08-14-messaging-module-code-review.md`
|
||||
- `docs/reviews/2026-08-14-notification-module-code-review.md`
|
||||
- `docs/reviews/2026-08-14-jpa-module-code-review.md`
|
||||
- `docs/reviews/2026-08-14-graphql-module-code-review.md`
|
||||
- **A P0 correctness or security finding on a runtime path is a prerequisite, not a follow-up.**
|
||||
Connecting wiring over a known data-loss path is forbidden (spec §11 Wave 2 closing note).
|
||||
|
||||
---
|
||||
|
||||
## Section A — JPA
|
||||
|
||||
### Task A1: Validate the resolved DataSource, not a parallel namespace (JPA-INT-002)
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/jpa/JpaDataSourceSettings.java`
|
||||
- Modify: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/jpa/JpaDataSourceProfileValidator.java`
|
||||
- Modify: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/persistencejpa/PersistenceJpaRootAutoConfiguration.java`
|
||||
- Test: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/autoconfigure/jpa/JpaResolvedDataSourceValidationTest.java`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `JpaDataSourceProfileValidator.validateResolved(DataSource)` — replaces
|
||||
`validateStable()`. Task A2 and Wave 3's `local-jpa` lane both consume it.
|
||||
|
||||
**Context:** Two defects, both verified in the spec against HEAD.
|
||||
|
||||
1. `JpaDataSourceSettings` binds `app.jpa-platform.datasource.*` while the pool that actually gets
|
||||
built comes from `spring.datasource.hikari.*` (`application.yml:25-50`). Two namespaces describing
|
||||
one pool means the validator can pass while the pool it validated is not the pool in use.
|
||||
2. `JpaDataSourceProfileValidator` is created as a bean but `validateStable` is never invoked at
|
||||
startup (`JpaPlatformRuntimeAutoConfiguration.java:93-99,159-165`). A validator nobody calls is a
|
||||
comment.
|
||||
|
||||
The fix removes the duplicate namespace entirely and validates the injected `DataSource` —
|
||||
`HikariDataSource#getMaximumPoolSize`, `getConnectionTimeout`, the resolved JDBC URL, and the product
|
||||
name and version read from `DatabaseMetaData`. Invocation moves into an `InitializingBean` inside the
|
||||
JPA root, so it runs exactly when JPA is on and never when it is off.
|
||||
|
||||
- [ ] **Step 1:** Write `JpaResolvedDataSourceValidationTest` — a Testcontainers PostgreSQL context
|
||||
asserting that (a) a pool whose `maximum-pool-size` violates the REQUIRES_NEW lower bound
|
||||
documented at `application.yml:33-37` fails startup naming `spring.datasource.hikari.maximum-pool-size`;
|
||||
(b) removing every `app.jpa-platform.datasource.*` property changes nothing, proving the
|
||||
namespace is dead; (c) an unreachable database fails startup rather than at first query.
|
||||
- [ ] **Step 2:** Run to verify it fails.
|
||||
- [ ] **Step 3:** Delete the `app.jpa-platform.datasource` binding from `JpaDataSourceSettings`;
|
||||
rewrite `JpaDataSourceProfileValidator` to take a `DataSource`; register the invocation in
|
||||
`PersistenceJpaRootAutoConfiguration`.
|
||||
- [ ] **Step 4:** Run to verify it passes.
|
||||
- [ ] **Step 5:** Run `./gradlew :adapter:outbound:persistence-jpa:test :app-bootstrap:test --console=plain --no-daemon`.
|
||||
- [ ] **Step 6:** Remove the now-dead `app.jpa-platform.datasource.*` rows from
|
||||
`docs/registries/env-keys.yaml`; run `./gradlew verifyEnvKeys`.
|
||||
- [ ] **Step 7:** Commit.
|
||||
|
||||
### Task A2: Separate local H2 from the default-off contract (JPA-INT-003)
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/app-bootstrap/src/main/resources/application-local.yml`
|
||||
- Create: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/autoconfigure/jpa/LocalJpaVendorParityTest.java`
|
||||
- Modify: `src/app-bootstrap/build.gradle` (a named non-release H2 developer task)
|
||||
|
||||
**Context:** H2 becomes repository/unit-test scope plus one explicitly-named developer convenience
|
||||
task. The user-facing completion criterion — "local JPA runtime smoke" — uses PostgreSQL, Flyway, and
|
||||
`ddl-auto=validate`, so local and dev share vendor semantics. Consequences to implement:
|
||||
|
||||
- `local` all-off boots with **no database at all** (Wave 1 already delivers this).
|
||||
- `local` + `APP_PERSISTENCE_JPA_ENABLED=true` requires the Compose PostgreSQL of Wave 3's
|
||||
`local-jpa` lane.
|
||||
- Profile absence must never resolve to H2/`create-drop`; Wave 3 Task 1 makes profile absence a
|
||||
startup error, and this task removes the H2 default that made absence dangerous.
|
||||
|
||||
- [ ] **Steps 1–6:** TDD cycle. The parity test asserts that `local` + JPA-on resolves the same
|
||||
vendor, migration mode, and schema policy as `dev` + JPA-on, differing only in address and
|
||||
credential.
|
||||
|
||||
---
|
||||
|
||||
## Section B — MongoDB
|
||||
|
||||
### Task B1: Move to the canonical Boot 4 namespace (MNG-INT-002, part 1)
|
||||
|
||||
**Files:**
|
||||
- Modify: every source and test referencing `spring.data.mongodb.*`
|
||||
- Test: `src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/MongoNamespaceContractTest.java`
|
||||
|
||||
**Context:** `spring.data.mongodb.*` is deprecated at error level in Spring Boot 4 metadata; the
|
||||
canonical namespace is `spring.mongodb.*`. `MongoPersistenceProperties`' own Javadoc points operators
|
||||
at the deprecated one. Building the new activation design on a namespace Boot reports as an error is
|
||||
building on sand.
|
||||
|
||||
- [ ] **Step 1:** Write a test asserting no production source or resource references
|
||||
`spring.data.mongodb.` — a source-tree scan, in the shape of the existing
|
||||
`SecretLeakStaticScanTest`.
|
||||
- [ ] **Steps 2–6:** migrate, run `./gradlew :adapter:outbound:persistence-mongo:test`, update the
|
||||
Javadoc, commit.
|
||||
|
||||
### Task B2: One SSOT from active profile to the real `MongoClientSettings` (MNG-INT-002, part 2)
|
||||
|
||||
**Files:**
|
||||
- Create: `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/client/MongoClientSettingsFactory.java`
|
||||
- Modify: `MongoRootAutoConfiguration` to register it as a `MongoClientSettingsBuilderCustomizer`
|
||||
- Test: `.../client/MongoClientSettingsFactoryTest.java`
|
||||
|
||||
**Context:** Typed profile, credential resolver, TLS, Stable API, and pool/timeout policy exist but
|
||||
are not connected to the builder Boot actually uses. One factory consumes the active profile and the
|
||||
secret reference and produces the real settings; the test asserts on the built
|
||||
`MongoClientSettings`, not on the intermediate typed objects.
|
||||
|
||||
Cardinality contract, from index §Scope boundaries: exactly one sync client and one pool; zero
|
||||
reactive inventory; secrets resolved **only** for the active profile — a profile present in the map
|
||||
but not selected must not have its secret read or its client built.
|
||||
|
||||
- [ ] **Steps 1–6:** TDD cycle asserting: one client, one pool, zero reactive beans, and that a
|
||||
non-active profile's deliberately-invalid secret reference is never resolved.
|
||||
|
||||
### Task B3: Startup validation that cannot fail open (MNG-INT-003)
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformAutoConfiguration.java`
|
||||
- Test: `.../autoconfigure/MongoStartupValidationTest.java`
|
||||
|
||||
**Context:** The startup check is created only when a `MongoTopologyProbe` bean is present
|
||||
(`MongoPlatformAutoConfiguration.java:137-183`), so a missing probe silently skips validation
|
||||
entirely. Additionally, transactions and change streams are hardcoded `true, true` in the capability
|
||||
flags, and absent admin credentials are treated as "no validation needed".
|
||||
|
||||
The fix, per index §Scope boundaries:
|
||||
- Mongo on ⇒ a probe is built from the live data-plane client, or the absence is a startup error.
|
||||
- Capability flags come from typed settings, never literals.
|
||||
- Admin credential/gateway belongs to a migration or deployment job's composition; the shipped
|
||||
application neither binds nor requires it.
|
||||
- `transactions` is a subordinate switch defaulting `false`; when on, the real replica-set capability
|
||||
of the data-plane credential is verified.
|
||||
- `change-streams` is experimental, always `false`, zero beans and zero threads. A replica-set
|
||||
qualification observing server capability is not evidence of shipped support.
|
||||
|
||||
- [ ] **Steps 1–6:** TDD cycle with one case per bullet.
|
||||
|
||||
### Task B4: Separate role from credential identity (MNG-INT-004)
|
||||
|
||||
**Files:**
|
||||
- Modify: the credential identity hash implementation
|
||||
- Test: `.../MongoCredentialIdentityTest.java`
|
||||
|
||||
**Context:** The identity hash includes the role, so the same secret reference used under two roles
|
||||
looks like two different credentials, defeating the separation it was meant to enforce.
|
||||
|
||||
- [ ] **Steps 1–5:** TDD cycle; the regression case is one secret reference under two roles, which
|
||||
must be detected as the same credential.
|
||||
|
||||
### Task B5: Resolve the three ghost release lanes
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/config/mongodb/release-contracts.json` **or** `src/adapter/outbound/persistence-mongo/build.gradle`
|
||||
- Modify: `docs/mongodb/advanced/sharding.md`, `scripts/verify-mongodb-advanced.sh`
|
||||
- Test: `ReleaseManifestTaskExistenceTest` (Wave 0 Task 9) is the arbiter
|
||||
|
||||
**Context:** Verified at HEAD: `release-contracts.json` names `mongoShardedTest` (line 30),
|
||||
`mongoAtlasTest` (38), and `mongoKmsTest` (46); `persistence-mongo/build.gradle` registers seven mongo
|
||||
lanes and none of those three. `scripts/verify-mongodb-advanced.sh:95` invokes `mongoShardedTest`, so
|
||||
that script currently cannot succeed either.
|
||||
|
||||
Two legitimate outcomes — choose one and record the decision in the plan's evidence log:
|
||||
|
||||
- **(a) Implement.** Register the three lanes with real required classes and protected-environment
|
||||
evidence, and include them in the Stable blocking set.
|
||||
- **(b) Demote.** Remove the Stable blocking claim from `release-contracts.json`, move the three to
|
||||
an explicit experimental/conditional promotion section, update `docs/mongodb/advanced/sharding.md`
|
||||
to stop describing an unrunnable gate, and make `verify-mongodb-advanced.sh` fail with a clear
|
||||
"not promoted" message rather than invoking a task that does not exist.
|
||||
|
||||
**Recommendation: (b).** Sharding, Atlas, and KMS each need a protected environment this repository
|
||||
does not have, and index §Scope boundaries already places them outside the shipped Stable runtime.
|
||||
Implementing them to satisfy a manifest entry would be the tail wagging the dog.
|
||||
|
||||
- [ ] **Steps 1–5:** apply the chosen outcome, run
|
||||
`./gradlew :app-bootstrap:test --tests '*ReleaseManifestTaskExistenceTest*'` to green, remove
|
||||
its `@Tag("wave0-red")`, commit.
|
||||
|
||||
---
|
||||
|
||||
## Section C — Messaging
|
||||
|
||||
### Task C1: Fix the secret scanner without weakening it (MSG-INT-005)
|
||||
|
||||
**Files:**
|
||||
- Create: `src/messaging/messaging-observability/src/main/java/dev/caskeleton/messaging/observation/SecretConcatenationClassifier.java`
|
||||
- Modify: `src/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/SecretLeakStaticScanTest.java`
|
||||
- Modify: `src/messaging/messaging-observability/src/test/java/dev/caskeleton/messaging/observation/SecretLeakScannerCharacterizationTest.java`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `SecretConcatenationClassifier.leaksASensitiveValue(String line)` — extracted from the
|
||||
test so the characterization can call the real thing.
|
||||
|
||||
**Context:** Root cause, confirmed by reading the scanner (index §The one reproduced red test):
|
||||
`CONCATENATION_OPERAND` captures a method call including its trailing `()`, while
|
||||
`DESCRIBES_RATHER_THAN_REVEALS` anchors with `$`. The safe-suffix exemption is therefore dead for
|
||||
every method call. Second offender: `existing.leaseToken() + 1` is arithmetic.
|
||||
|
||||
The two fixes:
|
||||
1. Strip a trailing `()` from `tail` before matching the safe-suffix pattern. Not: loosen the anchor —
|
||||
an unanchored `Id` would exempt `credentialIdentity`, which does carry the value.
|
||||
2. Treat an operand paired with a numeric literal as arithmetic. Detect it by inspecting the *other*
|
||||
side of the `+`: a decimal, hex, or floating literal makes the expression arithmetic.
|
||||
|
||||
Neither fix may weaken true-positive detection, which is what the characterization's first three
|
||||
cases exist to prove.
|
||||
|
||||
- [ ] **Step 1:** Extract the classifier to `src/main/java` unchanged, and point both tests at it.
|
||||
Run — the same 2 failures, now against the real class.
|
||||
- [ ] **Step 2:** Apply fix 1. Run — `methodCallWithSafeSuffixIsNotALeak` green, true positives still
|
||||
green.
|
||||
- [ ] **Step 3:** Apply fix 2. Run — `numericFencingIsNotALeak` green.
|
||||
- [ ] **Step 4:** Delete the duplicated classifier from
|
||||
`SecretLeakScannerCharacterizationTest` and have it call the extracted one, per that file's own
|
||||
Javadoc promise.
|
||||
- [ ] **Step 5:** Run `./gradlew :messaging:messaging-observability:test --console=plain --no-daemon`
|
||||
— the full module green, including `SecretLeakStaticScanTest`.
|
||||
- [ ] **Step 6:** Run `./gradlew test --console=plain --no-daemon --continue` — the repository-wide
|
||||
suite, which spec §3.1 recorded as failing on exactly this test. Record the result.
|
||||
- [ ] **Step 7:** Commit.
|
||||
|
||||
### Task C2: One publication authority and one settings owner (MSG-INT-002)
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/MessagingSettings.java` (delete after migration)
|
||||
- Modify: `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingProperties.java`
|
||||
- Modify: `src/config/architecture/modules.json`
|
||||
- Test: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/messaging/MessagingAuthorityContractTest.java`
|
||||
|
||||
**Context:** Three authorities share the `app.messaging` namespace today: `MessagingSettings`
|
||||
(adapter), the legacy `KafkaSender` config, and `MessagingProperties` (starter). The target:
|
||||
|
||||
```text
|
||||
app-bootstrap
|
||||
-> adapter:outbound:messaging # application port bridge
|
||||
-> messaging runtime starter # Stable runtime assembly
|
||||
adapter:outbound:messaging
|
||||
-> messaging-core-api # platform publish contract only
|
||||
messaging runtime starter
|
||||
-> selected platform implementation leaves
|
||||
```
|
||||
|
||||
Registry edges to add: `app-bootstrap -> messaging-spring-boot-starter` and
|
||||
`adapter-outbound-messaging -> messaging-core-api`.
|
||||
|
||||
Port discipline: the real application-owned contract is `OutboxMessagePublishPort`. The legacy generic
|
||||
`MessagePublisher` is an adapter-local type and must not leak into core. If general publish becomes a
|
||||
use-case need, define an application port first.
|
||||
|
||||
Forbidden: legacy and new publisher both emitting the same event (dual write).
|
||||
|
||||
- [x] **Characterization and the dual-write guard:** done. `MessagingAuthorityContractTest` records
|
||||
the two owners of `app.messaging` by name and asserts that exactly one production type
|
||||
implements `OutboxMessagePublishPort`, plus that the adapter-local `MessagePublisher` does not
|
||||
reach `application-core` or `domain-core`. A source scan, because no module sees both the
|
||||
adapter and the starter — which is the boundary working, not a gap in the test.
|
||||
- [ ] **The settings collapse moves into C3's change unit.** Deleting `MessagingSettings` means the
|
||||
adapter stops selecting a broker and becomes a port bridge over the platform's publish
|
||||
contract; it can only do that once the platform *has* a production publisher. Removing the
|
||||
binding first would leave the adapter unable to select anything, which is a worse state than
|
||||
the split it fixes. The guard above is what keeps the split honest until then, and it fails the
|
||||
moment a third owner appears or a second publisher starts emitting.
|
||||
|
||||
### Task C3: A real production sender, and membership earned by a live round trip (MSG-INT-003)
|
||||
|
||||
**Files:**
|
||||
- Create: the production Kafka and RabbitMQ sender implementations in the selected platform leaves
|
||||
- Modify: `src/config/architecture/modules.json`, `src/app-bootstrap/build.gradle`
|
||||
- Test: `src/app-bootstrap/src/test/java/.../MessagingLiveRoundTripQualificationTest.java` (Testcontainers Kafka)
|
||||
|
||||
**Context:** The legacy Kafka config requires a project-supplied `KafkaSender` that exists only as a
|
||||
test fake. A production app therefore has no sender at all, and every "messaging works" signal comes
|
||||
from a fixture.
|
||||
|
||||
**Membership rule, enforced here:** the starter and every internal leaf that actually resolves onto
|
||||
the runtime classpath gain `app-bootstrap` membership **in the same change unit** that turns
|
||||
`MessagingLiveRoundTripQualificationTest` green against a real broker. Leaves that are unsupported or
|
||||
unqualified are excluded from both the starter's dependencies and the registry.
|
||||
|
||||
Because Wave 1 Task 13 made the membership gate closure-based, adding the starter will surface every
|
||||
transitive leaf at once — that is intended, and each must be either recorded as a member or removed
|
||||
from the starter's dependency graph.
|
||||
|
||||
- [ ] **Steps 1–8:** TDD cycle ending with `./gradlew verifyRuntimeModuleMembership` green and
|
||||
`ShippedRuntimeFacadePresenceTest.messagingPlatformFacadeIsShipped` green with its tag removed.
|
||||
|
||||
### Task C4: One master-gated starter root (MSG-INT-004)
|
||||
|
||||
**Files:**
|
||||
- Create: `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java`
|
||||
- Modify: `src/messaging/messaging-spring-boot-starter/src/main/resources/META-INF/spring/...AutoConfiguration.imports`
|
||||
- Test: `.../MessagingStarterOffContractTest.java`
|
||||
|
||||
**Context:** Verified at HEAD, the starter registers five independent auto-configurations
|
||||
(`MessagingCoreAutoConfiguration`, `KafkaMessagingAutoConfiguration`,
|
||||
`RabbitMessagingAutoConfiguration`, `MessagingReliabilityAutoConfiguration`,
|
||||
`MessagingAdminAutoConfiguration`) and none carries a messaging master condition.
|
||||
|
||||
After this task `imports` holds exactly one entry — the root — which imports the selected provider and
|
||||
reliability children. Kafka and Rabbit must never assemble together merely because both client
|
||||
libraries are on the classpath; provider selection is a closed descriptor + registry, and an unknown
|
||||
or duplicate selection is a startup error.
|
||||
|
||||
The off test is full-context and includes starter imports **and** vendor Boot auto-configuration:
|
||||
zero beans, zero clients, zero threads.
|
||||
|
||||
- [ ] **Steps 1–7:** TDD cycle.
|
||||
|
||||
---
|
||||
|
||||
## Section D — Notification
|
||||
|
||||
### Task D1: Fix the mode SSOT drift (NTF-INT-002)
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/registries/env-keys.yaml:4266-4277`
|
||||
- Modify: every YAML, doc, and test using `ACCEPT_ONLY`
|
||||
- Test: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/notification/NotificationModeSsotTest.java`
|
||||
|
||||
**Context:** The Java enum is `SERVING|INGEST_ONLY`
|
||||
(`NotificationPlatformMode.java:11-23`); the env registry declares `SERVING|ACCEPT_ONLY`. Canonical
|
||||
name is `INGEST_ONLY`. The test asserts that the registry's enum values equal
|
||||
`NotificationPlatformMode.values()` — derived, so it cannot drift again.
|
||||
|
||||
- [ ] **Steps 1–5:** TDD cycle; smallest task in this wave, do it first so later tasks use one name.
|
||||
|
||||
### Task D2: Production provider assemblers (NTF-INT-001)
|
||||
|
||||
**Files:**
|
||||
- Create: production `ProviderRuntimeAssembler` implementations under
|
||||
`src/adapter/outbound/notification/src/main/java/.../platform/provider/`
|
||||
- Modify: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/notification/NotificationPlatformProviderConfig.java`
|
||||
- Test: `.../NotificationServingAssemblyTest.java`
|
||||
|
||||
**Context:** Configuration assembles `List<ProviderRuntimeAssembler>` but production main source has
|
||||
no implementation (`NotificationPlatformProviderConfig.java:78-99`). `SERVING` therefore cannot work
|
||||
in production regardless of settings.
|
||||
|
||||
`SERVING` turns on only when the selected provider family has a real assembler, secret resolver,
|
||||
timeout/rate/permit policy, and readiness contributor. A provider without one is not documented as
|
||||
Stable — update the capability docs in the same change.
|
||||
|
||||
Reference provider for the Wave 3 `local-notification-serving` lane: SMTP via Mailpit.
|
||||
|
||||
- [ ] **Steps 1–7:** TDD cycle.
|
||||
|
||||
### Task D3: Mode-scoped worker lifecycle (NTF-INT-003)
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/notification/NotificationPlatformWorkerConfig.java`
|
||||
- Test: `.../NotificationWorkerLifecycleTest.java`
|
||||
|
||||
**Context:** The worker config checks only master-enabled and unconditionally `start()`s background
|
||||
workers and the scheduler (`NotificationPlatformWorkerConfig.java:135-166`). `INGEST_ONLY` must start
|
||||
zero dispatch, recovery, and reconciliation threads.
|
||||
|
||||
Asserted on **live thread count**, via `AdapterActivationInventory.liveThreadNamesMatching`, not on
|
||||
bean absence — a worker bean that exists but was never started is acceptable; a thread is not.
|
||||
|
||||
- [ ] **Steps 1–6:** TDD cycle.
|
||||
|
||||
### Task D4: Retire the legacy selector namespace (NTF-INT-004)
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/registries/env-keys.yaml`, the notification YAML, and the optional-bean tests
|
||||
- Test: `.../NotificationLegacyNamespaceRetirementTest.java`
|
||||
|
||||
**Context:** The registry and YAML use provider selectors while the actual bean conditions mix
|
||||
`slack-webhook.enabled`, `google-email.enabled`, and `routes.*`. The delivery platform becomes the
|
||||
canonical runtime; the legacy R0 selector is isolated behind a migration shim that raises a naming
|
||||
migration error, then removed.
|
||||
|
||||
- [ ] **Steps 1–6:** TDD cycle; the negative assertion — that no legacy selector is documented as an
|
||||
activation key — is required by spec §6.4 and belongs in
|
||||
`MasterSwitchRegistryContractTest` (Wave 1 Task 12).
|
||||
|
||||
### Task D5: A frozen, non-empty route plan for INGEST_ONLY (NTF-INT-006)
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/adapter/outbound/notification/src/main/java/.../CanonicalNotificationPlanWriter.java`
|
||||
- Modify: `.../PolicyRoutePlanner.java`
|
||||
- Create: versioned route-metadata loading in the notification root
|
||||
- Test: `src/app-bootstrap/src/test/java/.../NotificationIngestHandoffQualificationTest.java`
|
||||
|
||||
**Context:** The most consequential blocker in this section, and the one most easily mistaken for
|
||||
working. Today the plan writer freezes a provider-specific routing plan at accept time and stores an
|
||||
**empty** plan when the route catalog is empty (`CanonicalNotificationPlanWriter.java:82-128`,
|
||||
`PolicyRoutePlanner.java:50-76`). Dispatch consumes the stored snapshot verbatim
|
||||
(`NotificationDispatchService.java:298-307`). So a row accepted in `INGEST_ONLY` with no routes never
|
||||
becomes deliverable, no matter how the application is later restarted.
|
||||
|
||||
The contract:
|
||||
- `INGEST_ONLY` startup **requires** versioned route metadata — provider family/id, channel
|
||||
eligibility, route config version — readable **without** credentials or live provider beans.
|
||||
- Accept freezes a non-empty immutable plan plus its route version.
|
||||
- An empty route catalog or empty plan is rejected at startup or at the accept boundary, explicitly.
|
||||
- No automatic replan after accept. A policy change needing replan is a separate backfill/migration
|
||||
with operator approval, idempotency, and audit.
|
||||
- `SERVING` startup verifies the production assembler registry supports every stored provider
|
||||
ID/version; a mismatched row is never silently reinterpreted.
|
||||
- During `INGEST_ONLY`: zero provider credentials, zero provider runtime beans, zero workers.
|
||||
|
||||
Qualification, which is also Wave 3's `local-notification-handoff` lane:
|
||||
`INGEST_ONLY accept → process stop → SERVING restart → exactly one delivery on the same frozen
|
||||
route`, against a real database and provider fixture.
|
||||
|
||||
- [ ] **Steps 1–9:** TDD cycle, ending with the handoff qualification green against Testcontainers
|
||||
PostgreSQL + Mailpit.
|
||||
|
||||
### Task D6: Decide the at-rest payload sensitivity contract (NTF-INT-007)
|
||||
|
||||
**Files:**
|
||||
- Either: create the encryption codec/port, ciphertext envelope, key ID, rotation/history, row
|
||||
migration, and decryption-failure contract
|
||||
- Or: create `docs/notification/at-rest-threat-model.md` plus a static variable-type restriction
|
||||
- Test: `.../NotificationPayloadAtRestContractTest.java`
|
||||
|
||||
**Context:** The accept path stores `encoded.variablesPayload()` into the request row in plaintext
|
||||
(`CanonicalNotificationPlanWriter.java:60-79`). The `PAYLOAD_ENCRYPTION` key is consumed only by
|
||||
callback raw-payload protection (`AesGcmCallbackPayloadProtection.java:88-97`), so requiring it in
|
||||
`INGEST_ONLY` would demand a secret that protects nothing — do not paper over the gap that way.
|
||||
|
||||
Per index §Scope boundaries, Notification is **not promoted to Stable** until one of the two branches
|
||||
is complete. Neither branch is optional; pick one, implement it fully, and record the decision.
|
||||
|
||||
**Recommendation: the threat-model branch**, if and only if the variable types can genuinely be
|
||||
restricted to non-sensitive values. Application-level encryption without rotation and migration
|
||||
designed in is a larger commitment than this wave can honour, and a half-built envelope is worse than
|
||||
a documented restriction.
|
||||
|
||||
- [ ] **Steps 1–6:** implement the chosen branch fully; a partial implementation of either is a fail.
|
||||
|
||||
---
|
||||
|
||||
## Section E — GraphQL
|
||||
|
||||
### Task E1: Collapse the two safety axes into one deployment mode (GQL-INT-002)
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/autoconfigure/GraphQlPlatformProperties.java`
|
||||
- Modify: `.../GraphQlPlatformStartupValidator.java`, `.../GraphQlPlatformAutoConfiguration.java`
|
||||
- Test: `.../GraphQlDeploymentModeContractTest.java`
|
||||
|
||||
**Context:** `GraphQlPlatformProperties` defaults to `production=false` **and**
|
||||
`environment=PRODUCTION_PUBLIC` simultaneously (`GraphQlPlatformProperties.java:32-54`). This is not a
|
||||
display inconsistency: anonymous principal handling, allow-by-default authorization, and part of
|
||||
request protection read only the boolean (`GraphQlPlatformStartupValidator.java:33-45`,
|
||||
`GraphQlPlatformAutoConfiguration.java:302-343,441-459`), so the enum can say production while the
|
||||
protections behave as if it is not — a configuration split-brain that bypasses production safety.
|
||||
|
||||
Both collapse into `backend.graphql.deployment-mode`, with the environment constraint from index
|
||||
§Global Constraints. Using either legacy key while GraphQL is on, alone or alongside the new one, is a
|
||||
migration error naming `APP_GRAPHQL_DEPLOYMENT_MODE`. With the master off, the detail namespace is
|
||||
neither bound nor validated.
|
||||
|
||||
- [x] **Steps 1–7:** done. `GraphQlPlatformEnvironment` → `GraphQlDeploymentMode`; `production` and
|
||||
`environment` are gone from the record and `production()` is derived from the mode;
|
||||
`GraphQlActivationEnvironmentPostProcessor` refuses both retired keys;
|
||||
`GraphQlDeploymentModeContractTest` (22 cases) and
|
||||
`GraphQlDeploymentModeRegistryParityTest` are green, and `local-graphql` passes end to end.
|
||||
|
||||
**Three amendments made while implementing, all recorded in
|
||||
[`evidence/2026-08-15-wave2-decisions.md`](evidence/2026-08-15-wave2-decisions.md):**
|
||||
|
||||
1. **Four modes, not six.** `TEST` and `STAGING` were unreachable from every runtime profile the
|
||||
composition-root validator permits, so they are gone. The registry parity test now derives its
|
||||
cases from the enum.
|
||||
2. **Boot's introspection default contradicted the platform's** — with the switch on and nothing else
|
||||
set, `spring.graphql.schema.introspection.enabled=true` against a platform console default of
|
||||
`false`, and the runtime validator correctly refused a contradiction nobody had configured. The
|
||||
same post-processor now contributes the platform's console values as the framework's defaults at
|
||||
the lowest precedence.
|
||||
3. **The Keycloak realm artifact could never have imported.** Keycloak rejects unknown fields, so the
|
||||
`_comment` and `_flowComment` annotation keys failed the whole import. Removed, rationale moved to
|
||||
`infra/keycloak/README.md`, and `verify-compose-profile-contracts.sh` now fails on any `_`-prefixed
|
||||
key in that artifact. The smoke client also could not read the 0600 secret (uid mismatch) and now
|
||||
runs as root in-container.
|
||||
|
||||
### Task E2: Prove the policy pipeline on the real request path (GQL-INT-003)
|
||||
|
||||
**Files:**
|
||||
- Create: `src/adapter/inbound/graphql/src/test/java/.../GraphQlPolicyRequestPathTest.java`
|
||||
|
||||
**Context:** Auto-configuration and a startup validator existing is not evidence that cost, authz,
|
||||
cursor, and idempotency policies apply. The test uses a random-port `/graphql` and asserts a policy
|
||||
violation is rejected **before** the resolver or use case is invoked — verified with a spy on the use
|
||||
case that must record zero invocations — and that JWT actor/tenant context reaches the resolver.
|
||||
|
||||
- [ ] **Steps 1–6:** TDD cycle, one case per policy.
|
||||
|
||||
### Task E3: One blocking JWT composition lane (GQL-INT-004)
|
||||
|
||||
**Files:**
|
||||
- Create: `src/app-bootstrap/src/graphqlRuntimeQualificationTest/java/dev/caskeleton/bootstrap/graphql/GraphQlJwtRuntimeQualificationTest.java`
|
||||
- Modify: `src/app-bootstrap/build.gradle` (register `graphqlRuntimeQualification`)
|
||||
- Modify: `src/gradle/graphql-platform-conventions.gradle`
|
||||
- Modify: `src/build.gradle` (`conditionalTransportQualification`)
|
||||
- Modify: `.github/workflows/ci-quality-gates.yml`
|
||||
|
||||
**Context:** Three separate defects, all verified:
|
||||
|
||||
1. `ConditionalTransportCompositionContractTest` asserts only that GraphQL classes exist
|
||||
(`:15-46`) — class existence is not composition evidence.
|
||||
2. `GraphqlHttpBoundaryQualificationTest` authenticates with test-only Basic Auth
|
||||
(`:40-59,189-229`) — not the shipped JWT composition.
|
||||
3. CI runs `check verifyPublicPathSnapshot verifyDependencyLocks` and
|
||||
`conditionalTransportQualification`, and **never** `graphqlStableTest`
|
||||
(`.github/workflows/ci-quality-gates.yml:48-53`), so that lane's required-class guard protects
|
||||
nothing in CI.
|
||||
|
||||
The canonical task is `:app-bootstrap:graphqlRuntimeQualification`. It:
|
||||
- depends on `bootJar`;
|
||||
- forces required class
|
||||
`dev.caskeleton.bootstrap.graphql.GraphQlJwtRuntimeQualificationTest` in the
|
||||
`graphqlRuntimeQualificationTest` source set;
|
||||
- runs the produced jar as a **child process**;
|
||||
- obtains a client-credentials token from a Keycloak container importing the same tracked realm
|
||||
artifact Wave 3 Task 4 creates;
|
||||
- calls real HTTP `/graphql`;
|
||||
- writes JUnit XML to `app-bootstrap/build/test-results/graphqlRuntimeQualification` and sanitized
|
||||
process/claim/startup logs to `app-bootstrap/build/evidence/graphql-runtime/`;
|
||||
- rejects zero-discovery, any skip, and stale XML.
|
||||
|
||||
Then: replace the GraphQL Basic Auth leg of root `conditionalTransportQualification` with this task,
|
||||
leaving the gRPC and WebSocket legs untouched; keep `GraphqlHttpBoundaryQualificationTest` as a module
|
||||
contract test but stop aggregating it into release evidence; and change the CI quality job to run
|
||||
`:adapter:inbound:graphql:graphqlStableTest :app-bootstrap:graphqlRuntimeQualification
|
||||
conditionalTransportQualification` with a single dependency edge so the GraphQL task cannot execute
|
||||
twice.
|
||||
|
||||
**Ordering note:** this task depends on Wave 3 Task 4 (the Keycloak realm artifact). Either run Wave 3
|
||||
Task 4 early, or defer E3 to immediately after it. Record which you chose.
|
||||
|
||||
- [ ] **Steps 1–9:** TDD cycle ending with the lane green and the CI workflow updated.
|
||||
|
||||
---
|
||||
|
||||
## Wave 2 Exit Criteria
|
||||
|
||||
- [ ] `./gradlew test --console=plain --no-daemon` — the full ordinary suite green (the single
|
||||
pre-existing failure closed by Task C1).
|
||||
- [ ] `./gradlew wave0RedReport --console=plain --no-daemon` — only Wave 3 and Wave 4 entries remain.
|
||||
- [ ] Each adapter's one-on lane passes against real infrastructure:
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformReleaseGate -Pjpa.matrix.versions=16 --console=plain
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformReleaseGate -Pjpa.matrix.versions=17 --console=plain
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformReleaseGate -Pjpa.matrix.versions=18 --console=plain
|
||||
./gradlew :adapter:outbound:persistence-mongo:mongoStableContractTest \
|
||||
:adapter:outbound:persistence-mongo:mongoReplicaSetTest \
|
||||
:adapter:outbound:persistence-mongo:mongoFailoverTest \
|
||||
:adapter:outbound:persistence-mongo:mongoMigrationTest \
|
||||
:adapter:outbound:persistence-mongo:mongoCompatibilityTest \
|
||||
:adapter:outbound:persistence-mongo:mongoSecurityIntegrationTest \
|
||||
:adapter:outbound:persistence-mongo:mongoPerformanceTest --console=plain
|
||||
./gradlew :adapter:inbound:graphql:graphqlStableTest \
|
||||
:app-bootstrap:graphqlRuntimeQualification conditionalTransportQualification --console=plain
|
||||
```
|
||||
- [ ] `./gradlew verifyRuntimeModuleMembership verifyCleanArchitectureDependencies verifyEnvKeys --console=plain` — green.
|
||||
- [ ] Every Section D and Section B decision (B5, D6) is recorded with its rationale in
|
||||
`docs/superpowers/plans/evidence/2026-08-15-wave2-decisions.md`.
|
||||
|
||||
## What Wave 2 explicitly does not do
|
||||
|
||||
- No `SPRING_PROFILES_ACTIVE` change, `.env` split, Compose file, Keycloak realm, or MinIO fixture
|
||||
(Wave 3) — except that Wave 2 Task E3 **consumes** Wave 3 Task 4's realm artifact.
|
||||
- No warning removal (Wave 4).
|
||||
- No build-logic extraction (Wave 5).
|
||||
- No promotion of Mongo reactive, change streams, sharding, Atlas, or KMS.
|
||||
- No promotion of Notification to Stable until D6 is complete.
|
||||
@@ -0,0 +1,444 @@
|
||||
# Wave 3 — Environment Separation and Infrastructure Smoke Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
|
||||
> (recommended) or superpowers:executing-plans. Steps use checkbox (`- [ ]`) syntax.
|
||||
> **Read [`2026-08-15-five-adapter-runtime-remediation-index.md`](2026-08-15-five-adapter-runtime-remediation-index.md)
|
||||
> first.**
|
||||
> **Entry criterion:** Wave 2 complete — full `test` green, each adapter's one-on lane passing.
|
||||
> **Exception:** Task 4 (Keycloak realm) is a prerequisite of Wave 2 Task E3 and may be pulled
|
||||
> forward. If it was, mark it complete here and continue.
|
||||
|
||||
**Goal:** Separate example configuration from operator input, make a profileless deployment
|
||||
impossible, and build the Compose lane matrix — with its two canonical scripts, Keycloak realm, and
|
||||
MinIO round trip — that proves each activation combination actually runs.
|
||||
|
||||
**Architecture:** One JSON contract file (`config/runtime/compose-profile-contracts.json`) is the SSOT
|
||||
for every lane: its Compose profile, its file stack, its explicit Spring runtime, and its exact sorted
|
||||
service set. Two scripts are the only entry points — one static
|
||||
(`verify-compose-profile-contracts.sh`), one dynamic (`run-compose-runtime-smoke.sh`) — and CI calls
|
||||
those scripts rather than inlining fragments of them, so a lane cannot be half-run by a workflow that
|
||||
forgot a flag. Shared infrastructure lives in its own `docker-compose.infra.yml`, never mixed into an
|
||||
environment overlay. Each lane gets a unique Compose project, mode-0700 temp directory, mode-0600
|
||||
secret files, sanitized evidence, and a `trap`-driven teardown scoped to that project alone.
|
||||
|
||||
**Tech Stack:** Docker Compose ≥ 2.24.4 (this machine: 5.4.0), PostgreSQL 16 with TLS, MongoDB replica
|
||||
set, Kafka, Mailpit, MinIO + `mc`, Keycloak with `--import-realm`, Bash.
|
||||
|
||||
**Spec:** [`2026-08-15-five-adapter-runtime-remediation-review-design.md`](../specs/2026-08-15-five-adapter-runtime-remediation-review-design.md)
|
||||
(§7 in full, §11 Wave 3, §12.4)
|
||||
|
||||
---
|
||||
|
||||
## Global Constraints
|
||||
|
||||
Inherited from the index. Wave 3 adds:
|
||||
|
||||
- **A secret value never reaches Git, rendered config, a command line, JUnit XML, or an evidence
|
||||
artifact.** Secrets are files created per run at mode `0600` and deleted on teardown.
|
||||
- **`up --wait` applies only to long-running services.** A one-shot client (`auth-smoke`,
|
||||
`object-storage-smoke`, `notification-smoke`, `minio-init`) is run with `run --rm` and must exit
|
||||
zero. A required one-shot that is missing, skipped, or non-zero fails the whole lane.
|
||||
- **Teardown is scoped.** `down --volumes --remove-orphans` runs against the lane's unique
|
||||
`COMPOSE_PROJECT_NAME` only. Never touch another project or a named volume outside the lane.
|
||||
- **Reference docs are authoritative for merge and import semantics**, not memory:
|
||||
- [Docker Compose merge rules](https://docs.docker.com/reference/compose-file/merge/)
|
||||
- [Keycloak realm import](https://www.keycloak.org/server/importExport)
|
||||
- **Static verification precedes dynamic.** `config` and `create` must pass before any `up`.
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
### Created
|
||||
|
||||
| File | Responsibility |
|
||||
| --- | --- |
|
||||
| `src/config/runtime/compose-profile-contracts.json` | The lane SSOT: id, Compose profile, file stack, Spring runtime, exact sorted service set, blocking flag. |
|
||||
| `docker-compose.infra.yml` | Every shared infrastructure service and one-shot smoke client. Owns nothing environment-specific. |
|
||||
| `docker-compose.prod-smoke.yml` | TLS PostgreSQL, prod env source, secret references. Test-only. |
|
||||
| `scripts/verify-compose-profile-contracts.sh` | The only static entry point. |
|
||||
| `scripts/run-compose-runtime-smoke.sh` | The only dynamic entry point. |
|
||||
| `infra/keycloak/realms/ca-skeleton-realm.json` | Reproducible realm import. No secret values. |
|
||||
| `infra/keycloak/entrypoint.sh` | Reads the secret file, exports it, execs `kc.sh start-dev --import-realm`. |
|
||||
| `infra/keycloak/smoke/auth-smoke.sh` | The one-shot client-credentials + protected-endpoint assertion. |
|
||||
| `infra/minio/smoke/object-storage-smoke.sh` | upload → HEAD → download → delete → wrong-credential rejection. |
|
||||
| `infra/minio/init/bucket-bootstrap.sh` | Bucket and minimum policy creation. Not a substitute for the round trip. |
|
||||
| `infra/notification/smoke/notification-smoke.sh` | Accept/ingest, Mailpit assertion, duplicate check. |
|
||||
| `src/.env.example` | Public key catalog with empty placeholders. Tracked. |
|
||||
| `src/.env.local.example` | Local opt-in combination example. Tracked. |
|
||||
|
||||
### Modified
|
||||
|
||||
| File | Change |
|
||||
| --- | --- |
|
||||
| `src/app-bootstrap/src/main/resources/application.yml` | Remove the `${SPRING_PROFILES_ACTIVE:local}` fallback. |
|
||||
| `docs/registries/env-keys.yaml` | `SPRING_PROFILES_ACTIVE` becomes a defaultless enum `local\|dev\|prod`. |
|
||||
| `src/app-bootstrap/build.gradle` | Replace the `bootRun`-only `.env` parsing with a single loader; pass an explicit profile. |
|
||||
| `src/build.gradle` | Rewrite `verifyEnvKeys`'s input contract: registry + profile YAML + `.env.example` + generated metadata; never a gitignored operator `.env`. |
|
||||
| `docker-compose.yml` | App only; no infrastructure. |
|
||||
| `docker-compose.local.yml` | Local overlay; profiles for service selection; PostgreSQL moves to infra. |
|
||||
| `docker-compose.dev.yml` | `tmpfs: !override []` then exactly one `/var/tmp/heap` bind mount; owns `SPRING_PROFILES_ACTIVE=dev` and its env source. |
|
||||
| `.gitignore` | Ignore `src/.env*` except the two `.example` files. |
|
||||
| `src/.env` | **Untracked** (`git rm --cached`). It is operator input, not a build input. |
|
||||
| `src/app-bootstrap/src/main/resources/logback-spring.xml` | Profile field reads the real active profile. |
|
||||
| `.github/workflows/ci-quality-gates.yml` | Call the two scripts; do not inline their commands. |
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Make a profileless deployment impossible
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/app-bootstrap/src/main/resources/application.yml:22-24`
|
||||
- Modify: `docs/registries/env-keys.yaml` (`SPRING_PROFILES_ACTIVE` row)
|
||||
- Create: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/activation/RuntimeEnvironmentProfileValidator.java`
|
||||
- Modify: `src/app-bootstrap/build.gradle` (`bootRun` passes an explicit profile)
|
||||
- Modify/replace: `EnvProfileMatrixContractTest` and any profileless-permitting test
|
||||
- Test: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/activation/RuntimeEnvironmentProfileValidatorTest.java`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `RuntimeEnvironmentProfileValidator`, an `EnvironmentPostProcessor` ordered **after**
|
||||
`MasterSwitchEnvironmentPostProcessor` (Wave 1 Task 2). Tasks 5–8 assume exactly one environment
|
||||
profile is resolvable.
|
||||
|
||||
**Context:** Verified at HEAD: `spring.profiles.active: ${SPRING_PROFILES_ACTIVE:local}`. A bootJar
|
||||
started with no profile silently becomes `local`, which — before Wave 2 Task A2 — also meant H2 and
|
||||
`create-drop`. Deployable cardinality is exactly one.
|
||||
|
||||
Rules: missing ⇒ error; blank ⇒ error; unknown ⇒ error naming the three permitted values; multiple
|
||||
(`local,prod`) ⇒ error, and `SPRING_PROFILES_ACTIVE` is **not** treated as CSV; `test` ⇒ rejected for a
|
||||
deployable artifact, permitted only in a test-source context.
|
||||
|
||||
Feature selection must not be expressed as a supplementary Spring profile — the five master switches
|
||||
are for that. The validator therefore rejects any active profile outside the permitted set rather than
|
||||
ignoring extras.
|
||||
|
||||
- [ ] **Step 1:** Write the validator test — one case per rule above, plus one asserting that a
|
||||
test-source context may still use `test`.
|
||||
- [ ] **Step 2:** Run to verify it fails.
|
||||
- [ ] **Step 3:** Remove the `:local` fallback from `application.yml`; write the validator; register
|
||||
it in `META-INF/spring.factories` next to the master-switch post-processor.
|
||||
- [ ] **Step 4:** Update the `SPRING_PROFILES_ACTIVE` registry row to a defaultless enum.
|
||||
- [ ] **Step 5:** Make `bootRun` pass an explicit profile so the developer convenience path stays
|
||||
usable without reintroducing an implicit default.
|
||||
- [ ] **Step 6:** Replace `EnvProfileMatrixContractTest`'s local-fallback expectation with the new
|
||||
fail-closed contract. Do not delete coverage — rewrite it.
|
||||
- [ ] **Step 7:** Run
|
||||
`./gradlew :app-bootstrap:test --console=plain --no-daemon` and
|
||||
`./gradlew verifyEnvKeys --console=plain --no-daemon`.
|
||||
- [ ] **Step 8:** Commit.
|
||||
|
||||
---
|
||||
|
||||
## Task 2: Separate example configuration from operator input
|
||||
|
||||
**Files:**
|
||||
- Create: `src/.env.example`, `src/.env.local.example`
|
||||
- Modify: `.gitignore`
|
||||
- Untrack: `src/.env` (`git rm --cached src/.env` — the human runs this)
|
||||
- Modify: `src/build.gradle` (`verifyEnvKeys` input contract, lines ~2209-2229, ~2263-2276)
|
||||
- Modify: `src/app-bootstrap/build.gradle` (single env loader, replacing the `bootRun`-only parser at ~251-272)
|
||||
- Test: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/activation/EnvSourceSeparationTest.java`
|
||||
|
||||
**Context:** Verified at HEAD: `src/.env` **is tracked** (`git ls-files` lists it), there is no
|
||||
`.env.example`, and `.gitignore` contains only three unrelated lines. The tracked file carries
|
||||
`SPRING_PROFILES_ACTIVE=local`, `APP_DATASOURCE_DDL_AUTO=update`, and local credentials — which is why
|
||||
`dev` inherits `ddl-auto=update` and fails.
|
||||
|
||||
`verifyEnvKeys` currently **requires** `src/.env` to exist and compares required placeholders against
|
||||
it. That contract is false in both directions: it passes only when a real secret file is present, and
|
||||
it would pass with no example file at all. The new SSOT is the env registry, the profile YAMLs,
|
||||
`.env.example`, and the generated configuration metadata. Gitignored operator `.env*` files and real
|
||||
secret values leave the build inputs entirely.
|
||||
|
||||
`.gitignore` addition:
|
||||
|
||||
```gitignore
|
||||
src/.env*
|
||||
!src/.env.example
|
||||
!src/.env.local.example
|
||||
```
|
||||
|
||||
- [ ] **Step 1:** Write `EnvSourceSeparationTest` — asserts `.env.example` exists and every registry
|
||||
key appears in it; that no example value looks like a real secret (non-empty for a
|
||||
`classification: secret` row); and that `src/.env` is **not** tracked
|
||||
(`git ls-files --error-unmatch src/.env` must fail).
|
||||
- [ ] **Step 2:** Run to verify it fails.
|
||||
- [ ] **Step 3:** Generate `.env.example` from the registry — every key, secrets as empty
|
||||
placeholders or `secret://` references. Write `.env.local.example` with a documented local
|
||||
opt-in combination.
|
||||
- [ ] **Step 4:** Update `.gitignore`; ask the human to run `git rm --cached src/.env`.
|
||||
- [ ] **Step 5:** Rewrite `verifyEnvKeys`'s inputs; replace the `bootRun`-only `.env` parser with a
|
||||
loader that selects the file by environment, or with Spring's standard config import.
|
||||
- [ ] **Step 6:** Run `./gradlew verifyEnvKeys :app-bootstrap:test --console=plain --no-daemon`.
|
||||
- [ ] **Step 7:** Commit.
|
||||
|
||||
---
|
||||
|
||||
## Task 3: The Compose contract SSOT and the static verifier
|
||||
|
||||
**Files:**
|
||||
- Create: `src/config/runtime/compose-profile-contracts.json`
|
||||
- Create: `scripts/verify-compose-profile-contracts.sh`
|
||||
- Modify: `docker-compose.yml`, `docker-compose.local.yml`, `docker-compose.dev.yml`
|
||||
- Create: `docker-compose.infra.yml`, `docker-compose.prod-smoke.yml`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: the contract file, whose schema is
|
||||
`{ "minimumComposeVersion": "2.24.4", "lanes": [ { "id", "composeProfile"|null, "files": [...],
|
||||
"springRuntime", "services": [...sorted], "blocking": true } ] }`.
|
||||
Task 7's runtime-smoke script and Wave 6's matrix both read it.
|
||||
|
||||
**Context:** The full lane table is spec §7.2 and is reproduced here as the exact content to encode.
|
||||
`base`, `infra`, `local`, `dev`, `prod-smoke` mean `docker-compose.yml`, `docker-compose.infra.yml`,
|
||||
`docker-compose.local.yml`, `docker-compose.dev.yml`, `docker-compose.prod-smoke.yml`, merged in the
|
||||
order listed.
|
||||
|
||||
| lane | Compose profile | file stack | Spring runtime | services (sorted) |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `off-local` | — | base+local | `local` | `app` |
|
||||
| `off-dev` | — | base+dev | `dev` | `app` |
|
||||
| `off-prod` | — | base+prod-smoke | `prod` | `app` |
|
||||
| `local-jpa` | `local-jpa` | base+infra+local | `local` | `app,db` |
|
||||
| `local-mongo` | `local-mongo` | base+infra+local | `local` | `app,mongo,mongo-rs-init` |
|
||||
| `local-messaging` | `local-messaging` | base+infra+local | `local` | `app,kafka` |
|
||||
| `local-messaging-outbox` | `local-messaging-outbox` | base+infra+local | `local` | `app,db,kafka` |
|
||||
| `local-notification-ingest` | `local-notification-ingest` | base+infra+local | `local` | `app,db,notification-smoke` |
|
||||
| `local-notification-serving` | `local-notification-serving` | base+infra+local | `local` | `app,db,mailpit,notification-smoke` |
|
||||
| `local-notification-handoff` | `local-notification-handoff` | base+infra+local | `local` | `app,db,mailpit,notification-smoke` |
|
||||
| `local-graphql` | `local-graphql` | base+infra+local | `local` | `app,auth-smoke,keycloak` |
|
||||
| `shared-infra-local` | `shared-infra` | base+infra+local | `local` | `app,auth-smoke,db,keycloak,minio,minio-init,object-storage-smoke` |
|
||||
| `shared-infra-dev` | `shared-infra` | base+infra+dev | `dev` | `app,auth-smoke,db,keycloak,minio,minio-init,object-storage-smoke` |
|
||||
| `prod-smoke` | `prod-smoke` | base+infra+prod-smoke | `prod` | `app,auth-smoke,db,keycloak,minio,minio-init,object-storage-smoke` |
|
||||
| `all-adapters` | `all-adapters` | base+infra+local | `local` | `app,auth-smoke,db,kafka,keycloak,mailpit,mongo,mongo-rs-init,notification-smoke` |
|
||||
|
||||
Service membership rules:
|
||||
- `auth-smoke` ∈ `local-graphql`, `shared-infra`, `prod-smoke`, `all-adapters`.
|
||||
- `object-storage-smoke` ∈ `shared-infra`, `prod-smoke`.
|
||||
- `notification-smoke` ∈ the three local notification profiles and `all-adapters`.
|
||||
- `minio-init` bootstraps bucket and policy; it is **not** a substitute for the round trip.
|
||||
- A Compose profile selects services; it never implies a Spring profile.
|
||||
|
||||
The dev merge fix, using Compose ≥ 2.24.4 semantics: the dev overlay declares
|
||||
`tmpfs: !override []` to replace the base tmpfs, then declares the `/var/tmp/heap` bind mount exactly
|
||||
once. Do not assume an empty sequence auto-deletes the base sequence — verify target uniqueness in the
|
||||
merged JSON, which is what the script's final check does.
|
||||
|
||||
The verifier checks, per lane:
|
||||
1. `docker compose version --short` ≥ the contract's `minimumComposeVersion` (semver compare);
|
||||
2. `config --services` for the lane's file stack (with `--profile <name>`, omitted for the three off
|
||||
lanes) equals the contract's sorted set **exactly** — not a superset;
|
||||
3. the rendered `app` service's `SPRING_PROFILES_ACTIVE` equals the lane's `springRuntime`;
|
||||
4. `--profile '*' config --format json` renders, and every service's `volumes` + `tmpfs` targets are
|
||||
unique within that service.
|
||||
|
||||
- [ ] **Step 1:** Write the contract JSON encoding the table above.
|
||||
- [ ] **Step 2:** Restructure the Compose files: move PostgreSQL out of `docker-compose.local.yml`
|
||||
into `docker-compose.infra.yml`; add Mongo + `mongo-rs-init`, Kafka, Mailpit, MinIO +
|
||||
`minio-init` + `object-storage-smoke`, Keycloak + `auth-smoke`, `notification-smoke`; add
|
||||
Compose `profiles:` to each; create `docker-compose.prod-smoke.yml`; apply the `!override` fix
|
||||
to `docker-compose.dev.yml` and give it `SPRING_PROFILES_ACTIVE=dev` plus its env source.
|
||||
- [ ] **Step 3:** Write `scripts/verify-compose-profile-contracts.sh` implementing checks 1–4.
|
||||
`set -euo pipefail`; `jq` for JSON; exit non-zero with the lane id and the exact diff on any
|
||||
mismatch.
|
||||
- [ ] **Step 4:** Run `./scripts/verify-compose-profile-contracts.sh`. Expected: all 15 lanes pass.
|
||||
- [ ] **Step 5:** Run
|
||||
`cd src && ./gradlew :app-bootstrap:test --tests '*ComposeMergeCharacterizationTest*'`
|
||||
— the dev case is now green; remove its `@Tag("wave0-red")`.
|
||||
- [ ] **Step 6:** Pin the Compose minimum version in `README.md` and the CI workflow.
|
||||
- [ ] **Step 7:** Commit.
|
||||
|
||||
---
|
||||
|
||||
## Task 4: The Keycloak realm and its acceptance
|
||||
|
||||
> **May be pulled forward** — Wave 2 Task E3 depends on this artifact.
|
||||
|
||||
**Files:**
|
||||
- Create: `infra/keycloak/realms/ca-skeleton-realm.json`
|
||||
- Create: `infra/keycloak/entrypoint.sh`
|
||||
- Create: `infra/keycloak/smoke/auth-smoke.sh`
|
||||
- Modify: `docker-compose.infra.yml`, `src/app-bootstrap/src/main/resources/application-local.yml`
|
||||
|
||||
**Context:** The realm defines `ca-skeleton-api` as a **confidential** client with client
|
||||
authentication and a service account enabled, and with standard flow and direct access grant
|
||||
**disabled**. The service account carries realm role `user` and client role `graphql-query`; an
|
||||
audience mapper puts `ca-skeleton-api` into `aud`. Authentication for smoke is OAuth 2.0
|
||||
`client_credentials` — one method, no alternatives. No test user, no password grant, no direct access
|
||||
grant.
|
||||
|
||||
The seven acceptance checks (spec §7.3):
|
||||
1. realm `ca-skeleton` imported;
|
||||
2. client/audience `ca-skeleton-api` exists;
|
||||
3. the application's roles and the role/permission claim mapping exist;
|
||||
4. a token is issued via the service account's client credentials;
|
||||
5. the token has non-blank `sub`, exact `iss`, `aud=ca-skeleton-api`, `realm_access.roles` containing
|
||||
`user`, and `resource_access.ca-skeleton-api.roles` containing `graphql-query`;
|
||||
6. public health succeeds unauthenticated; protected REST and GraphQL succeed only with a valid token;
|
||||
7. wrong realm, wrong audience, and expired token are rejected with the expected safe error contract.
|
||||
|
||||
**The issuer trap, and why one hostname is not enough.** `application-local.yml:68-76,142-145` defaults
|
||||
the issuer to `localhost:8081`. That resolves on the host and, inside the app container, points at the
|
||||
app itself. JWKS discovery is lazy (`JwtDecoderConfig.java:25-58`), so startup succeeds and the error
|
||||
only appears at the first protected request. Do not assume one hostname resolves everywhere:
|
||||
|
||||
- **bootJar qualification** (Wave 2 E3): inject Testcontainers' *mapped* Keycloak URL into both the
|
||||
token endpoint and the app issuer — the same single URL on both sides.
|
||||
- **Compose smoke**: put `app` and `auth-smoke` on the same network and inject
|
||||
`http://keycloak:8080/realms/ca-skeleton` into both.
|
||||
|
||||
A token obtained from one URL and validated against another is not evidence, and neither is a
|
||||
successful startup.
|
||||
|
||||
**Secret handling.** The qualification script creates a URL-safe random secret file at mode `0600` per
|
||||
run and mounts it as a Compose/Testcontainers secret. `entrypoint.sh` reads
|
||||
`/run/secrets/keycloak-graphql-smoke-client-secret`, exports it as a process-local
|
||||
`KEYCLOAK_GRAPHQL_SMOKE_CLIENT_SECRET`, and `exec`s
|
||||
`/opt/keycloak/bin/kc.sh start-dev --import-realm`. The realm JSON contains only the
|
||||
`${KEYCLOAK_GRAPHQL_SMOKE_CLIENT_SECRET}` reference. The file is removed on teardown.
|
||||
|
||||
- [ ] **Steps 1–8:** build the realm, entrypoint, and smoke script; wire the Compose service; run
|
||||
`./scripts/verify-compose-profile-contracts.sh` and then the `local-graphql` lane; confirm all
|
||||
seven checks; confirm no secret value appears in any rendered config or artifact
|
||||
(`grep -r` the evidence directory for the generated value must find nothing).
|
||||
|
||||
---
|
||||
|
||||
## Task 5: MinIO bucket bootstrap and a real object round trip
|
||||
|
||||
**Files:**
|
||||
- Create: `infra/minio/init/bucket-bootstrap.sh`, `infra/minio/smoke/object-storage-smoke.sh`
|
||||
- Modify: `docker-compose.infra.yml`
|
||||
|
||||
**Context:** MinIO readiness is not success. `minio-init` creates the test bucket and minimum policy;
|
||||
`object-storage-smoke` is a **black-box** one-shot that consumes the lane's endpoint, bucket, and
|
||||
secret file and performs, in order and with no step skippable:
|
||||
|
||||
1. upload known bytes to a random object key;
|
||||
2. HEAD and verify size and checksum;
|
||||
3. download and verify byte equality;
|
||||
4. delete and verify not-found;
|
||||
5. attempt the same operations with a deliberately wrong credential and verify rejection.
|
||||
|
||||
Results are written to `minio-roundtrip.json` in the lane's evidence directory, with no secrets.
|
||||
|
||||
Boundaries: the existing object-storage qualification owns its own Testcontainers and random
|
||||
credentials, so it is **not** evidence about this Compose service — keep it, but give the Compose lane
|
||||
a separate name and separate artifacts. Local or static credentials are never passed to `prod-smoke`.
|
||||
`minio-init` succeeding is never accepted in place of the round trip. Whether object storage joins the
|
||||
`app-bootstrap` runtime is a **separate decision** from the five master switches; if it does not, this
|
||||
smoke client is a release fixture, not a production bean.
|
||||
|
||||
The client image is pinned **by digest**.
|
||||
|
||||
- [ ] **Steps 1–6:** build both scripts, wire the services, run the `shared-infra-local` lane, verify
|
||||
the artifact, confirm no secret leaked, commit.
|
||||
|
||||
---
|
||||
|
||||
## Task 6: The notification smoke client and the stateful handoff lane
|
||||
|
||||
**Files:**
|
||||
- Create: `infra/notification/smoke/notification-smoke.sh`
|
||||
- Modify: `docker-compose.infra.yml`
|
||||
|
||||
**Context:** Three lanes use this client. `local-notification-ingest` proves durable accept with zero
|
||||
provider beans and zero workers. `local-notification-serving` proves a real Mailpit delivery.
|
||||
|
||||
`local-notification-handoff` is a **composite stateful lane**, not two lanes concatenated. The same
|
||||
project, the same PostgreSQL service, and the same named volume persist across four phases:
|
||||
|
||||
1. Start DB and app with `INGEST_ONLY` phase env. Store an accept request using credential-free
|
||||
Mailpit route metadata. Record the request ID and route version in evidence. Confirm via the
|
||||
activation report that provider beans/calls and worker threads are all zero.
|
||||
2. Stop **only the app**, cleanly. Do not bring down the DB or the volume.
|
||||
3. In the same project, recreate the app with `SERVING` phase env and reference-provider settings
|
||||
(`--force-recreate`), and bring Mailpit to ready.
|
||||
4. Re-run the smoke with the phase-1 request ID and frozen route version. Assert exactly one Mailpit
|
||||
message, a terminal DB state, and the same route version. Wait at least one more dispatch poll
|
||||
window and assert duplicates are still zero.
|
||||
|
||||
Only after both phases and the intermediate app exit succeed does the lane proceed to shared evidence
|
||||
collection and teardown. Deleting the volume after phase 1, or copying rows into a second project, is
|
||||
not handoff evidence.
|
||||
|
||||
- [ ] **Steps 1–7:** build the client, encode the phases in the runtime-smoke wrapper (Task 7), run
|
||||
the lane, verify the evidence, commit.
|
||||
|
||||
---
|
||||
|
||||
## Task 7: The runtime-smoke wrapper
|
||||
|
||||
**Files:**
|
||||
- Create: `scripts/run-compose-runtime-smoke.sh`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `--matrix <contract.json>` (all blocking lanes, zero-discovery and zero-skip) and
|
||||
`--lane <id>` (focused reproduction only — never a substitute for a matrix run). Wave 6 runs the
|
||||
matrix form.
|
||||
|
||||
**Context:** The wrapper enforces this order internally so no human and no CI job can skip a step:
|
||||
|
||||
1. Create a per-lane, per-run `COMPOSE_PROJECT_NAME` and a mode-`0700` temp directory; write env and
|
||||
secret files at mode `0600`. **Fail** if the evidence directory already exists — never reuse one.
|
||||
2. Run `verify-compose-profile-contracts.sh`, then `config`, then `create`.
|
||||
3. `up --wait` the long-running services only; check app health/readiness and the resolved activation
|
||||
report from Wave 1's `adapteractivation` endpoint.
|
||||
4. `run --rm` each one-shot the lane declares (`auth-smoke`, `object-storage-smoke`,
|
||||
`notification-smoke`); for JPA lanes, assert the app's migration/schema/TLS report. A required
|
||||
one-shot that is missing, skipped, or non-zero fails the lane.
|
||||
5. Write to `src/app-bootstrap/build/evidence/runtime-smoke/<lane>/<run-id>/`: `manifest.json`, the
|
||||
Compose and service-set digest, activation/health, DB migration/TLS, sanitized Keycloak claims,
|
||||
the MinIO round trip, and a warning/error summary. Never a raw token, URI credential, secret value,
|
||||
or rendered secret.
|
||||
6. On **both** success and failure: collect sanitized logs and container exits **first**, then in a
|
||||
`trap` run `down --volumes --remove-orphans` against this project only, and delete the temp env and
|
||||
secret files. Never touch another project or an outside named volume.
|
||||
|
||||
The `local-notification-handoff` phase sequence from Task 6 lives here.
|
||||
|
||||
- [ ] **Steps 1–8:** write it, run `--lane off-local` first, then `--lane local-jpa`, then the full
|
||||
`--matrix`, verifying evidence and teardown each time. Confirm with
|
||||
`docker ps -a` and `docker volume ls` that nothing outside the lane's project was touched.
|
||||
|
||||
---
|
||||
|
||||
## Task 8: Wire CI to the scripts
|
||||
|
||||
**Files:**
|
||||
- Modify: `.github/workflows/ci-quality-gates.yml`
|
||||
|
||||
**Context:** CI calls the two scripts and nothing else for Compose work. Verified at HEAD, the quality
|
||||
job runs `./gradlew check verifyPublicPathSnapshot verifyDependencyLocks` and
|
||||
`./gradlew conditionalTransportQualification`, with no Compose verification at all. Inlining wrapper
|
||||
fragments would let a workflow silently run a lane without its one-shots, and past evidence must never
|
||||
be aggregated as a current pass.
|
||||
|
||||
- [ ] **Steps 1–4:** add the two script invocations, run the workflow (or `act`/a branch push), confirm
|
||||
both execute and fail loudly on a deliberately broken lane, commit.
|
||||
|
||||
---
|
||||
|
||||
## Wave 3 Exit Criteria
|
||||
|
||||
- [ ] `./scripts/verify-compose-profile-contracts.sh` — all 15 lanes pass.
|
||||
- [ ] `./scripts/run-compose-runtime-smoke.sh --matrix src/config/runtime/compose-profile-contracts.json`
|
||||
— every blocking lane passes with zero discovery failures and zero skips, including
|
||||
`prod-smoke` actually starting TLS DB + app + Keycloak + MinIO and running both one-shots.
|
||||
- [ ] `git ls-files src/.env` returns nothing; `src/.env.example` and `src/.env.local.example` are
|
||||
tracked.
|
||||
- [ ] A profileless bootJar start fails; `local,prod` fails; `stage` fails; each of `local`, `dev`,
|
||||
`prod` succeeds.
|
||||
- [ ] `cd src && ./gradlew verifyEnvKeys --console=plain --no-daemon` — green with the new input
|
||||
contract, and green with `src/.env` absent.
|
||||
- [ ] `./gradlew wave0RedReport` — only the Wave 4 warning entry remains.
|
||||
- [ ] No secret value appears anywhere under
|
||||
`src/app-bootstrap/build/evidence/` (`grep -r` the generated values finds nothing).
|
||||
|
||||
## What Wave 3 explicitly does not do
|
||||
|
||||
- No warning removal (Wave 4) and no build-logic extraction (Wave 5).
|
||||
- No promotion of object storage into the `app-bootstrap` runtime — that decision is separate from the
|
||||
five master switches and is not made here.
|
||||
- No reuse of local MinIO or Keycloak credentials in `prod-smoke`.
|
||||
- No acceptance of `minio-init` success as round-trip evidence, of Keycloak readiness as realm
|
||||
evidence, or of a successful startup as issuer evidence.
|
||||
@@ -0,0 +1,254 @@
|
||||
# Wave 4 — Runtime Warning and IDE Error Zero Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
|
||||
> (recommended) or superpowers:executing-plans. Steps use checkbox (`- [ ]`) syntax.
|
||||
> **Read [`2026-08-15-five-adapter-runtime-remediation-index.md`](2026-08-15-five-adapter-runtime-remediation-index.md)
|
||||
> first.**
|
||||
> **Entry criterion:** Wave 3 complete — the Compose lane matrix passes and each environment starts
|
||||
> from its own env source.
|
||||
|
||||
**Goal:** Zero WARN and zero ERROR in `local`, `dev`, and `prod` startup logs with an **empty**
|
||||
allowlist, plus a structured-log profile field that agrees with the real active profile, plus IDE
|
||||
suppressions narrowed to the exact false positives they were written for.
|
||||
|
||||
**Architecture:** Every warning is fixed at its cause, never suppressed. The three runtime warning
|
||||
families each have a different root cause and therefore a different fix: the Micrometer warnings are an
|
||||
ordering problem (a filter installed after meters exist), the `BeanPostProcessorChecker` warnings are a
|
||||
dependency-graph problem (a bean resolved too early), and the Flyway one is diagnosed before it is
|
||||
fixed because "framework bug" and "application eager dependency" call for opposite responses. The
|
||||
warning gate itself is the Wave 0 recorder, promoted from characterization to a blocking check.
|
||||
|
||||
**Tech Stack:** Micrometer `MeterRegistryCustomizer`/`MeterFilter`, Spring `ObjectProvider`, Logback
|
||||
`springProfile`, Eclipse JDT preferences, Spring Tools LS settings.
|
||||
|
||||
**Spec:** [`2026-08-15-five-adapter-runtime-remediation-review-design.md`](../specs/2026-08-15-five-adapter-runtime-remediation-review-design.md)
|
||||
(§9 in full, §11 Wave 4)
|
||||
|
||||
---
|
||||
|
||||
## Global Constraints
|
||||
|
||||
Inherited from the index. Wave 4 adds:
|
||||
|
||||
- **Fix the cause, never the symptom.** Lowering a log level, adding a logger exclusion, or marking a
|
||||
bean `ROLE_INFRASTRUCTURE` to quiet a checker are all forbidden. `ROLE_INFRASTRUCTURE` is called out
|
||||
by name in spec §9.2 because it looks like a fix and is a mute button.
|
||||
- **The allowlist is empty by default and empty at the end.** A third-party warning that genuinely
|
||||
cannot be removed during implementation may be quarantined in a registry entry carrying an owner, an
|
||||
upstream issue link, and an expiry date — but the final warning-zero judgement requires **zero
|
||||
allowlist entries** unless the user separately approves an exception.
|
||||
- **A Gradle gate does not speak for the IDE.** IDE Problems zero is confirmed by a human, against a
|
||||
named JDK, extension set, and settings file. Do not claim a Gradle task verified it.
|
||||
- **Hikari leak-detection messages are not memory leaks.** They are a distinct diagnostic; connection
|
||||
leaks and ThreadLocal/executor lifecycle get their own tests rather than being folded into this
|
||||
wave's warning count.
|
||||
|
||||
---
|
||||
|
||||
## Baseline
|
||||
|
||||
Reproduced during the review and pinned by Wave 0 Task 6:
|
||||
|
||||
| Warning | Source | Task |
|
||||
| --- | --- | --- |
|
||||
| `BeanPostProcessorChecker` early instantiation of `RolePermissionPolicy`, `RolePermissionRegistry`, `AuthorizationAdapter` | authorization E2E bean-creation chain | 2 |
|
||||
| ×2 "meter registered before MeterFilter added" | `MetricsContractConfig.java:17-50` installs filters in `@PostConstruct` | 1 |
|
||||
| `BeanPostProcessorChecker` on a Flyway converter (dev only) | Boot/Flyway configuration ordering | 3 |
|
||||
| structured-log `profile` field disagrees with the real active profile | `logback-spring.xml:8-9` reads `SPRING_PROFILES_ACTIVE` with `defaultValue="local"` | 4 |
|
||||
|
||||
Also confirmed green and to be kept green: `./gradlew help --warning-mode all` and
|
||||
`./gradlew compileJava compileTestJava --warning-mode all` both succeed with no deprecation or
|
||||
`-Werror` output. Java compilation already runs `-Werror -Xlint:deprecation -Xlint:unchecked`
|
||||
(`src/build.gradle:353`).
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Install meter filters before the registry has meters
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/metrics/MetricsContractConfig.java`
|
||||
- Modify: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/bootstrap/metrics/SampleMetricsContractConfig.java`
|
||||
- Test: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/metrics/MeterFilterOrderingTest.java`
|
||||
|
||||
**Context:** `MetricsContractConfig` fetches the registry in `@PostConstruct` and installs filters
|
||||
then — by which point meters registered during earlier bean construction already exist, and Micrometer
|
||||
warns that the filter cannot apply to them. The filter is not merely noisy; it is **partially
|
||||
ineffective**, which is the real defect. A naming or tag policy that skips the meters registered before
|
||||
it produces inconsistent metric names in production.
|
||||
|
||||
The same late-filter assembly is duplicated in `SampleMetricsContractConfig.java:18-41`. Fixing only
|
||||
the app-bootstrap copy leaves the warning reproducible from the sample composition root, so both change
|
||||
together.
|
||||
|
||||
The fix is `MeterRegistryCustomizer<MeterRegistry>` beans, which Boot applies at registry creation, with
|
||||
explicit `@Order` where filters must compose in a defined sequence.
|
||||
|
||||
- [ ] **Step 1:** Write `MeterFilterOrderingTest` — a context asserting (a) zero Micrometer warnings
|
||||
via `StartupWarningRecorder`, and (b) that a meter registered by the earliest-constructed bean
|
||||
still carries the filter's effect, which is the assertion that proves the fix rather than the
|
||||
silence.
|
||||
- [ ] **Step 2:** Run to verify it fails.
|
||||
- [ ] **Step 3:** Convert both configs to `MeterRegistryCustomizer`.
|
||||
- [ ] **Step 4:** Run to verify it passes.
|
||||
- [ ] **Step 5:** Run `./gradlew :app-bootstrap:test :sample-portfolio:test --console=plain --no-daemon`.
|
||||
- [ ] **Step 6:** Commit.
|
||||
|
||||
---
|
||||
|
||||
## Task 2: Remove the authorization early-instantiation chain
|
||||
|
||||
**Files:**
|
||||
- Create: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/security/AuthorizationBeanGraphTest.java`
|
||||
- Modify: whichever configuration the reproduction identifies
|
||||
|
||||
**Context:** `RolePermissionPolicy`, `RolePermissionRegistry`, and `AuthorizationAdapter` are
|
||||
instantiated before all `BeanPostProcessor`s are ready, so they are not eligible for post-processing —
|
||||
meaning AOP, `@Transactional`, and metrics decoration may silently not apply to them. That is the harm;
|
||||
the log line is only how it is visible.
|
||||
|
||||
**Diagnose before fixing.** Build a minimal context that reproduces the chain and identify which
|
||||
consumer resolves `AuthorizationPort` eagerly — spec §9.2 points at an infrastructure advisor and a
|
||||
Spring Data projection post-processor as the likely candidates, but *likely* is not a diagnosis. Only
|
||||
then choose between deferring the lookup through `ObjectProvider`/`Supplier` and excluding an
|
||||
unnecessary slice auto-configuration.
|
||||
|
||||
Forbidden: marking the beans `ROLE_INFRASTRUCTURE`. It silences the checker and leaves the beans
|
||||
un-post-processed, which is the actual problem.
|
||||
|
||||
- [ ] **Steps 1–7:** minimal reproduction → named diagnosis recorded in the evidence log → fix →
|
||||
assert zero `BeanPostProcessorChecker` records for these three types → full suite → commit.
|
||||
|
||||
---
|
||||
|
||||
## Task 3: Diagnose and fix the Flyway converter warning
|
||||
|
||||
**Files:**
|
||||
- Create: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/migration/FlywayConfigurationOrderingTest.java`
|
||||
- Modify: as the diagnosis dictates
|
||||
|
||||
**Context:** Appears on `dev` only. Pin the Boot/Flyway configuration creation order in a minimal
|
||||
reproduction, then decide: a framework bug is reported upstream and quarantined with an owner and
|
||||
expiry; an application eager dependency is fixed here. The two answers are opposite, so guessing costs
|
||||
more than reproducing.
|
||||
|
||||
Note that Wave 1 Task 9 moved migration under the JPA capability root, so this warning now appears only
|
||||
in JPA-on contexts — reproduce it there.
|
||||
|
||||
- [ ] **Steps 1–6:** reproduce → diagnose → fix or quarantine with owner/issue/expiry → assert → commit.
|
||||
|
||||
---
|
||||
|
||||
## Task 4: Make the log profile field agree with the active profile
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/app-bootstrap/src/main/resources/logback-spring.xml:8-9`
|
||||
- Test: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/logging/LogProfileAgreementTest.java`
|
||||
|
||||
**Context:** Verified at HEAD: logback reads `SPRING_PROFILES_ACTIVE` with `defaultValue="local"`,
|
||||
independently of Spring's resolved profile. Overriding the profile on the CLI to `prod` while a stale
|
||||
`local` value sits in the environment produces production logs stamped `local` — the field that exists
|
||||
precisely so somebody can tell which environment a log line came from, lying about it.
|
||||
|
||||
Wave 3 Task 1 removed the profile default from `application.yml`, so the remaining fallback here is the
|
||||
last one. Replace the `springProperty` read with `spring.profiles.active` resolved by Spring, and remove
|
||||
the `defaultValue` entirely — with Wave 3's validator, an absent profile can no longer reach a running
|
||||
application, so a default would only mask a contradiction.
|
||||
|
||||
- [ ] **Steps 1–6:** TDD cycle; the test asserts the emitted `profile` field equals
|
||||
`Environment#getActiveProfiles()[0]` for each of `local`, `dev`, `prod`.
|
||||
|
||||
---
|
||||
|
||||
## Task 5: Narrow the IDE suppressions
|
||||
|
||||
**Files:**
|
||||
- Modify: `.vscode/settings.json`
|
||||
- Modify: `.vscode/jdt-compiler.prefs`
|
||||
|
||||
**Context:** Two blanket suppressions, both currently global:
|
||||
|
||||
1. `spring-boot.ls.problem.boot2.MISSING_CONFIGURATION_ANNOTATION: "IGNORE"` — its own comment names
|
||||
the cause: two stereotype-free legacy shims in `adapter:outbound:httpclient`
|
||||
(`OutboundHttpClientConfig`, `OutboundHttpResilienceConfig`) that cannot take `@Configuration`
|
||||
because both composition roots component-scan `dev.caskeleton.adapter`. **Wave 1 Task 3 narrowed
|
||||
those scans**, which removes the reason: convert both shims to structural imports under their
|
||||
capability root, then restore the setting to `WARNING`.
|
||||
2. `.vscode/jdt-compiler.prefs:21-24` ignores three JDT warning categories. Build-versus-JDT
|
||||
divergence is real and these are documented, so keep them — but confirm each is still needed by
|
||||
flipping it back and observing the diagnostics, and record what each currently suppresses.
|
||||
|
||||
Note `.vscode/` is listed in `.gitignore`, so these files are local. Record the reviewed settings in
|
||||
`docs/ide/vscode-baseline.md` so the human's IDE-zero confirmation is reproducible against a named
|
||||
configuration rather than against whatever their editor happens to hold.
|
||||
|
||||
- [ ] **Steps 1–6:** convert the two shims to structural imports → restore the Spring LS setting to
|
||||
`WARNING` → confirm zero new diagnostics → review the three JDT entries and document them →
|
||||
commit.
|
||||
|
||||
---
|
||||
|
||||
## Task 6: Promote the warning recorder to a blocking gate
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/activation/StartupWarningZeroTest.java`
|
||||
- Modify: `scripts/run-compose-runtime-smoke.sh`
|
||||
- Create: `src/config/runtime/warning-allowlist.json`
|
||||
|
||||
**Context:** Extend `StartupWarningZeroTest` from the one all-off `local` case to all three
|
||||
environments and to each one-on activation combination.
|
||||
|
||||
**Wave 0 recorded this test as green, and that is a measurement gap, not good news.** It boots
|
||||
`WebApplicationType.NONE` with every adapter off, while the warnings in the baseline table were
|
||||
observed under `bootRun` — a **web** application with JPA active. The extension must therefore use
|
||||
`WebApplicationType.SERVLET` and JPA-on combinations, or the gate will keep passing while every
|
||||
warning it exists to catch is still emitted. See
|
||||
`docs/superpowers/plans/evidence/2026-08-15-wave0-baseline.md`, "Deviations", item 1. The allowlist file ships **empty**, with a
|
||||
schema requiring `owner`, `upstreamIssue`, and `expiry` on any entry, and a check that fails an entry
|
||||
whose expiry has passed — so a temporary quarantine cannot become permanent by being forgotten.
|
||||
|
||||
Wave 3's runtime-smoke wrapper already writes a warning/error summary per lane. Make a non-empty
|
||||
summary fail the lane, so the gate covers real container startups and not only in-JVM tests.
|
||||
|
||||
- [ ] **Steps 1–7:** extend the test → add the allowlist schema and expiry check → make the wrapper
|
||||
fail on non-empty → run the full matrix → confirm zero → commit.
|
||||
|
||||
---
|
||||
|
||||
## Task 7: Separate the resource-leak question from the warning question
|
||||
|
||||
**Files:**
|
||||
- Create: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/resource/ConnectionLeakTest.java`
|
||||
- Create: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/resource/ThreadLifecycleTest.java`
|
||||
|
||||
**Context:** Spec §9.2 item 5 is explicit that a Hikari leak-detection message is not a memory leak and
|
||||
must not be treated as one. These two tests answer the question the message raises, on their own terms:
|
||||
a connection acquired and not returned is detected as a leak; every executor, scheduler, and ThreadLocal
|
||||
created by an adapter is released when its context closes.
|
||||
|
||||
The thread half reuses `AdapterActivationInventory.liveThreadNamesMatching` (Wave 0 Task 2) — start a
|
||||
context with one adapter on, close it, and assert the adapter's threads are gone.
|
||||
|
||||
- [ ] **Steps 1–6:** TDD cycle for both.
|
||||
|
||||
---
|
||||
|
||||
## Wave 4 Exit Criteria
|
||||
|
||||
- [ ] `cd src && ./gradlew clean compileJava compileTestJava --warning-mode=fail --no-daemon --console=plain` — green.
|
||||
- [ ] `cd src && ./gradlew test --warning-mode=fail --no-daemon --console=plain` — green.
|
||||
- [ ] `StartupWarningZeroTest` green for `local`, `dev`, `prod`, all-off and each one-on combination.
|
||||
- [ ] `src/config/runtime/warning-allowlist.json` contains **zero** entries.
|
||||
- [ ] `./scripts/run-compose-runtime-smoke.sh --matrix src/config/runtime/compose-profile-contracts.json`
|
||||
— every lane's warning/error summary is empty.
|
||||
- [ ] The structured-log `profile` field equals `Environment#getActiveProfiles()[0]` in every smoke.
|
||||
- [ ] `./gradlew wave0RedReport` — empty.
|
||||
- [ ] A human has confirmed IDE Problems zero against the configuration recorded in
|
||||
`docs/ide/vscode-baseline.md`, and that confirmation is recorded with the JDK and extension
|
||||
versions used. **This is a human step; no Gradle task may claim it.**
|
||||
|
||||
## What Wave 4 explicitly does not do
|
||||
|
||||
- No log-level lowering, logger exclusion, or `ROLE_INFRASTRUCTURE` marking to reach silence.
|
||||
- No allowlist entry without owner, upstream issue, and expiry — and none surviving to the exit check.
|
||||
- No claim that a Gradle gate verified the IDE.
|
||||
- No build-logic extraction (Wave 5).
|
||||
@@ -0,0 +1,239 @@
|
||||
# Wave 5 — Gradle Build Logic Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
|
||||
> (recommended) or superpowers:executing-plans. Steps use checkbox (`- [ ]`) syntax.
|
||||
> **Read [`2026-08-15-five-adapter-runtime-remediation-index.md`](2026-08-15-five-adapter-runtime-remediation-index.md)
|
||||
> first.**
|
||||
> **Entry criterion:** Wave 4 complete — a fully green, warning-zero baseline whose task graph,
|
||||
> dependency graph, test selection, and evidence output have been captured as a comparison artifact.
|
||||
|
||||
**Goal:** Extract the duplicated source-set, test-lane, testkit, API-surface, evidence, registry, and
|
||||
dependency machinery into eight TestKit-tested convention plugins in a `build-logic` included build,
|
||||
so that root, settings, and leaf build files each hold only their own responsibility — with the task
|
||||
graph, dependency graph, test selection, and evidence semantics provably unchanged.
|
||||
|
||||
**Architecture:** A `build-logic` included build holds precompiled convention plugins. Settings and
|
||||
root stop re-implementing registry parsing against each other by sharing one typed parser/validator.
|
||||
Every extraction is one step, and every step is verified by diffing the captured baseline artifacts —
|
||||
because the failure mode this wave uniquely risks is a task quietly ceasing to exist and the build
|
||||
reporting green for work it no longer does.
|
||||
|
||||
**Tech Stack:** Gradle 9 included builds, precompiled script plugins (`build-logic/src/main/groovy`),
|
||||
Gradle TestKit.
|
||||
|
||||
**Spec:** [`2026-08-15-five-adapter-runtime-remediation-review-design.md`](../specs/2026-08-15-five-adapter-runtime-remediation-review-design.md)
|
||||
(§10 in full, §11 Wave 5, §14 closing paragraph)
|
||||
|
||||
---
|
||||
|
||||
## Global Constraints
|
||||
|
||||
Inherited from the index. Wave 5 adds:
|
||||
|
||||
- **Never share a diff with a runtime change.** Spec §14 is explicit: build refactoring on top of a
|
||||
red or unverified baseline produces false evidence, because a task that stops existing looks the
|
||||
same as a task that passes.
|
||||
- **LOC is not the goal.** Do not hide logic to move a number. Completion is judged by whether the
|
||||
same source-set/`Test`/API-surface machinery is still copied into two or more leaves, and whether
|
||||
root, settings, and leaf hold only their stated responsibilities.
|
||||
- **Each extraction step is verified by artifact diff, not by "the build still works".**
|
||||
- **Provider semantics stay per-module.** Image, scenario, security requirement, and promotion meaning
|
||||
differ per provider and stay in each module's registry. Do not merge them into one over-general DSL —
|
||||
spec §8.2 names that as a pattern to avoid.
|
||||
- **Do not remove a dependency a provider actually uses.** The exclusion convention exists to make
|
||||
declared exclusions real, not to strip dependencies centrally.
|
||||
|
||||
---
|
||||
|
||||
## Measured baseline
|
||||
|
||||
| File | Lines |
|
||||
| --- | ---: |
|
||||
| `src/build.gradle` | 2,767 |
|
||||
| `src/settings.gradle` | 185 |
|
||||
| `src/app-bootstrap/build.gradle` | 273 |
|
||||
| `src/adapter/outbound/persistence-jpa/build.gradle` | 352 |
|
||||
| `src/adapter/outbound/persistence-mongo/build.gradle` | 346 |
|
||||
| `src/adapter/outbound/messaging/build.gradle` | 105 |
|
||||
| `src/adapter/outbound/notification/build.gradle` | 39 |
|
||||
| `src/adapter/inbound/graphql/build.gradle` | 241 |
|
||||
| `src/gradle/jpa-evidence.gradle` | 930 |
|
||||
|
||||
The duplication that matters, not the size:
|
||||
|
||||
- custom source set + `extendsFrom` + `Test` task + `failOnNoDiscoveredTests`, repeated per lane;
|
||||
- strict qualification lane registration and result-directory wiring, repeated;
|
||||
- testkit artifact/source-set wiring, repeated;
|
||||
- API-surface snapshot render/update/verify machinery, repeated;
|
||||
- registry parsing and validation implemented **twice**, once in settings and once in root
|
||||
verification;
|
||||
- release-evidence manifest and output handling, repeated;
|
||||
- dependency exclusion intent that drifts from the resolved graph — e.g. the notification build claims
|
||||
a YAML exclusion (`adapter/outbound/notification/build.gradle:21-33`) while SnakeYAML remains in its
|
||||
lockfile (`gradle.lockfile:165`).
|
||||
|
||||
And one policy violation: `settings.gradle:37-44` hardcodes `expectedModuleCount = 44`, with a comment
|
||||
arguing the count should be a deliberate decision — but the project policy (`AGENTS.md:52-55`) makes the
|
||||
registry the count's SSOT and `verifyDocumentedLeafCount` enforces it against documents. A number in
|
||||
the build file is the same drift the policy forbids in prose. Meanwhile `verifyDocumentedLeafCount`
|
||||
inspects only some root documents, so a stale count in a module `CLAUDE.md` — for example
|
||||
`src/app-bootstrap/CLAUDE.md`'s "19-leaf dependency list" — is not caught.
|
||||
|
||||
---
|
||||
|
||||
## Task 0: Capture the comparison baseline
|
||||
|
||||
**Files:**
|
||||
- Create: `scripts/capture-build-baseline.sh`
|
||||
- Create: `docs/superpowers/plans/evidence/2026-08-15-wave5-baseline/`
|
||||
|
||||
**Context:** This is the instrument the whole wave is judged by. Capture, from the green Wave 4 state:
|
||||
|
||||
1. `./gradlew tasks --all` — the full task list;
|
||||
2. per-module `./gradlew <path>:dependencies --configuration runtimeClasspath`;
|
||||
3. every lane's JUnit XML **class list** (not timings);
|
||||
4. every evidence directory's file list and manifest schema;
|
||||
5. `./gradlew <every architecture-wide verify task>` output.
|
||||
|
||||
Normalize timestamps, durations, and absolute paths, so a diff shows semantic change only.
|
||||
|
||||
- [ ] **Steps 1–4:** write the script, run it, commit the baseline, and prove the script is
|
||||
deterministic by running it twice and diffing (must be identical).
|
||||
|
||||
---
|
||||
|
||||
## Task 1: `ca.architecture-registry` — one parser for settings and root
|
||||
|
||||
**Files:**
|
||||
- Create: `build-logic/settings.gradle`, `build-logic/build.gradle`
|
||||
- Create: `build-logic/src/main/groovy/ca.architecture-registry.gradle`
|
||||
- Create: `build-logic/src/main/java/dev/caskeleton/buildlogic/registry/ModuleRegistry.java`
|
||||
- Create: `build-logic/src/test/java/dev/caskeleton/buildlogic/registry/ModuleRegistryTest.java`
|
||||
- Modify: `src/settings.gradle`, `src/build.gradle`
|
||||
|
||||
**Context:** First extraction because everything else reads the registry. One typed parser/validator,
|
||||
fail-closed on: a project directory with a `build.gradle` that the registry does not list; a
|
||||
`source_path` that does not exist; a duplicate ID or path; and drift between the resolved runtime
|
||||
project closure and declared memberships (Wave 1 Task 13 already made the closure the comparison input).
|
||||
|
||||
Remove `expectedModuleCount`. The registry is the count.
|
||||
|
||||
Extend `verifyDocumentedLeafCount` to cover tracked root `AGENTS.md`, root `CLAUDE.md`, and **all**
|
||||
`src/**/CLAUDE.md`, and wire it into `check` and CI. Prefer removing the duplicated number from each
|
||||
document over asserting it — a count that is not written cannot drift. Where a document genuinely needs
|
||||
the number, it must be generated.
|
||||
|
||||
- [ ] **Steps 1–8:** TestKit tests first (malformed registry, missing path, duplicate ID, membership
|
||||
drift), then the plugin, then delete both re-implementations, then diff against the baseline.
|
||||
|
||||
## Task 2: `ca.strict-test-lane`
|
||||
|
||||
**Files:** `build-logic/src/main/groovy/ca.strict-test-lane.gradle` + TestKit tests; then apply to the
|
||||
JPA, Mongo, GraphQL, messaging, and app-bootstrap leaves one at a time.
|
||||
|
||||
**Context:** The single largest duplication. The convention owns source set creation, configuration
|
||||
`extendsFrom`, the `Test` task, `failOnNoDiscoveredTests`, stale-XML deletion, required-class
|
||||
enforcement, and the results directory — the shape
|
||||
`src/gradle/graphql-platform-conventions.gradle:55-100` implements by hand today.
|
||||
|
||||
Semantics that must survive verbatim, because each was written against a real failure: stale JUnit XML
|
||||
is deleted before the lane runs (a deleted class would otherwise report as executed), and a lane that
|
||||
executes no test case for a required class fails with a message saying the lane is green only because
|
||||
the class is gone.
|
||||
|
||||
TestKit cases: empty lane fails; duplicate task registration fails; a required class with no executed
|
||||
test case fails; stale XML is removed.
|
||||
|
||||
- [ ] **Steps 1–9:** one leaf per step, diffing lane task names and JUnit XML class lists against the
|
||||
baseline after each.
|
||||
|
||||
## Task 3: `ca.api-surface`
|
||||
|
||||
Read-only `verify` plus an explicitly-named approved `update` task. The two must not be the same task
|
||||
with a flag — an update that runs by default silently blesses a surface change.
|
||||
|
||||
- [ ] **Steps 1–6:** TestKit tests, extraction, per-leaf application, diff.
|
||||
|
||||
## Task 4: `ca.testkit-publisher`
|
||||
|
||||
Testkit source set and consumable artifact, currently repeated. `app-bootstrap` consumes
|
||||
`project(path: ':adapter:outbound:persistence-jpa', configuration: 'jpaTestkit')`; the convention must
|
||||
keep that consumer contract byte-identical.
|
||||
|
||||
- [ ] **Steps 1–6.**
|
||||
|
||||
## Task 5: `ca.evidence`
|
||||
|
||||
Manifest and result schema, deterministic output ordering, and a no-empty-evidence rule. Applies to
|
||||
`src/gradle/jpa-evidence.gradle` (930 lines) and the Mongo/GraphQL equivalents.
|
||||
|
||||
Provider-specific promotion meaning stays in each module registry.
|
||||
|
||||
- [ ] **Steps 1–7.**
|
||||
|
||||
## Task 6: `ca.dependency-policy`
|
||||
|
||||
Common exclusions and constraints, plus verification that each configuration's **resolved graph and
|
||||
lockfile** match the declared intent. The notification/SnakeYAML case is the acceptance test: a build
|
||||
that declares an exclusion while the lockfile still carries the dependency must fail.
|
||||
|
||||
Guard rail: a dependency a provider genuinely uses directly is never centrally removed.
|
||||
|
||||
- [ ] **Steps 1–7.**
|
||||
|
||||
## Task 7: `ca.java-leaf`
|
||||
|
||||
Java 21 toolchain, encoding, compiler flags (`-Werror -Xlint:deprecation -Xlint:unchecked`, currently
|
||||
`src/build.gradle:353`), Error Prone, and the baseline test task.
|
||||
|
||||
- [ ] **Steps 1–6.**
|
||||
|
||||
## Task 8: `ca.optional-adapter`
|
||||
|
||||
Activation metadata plus disabled/on composition-contract wiring for the five adapters. This is the
|
||||
convention that makes Wave 1's off-invariant testing a build-level default rather than something each
|
||||
leaf remembers.
|
||||
|
||||
- [ ] **Steps 1–6.**
|
||||
|
||||
---
|
||||
|
||||
## Task 9: Reduce the three build files to their responsibilities
|
||||
|
||||
**Files:** `src/settings.gradle`, `src/build.gradle`, each leaf `build.gradle`
|
||||
|
||||
Target responsibilities:
|
||||
|
||||
- `settings.gradle`: plugin management, root project name, and applying the registry settings plugin.
|
||||
Nothing else.
|
||||
- root `build.gradle`: shared plugin and version declarations plus architecture-wide lifecycle tasks.
|
||||
- leaf `build.gradle`: plugins, project and external dependencies, and that leaf's own semantic
|
||||
lane/matrix.
|
||||
|
||||
- [ ] **Steps 1–5:** reduce, run the full verification set, diff against the baseline, commit.
|
||||
|
||||
---
|
||||
|
||||
## Wave 5 Exit Criteria
|
||||
|
||||
- [ ] `./scripts/capture-build-baseline.sh` output **diffs clean** against the Wave 4 baseline for the
|
||||
task list, dependency graphs, JUnit XML class lists, and evidence manifests. A task that
|
||||
disappeared is a failure even if everything green stayed green.
|
||||
- [ ] `cd src && ./gradlew clean check --warning-mode=fail --no-daemon --console=plain` — green.
|
||||
- [ ] `./gradlew verifyCleanArchitectureDependencies verifyEnvKeys verifyRuntimeModuleMembership
|
||||
verifyPublicPathSnapshot verifyDocumentedLeafCount --console=plain` — green.
|
||||
- [ ] `build-logic`'s own TestKit suite is green and covers malformed registry, empty lane, duplicate
|
||||
task, and membership drift.
|
||||
- [ ] `expectedModuleCount` is gone from `src/settings.gradle`.
|
||||
- [ ] `verifyDocumentedLeafCount` covers root `AGENTS.md`, root `CLAUDE.md`, and every
|
||||
`src/**/CLAUDE.md`, and is wired into `check` and CI.
|
||||
- [ ] No source-set/`Test`/API-surface machinery is copied into two or more leaves.
|
||||
- [ ] `./scripts/run-compose-runtime-smoke.sh --matrix ...` — still green, proving the refactor did not
|
||||
change what actually runs.
|
||||
|
||||
## What Wave 5 explicitly does not do
|
||||
|
||||
- No runtime, configuration, or test-behaviour change in the same diff.
|
||||
- No LOC-driven relocation that hides logic.
|
||||
- No merging of provider-specific release matrices into one generic DSL.
|
||||
- No central removal of a dependency a provider uses directly.
|
||||
@@ -0,0 +1,237 @@
|
||||
# Wave 6 — Final Qualification and Documentation Sync Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans (this wave is
|
||||
> verification-heavy and benefits from one session holding the whole evidence set).
|
||||
> **Read [`2026-08-15-five-adapter-runtime-remediation-index.md`](2026-08-15-five-adapter-runtime-remediation-index.md)
|
||||
> first.**
|
||||
> **Entry criterion:** Wave 5 complete — build logic extracted with a clean baseline diff.
|
||||
|
||||
**Goal:** Run every blocking gate, the full activation matrix, and every environment smoke; reconcile
|
||||
generated metadata and documentation with the code; and produce the evidence set that lets each
|
||||
Definition-of-Done checkbox in spec §13 be ticked with a command and its output attached.
|
||||
|
||||
**Architecture:** Wave 6 adds no capability. It executes, records, and reconciles. Every claim is
|
||||
backed by a command and its output stored under
|
||||
`docs/superpowers/plans/evidence/2026-08-15-wave6-final/`. A checkbox without attached evidence stays
|
||||
unticked, and a gate that could not run is reported as not-run with its reason — never as passing.
|
||||
|
||||
**Spec:** [`2026-08-15-five-adapter-runtime-remediation-review-design.md`](../specs/2026-08-15-five-adapter-runtime-remediation-review-design.md)
|
||||
(§12 in full, §13, §11 Wave 6)
|
||||
|
||||
---
|
||||
|
||||
## Global Constraints
|
||||
|
||||
Inherited from the index. Wave 6 adds:
|
||||
|
||||
- **Use `superpowers:verification-before-completion` before any completion claim.** Evidence precedes
|
||||
assertion, always.
|
||||
- **A not-run gate is reported as not-run.** Spec HARD-STOP 6 (`AGENTS.md:22`) makes claiming
|
||||
completion without the verification, or without naming why it could not run, a stop condition.
|
||||
- **No conclusion broader than its evidence** (HARD-STOP 7). "The matrix passed" requires the matrix,
|
||||
not a representative lane.
|
||||
- **The wave ends with the LLM Wiki capture** required by `AGENTS.md:79-90`, or with an explicit
|
||||
reported reason it was blocked.
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Build and architecture gates
|
||||
|
||||
- [ ] Run and capture each:
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew clean compileJava compileTestJava --warning-mode=fail --no-daemon --console=plain
|
||||
./gradlew test --warning-mode=fail --no-daemon --console=plain
|
||||
./gradlew check --warning-mode=fail --no-daemon --console=plain
|
||||
./gradlew verifyCleanArchitectureDependencies verifyEnvKeys \
|
||||
verifyRuntimeModuleMembership verifyPublicPathSnapshot \
|
||||
verifyDocumentedLeafCount --console=plain
|
||||
```
|
||||
|
||||
- [ ] Confirm `./gradlew wave0RedReport --console=plain --no-daemon` reports an **empty** red set,
|
||||
then delete the `wave0Red` lanes and the aggregate — the characterizations they tracked are now
|
||||
ordinary tests, and a permanent lane for an empty set is a lane that stops being read.
|
||||
|
||||
## Task 2: Focused module gates
|
||||
|
||||
Gradle paths are read from `src/config/architecture/modules.json`, never from memory.
|
||||
|
||||
- [ ] Run and capture:
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:outbound:persistence-jpa:test --console=plain
|
||||
./gradlew :adapter:outbound:persistence-mongo:test --console=plain
|
||||
./gradlew :adapter:outbound:messaging:test --console=plain
|
||||
./gradlew :adapter:outbound:notification:test --console=plain
|
||||
./gradlew :adapter:inbound:graphql:test --console=plain
|
||||
./gradlew :adapter:inbound:graphql:graphqlStableTest \
|
||||
:app-bootstrap:graphqlRuntimeQualification \
|
||||
conditionalTransportQualification --console=plain
|
||||
```
|
||||
|
||||
- [ ] Run the messaging platform's Stable facade focused tests and its live-broker lane separately.
|
||||
Record explicitly that ordinary `test` does **not** substitute for the Docker-backed
|
||||
qualification.
|
||||
|
||||
- [ ] Persistence blocking lanes:
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformReleaseGate -Pjpa.matrix.versions=16 --console=plain
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformReleaseGate -Pjpa.matrix.versions=17 --console=plain
|
||||
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformReleaseGate -Pjpa.matrix.versions=18 --console=plain
|
||||
./gradlew :adapter:outbound:persistence-mongo:mongoStableContractTest \
|
||||
:adapter:outbound:persistence-mongo:mongoReplicaSetTest \
|
||||
:adapter:outbound:persistence-mongo:mongoFailoverTest \
|
||||
:adapter:outbound:persistence-mongo:mongoMigrationTest \
|
||||
:adapter:outbound:persistence-mongo:mongoCompatibilityTest \
|
||||
:adapter:outbound:persistence-mongo:mongoSecurityIntegrationTest \
|
||||
:adapter:outbound:persistence-mongo:mongoPerformanceTest --console=plain
|
||||
```
|
||||
|
||||
- [ ] Confirm Wave 2 Task B5's decision is reflected: either the three lanes exist and run, or their
|
||||
Stable blocking claim is gone from `src/config/mongodb/release-contracts.json`,
|
||||
`docs/mongodb/advanced/sharding.md`, and `scripts/verify-mongodb-advanced.sh`. Attach the
|
||||
`ReleaseManifestTaskExistenceTest` result.
|
||||
|
||||
## Task 3: The activation matrix
|
||||
|
||||
Run each row and capture the resolved activation report, health, exit code, WARN/ERROR count, and the
|
||||
bean/thread inventory.
|
||||
|
||||
| # | Matrix | Expected |
|
||||
| --- | --- | --- |
|
||||
| 1 | five off | boots with no external infrastructure; health OK; adapter beans, resources, threads, endpoints all zero |
|
||||
| 2 | JPA only | PostgreSQL + Flyway + Hibernate `validate` succeed; no Mongo, GraphQL, broker, or provider |
|
||||
| 3 | Mongo only | replica set, client, topology, security succeed; no JPA entity, repository, or pool |
|
||||
| 4 | Messaging only | broker publish/consume succeeds; with relay off, no database needed |
|
||||
| 5 | Notification + JPA, `INGEST_ONLY` | durable accept on a frozen non-empty versioned route; provider credentials, calls, and workers all zero; after a `SERVING` restart, exactly one delivery on the same route |
|
||||
| 6 | Notification + JPA, `SERVING` | reference provider delivery and receipt succeed |
|
||||
| 7 | GraphQL only | schema endpoint plus security/policy pipeline succeed; no persistence resolver |
|
||||
| 8 | relay on, dependency missing | startup rejects, **naming the exact missing switch or provider** |
|
||||
| 9 | JPA + Mongo | distinct ports succeed; two implementations of one port is a startup rejection, not a `@Primary` pick |
|
||||
| 10 | five on | every dependency and endpoint ready; no silent fallback and no duplicate authority |
|
||||
|
||||
- [ ] Row 8 must be checked for the *name*, not merely for a failure. A generic "misconfiguration" is a
|
||||
fail.
|
||||
- [ ] Row 9's conflict case must fail; a bean-ordering or `@Primary` resolution is a fail.
|
||||
|
||||
## Task 4: Environment and runtime gates
|
||||
|
||||
- [ ] Compose artifacts, statically then dynamically:
|
||||
|
||||
```bash
|
||||
./scripts/verify-compose-profile-contracts.sh
|
||||
./scripts/run-compose-runtime-smoke.sh --matrix src/config/runtime/compose-profile-contracts.json
|
||||
```
|
||||
|
||||
- [ ] Confirm the matrix owned every lane: `off-local`, `off-dev`, `off-prod`, each local adapter lane,
|
||||
`shared-infra-local`, `shared-infra-dev`, `prod-smoke`, `all-adapters`.
|
||||
- [ ] Confirm `prod-smoke` actually **started** TLS PostgreSQL, the app, Keycloak, and MinIO and ran
|
||||
both one-shots — a `config`-only pass is a fail.
|
||||
- [ ] Confirm each run stored exit code, active profile, resolved activation report, and WARN/ERROR
|
||||
count as artifacts.
|
||||
- [ ] Confirm no dev or prod lane was made to pass with a local override. Spec §12.4 does not accept
|
||||
that as evidence for the profile.
|
||||
- [ ] Confirm teardown left no stray project or volume: `docker ps -a`, `docker volume ls`.
|
||||
|
||||
## Task 5: Documentation and metadata reconciliation
|
||||
|
||||
- [ ] Regenerate Spring configuration metadata and diff against the env registry and the YAMLs; any
|
||||
drift is a fail.
|
||||
- [ ] Confirm every registry env key appears in `src/.env.example` and that no example carries a real
|
||||
secret.
|
||||
- [ ] Confirm `docs/registries/env-keys.yaml` lists the five masters with `false` defaults and the two
|
||||
subordinate selectors with their `required-when` conditions.
|
||||
- [ ] Confirm no demoted key (`APP_MESSAGING_BROKER`, `APP_NOTIFICATION_SLACK_PROVIDER`,
|
||||
`APP_NOTIFICATION_EMAIL_PROVIDER`, `app.jpa-platform.enabled`) is documented anywhere as an
|
||||
activation switch.
|
||||
- [ ] Update `README.md` with the five switches, the Compose minimum version, and the two script entry
|
||||
points.
|
||||
- [ ] Update `src/app-bootstrap/CLAUDE.md`, replacing its "19-leaf dependency list" phrasing with a
|
||||
pointer to the registry — a count in prose is the drift `AGENTS.md:52-55` forbids.
|
||||
- [ ] Confirm the capability docs do not label as Stable anything the index's scope boundaries exclude:
|
||||
Mongo reactive, change streams, sharding, Atlas, KMS; Notification before NTF-INT-007 is closed.
|
||||
|
||||
## Task 6: Definition of Done
|
||||
|
||||
Walk spec §13 and tick each box **only** with attached evidence. Reproduced here as the checklist:
|
||||
|
||||
- [ ] Five runtime facades on one bootJar runtime classpath.
|
||||
- [ ] Five canonical master switches in registry, YAML, metadata, and docs, all defaulting `false`.
|
||||
- [ ] All-off `local`, `dev`, `prod` smoke succeeds with no external resources.
|
||||
- [ ] Each adapter's off invariant and on fail-closed contract pinned by full-context tests.
|
||||
- [ ] Mongo, GraphQL, and Messaging Stable facades' resolved runtime membership matches the registry.
|
||||
- [ ] The JPA switch controls the whole DataSource/Hikari/entity/repository/Hibernate/Flyway/DB
|
||||
health-and-metrics graph.
|
||||
- [ ] Messaging has a real broker bridge and a consistent relay dependency.
|
||||
- [ ] Notification `SERVING` works through production assemblers; `INGEST_ONLY` starts no worker.
|
||||
- [ ] Notification handoff proves, in one project and DB volume, `INGEST_ONLY` accept → restart →
|
||||
`SERVING` delivery exactly once on the same frozen route, with zero duplicates.
|
||||
- [ ] GraphQL policy and JWT context execute on the real `/graphql` request path.
|
||||
- [ ] GraphQL blocking qualification runs the bootJar JWT composition exactly once and uses neither
|
||||
class-existence nor test-only Basic Auth as release evidence.
|
||||
- [ ] `SPRING_PROFILES_ACTIVE` is exactly one of `local|dev|prod`; profileless, multiple, and unknown
|
||||
deployments are rejected.
|
||||
- [ ] GraphQL on requires one environment-permitted `APP_GRAPHQL_DEPLOYMENT_MODE`; the legacy
|
||||
boolean/enum split-brain is rejected.
|
||||
- [ ] Profiles and env example/secret sources are separated; real secret files are excluded from
|
||||
tracking, rendering, and evidence.
|
||||
- [ ] Compose minimum version, per-profile exact service sets, the whole merged model, and mount-target
|
||||
uniqueness are verified by the canonical script.
|
||||
- [ ] The runtime-smoke wrapper performs create, `up --wait`, required one-shots, sanitized evidence,
|
||||
and unique-project teardown with zero skips across `local`, `dev`, and `prod` blocking lanes.
|
||||
- [ ] PostgreSQL, Mongo, broker, MinIO, and Keycloak/realm smoke evidence exists.
|
||||
- [ ] The Keycloak realm provides a client-credentials-only service account, audience, and role claims,
|
||||
and real JWT-protected REST and GraphQL requests succeed against the same issuer URL per lane.
|
||||
- [ ] Full `test` and `check`, plus architecture, env, public-path, and strict qualification, all pass.
|
||||
- [ ] Zero Gradle, javac, Checkstyle, SpotBugs, and runtime-startup errors and warnings; zero allowlist
|
||||
entries; IDE Problems zero confirmed separately on the same toolchain.
|
||||
- [ ] The real active profile and the structured-log profile field agree; zero late-MeterFilter
|
||||
warnings.
|
||||
- [ ] After convention-plugin extraction, task selection, dependency graph, and evidence semantics are
|
||||
unchanged.
|
||||
- [ ] Every P0 blocker on a runtime path from the detailed module reviews is either closed or its
|
||||
capability is explicitly inactive/experimental.
|
||||
- [ ] Changed files, commands, results, not-run/blocked items, and evidence grades are captured in the
|
||||
LLM Wiki branch-note.
|
||||
|
||||
## Task 7: LLM Wiki capture
|
||||
|
||||
Per `AGENTS.md:79-90`:
|
||||
|
||||
- [ ] Create or update
|
||||
`/home/donghyeon/workspace/ai-tool/llm-wiki-private/raw/branch-notes/<branch-name>.md` with the
|
||||
implementation, changed files, decisions, verification commands, failures/blocks, and evidence
|
||||
grades.
|
||||
- [ ] Create derived documents where genuine material exists: `raw/errors/`, `raw/interviews/`,
|
||||
`raw/blog-topics/`. Each links upward via `## Parent`; the branch-note's `## Cluster / 묶음`
|
||||
links back.
|
||||
- [ ] Where no derived document is warranted, record that judgement explicitly ("추출할 별도 글감
|
||||
없음") rather than omitting the section.
|
||||
- [ ] Do not create `wiki/blog/`, `wiki/interview/`, `wiki/portfolio/`, `wiki/concepts/`, or
|
||||
`wiki/projects/` without an explicit canonical extraction request.
|
||||
|
||||
## Task 8: Final report
|
||||
|
||||
Per `AGENTS.md:239-251`, the closing response states: changed files; the core changes; verification
|
||||
commands run; verifications that failed or could not run, with reasons; the Wiki capture result; and
|
||||
remaining risks or follow-ups.
|
||||
|
||||
- [ ] Explicitly restate what remains **out of scope and not production-ready**, from the index's scope
|
||||
boundaries: Mongo reactive, change streams, sharding, Atlas, KMS; Notification's at-rest decision
|
||||
if the threat-model branch was chosen; object storage's runtime inclusion; Fileserver internals.
|
||||
|
||||
---
|
||||
|
||||
## Wave 6 Exit Criteria
|
||||
|
||||
- [ ] Every §13 checkbox above is ticked **with attached evidence**, or is explicitly reported as
|
||||
not-met with its reason.
|
||||
- [ ] `docs/superpowers/plans/evidence/2026-08-15-wave6-final/` holds the output of every command in
|
||||
Tasks 1–4.
|
||||
- [ ] The LLM Wiki branch-note exists and links its derived documents.
|
||||
- [ ] No completion, "all passing", or "production-ready" claim appears anywhere without the command
|
||||
output that supports it.
|
||||
@@ -0,0 +1,709 @@
|
||||
# Wave 0 — Red Baseline Evidence
|
||||
|
||||
- Repository HEAD at capture: `2f5d2fc21954286213c1474d19935f571ef896ea`
|
||||
- Captured: 2026-08-15
|
||||
- Toolchain: JDK 21.0.11, Gradle 9.0.0, Docker Engine 29.7.2, Docker Compose 5.4.0
|
||||
- Plan: [`2026-08-15-wave0-red-baseline.md`](../2026-08-15-wave0-red-baseline.md)
|
||||
|
||||
## Exit state
|
||||
|
||||
```
|
||||
$ cd src && ./gradlew wave0RedReport --console=plain --no-daemon
|
||||
BUILD SUCCESSFUL in 1m 7s
|
||||
```
|
||||
|
||||
**12 red, 1 unexpectedly green.** The red set matches the plan's expected table except for
|
||||
`StartupWarningZeroTest`, recorded as a deviation below.
|
||||
|
||||
| Red test | Closed by | Confirmed cause |
|
||||
| --- | --- | --- |
|
||||
| `SecretLeakScannerCharacterizationTest.methodCallWithSafeSuffixIsNotALeak` | Wave 2 C1 | safe-suffix `$` anchor cannot match past a captured `()` |
|
||||
| `SecretLeakScannerCharacterizationTest.numericFencingIsNotALeak` | Wave 2 C1 | every `+` read as string concatenation |
|
||||
| `FiveAdapterOffInventoryTest.jpaOffHoldsNothing` | Wave 1 T4/T9 | see JPA inventory below |
|
||||
| `FiveAdapterOffInventoryTest.messagingOffHoldsNothing` | Wave 1 T7 | see messaging inventory below |
|
||||
| `FiveAdapterOffInventoryTest.notificationOffHoldsNothing` | Wave 1 T3/T8 | see notification inventory below |
|
||||
| `ShippedRuntimeFacadePresenceTest.mongoFacadeIsShipped` | Wave 1 T5 | `ClassNotFoundException` — not on the runtime classpath |
|
||||
| `ShippedRuntimeFacadePresenceTest.graphQlFacadeIsShipped` | Wave 1 T6 | `ClassNotFoundException` |
|
||||
| `ShippedRuntimeFacadePresenceTest.messagingPlatformFacadeIsShipped` | Wave 2 C3 | `ClassNotFoundException` |
|
||||
| `DefaultProfileBootCharacterizationTest.localProfileStartsWithShippedDefaults` | Wave 1 T9 | relay-enabled with blank broker |
|
||||
| `DefaultProfileBootCharacterizationTest.devProfileStartsWithShippedDefaults` | Wave 1 T9 / Wave 3 T2 | same validator reached first |
|
||||
| `ComposeMergeCharacterizationTest.devStackRenders` | Wave 3 T3 | duplicate `/var/tmp/heap` mount target |
|
||||
| `ReleaseManifestTaskExistenceTest.mongoReleaseContractNamesOnlyRegisteredTasks` | Wave 2 B5 | three unregistered tasks |
|
||||
|
||||
Green as planned: `StartupWarningRecorderTest`, `RuntimeMembershipClasspathAgreementTest`,
|
||||
`ComposeMergeCharacterizationTest` base/local, `ShippedRuntimeFacadePresenceTest` JPA/notification,
|
||||
`FiveAdapterOffInventoryTest` Mongo/GraphQL (vacuously — see Task 4), the three non-red scanner cases,
|
||||
`DefaultProfileBootCharacterizationTest.prodProfileRefusesPlaintextJdbc`.
|
||||
|
||||
## Task 1 — secret scanner
|
||||
|
||||
```
|
||||
$ ./gradlew :messaging:messaging-observability:test --tests '*SecretLeakScannerCharacterizationTest*'
|
||||
SecretLeakScannerCharacterizationTest > RED: incrementing a fencing token is arithmetic, not concatenation FAILED
|
||||
SecretLeakScannerCharacterizationTest > RED: a method call whose name ends in a safe suffix is not a leak FAILED
|
||||
5 tests completed, 2 failed
|
||||
```
|
||||
|
||||
The pre-existing repository failure this characterizes:
|
||||
|
||||
```
|
||||
$ ./gradlew :messaging:messaging-observability:test --tests '*SecretLeakStaticScanTest*'
|
||||
SecretLeakStaticScanTest > noSensitiveIdentifierIsConcatenatedIntoAString() FAILED
|
||||
java.lang.AssertionError: [a concatenated secret never reaches the redactor, so it must not be written at all]
|
||||
Expecting empty but was: ["KafkaSecurityConfigurer.java:104 + oauth.credentialId());",
|
||||
"InMemoryAdminOperationJournal.java:110 existing.leaseToken() + 1,"]
|
||||
```
|
||||
|
||||
## Task 3 — off-state inventories
|
||||
|
||||
Captured from the failure messages, with all five switches off on `local`. These are the exact type
|
||||
lists Wave 1 works down.
|
||||
|
||||
**JPA off** — a connection pool, the entity/repository scan, and the H2 vendor configuration all
|
||||
exist:
|
||||
|
||||
```
|
||||
com.zaxxer.hikari.HikariDataSource
|
||||
dev.caskeleton.adapter.outbound.persistence.audit.DomainContextAuditContextPort
|
||||
dev.caskeleton.adapter.outbound.persistence.config.PersistenceJpaConfig
|
||||
dev.caskeleton.adapter.outbound.persistence.config.PersistenceVendorSettings
|
||||
dev.caskeleton.adapter.outbound.persistence.failure.PersistenceExceptionTranslator
|
||||
dev.caskeleton.adapter.outbound.persistence.failure.StandardSqlStateErrorMapping
|
||||
dev.caskeleton.adapter.outbound.persistence.fileserver.repository.FileTransitionRepository
|
||||
dev.caskeleton.adapter.outbound.persistence.fileserver.repository.FileserverCleanupRepository
|
||||
dev.caskeleton.adapter.outbound.persistence.fileserver.repository.FileserverQuotaRepository
|
||||
dev.caskeleton.adapter.outbound.persistence.fileserver.repository.FileserverRecoveryRepository
|
||||
dev.caskeleton.adapter.outbound.persistence.fileserver.repository.JpaFileRepository
|
||||
dev.caskeleton.adapter.outbound.persistence.fileserver.repository.JpaUploadSessionRepository
|
||||
dev.caskeleton.adapter.outbound.persistence.fileserver.repository.UploadLeaseRepository
|
||||
dev.caskeleton.adapter.outbound.persistence.h2.H2IdempotencyClaimRepository
|
||||
dev.caskeleton.adapter.outbound.persistence.h2.H2LocalTimeoutConfigurer
|
||||
dev.caskeleton.adapter.outbound.persistence.h2.H2OutboxClaimRepository
|
||||
dev.caskeleton.adapter.outbound.persistence.h2.H2PersistenceConfig
|
||||
dev.caskeleton.adapter.outbound.persistence.h2.H2SqlStateErrorMapping
|
||||
(list truncated in the assertion message)
|
||||
```
|
||||
|
||||
Confirms JPA-INT-001 and the JPA half of §4.3's consumer table: the Fileserver repositories are on
|
||||
this list, which is why Wave 1 Task 4's `DataSourceRequirement` must name Fileserver as a relational
|
||||
consumer rather than treating the pool as JPA's alone.
|
||||
|
||||
**Messaging off**:
|
||||
|
||||
```
|
||||
dev.caskeleton.adapter.outbound.messaging.MessagingConfig
|
||||
dev.caskeleton.adapter.outbound.messaging.MessagingSettings
|
||||
dev.caskeleton.adapter.outbound.messaging.core.DisabledMessagePublisher
|
||||
dev.caskeleton.adapter.outbound.messaging.kafka.KafkaAdapterConfig
|
||||
dev.caskeleton.adapter.outbound.messaging.kafka.KafkaAdapterSettings
|
||||
dev.caskeleton.adapter.outbound.messaging.outbox.DisabledOutboxMessagePublisher
|
||||
dev.caskeleton.adapter.outbound.messaging.outbox.Slf4jOutboxRelayFailureReportAdapter
|
||||
```
|
||||
|
||||
Note `DisabledMessagePublisher` and `DisabledOutboxMessagePublisher`: the sentinel behaviour is
|
||||
correct, but off-invariant item 9 requires the **composition root** to supply it rather than the
|
||||
adapter. Wave 1 Task 7 moves it.
|
||||
|
||||
**Notification off** — settings bind with the master off, which is NTF-INT-005 exactly:
|
||||
|
||||
```
|
||||
dev.caskeleton.adapter.outbound.notification.NotificationConfig
|
||||
dev.caskeleton.adapter.outbound.notification.NotificationRoutesSettings
|
||||
dev.caskeleton.adapter.outbound.notification.core.RoutingNotifier
|
||||
dev.caskeleton.adapter.outbound.notification.email.google.GoogleEmailNotificationAdapterConfig
|
||||
dev.caskeleton.adapter.outbound.notification.platform.autoconfigure.NotificationPlatformSettings
|
||||
dev.caskeleton.adapter.outbound.notification.slack.webhook.SlackNotificationAdapterConfig
|
||||
dev.caskeleton.bootstrap.notification.NotificationPlatformSecretsConfig$NotificationSecretsSettings
|
||||
```
|
||||
|
||||
## Task 5 — default-profile boot
|
||||
|
||||
Both `local` and `dev` fail on the same validator, with the message it was written to give:
|
||||
|
||||
```
|
||||
org.springframework.beans.factory.BeanCreationException: Error creating bean with name
|
||||
'outboxRelayBrokerRequirementValidator' defined in class path resource
|
||||
[dev/caskeleton/bootstrap/outbox/OutboxConfig.class]: ca-skeleton.outbox.relay-enabled is enabled
|
||||
but app.messaging.broker is blank, so every claimed outbox row would fail to publish and be
|
||||
exhausted to DEAD. Either configure a broker, or set ca-skeleton.outbox.relay-enabled=false so
|
||||
PENDING rows are preserved until one exists.
|
||||
```
|
||||
|
||||
`dev` reaches this validator before the `ddl-auto=update` conflict the spec recorded from `bootRun`,
|
||||
so the `ddl-auto` failure is currently **masked**. It will surface once Wave 1 Task 9 sets
|
||||
`relay-enabled: false`, and Wave 3 Task 2 closes it.
|
||||
|
||||
## Task 7 — Compose merge
|
||||
|
||||
```
|
||||
$ docker compose -f docker-compose.yml -f docker-compose.dev.yml config
|
||||
services.app.volumes[1]: target /var/tmp/heap already mounted as services.app.tmpfs[1]
|
||||
```
|
||||
|
||||
Base and local render cleanly (`app`, and `app,db` respectively).
|
||||
|
||||
## Task 8 — runtime project closure
|
||||
|
||||
```
|
||||
$ ./gradlew :app-bootstrap:runtimeClasspathManifest
|
||||
$ cat app-bootstrap/build/architecture/runtime-project-closure.txt
|
||||
```
|
||||
|
||||
The manifest resolves and `RuntimeMembershipClasspathAgreementTest` is **green** — direct
|
||||
dependencies and the resolved closure agree today, because no build-only leaf is reachable. This is
|
||||
the gate that must stay green while Waves 1 and 2 add the Mongo, GraphQL, and messaging edges.
|
||||
|
||||
## Task 9 — release manifest
|
||||
|
||||
```
|
||||
ReleaseManifestTaskExistenceTest FAILED
|
||||
the Mongo release contract names task(s) that no build file registers, so a release manifest can
|
||||
report them green without ever running them
|
||||
missing: [mongoAtlasTest, mongoKmsTest, mongoShardedTest]
|
||||
registered: [mongoReplicaSetTest, mongoFailoverTest, mongoMigrationTest, mongoCompatibilityTest,
|
||||
mongoSecurityIntegrationTest, mongoPerformanceTest, mongoStableContractTest]
|
||||
```
|
||||
|
||||
`scripts/verify-mongodb-advanced.sh:95` also invokes `mongoShardedTest`, so that script cannot
|
||||
currently succeed either.
|
||||
|
||||
---
|
||||
|
||||
## Deviations from the plan
|
||||
|
||||
### 1. `StartupWarningZeroTest` is green, not red
|
||||
|
||||
The plan expected this red. It passes: an **all-off, non-web** `local` startup emits zero WARN and
|
||||
zero ERROR.
|
||||
|
||||
That is not a contradiction of spec §9.1 — the warnings recorded there
|
||||
(`BeanPostProcessorChecker` on the authorization beans, two Micrometer late-`MeterFilter` warnings,
|
||||
a Flyway converter warning on `dev`) were observed during `bootRun`, which is a **web** application
|
||||
with JPA active. This test is narrower than the configuration that produces them.
|
||||
|
||||
Consequence for Wave 4: `StartupWarningZeroTest` as written does not yet measure the warnings Wave 4
|
||||
must remove. Wave 4 Task 6 already calls for extending it to all three environments and every one-on
|
||||
combination; that extension must also use `WebApplicationType.SERVLET`, or the gate will keep
|
||||
passing while the warnings remain. Recorded here so the omission is not discovered as a surprise.
|
||||
|
||||
### 2. A test-harness defect surfaced first, and is not a production defect
|
||||
|
||||
Booting `CaSkeletonApplication` in-JVM from `app-bootstrap`'s own test source set fails before any
|
||||
adapter is examined:
|
||||
|
||||
```
|
||||
BeanDefinitionOverrideException: Invalid bean definition with name 'outboxEventJpaRepository'
|
||||
defined in ... @EnableJpaRepositories declared on PersistenceJpaConfig: ... there is already
|
||||
[...] defined in ... @EnableJpaRepositories declared on OutboxContainerTestSupport.OutboxRepositoryConfig
|
||||
```
|
||||
|
||||
Cause: `CaSkeletonApplication` component-scans `dev.caskeleton.bootstrap`; this module's test sources
|
||||
live in that package; so an in-JVM boot discovers a **test-only** configuration
|
||||
(`OutboxContainerTestSupport.OutboxRepositoryConfig`) that the shipped jar has never contained.
|
||||
|
||||
This is a property of the measurement, not of the product — `bootRun` is unaffected. Left alone it
|
||||
would have reported the same cause for every activation characterization and hidden the defects they
|
||||
exist to name. `ShippedCompositionHarness` registers a `TypeExcludeFilter` that drops candidates
|
||||
whose class file came from a test output directory, which is a rule about provenance rather than a
|
||||
class-name list somebody has to maintain.
|
||||
|
||||
**This is a workaround for measuring, not a fix.** The faithful instrument is running the produced
|
||||
jar as a child process, which is what Wave 2 Task E3 builds for GraphQL. If Wave 1's off-invariant
|
||||
work needs stronger evidence than the harness can give, promote the activation tests to that shape
|
||||
rather than trusting the exclusion.
|
||||
|
||||
### 3. A property-precedence trap worth remembering
|
||||
|
||||
`SpringApplicationBuilder#properties(String...)` contributes to `defaultProperties`, the
|
||||
lowest-precedence source, so the all-off set lost to `application.yml`'s `relay-enabled: true` and
|
||||
the "all-off" context died on the relay validator. The harness passes `--key=value` command-line
|
||||
arguments instead. Any later test that sets an all-off baseline must do the same.
|
||||
|
||||
## Files added by Wave 0
|
||||
|
||||
Production sources changed: **none**. Verified by inspection — every path below is a test source or
|
||||
a Gradle lane registration.
|
||||
|
||||
| File | Kind |
|
||||
| --- | --- |
|
||||
| `src/messaging/messaging-observability/src/test/java/.../SecretLeakScannerCharacterizationTest.java` | test |
|
||||
| `src/app-bootstrap/src/test/java/.../activation/AdapterActivationInventory.java` | test fixture |
|
||||
| `src/app-bootstrap/src/test/java/.../activation/ShippedCompositionHarness.java` | test fixture |
|
||||
| `src/app-bootstrap/src/test/java/.../activation/FiveAdapterOffInventoryTest.java` | test |
|
||||
| `src/app-bootstrap/src/test/java/.../activation/ShippedRuntimeFacadePresenceTest.java` | test |
|
||||
| `src/app-bootstrap/src/test/java/.../activation/DefaultProfileBootCharacterizationTest.java` | test |
|
||||
| `src/app-bootstrap/src/test/java/.../activation/StartupWarningRecorder.java` | test fixture |
|
||||
| `src/app-bootstrap/src/test/java/.../activation/StartupWarningRecorderTest.java` | test |
|
||||
| `src/app-bootstrap/src/test/java/.../activation/StartupWarningZeroTest.java` | test |
|
||||
| `src/app-bootstrap/src/test/java/.../compose/ComposeMergeCharacterizationTest.java` | test |
|
||||
| `src/app-bootstrap/src/test/java/.../registry/RuntimeMembershipClasspathAgreementTest.java` | test |
|
||||
| `src/app-bootstrap/src/test/java/.../registry/ReleaseManifestTaskExistenceTest.java` | test |
|
||||
| `src/app-bootstrap/build.gradle` | lane registration (`runtimeClasspathManifest`, `wave0Red`) |
|
||||
| `src/messaging/messaging-observability/build.gradle` | lane registration (`wave0Red`) |
|
||||
| `src/build.gradle` | lane registration (`wave0RedReport`) |
|
||||
|
||||
---
|
||||
|
||||
# Wave 1 progress note (same session)
|
||||
|
||||
## The repository-wide `test` is green
|
||||
|
||||
```
|
||||
$ cd src && ./gradlew test --console=plain --no-daemon --continue
|
||||
BUILD SUCCESSFUL in 3m 20s
|
||||
```
|
||||
|
||||
It was **red at HEAD** before this work, on `SecretLeakStaticScanTest` (spec §3.1). Two changes made
|
||||
it green, and neither is a suppression:
|
||||
|
||||
1. **The scanner defect is fixed** (Wave 2 C1, pulled forward because it was the only thing keeping
|
||||
the build red). A captured method call keeps its trailing `()`, so the safe-suffix exemption's `$`
|
||||
anchor never matched — stripping the call fixes it, where unanchoring the pattern would also have
|
||||
exempted `credentialIdentity`, which does carry the value. And a `+` with a numeric literal on
|
||||
either side is arithmetic, which cannot put a secret into a string. The three true-positive cases
|
||||
in the characterization are what prove the fix was not a weakening.
|
||||
2. **Wave 0's deliberately-red characterizations are excluded from the ordinary `test` task** and
|
||||
reported by `wave0RedReport` instead. A permanently red `test` is a build nobody can use, and a
|
||||
gate nobody can use stops catching the regressions it exists for. Wave 6 requires the tag set to
|
||||
be empty, so the exclusion cannot quietly become forgetting.
|
||||
|
||||
## Remaining red set: 4
|
||||
|
||||
| Red | Closed by |
|
||||
| --- | --- |
|
||||
| `ShippedRuntimeFacadePresenceTest.graphQlFacadeIsShipped` | Wave 1 T6 |
|
||||
| `ShippedRuntimeFacadePresenceTest.messagingPlatformFacadeIsShipped` | Wave 2 C3 |
|
||||
| `ComposeMergeCharacterizationTest.devStackRenders` | Wave 3 T3 |
|
||||
| `ReleaseManifestTaskExistenceTest.mongoReleaseContractNamesOnlyRegisteredTasks` | Wave 2 B5 |
|
||||
|
||||
Down from 12 at the Wave 0 baseline.
|
||||
|
||||
## Known defect left as found: the shared-contract scope rule
|
||||
|
||||
`CleanArchitectureTest.SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES` has two faults
|
||||
that mask each other:
|
||||
|
||||
- its subject pattern is `..shared..`, which matches any package named `shared` anywhere rather than
|
||||
the shared-contract module;
|
||||
- its allowlist contains the bare module root `dev.caskeleton.shared` and the check matches by
|
||||
prefix, so **every** package inside the module is blessed automatically.
|
||||
|
||||
Net effect: the rule catches nothing inside the module it is named after, and does catch unrelated
|
||||
leaves that happen to have a `shared` package — which is how it surfaced, when the Mongo leaf joined
|
||||
the composition root's analysis scope.
|
||||
|
||||
Fixing it properly requires the violation fixture that proves the rule works to move inside
|
||||
`dev.caskeleton.shared`, which then puts the fixture in the rule's own analysis scope, which requires
|
||||
reworking how fixtures are scanned. That is a separate change from adapter activation, so the rule is
|
||||
left as found with the defect documented at the rule itself, and the Mongo tenancy package added to
|
||||
the allowlist to keep the build honest in the meantime. **This is technical debt, not a fix.**
|
||||
|
||||
## Corrections to the spec and to these plans, found by executing them
|
||||
|
||||
| Claim | Reality |
|
||||
| --- | --- |
|
||||
| `ca-skeleton.idempotency.provider` | The property does not exist. It is `ca-skeleton.capabilities.idempotency.provider`. |
|
||||
| `app.fileserver.enabled` | It is `app.fileserver-platform.enabled`. |
|
||||
| Notification/GraphQL selectors are legacy master aliases | They are subordinate settings that stay valid while the adapter is on. Treating them as aliases made every shipped configuration ambiguous. |
|
||||
| `AutoConfigurationImportFilter` registers in `.imports` | It registers in `META-INF/spring.factories`. Getting this wrong fails open silently — the filter simply never runs. |
|
||||
| The JPA root can import one exported entry | Inverting the vendor→config import to create one produced a package cycle. The composition root names both vendor configs instead, and the export surface admits them with that reason recorded. |
|
||||
|
||||
## Shipping Mongo pulled in reactive Mongo
|
||||
|
||||
Adding the Mongo leaf to `app-bootstrap` put `spring-boot-starter-data-mongodb-reactive` and
|
||||
`mongodb-driver-reactivestreams` on the runtime classpath. The index's scope boundaries exclude
|
||||
reactive Mongo from the shipped Stable runtime, and leaving the starter there would have let Boot
|
||||
build a second client and pool from the same URI as soon as the master switch went on. Both are
|
||||
excluded at the composition root rather than in the leaf, which still compiles the reactive paths for
|
||||
a future promotion.
|
||||
|
||||
---
|
||||
|
||||
# Session close — Wave 1 complete, Wave 2/3 partially landed
|
||||
|
||||
## Verified state
|
||||
|
||||
```
|
||||
$ cd src && ./gradlew test --console=plain --no-daemon --continue
|
||||
BUILD SUCCESSFUL in 2m 58s
|
||||
|
||||
$ ./gradlew verifyEnvKeys verifyCleanArchitectureDependencies \
|
||||
verifyRuntimeModuleMembership verifyPublicPathSnapshot
|
||||
verifyRuntimeModuleMembership: 2 runtime composition(s) match the registry
|
||||
BUILD SUCCESSFUL
|
||||
|
||||
$ ./gradlew wave0RedReport
|
||||
1 red remaining
|
||||
```
|
||||
|
||||
**12 red at the Wave 0 baseline → 1.** The survivor is
|
||||
`ShippedRuntimeFacadePresenceTest.messagingPlatformFacadeIsShipped`, which Wave 2 C3 closes: the
|
||||
messaging platform has no production sender, only a test fake, so giving it runtime membership now
|
||||
would ship a path that cannot work.
|
||||
|
||||
## Wave 1 — complete (13/13)
|
||||
|
||||
| Task | Delivered |
|
||||
| --- | --- |
|
||||
| T1 | `MasterSwitch` / `MasterSwitchParser` in `shared-contract` — five names in one place, strict parse |
|
||||
| T2 | `MasterSwitchEnvironmentPostProcessor` — rejects before any detail namespace binds |
|
||||
| T3 | Both composition-root scans narrowed; the properties scan names its packages because it has no `excludeFilters` |
|
||||
| T4 | `PersistenceJpaRootAutoConfiguration` + `DataSourceRequirement` + `JpaOffAutoConfigurationImportFilter` |
|
||||
| T5 | Mongo shipped, one authority, reactive starter excluded from the runtime |
|
||||
| T6 | GraphQL shipped, one authority, Boot GraphQL auto-configurations filtered |
|
||||
| T7 | Messaging bridge gated; disabled sentinels moved to the composition root |
|
||||
| T8 | `NotificationRootAutoConfiguration` — secrets and registries named rather than scanned |
|
||||
| T9 | Migration, outbox and idempotency under capability roots |
|
||||
| T10 | `CapabilityDependencyValidator` — 8 rules, each naming the exact missing switch |
|
||||
| T11 | `DatabaseReadinessGroupPostProcessor` — `db` membership derived from the capability closure |
|
||||
| T12 | 8 env registry rows + YAML binding + a contract test derived from the enum |
|
||||
| T13 | Membership gate reads the resolved runtime closure instead of declared dependencies |
|
||||
|
||||
Measured effect, JPA off: **~30 beans → 0** (pool, entity scan, repositories, Hibernate, Flyway, DB
|
||||
health all gone).
|
||||
|
||||
## Pulled forward from later waves
|
||||
|
||||
- **Wave 2 C1** — the secret scanner's two false positives fixed at the cause. This is what made a
|
||||
repository-wide green `test` possible; it had been red at HEAD.
|
||||
- **Wave 2 B5** — the three ghost Mongo lanes demoted to `experimental_contracts` rather than
|
||||
implemented, with the script and doc updated to match.
|
||||
- **Wave 3 T1** — profileless deploys refused, scoped to the deployable artifact so slice tests are
|
||||
unaffected.
|
||||
- **Wave 3 T3** — the dev Compose `tmpfs: !override []` fix; merge verified and mount targets checked
|
||||
for uniqueness in the merged model.
|
||||
|
||||
## The defaulting cascade, and what it cost
|
||||
|
||||
Removing the relay's blanket refusal exposed the failure underneath it, exactly as this document
|
||||
predicted — and then that one exposed a third. The sequence was:
|
||||
|
||||
1. relay-enabled with a blank broker (fixed in T9);
|
||||
2. `ddl-auto=update` against a Flyway-owned schema (fixed by changing the tracked `.env`);
|
||||
3. `logging.level.root` failing to bind, because **62 placeholders in `application.yml` had no inline
|
||||
default at all** and only `application-local.yml` pinned enough of them for one profile to start.
|
||||
|
||||
55 of those 62 now carry a default. The remaining seven are deliberate: the datasource URL, username
|
||||
and password, the application name, and the JWT issuer and audience — a default for any of them is a
|
||||
deployment running against something nobody chose. CORS allowed-origins was moved out of that set
|
||||
after the fact: CORS is off by default and an empty origin list is the safest value rather than an
|
||||
arbitrary one, so it defaults to empty.
|
||||
|
||||
One of the added defaults was itself wrong — `max-age-seconds` got `600s` while the field is a
|
||||
`long` — which is worth recording because it only surfaced through a real boot. A bulk defaulting
|
||||
pass needs a boot per profile to be believed.
|
||||
|
||||
## Still open
|
||||
|
||||
- `ShippedRuntimeFacadePresenceTest.messagingPlatformFacadeIsShipped` (Wave 2 C3).
|
||||
- The `..shared..` ArchUnit rule remains defective and documented at the rule itself; see the earlier
|
||||
note. Unchanged this session.
|
||||
- Waves 2 (remaining), 3 (Compose lane matrix, Keycloak, MinIO), 4, 5 and 6 are untouched.
|
||||
|
||||
---
|
||||
|
||||
# Continuation — Wave 3 T2 and Wave 4 T1 landed; a Wave 4 fix disproved
|
||||
|
||||
## Verified state
|
||||
|
||||
```
|
||||
$ cd src && ./gradlew test BUILD SUCCESSFUL
|
||||
$ ./gradlew verifyEnvKeys verifyCleanArchitectureDependencies \
|
||||
verifyRuntimeModuleMembership verifyPublicPathSnapshot
|
||||
BUILD SUCCESSFUL
|
||||
$ ./gradlew wave0RedReport 2 red
|
||||
```
|
||||
|
||||
## Wave 3 T2 — env source separation, complete
|
||||
|
||||
`src/.env` is untracked. `src/.env.example` (309 keys, generated from the registry, 12
|
||||
secret-classified keys left empty) and `src/.env.local.example` are tracked in its place, and
|
||||
`.gitignore` carries `src/.env*` with the two examples negated.
|
||||
|
||||
`verifyEnvKeys` now reads the example. Reading the real file made it false in **both** directions: it
|
||||
passed only where an operator's own environment file happened to exist, and it would have passed with
|
||||
no example at all — so the file an adopter actually copies was never verified, while a file full of
|
||||
real credentials was a build input. Proven by deleting `src/.env` and re-running: green.
|
||||
|
||||
Its rule B was inverted while retargeting. It required every key in the file to be an
|
||||
`application.yml` placeholder, which is true of a hand-maintained `.env` and false of a catalogue —
|
||||
most registry keys are bound by typed settings inside a leaf. Inverted to "every registered `APP_` key
|
||||
appears in the example", it now catches the drift that actually matters: a key added to the registry
|
||||
that never reached the file an adopter copies.
|
||||
|
||||
`SPRING_PROFILES_ACTIVE` was also corrected in the registry — `type: enum`, `required: true`, no
|
||||
default — to match Wave 3 T1.
|
||||
|
||||
## Wave 4 T1 — MeterFilter ordering, complete
|
||||
|
||||
`MetricsContractConfig` and `SampleMetricsContractConfig` both install their filters through a
|
||||
`MeterRegistryCustomizer` instead of a `@PostConstruct` that fetched the registry. The warning was the
|
||||
visible half of the real defect: a filter applies only to meters registered after it, so the
|
||||
cardinality and distribution policies were being applied to some meters and not others. Both
|
||||
composition roots changed together, because fixing one leaves the warning reproducible from the other.
|
||||
|
||||
The Boot 4 package is `org.springframework.boot.micrometer.metrics.autoconfigure`, found by inspecting
|
||||
the resolved jars rather than assumed.
|
||||
|
||||
## Wave 4 T4 — attempted, disproved, and left as found
|
||||
|
||||
The spec calls the structured log's `profile` field a drift: it reads `SPRING_PROFILES_ACTIVE`, so
|
||||
overriding the profile on the command line while a stale value sits in the environment stamps lines
|
||||
with the stale one. The drift is real.
|
||||
|
||||
The obvious fix — bind the field to `spring.profiles.active` — **does not work**, and an existing
|
||||
contract test said so. `LogProfileDriftCharacterizationTest` was written to settle the question by
|
||||
observation rather than argument, and it observed an empty string: Logback initialises before that
|
||||
property resolves. A field that says nothing is not an improvement on a field that is sometimes wrong.
|
||||
|
||||
The binding was reverted to what it was, with the reason recorded at the declaration, and the
|
||||
characterization kept as a tagged red. The fix needs a different mechanism — setting the logger
|
||||
context property from the resolved environment once it is ready, rather than declaring the source in
|
||||
XML — which is Wave 4's to build.
|
||||
|
||||
## Remaining red: 2
|
||||
|
||||
| Red | Closed by |
|
||||
| --- | --- |
|
||||
| `ShippedRuntimeFacadePresenceTest.messagingPlatformFacadeIsShipped` | Wave 2 C3 — no production sender exists, only a test fake |
|
||||
| `LogProfileDriftCharacterizationTest` | Wave 4 — needs the mechanism above |
|
||||
|
||||
---
|
||||
|
||||
# Continuation — Wave 3 Compose lane matrix (static half) and Keycloak realm
|
||||
|
||||
## Verified state
|
||||
|
||||
```
|
||||
$ cd src && ./gradlew test BUILD SUCCESSFUL
|
||||
$ ./gradlew verifyEnvKeys verifyCleanArchitectureDependencies \
|
||||
verifyRuntimeModuleMembership verifyPublicPathSnapshot BUILD SUCCESSFUL
|
||||
$ ./scripts/verify-compose-profile-contracts.sh
|
||||
all 15 lanes match src/config/runtime/compose-profile-contracts.json
|
||||
$ ./gradlew wave0RedReport 2 red
|
||||
```
|
||||
|
||||
## What landed
|
||||
|
||||
**`src/config/runtime/compose-profile-contracts.json`** — the lane SSOT. 15 lanes, each fixing a
|
||||
Compose profile, a file stack, an explicit Spring runtime, and the exact service set that stack must
|
||||
render. Exact rather than superset: a lane that quietly gains a service is a lane whose evidence
|
||||
describes a different stack than the one that ran.
|
||||
|
||||
**`docker-compose.infra.yml`** — every shared service, each carrying Compose profiles so nothing
|
||||
starts unless a lane names it: PostgreSQL, a single-node Mongo replica set with an idempotent
|
||||
initiator, Kafka, Mailpit, MinIO with bucket bootstrap, Keycloak, and the three one-shot smoke
|
||||
clients. Infrastructure no longer lives inside environment overlays, which is what let `local` stop
|
||||
meaning "the app plus a database".
|
||||
|
||||
**`docker-compose.prod-smoke.yml`** — a production-shaped runtime whose JDBC URL carries
|
||||
`sslmode=verify-full`, so the prod validators are satisfied rather than bypassed.
|
||||
|
||||
**`scripts/verify-compose-profile-contracts.sh`** — the static entry point, wired into the ordinary
|
||||
test suite so a lane cannot drift until somebody remembers to run a shell script. It checks the
|
||||
Compose version floor, the exact service set per lane, the rendered `SPRING_PROFILES_ACTIVE`, and
|
||||
mount-target uniqueness in the merged model.
|
||||
|
||||
**Keycloak realm** (`infra/keycloak/`) — `ca-skeleton-api` as a confidential client with a service
|
||||
account, standard flow and direct access grant off, an audience mapper and realm/client role mappers.
|
||||
The client secret is a `${...}` reference; the entrypoint reads it from a mounted secret file and
|
||||
execs `kc.sh`, so no value reaches Git, the rendered config, or `docker inspect`.
|
||||
|
||||
**Smoke clients** — `auth-smoke` (the seven realm checks, against the same issuer URL the app is
|
||||
given), `object-storage-smoke` (upload → HEAD → download → delete → wrong-credential rejection, none
|
||||
skippable), `notification-smoke` (three phases, so the handoff lane's accept and verify are the same
|
||||
client talking about the same request id).
|
||||
|
||||
## What the verifier caught immediately
|
||||
|
||||
Writing it was worth it before running anything. On first execution it failed four lanes:
|
||||
|
||||
- `off-local` rendered `app,db`, because the `db` service was still in the local overlay as well as
|
||||
in the new infra file;
|
||||
- three lanes could not render at all, because the local overlay's `depends_on: db` pointed at a
|
||||
service their profile does not enable — Compose refuses that outright.
|
||||
|
||||
Both are the same mistake: infrastructure declared where the environment is described. `db` now lives
|
||||
only in the infra file, and the `depends_on` is gone — ordering belongs to the runtime-smoke wrapper,
|
||||
which knows which services a lane actually starts.
|
||||
|
||||
## Two follow-on defects found and fixed
|
||||
|
||||
**Untracking `src/.env` broke local Compose on a fresh clone.** `docker compose config` failed
|
||||
outright because the local overlay declared `env_file: ./src/.env`. Marked `required: false`, and
|
||||
verified by moving the file aside: the stack renders. A convenience override had become a hard
|
||||
prerequisite for rendering the stack at all.
|
||||
|
||||
**The developer host-port contract moved with the service.**
|
||||
`DeveloperExperienceContractTest.localComposePublishesTheHostPortTheCommittedDatasourceUrlTargets`
|
||||
asserted against the local overlay. It now asserts against the infra file and additionally that the
|
||||
service carries the `local-jpa` profile — without which the port assertion would pass for a service
|
||||
no lane ever brings up.
|
||||
|
||||
## Still open in Wave 3
|
||||
|
||||
`scripts/run-compose-runtime-smoke.sh` — the dynamic half — is not written. Nothing here has been
|
||||
started; what is verified is that all 15 lanes render exactly what they claim, with the right Spring
|
||||
runtime and no mount collisions. The lanes have not been run, and this document does not claim they
|
||||
have.
|
||||
|
||||
---
|
||||
|
||||
# Continuation — the Compose lanes actually run
|
||||
|
||||
## Verified state
|
||||
|
||||
```
|
||||
$ cd src && ./gradlew test verifyEnvKeys verifyCleanArchitectureDependencies \
|
||||
verifyRuntimeModuleMembership verifyPublicPathSnapshot BUILD SUCCESSFUL
|
||||
$ ./scripts/verify-compose-profile-contracts.sh all 15 lanes match
|
||||
$ ./scripts/run-compose-runtime-smoke.sh --lane off-local passed
|
||||
$ ./scripts/run-compose-runtime-smoke.sh --lane off-dev passed
|
||||
$ ./scripts/run-compose-runtime-smoke.sh --lane off-prod passed
|
||||
```
|
||||
|
||||
Each lane's own report, fetched from the running application rather than asserted from the flags the
|
||||
lane passed in:
|
||||
|
||||
| lane | activeProfile | switches on | dataSourceRequiredBy |
|
||||
| --- | --- | --- | --- |
|
||||
| `off-local` | `local` | none | not required |
|
||||
| `off-dev` | `dev` | none | not required |
|
||||
| `off-prod` | `prod` | none | not required |
|
||||
|
||||
`docker ps -a` and `docker volume ls` show no surviving `casmoke` project or volume.
|
||||
|
||||
**This is the Wave 1 exit criterion, demonstrated for the first time in a real container:** all five
|
||||
adapters off, three environments, no infrastructure of any kind, and the application reporting so
|
||||
itself.
|
||||
|
||||
## What was built
|
||||
|
||||
`scripts/run-compose-runtime-smoke.sh` — the dynamic entry point. Unique project per lane, evidence
|
||||
directory that refuses to reuse a previous run's, static contract then `config` then `create`,
|
||||
`up --wait` on long-running services only, a bounded readiness poll, every declared one-shot with a
|
||||
non-zero exit failing the lane, sanitized evidence, and a `trap` teardown scoped to the lane's own
|
||||
project — logs collected before the teardown, not after.
|
||||
|
||||
`AdapterActivationEndpoint` / `AdapterActivationReport` — the application's own answer about what
|
||||
resolved on. A lane asserting on its own environment passes whenever it set the variables correctly,
|
||||
which is not the claim being made.
|
||||
|
||||
## Six defects the lanes found, in the order they surfaced
|
||||
|
||||
Each was invisible to every check that existed before, and none would have been found by reading.
|
||||
|
||||
1. **A stale image.** The app service declares both `build:` and `image:`, so Compose reused a tag
|
||||
from an older state of the repository — the first run failed on a class that no longer exists in
|
||||
the tree. The wrapper now builds explicitly. A lane running a stale image produces evidence about
|
||||
code nobody changed.
|
||||
2. **The actuator is on its own connector.** Fetching `8080/actuator` returned an empty file that
|
||||
read exactly like a failed assertion about the profile.
|
||||
3. **The activation endpoint was authenticated.** Management auth is JWT, so only a lane with an
|
||||
identity provider could have read it — excluding the all-off lanes, whose claim is the hardest to
|
||||
check any other way. It is now permit-all alongside health/info/prometheus, and
|
||||
`AdapterActivationReportShapeTest` holds it to property names and booleans so that stays true.
|
||||
`ManagementActuatorSecurityContractTest` records the allowlist decision rather than absorbing it.
|
||||
4. **`off-local` was passing by luck.** It read the developer's own `src/.env` for the seven
|
||||
deliberately-undefaulted values. The wrapper now generates them per run, so a lane reproduces
|
||||
anywhere rather than on the machine it was written on.
|
||||
5. **The dev overlay has no healthcheck**, so `up --wait` returned as soon as the container was
|
||||
created and the first fetch landed before startup finished. The wrapper polls with a bound rather
|
||||
than trusting `--wait` alone.
|
||||
6. **`environment:` beat `env_file:` in the prod overlay.** `APP_DATASOURCE_PASSWORD:
|
||||
"${APP_DATASOURCE_PASSWORD:-}"` read the host shell, not the lane's generated file, and injected
|
||||
an empty string — which the prod env validator then refused, correctly, about a value the lane had
|
||||
actually supplied.
|
||||
|
||||
## Not claimed
|
||||
|
||||
The twelve infrastructure-bearing lanes have not been run. `--matrix` exists and is untested against
|
||||
them; what is demonstrated is the three all-off lanes end to end and that all fifteen render exactly
|
||||
what they claim. Keycloak, MinIO, Mongo, Kafka and Mailpit have been written and rendered, not
|
||||
started.
|
||||
|
||||
---
|
||||
|
||||
# Continuation — the infrastructure lanes, and what running them found
|
||||
|
||||
## Verified state
|
||||
|
||||
```
|
||||
$ cd src && ./gradlew test verifyEnvKeys verifyCleanArchitectureDependencies \
|
||||
verifyRuntimeModuleMembership verifyPublicPathSnapshot BUILD SUCCESSFUL
|
||||
$ ./scripts/verify-compose-profile-contracts.sh all 15 lanes match
|
||||
$ ./scripts/run-compose-runtime-smoke.sh --matrix src/config/runtime/compose-profile-contracts.json
|
||||
all 4 blocking lanes passed
|
||||
```
|
||||
|
||||
No surviving `casmoke` container or volume.
|
||||
|
||||
| lane | activeProfile | switches on | vendor |
|
||||
| --- | --- | --- | --- |
|
||||
| `off-local` | local | none | none |
|
||||
| `off-dev` | dev | none | none |
|
||||
| `off-prod` | prod | none | none |
|
||||
| `local-mongo` | local | `persistence-mongo` | none |
|
||||
|
||||
`local-mongo` is the first adapter proven on against real infrastructure: a single-node replica set,
|
||||
the Mongo master switch on, no other switch on, and no relational connection required.
|
||||
|
||||
## The contract gained two assertions, because a green lane was not yet a meaningful one
|
||||
|
||||
**`expectedSwitchesOn`.** A lane named `local-jpa` that ran with JPA off would render the right
|
||||
services, start cleanly, and prove nothing. The wrapper now compares the switches the application
|
||||
reports against what the lane asked for.
|
||||
|
||||
**`expectedPersistenceVendor`.** `local-jpa` passed for a while against H2 while the PostgreSQL
|
||||
container it started sat untouched beside it — `application-local.yml` pinned an in-memory URL as a
|
||||
literal, which outranks any environment a caller supplies. Every other field in the report looked
|
||||
correct. The report now carries the vendor resolved from the JDBC URL, and the lane asserts it.
|
||||
|
||||
That pin was not unique. `application-local.yml` also pinned `app.messaging.broker: ""` and the two
|
||||
notification provider selectors, so `local-messaging` started Kafka, set `APP_MESSAGING_BROKER=kafka`
|
||||
and was refused by the dependency validator for a value it had supplied. All four are placeholders
|
||||
now; the defaults are unchanged, so a developer who sets nothing gets exactly what they got before.
|
||||
|
||||
## Four defects in the wrapper itself
|
||||
|
||||
1. **It reported success for lanes it never ran.** `docker compose exec` consumes stdin, and inside a
|
||||
plain `while read` loop it ate the remaining lanes — the first ran, the loop ended, and the script
|
||||
said all six passed. Reading on fd 3 fixes it; a ran-count guard makes a partial matrix a failure
|
||||
rather than a pass. A wrapper whose own success message is a false green is worse than no wrapper.
|
||||
2. **Compose project names reject uppercase**, so the run id is lowercased for the project while the
|
||||
evidence directory keeps the readable timestamp.
|
||||
3. **`env_file` lists merge and the later file wins.** The developer's optional `src/.env`, declared
|
||||
by the local overlay after the base, silently overrode the lane's own values. Lane settings now go
|
||||
into a generated `environment:` overlay, which beats every `env_file` regardless of order.
|
||||
4. **`up --wait` is not a readiness gate where no healthcheck exists** — the dev overlay has none, so
|
||||
the first fetch landed before startup finished. The wrapper polls with a bound.
|
||||
|
||||
## Two spec findings confirmed in a real composition, not inferred
|
||||
|
||||
**MSG-INT-003.** With a healthy Kafka and the broker selected, startup fails on a missing
|
||||
`KafkaSender` bean: the legacy Kafka configuration requires a project-supplied sender, and production
|
||||
has none — only the tests provide a fake. This is precisely why the messaging platform leaves must
|
||||
not get runtime membership before a real transport bridge exists.
|
||||
|
||||
**GQL-INT-002.** `APP_GRAPHQL_DEPLOYMENT_MODE` is registered and bound, but the platform still reads
|
||||
the old `production` boolean and `environment` enum, which default to `false` and `PRODUCTION_PUBLIC`.
|
||||
The startup validator therefore sees a production deployment with introspection enabled and refuses.
|
||||
|
||||
A third was found that the spec did not predict: **shipping GraphQL into the same context as the rest
|
||||
of the application produced two `Clock` beans**, because the platform's clock was conditioned on its
|
||||
own bean *name* rather than on the type. Every injection point wanting a `Clock` failed to start. It
|
||||
now backs off on the type, which is what auto-configuration is for — and this could not have happened
|
||||
while the leaf was build-only.
|
||||
|
||||
## Lanes marked not-blocking, with reasons recorded in the contract
|
||||
|
||||
`local-jpa`, `local-messaging-outbox`, the three notification lanes, `shared-infra-local`,
|
||||
`shared-infra-dev`, `prod-smoke` and `all-adapters` are blocked on an open JPA finding: the entity
|
||||
scan is unconditional while the Flyway migration streams are partitioned by capability, so
|
||||
`ddl-auto=validate` against real PostgreSQL fails on `fs_cleanup_item`. Scoping the entity scan to
|
||||
active capabilities is Wave 2 JPA work.
|
||||
|
||||
`local-messaging` is blocked on MSG-INT-003 and `local-graphql` on GQL-INT-002, both above.
|
||||
|
||||
Each carries its reason in `compose-profile-contracts.json` and each keeps its assertions, so the
|
||||
lanes fail loudly rather than passing against the wrong thing.
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -1,174 +0,0 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from collections import Counter
|
||||
from pathlib import Path
|
||||
import hashlib
|
||||
import json
|
||||
import re
|
||||
import sys
|
||||
|
||||
ROOT = Path('/mnt/data')
|
||||
DESIGN = ROOT / 'fileserver-platform-design.md'
|
||||
PLAN = ROOT / 'fileserver-platform-implementation-plan.md'
|
||||
|
||||
errors: list[str] = []
|
||||
checks: list[tuple[str, bool, str]] = []
|
||||
|
||||
|
||||
def add(name: str, ok: bool, detail: str) -> None:
|
||||
checks.append((name, ok, detail))
|
||||
if not ok:
|
||||
errors.append(f'{name}: {detail}')
|
||||
|
||||
|
||||
def sha256(path: Path) -> str:
|
||||
return hashlib.sha256(path.read_bytes()).hexdigest()
|
||||
|
||||
for path in (DESIGN, PLAN):
|
||||
add(f'{path.name} exists', path.exists(), str(path))
|
||||
|
||||
if errors:
|
||||
print('\n'.join(errors), file=sys.stderr)
|
||||
raise SystemExit(1)
|
||||
|
||||
design = DESIGN.read_text(encoding='utf-8')
|
||||
plan = PLAN.read_text(encoding='utf-8')
|
||||
|
||||
add('design title', design.startswith('# Fileserver Platform 설계서'), True.__str__())
|
||||
add('plan header', plan.startswith('# Fileserver Platform Implementation Plan\n\n> **For agentic workers:**'), 'required Superpowers header')
|
||||
add('design code fences', design.count('```') % 2 == 0, f"count={design.count('```')}")
|
||||
add('plan code fences', plan.count('```') % 2 == 0, f"count={plan.count('```')}")
|
||||
|
||||
for label, text in [('design', design), ('plan', plan)]:
|
||||
forbidden = [r'\bTBD\b', r'\bTODO\b', r'implement later', r'fill in details', r'Similar to Task']
|
||||
hits = [p for p in forbidden if re.search(p, text, re.I)]
|
||||
add(f'{label} placeholder scan', not hits, f'hits={hits}')
|
||||
|
||||
required_design_sections = [
|
||||
'## 5. 지원 매트릭스',
|
||||
'## 6. 전체 아키텍처',
|
||||
'## 9. 상태 머신과 invariant',
|
||||
'## 10. Metadata Store 설계',
|
||||
'## 11. Content Store Port',
|
||||
'## 12. Local Filesystem Adapter',
|
||||
'## 14. Publish와 완료 처리',
|
||||
'## 15. Upload Application 설계',
|
||||
'## 19. HTTP API',
|
||||
'## 20. Range와 Conditional Request',
|
||||
'## 21. Spring MVC Adapter',
|
||||
'## 22. Spring WebFlux Adapter',
|
||||
'## 23. Nginx 전송 위임',
|
||||
'## 24. 재개 가능한 업로드',
|
||||
'## 27. 보안 정책',
|
||||
'## 28. 다중 인스턴스와 NFS',
|
||||
'## 30. 관측성',
|
||||
'## 33. 테스트 전략',
|
||||
'## 37. 완료 정의',
|
||||
]
|
||||
missing_sections = [s for s in required_design_sections if s not in design]
|
||||
add('design section coverage', not missing_sections, f'missing={missing_sections}')
|
||||
|
||||
source_topics = {
|
||||
'MVC': ['Spring MVC Adapter', 'MvcTransferExecutorProperties'],
|
||||
'WebFlux': ['Spring WebFlux Adapter', 'DataBuffer'],
|
||||
'local/PVC/NFS': ['Kubernetes PVC', 'NFSv4.1', 'Local Filesystem Adapter'],
|
||||
'content/metadata separation': ['Content Store Port', 'Metadata Store 설계'],
|
||||
'upload': ['Upload Application 설계', 'multipart', 'application/octet-stream'],
|
||||
'download': ['Range와 Conditional Request', 'ETag', 'If-Range'],
|
||||
'publish': ['ATOMIC_MOVE_REQUIRED', 'METADATA_POINTER', 'AmbiguousCompletionException'],
|
||||
'security': ['traversal', 'symlink', 'READY gate'],
|
||||
'resumable': ['tus 1.0 Stable', 'draft-12 Experimental'],
|
||||
'observability': ['Metric', 'Trace', 'Audit'],
|
||||
}
|
||||
for topic, needles in source_topics.items():
|
||||
missing = [n for n in needles if n not in design]
|
||||
add(f'design topic: {topic}', not missing, f'missing={missing}')
|
||||
|
||||
# Core Port snippet must not expose adapter types.
|
||||
port_match = re.search(r'### 11\.2 Blocking SPI\n(.*?)### 11\.3 Async SPI', design, re.S)
|
||||
port_text = port_match.group(1) if port_match else ''
|
||||
forbidden_port_types = ['java.nio.file.Path', 'org.springframework.core.io.Resource', 'DataBuffer', 'Flux<']
|
||||
port_hits = [x for x in forbidden_port_types if x in port_text]
|
||||
add('blocking core port leakage', bool(port_match) and not port_hits, f'hits={port_hits}')
|
||||
|
||||
# Task structure.
|
||||
task_matches = list(re.finditer(r'^### Task (\d+):', plan, re.M))
|
||||
task_numbers = [int(m.group(1)) for m in task_matches]
|
||||
add('task count', len(task_numbers) == 33, f'count={len(task_numbers)}')
|
||||
add('task numbering', task_numbers == list(range(1, 34)), f'numbers={task_numbers}')
|
||||
|
||||
missing_task_blocks: dict[int, list[str]] = {}
|
||||
for idx, match in enumerate(task_matches):
|
||||
end = task_matches[idx + 1].start() if idx + 1 < len(task_matches) else plan.find('\n## 3.', match.start())
|
||||
segment = plan[match.start():end]
|
||||
required = [
|
||||
'**Files:**', '**Interfaces:**', '**Step 1:', '**Step 2:',
|
||||
'**Step 3:', '**Step 4:', '**Step 5:', 'Expected:', 'git commit'
|
||||
]
|
||||
missing = [item for item in required if item not in segment]
|
||||
if missing:
|
||||
missing_task_blocks[int(match.group(1))] = missing
|
||||
add('task block completeness', not missing_task_blocks, json.dumps(missing_task_blocks, ensure_ascii=False))
|
||||
|
||||
create_paths = re.findall(r'^- Create: `([^`]+)`', plan, re.M)
|
||||
duplicates = {path: count for path, count in Counter(create_paths).items() if count > 1}
|
||||
add('unique create paths', not duplicates, json.dumps(duplicates, ensure_ascii=False))
|
||||
|
||||
required_plan_topics = [
|
||||
'Task 10: Storage capability probe',
|
||||
'Task 11: Streaming append',
|
||||
'Task 13: Atomic move와 metadata pointer publish',
|
||||
'Task 18: HTTP Range',
|
||||
'Task 21: Spring WebFlux raw·multipart upload',
|
||||
'Task 23: Nginx `X-Accel-Redirect`',
|
||||
'Task 26: 다중 인스턴스 writer lease',
|
||||
'Task 27: tus 1.0 Stable',
|
||||
'Task 28: HTTPbis resumable upload draft-12 Experimental',
|
||||
'Task 29: HTTP Problem Detail과 보안 hardening',
|
||||
'Task 32: Filesystem, HTTP, fault, performance Testkit',
|
||||
'Task 33: CI matrix',
|
||||
]
|
||||
missing_plan_topics = [x for x in required_plan_topics if x not in plan]
|
||||
add('plan scope coverage', not missing_plan_topics, f'missing={missing_plan_topics}')
|
||||
|
||||
add('no Redis carryover', 'redis' not in design.lower() and 'redis' not in plan.lower(), 'search term=redis')
|
||||
add('no deprecated nginx token design', 'DelegatedPathToken' not in design + plan and 'opaque-token' not in design + plan, 'token mapper removed')
|
||||
|
||||
status = 'PASS' if not errors else 'FAIL'
|
||||
report = ROOT / 'fileserver-superpowers-validation.md'
|
||||
lines = [
|
||||
'# Fileserver Superpowers 문서 검증',
|
||||
'',
|
||||
f'**결과:** {status}',
|
||||
'',
|
||||
'## 파일',
|
||||
'',
|
||||
f'- `{DESIGN.name}` — {len(design.splitlines())} lines, {len(design.encode())} bytes, SHA-256 `{sha256(DESIGN)}`',
|
||||
f'- `{PLAN.name}` — {len(plan.splitlines())} lines, {len(plan.encode())} bytes, SHA-256 `{sha256(PLAN)}`',
|
||||
'',
|
||||
'## 검증 항목',
|
||||
'',
|
||||
]
|
||||
for name, ok, detail in checks:
|
||||
lines.append(f"- [{'x' if ok else ' '}] **{name}** — {detail}")
|
||||
|
||||
lines += [
|
||||
'',
|
||||
'## 검증 범위의 한계',
|
||||
'',
|
||||
'- 현재 Backend Skeleton 저장소가 입력되지 않아 Gradle compilation, integration test, Nginx execution, PVC·NFS certification은 실행하지 않았다.',
|
||||
'- 본 검증은 설계·계획 문서의 구조, 내부 일관성, 범위 추적성, 미확정 표식과 중복 경로를 확인한 정적 검증이다.',
|
||||
]
|
||||
report.write_text('\n'.join(lines) + '\n', encoding='utf-8')
|
||||
|
||||
print(json.dumps({
|
||||
'status': status,
|
||||
'errors': errors,
|
||||
'checks': len(checks),
|
||||
'design_lines': len(design.splitlines()),
|
||||
'plan_lines': len(plan.splitlines()),
|
||||
'task_count': len(task_numbers),
|
||||
'report': str(report),
|
||||
}, ensure_ascii=False, indent=2))
|
||||
|
||||
raise SystemExit(0 if not errors else 1)
|
||||
@@ -1,6 +0,0 @@
|
||||
44ba9931722364a53fcb3b5f31a1d539eabcaf42db775f5a33fb558f558c7504 README.md
|
||||
d064f0ac6c3be0e5c76ef22454db2a97e1d78ed287bd22f4c125f19aba3ad8e3 VALIDATION.md
|
||||
1ef15812f33dc998a6332b87523ed5942ba46d79d984a0ca776b05bb9247a06a docs/superpowers/plans/2026-08-12-graphql-advanced-capabilities-expansion-plan.md
|
||||
5ae70b53e22cdb852b2bb0df171dec868bfe99b15bb8e71fb2b0b3431cd7e2cd docs/superpowers/plans/2026-08-12-graphql-api-execution-platform-implementation-plan.md
|
||||
8d0203203f6bfe4b2e18625eff23bb308ba6454703a4ca4cd3236dab31ecafc3 docs/superpowers/specs/2026-08-12-graphql-api-execution-platform-design.md
|
||||
8048fe6a536de67d2cf5b0df05d35128f2c68ba8f0dd615831b40430fc76277b validate_graphql_docs.py
|
||||
@@ -1,249 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
from __future__ import annotations
|
||||
|
||||
from pathlib import Path
|
||||
import re
|
||||
import sys
|
||||
import hashlib
|
||||
|
||||
ROOT = Path(__file__).resolve().parent
|
||||
DESIGN = ROOT / "docs/superpowers/specs/2026-08-12-graphql-api-execution-platform-design.md"
|
||||
STABLE = ROOT / "docs/superpowers/plans/2026-08-12-graphql-api-execution-platform-implementation-plan.md"
|
||||
ADVANCED = ROOT / "docs/superpowers/plans/2026-08-12-graphql-advanced-capabilities-expansion-plan.md"
|
||||
|
||||
checks: list[tuple[str, bool, str]] = []
|
||||
|
||||
def check(name: str, condition: bool, detail: str = "") -> None:
|
||||
checks.append((name, bool(condition), detail))
|
||||
|
||||
def read(path: Path) -> str:
|
||||
check(f"file exists: {path.name}", path.exists(), str(path))
|
||||
return path.read_text(encoding="utf-8") if path.exists() else ""
|
||||
|
||||
design = read(DESIGN)
|
||||
stable = read(STABLE)
|
||||
advanced = read(ADVANCED)
|
||||
|
||||
# Basic document integrity
|
||||
check("design line floor", len(design.splitlines()) >= 2000, str(len(design.splitlines())))
|
||||
check("stable plan line floor", len(stable.splitlines()) >= 4000, str(len(stable.splitlines())))
|
||||
check("advanced plan line floor", len(advanced.splitlines()) >= 1500, str(len(advanced.splitlines())))
|
||||
for label, text in [("design", design), ("stable", stable), ("advanced", advanced)]:
|
||||
check(f"{label} code fences balanced", text.count("```") % 2 == 0, str(text.count("```")))
|
||||
for marker in ["TODO", "TBD", "FIXME", "implement later", "fill in details"]:
|
||||
check(f"{label} no placeholder {marker}", marker.lower() not in text.lower())
|
||||
|
||||
# Design required sections and source traceability
|
||||
required_design_terms = [
|
||||
"# GraphQL API 실행 플랫폼 설계서",
|
||||
"GraphQL Platform owns",
|
||||
"Domain/Application owns",
|
||||
"G1 Standard GraphQL API",
|
||||
"G2 Advanced Execution",
|
||||
"G3 GraphQL Extension",
|
||||
"G4 Admin Plane",
|
||||
"SDL",
|
||||
"September 2025",
|
||||
"application/graphql-response+json",
|
||||
"HTTP `200`",
|
||||
"GraphQlRequestContext",
|
||||
"DataLoader",
|
||||
"GraphQlFetchProfile",
|
||||
"HMAC",
|
||||
"Idempotency",
|
||||
"Partial Data",
|
||||
"Persisted Operation",
|
||||
"Subscription",
|
||||
"Federation",
|
||||
"GraphQL Multipart Upload",
|
||||
"Fileserver",
|
||||
"부록 B. 입력 심층 리서치 원문",
|
||||
"# GraphQL API 실행 플랫폼 심층 리서치",
|
||||
]
|
||||
for term in required_design_terms:
|
||||
check(f"design contains {term}", term in design)
|
||||
|
||||
# Critical design invariants
|
||||
critical_pairs = [
|
||||
("field error uses HTTP 200", "field error" in design.lower() and "HTTP `200`" in design),
|
||||
("no draft 294 stable", "294" in design and "Stable" in design),
|
||||
("dataloader request scope", "request" in design.lower() and "DataLoader" in design),
|
||||
("cursor HMAC", "Cursor" in design and "HMAC" in design),
|
||||
("no multipart upload", "Multipart Upload" in design and "Fileserver" in design),
|
||||
("single schema default", "Single Executable Schema" in design),
|
||||
("request-wide transaction prohibited", "request-wide" in design.lower() and "transaction" in design.lower()),
|
||||
("entity/document boundary", "JPA Entity" in design and "MongoDB Document" in design),
|
||||
]
|
||||
for name, condition in critical_pairs:
|
||||
check(name, condition)
|
||||
|
||||
# Plan headers and global constraints
|
||||
stable_header_terms = [
|
||||
"# GraphQL API 실행 플랫폼 Implementation Plan",
|
||||
"REQUIRED SUB-SKILL",
|
||||
"**Goal:**",
|
||||
"**Architecture:**",
|
||||
"**Tech Stack:**",
|
||||
"## Global Constraints",
|
||||
"Stable Task",
|
||||
]
|
||||
advanced_header_terms = [
|
||||
"# GraphQL Advanced Capability Expansion Implementation Plan",
|
||||
"REQUIRED SUB-SKILL",
|
||||
"backend.graphql.advanced.*",
|
||||
"Stable 구현 계획 Task `1–48`",
|
||||
]
|
||||
for term in stable_header_terms:
|
||||
check(f"stable header contains {term}", term in stable)
|
||||
for term in advanced_header_terms:
|
||||
check(f"advanced header contains {term}", term in advanced)
|
||||
|
||||
# Task sequence and per-task structure
|
||||
def task_sections(text: str) -> list[tuple[int, str]]:
|
||||
matches = list(re.finditer(r"^### Task (\d+): .+$", text, re.MULTILINE))
|
||||
result = []
|
||||
for i, match in enumerate(matches):
|
||||
start = match.start()
|
||||
end = matches[i+1].start() if i+1 < len(matches) else len(text)
|
||||
result.append((int(match.group(1)), text[start:end]))
|
||||
return result
|
||||
|
||||
stable_tasks = task_sections(stable)
|
||||
advanced_tasks = task_sections(advanced)
|
||||
check("stable task count", len(stable_tasks) == 48, str(len(stable_tasks)))
|
||||
check("advanced task count", len(advanced_tasks) == 19, str(len(advanced_tasks)))
|
||||
check("stable task sequence", [n for n, _ in stable_tasks] == list(range(1, 49)))
|
||||
check("advanced task sequence", [n for n, _ in advanced_tasks] == list(range(1, 20)))
|
||||
|
||||
def validate_tasks(label: str, tasks: list[tuple[int, str]]) -> None:
|
||||
required = [
|
||||
"**Files:**",
|
||||
"**Interfaces:**",
|
||||
"**Implementation requirements:**",
|
||||
"**Step 1: Write the failing test**",
|
||||
"**Step 2: Run the focused test and verify the failure**",
|
||||
"**Step 3: Implement the smallest complete production contract**",
|
||||
"**Step 4: Run the focused test and the owning suite**",
|
||||
"**Step 5: Commit the independently reviewable change**",
|
||||
"Expected: FAIL",
|
||||
"Expected: PASS",
|
||||
"git commit -m",
|
||||
]
|
||||
for number, section in tasks:
|
||||
for token in required:
|
||||
check(f"{label} task {number} contains {token}", token in section)
|
||||
check(f"{label} task {number} has test path", "- Test: `" in section)
|
||||
check(f"{label} task {number} has production file", "- Create: `" in section)
|
||||
check(f"{label} task {number} fences balanced", section.count("```") % 2 == 0)
|
||||
check(f"{label} task {number} has gradle test", "./gradlew" in section and ":test" in section)
|
||||
|
||||
validate_tasks("stable", stable_tasks)
|
||||
validate_tasks("advanced", advanced_tasks)
|
||||
|
||||
# Create paths
|
||||
def create_paths(text: str) -> list[str]:
|
||||
return re.findall(r"^- Create: `([^`]+)`$", text, re.MULTILINE)
|
||||
|
||||
stable_paths = create_paths(stable)
|
||||
advanced_paths = create_paths(advanced)
|
||||
check("stable create paths exist", len(stable_paths) >= 150, str(len(stable_paths)))
|
||||
check("advanced create paths exist", len(advanced_paths) >= 80, str(len(advanced_paths)))
|
||||
check("stable create paths unique", len(stable_paths) == len(set(stable_paths)))
|
||||
check("advanced create paths unique", len(advanced_paths) == len(set(advanced_paths)))
|
||||
check("stable and advanced paths disjoint", set(stable_paths).isdisjoint(advanced_paths))
|
||||
for index, path in enumerate(stable_paths, 1):
|
||||
check(f"stable create path {index} exact", "*" not in path and "..." not in path and (path.startswith("modules/graphql/") or path.startswith("build-logic/")))
|
||||
for index, path in enumerate(advanced_paths, 1):
|
||||
check(f"advanced create path {index} exact", "*" not in path and "..." not in path and path.startswith("modules/graphql-advanced/"))
|
||||
|
||||
# Stable/Advanced separation
|
||||
for forbidden in [
|
||||
"modules/graphql/graphql-websocket/",
|
||||
"modules/graphql/graphql-federation/",
|
||||
"modules/graphql/graphql-persisted-operation/",
|
||||
"modules/graphql/graphql-rsocket/",
|
||||
]:
|
||||
check(f"stable excludes {forbidden}", forbidden not in stable)
|
||||
|
||||
for required in [
|
||||
"modules/graphql-advanced/graphql-persisted-operation/",
|
||||
"modules/graphql-advanced/graphql-websocket/",
|
||||
"modules/graphql-advanced/graphql-subscription/",
|
||||
"modules/graphql-advanced/graphql-federation/",
|
||||
"modules/graphql-advanced/graphql-rsocket/",
|
||||
]:
|
||||
check(f"advanced includes {required}", required in advanced)
|
||||
|
||||
# Stable coverage
|
||||
stable_required_terms = [
|
||||
"GraphQlRequestContext",
|
||||
"GraphQlClientPolicy",
|
||||
"GraphQlSchemaContract",
|
||||
"SchemaMappingInspector",
|
||||
"@oneOf",
|
||||
"GraphQlHttpProfile",
|
||||
"application/graphql-response+json",
|
||||
"GraphQlExecutionProfile",
|
||||
"GraphQlWireError",
|
||||
"GraphQlTenantIsolationPolicy",
|
||||
"GraphQlParserLimits",
|
||||
"GraphQlComplexityCalculator",
|
||||
"GraphQlRuntimeBudget",
|
||||
"GraphQlPreparsedCacheKey",
|
||||
"GraphQlBatchPolicy",
|
||||
"GraphQlFetchProfile",
|
||||
"HmacGraphQlCursorCodec",
|
||||
"GraphQlConnection",
|
||||
"GraphQlMutationIdempotencyContext",
|
||||
"GraphQlMetricCardinalityPolicy",
|
||||
"GraphQlPlatformStartupValidator",
|
||||
"GraphQlReleaseGate",
|
||||
]
|
||||
for term in stable_required_terms:
|
||||
check(f"stable coverage {term}", term in stable)
|
||||
|
||||
advanced_required_terms = [
|
||||
"GraphQlPersistedOperation",
|
||||
"GraphQlWebSocketProtocol",
|
||||
"GraphQlSubscriptionBufferPolicy",
|
||||
"GraphQlSubscriptionOrderingProfile",
|
||||
"GraphQlSseConnectionPolicy",
|
||||
"GraphQlReplayPosition",
|
||||
"GraphQlDataLoaderDependencyGraph",
|
||||
"GraphQlFederationEntityKey",
|
||||
"GraphQlFederationCompositionGate",
|
||||
"GraphQlGeneratedSourceBoundary",
|
||||
"GraphQlRepositoryAllowlist",
|
||||
"GraphQlRSocketRoutePolicy",
|
||||
"GraphQlHttpGetOperationPolicy",
|
||||
"GraphQlIncrementalCompatibilityGate",
|
||||
"GraphQlAdvancedReleaseGate",
|
||||
]
|
||||
for term in advanced_required_terms:
|
||||
check(f"advanced coverage {term}", term in advanced)
|
||||
|
||||
# Prohibited API patterns
|
||||
prohibited_patterns = [
|
||||
(r"interface\s+GenericGraphQlRepository", "no generic graphql repository"),
|
||||
(r"public\s+.*\bEntityManager\b", "no public entity manager"),
|
||||
(r"public\s+.*\bMongoTemplate\b", "no public mongo template"),
|
||||
(r"scalar\s+Upload\b", "no upload scalar declaration"),
|
||||
(r"@Transactional\s+.*GraphQL request", "no request-wide transaction implementation"),
|
||||
]
|
||||
for pattern, name in prohibited_patterns:
|
||||
check(name, re.search(pattern, stable, re.IGNORECASE | re.MULTILINE) is None)
|
||||
|
||||
# File hashes can be printed for package evidence
|
||||
for path in [DESIGN, STABLE, ADVANCED]:
|
||||
if path.exists():
|
||||
digest = hashlib.sha256(path.read_bytes()).hexdigest()
|
||||
check(f"sha256 computed: {path.name}", len(digest) == 64, digest)
|
||||
|
||||
failed = [(n, d) for n, ok, d in checks if not ok]
|
||||
print(f"CHECKS={len(checks)}")
|
||||
print(f"PASSED={len(checks)-len(failed)}")
|
||||
print(f"FAILED={len(failed)}")
|
||||
for name, detail in failed:
|
||||
print(f"FAIL: {name}" + (f" :: {detail}" if detail else ""))
|
||||
|
||||
sys.exit(1 if failed else 0)
|
||||
@@ -1,148 +0,0 @@
|
||||
from pathlib import Path
|
||||
import re
|
||||
import sys
|
||||
import zipfile
|
||||
|
||||
base = Path('/mnt/data')
|
||||
design_path = base / 'httpclient-platform-design.md'
|
||||
plan_path = base / 'httpclient-platform-implementation-plan.md'
|
||||
errors = []
|
||||
notes = []
|
||||
|
||||
def read(p):
|
||||
if not p.exists():
|
||||
errors.append(f'missing file: {p}')
|
||||
return ''
|
||||
return p.read_text(encoding='utf-8')
|
||||
|
||||
design = read(design_path)
|
||||
plan = read(plan_path)
|
||||
|
||||
# Basic size and structure
|
||||
if len(design.splitlines()) < 1200:
|
||||
errors.append(f'design unexpectedly short: {len(design.splitlines())} lines')
|
||||
if len(plan.splitlines()) < 2500:
|
||||
errors.append(f'plan unexpectedly short: {len(plan.splitlines())} lines')
|
||||
|
||||
# Task continuity and task internals
|
||||
matches = list(re.finditer(r'^### Task (\d+): (.+)$', plan, flags=re.M))
|
||||
nums = [int(m.group(1)) for m in matches]
|
||||
expected = list(range(1, (max(nums) if nums else 0) + 1))
|
||||
if nums != expected:
|
||||
errors.append(f'task numbers not continuous: {nums[:5]}...{nums[-5:] if nums else []}')
|
||||
|
||||
for i, m in enumerate(matches):
|
||||
start = m.start()
|
||||
end = matches[i+1].start() if i+1 < len(matches) else plan.find('\n## 3. Plan Self-Review Checklist', start)
|
||||
if end == -1:
|
||||
end = len(plan)
|
||||
block = plan[start:end]
|
||||
n = m.group(1)
|
||||
for token in ['**Files:**', '**Interfaces:**', '**Step 1:', '**Step 2:', '**Step 3:', '**Step 4:', '**Step 5:']:
|
||||
if token not in block:
|
||||
errors.append(f'Task {n} missing {token}')
|
||||
if 'git commit -m ' not in block:
|
||||
errors.append(f'Task {n} missing commit command')
|
||||
if 'Expected:' not in block:
|
||||
errors.append(f'Task {n} missing expected result')
|
||||
|
||||
# Markdown fence balance
|
||||
for name, text in [('design', design), ('plan', plan)]:
|
||||
count = len(re.findall(r'^```', text, flags=re.M))
|
||||
if count % 2:
|
||||
errors.append(f'{name} has unbalanced code fences: {count}')
|
||||
|
||||
# Placeholder scan
|
||||
patterns = {
|
||||
'TBD': r'\bTBD\b',
|
||||
'TODO': r'\bTODO\b',
|
||||
'implement later': r'implement later',
|
||||
'fill in': r'fill in',
|
||||
'similar to task': r'similar to Task',
|
||||
'placeholder': r'placeholder',
|
||||
}
|
||||
for name, text in [('design', design), ('plan', plan)]:
|
||||
for label, pat in patterns.items():
|
||||
if re.search(pat, text, flags=re.I):
|
||||
errors.append(f'{name} contains placeholder pattern: {label}')
|
||||
|
||||
# Duplicate create path scan
|
||||
create_paths = re.findall(r'^- Create: `([^`]+)`', plan, flags=re.M)
|
||||
dupes = sorted({p for p in create_paths if create_paths.count(p) > 1})
|
||||
if dupes:
|
||||
errors.append(f'duplicate Create paths: {dupes}')
|
||||
|
||||
# Required design coverage
|
||||
required_design_terms = [
|
||||
'H1 Typed Service Client', 'H2 Generic Exchange', 'H3 Dynamic Target',
|
||||
'ExecutionEvidence', 'BodyReplayability', 'OperationIdempotency',
|
||||
'Named Client Profile', 'Apache HttpClient 5', 'Reactor Netty',
|
||||
'Retry Coordinator', 'Circuit Breaker', 'Rate Limiter', 'Bulkhead',
|
||||
'OAuth2', 'TLS', 'SSRF', 'Streaming', 'SSE', 'HTTP/3',
|
||||
'Spring Framework 6.2', 'Spring 7', 'RestTemplate'
|
||||
]
|
||||
for term in required_design_terms:
|
||||
if term not in design:
|
||||
errors.append(f'design missing term: {term}')
|
||||
|
||||
required_plan_terms = [
|
||||
'httpclient-core-api', 'httpclient-transport-apache', 'httpclient-transport-jdk',
|
||||
'httpclient-transport-reactor-netty', 'httpclient-dynamic-target',
|
||||
'httpclient-spring-boot-starter', 'HttpAmbiguousExecutionException',
|
||||
'first response byte', 'DNS/IP Pinning', 'SingleFlightTokenLoader',
|
||||
'httpClientStableContractTest', 'spring62CompatibilityTest',
|
||||
'spring70CompatibilityTest'
|
||||
]
|
||||
for term in required_plan_terms:
|
||||
if term not in plan:
|
||||
errors.append(f'plan missing term: {term}')
|
||||
|
||||
# Core API should not deliberately expose native clients in design signatures.
|
||||
for forbidden_signature in [
|
||||
'ApacheHttpClient nativeApacheClient()',
|
||||
'HttpClient nativeJdkClient()',
|
||||
'WebClient.Builder mutableBuilder()',
|
||||
'RestClient.Builder mutableBuilder()'
|
||||
]:
|
||||
# These appear in an explicit "do not provide" code block. Note rather than fail.
|
||||
if forbidden_signature in design:
|
||||
notes.append(f'explicitly forbidden signature documented: {forbidden_signature}')
|
||||
|
||||
# Record task count and file counts
|
||||
notes.append(f'design lines={len(design.splitlines())}, bytes={len(design.encode())}')
|
||||
notes.append(f'plan lines={len(plan.splitlines())}, bytes={len(plan.encode())}')
|
||||
notes.append(f'tasks={len(nums)}, create_paths={len(create_paths)}')
|
||||
|
||||
report = base / 'httpclient-superpowers-validation.md'
|
||||
status = 'PASS' if not errors else 'FAIL'
|
||||
report_text = [
|
||||
'# HTTP Client Superpowers 문서 검증', '',
|
||||
f'**검증 결과:** {status}', '',
|
||||
'## 검증 항목', '',
|
||||
f'- 설계서 존재 및 최소 구조: {"PASS" if design else "FAIL"}',
|
||||
f'- 구현 계획서 존재 및 최소 구조: {"PASS" if plan else "FAIL"}',
|
||||
f'- Task 번호 연속성: {"PASS" if nums == expected else "FAIL"}',
|
||||
f'- Task별 Files·Interfaces·Step 1~5·Expected·Commit: {"PASS" if not any("Task " in e for e in errors) else "FAIL"}',
|
||||
f'- Markdown code fence 균형: {"PASS" if not any("code fences" in e for e in errors) else "FAIL"}',
|
||||
f'- Placeholder scan: {"PASS" if not any("placeholder" in e for e in errors) else "FAIL"}',
|
||||
f'- 중복 Create 경로: {"PASS" if not dupes else "FAIL"}',
|
||||
f'- 핵심 설계 범위: {"PASS" if not any("design missing" in e for e in errors) else "FAIL"}',
|
||||
f'- 핵심 구현 범위: {"PASS" if not any("plan missing" in e for e in errors) else "FAIL"}',
|
||||
'', '## 통계', ''
|
||||
]
|
||||
report_text += [f'- {note}' for note in notes]
|
||||
if errors:
|
||||
report_text += ['', '## 오류', ''] + [f'- {e}' for e in errors]
|
||||
else:
|
||||
report_text += ['', '## 결론', '',
|
||||
'- 설계 결정과 구현 작업의 정적 추적성이 확인됐다.',
|
||||
'- 실제 저장소가 제공되지 않았으므로 Gradle compile, integration, fault, security, performance test는 아직 실행되지 않았다.',
|
||||
'- 계획의 Java 21, Gradle Kotlin DSL, root package는 명시된 구현 가정이다.']
|
||||
report.write_text('\n'.join(report_text) + '\n', encoding='utf-8')
|
||||
|
||||
print(status)
|
||||
for note in notes:
|
||||
print(note)
|
||||
for e in errors:
|
||||
print('ERROR:', e)
|
||||
sys.exit(0 if not errors else 1)
|
||||
@@ -0,0 +1,31 @@
|
||||
# Keycloak realm artifact
|
||||
|
||||
`realms/ca-skeleton-realm.json` is imported by the `keycloak` service in `docker-compose.infra.yml`
|
||||
and is the same realm every GraphQL qualification lane authenticates against.
|
||||
|
||||
## The client secret is a reference, never a value
|
||||
|
||||
The confidential client `ca-skeleton-api` carries `"secret": "${KEYCLOAK_GRAPHQL_SMOKE_CLIENT_SECRET}"`.
|
||||
`entrypoint.sh` reads the value from the Compose secret mounted at
|
||||
`/run/secrets/keycloak-graphql-smoke-client-secret`, exports it, and execs `kc.sh start-dev
|
||||
--import-realm`, so the value never reaches Git, a rendered Compose config, a command line, or an
|
||||
evidence file. A realm file with a working credential in it is a credential in the repository, and
|
||||
"it is only for smoke tests" is not something a scanner or a fork can tell.
|
||||
|
||||
## No comment keys in the realm JSON
|
||||
|
||||
Keycloak deserializes this file into `RealmRepresentation` with unknown fields **rejected**, not
|
||||
ignored. A `"_comment"` key here fails the whole import with `Unrecognized field "_comment"`, the
|
||||
container exits 1, and the lane fails on Keycloak rather than on anything it was testing. That is
|
||||
why this rationale lives in Markdown next to the artifact instead of inside it.
|
||||
|
||||
## What the realm grants
|
||||
|
||||
- realm role `user` — the baseline role the application authorizes ordinary calls on
|
||||
- client role `ca-skeleton-api:graphql-query` — permission to execute a GraphQL query
|
||||
- a service account for the client-credentials grant the qualification lane uses
|
||||
- audience and realm/client role mappers, so the issued token carries what the resource server
|
||||
validates
|
||||
|
||||
Standard flow and direct access grants are disabled: the lane authenticates as a service, and an
|
||||
enabled password grant is a second way in that nothing tests.
|
||||
Executable
+23
@@ -0,0 +1,23 @@
|
||||
#!/usr/bin/env bash
|
||||
# Reads the client secret from its mounted file, exports it for the realm import, and execs Keycloak.
|
||||
#
|
||||
# The realm artifact carries ${KEYCLOAK_GRAPHQL_SMOKE_CLIENT_SECRET} rather than a value, so the
|
||||
# secret is never in Git. Passing it as a container `environment:` entry would have put it in the
|
||||
# rendered Compose config and in `docker inspect`; a file read here keeps it process-local.
|
||||
set -euo pipefail
|
||||
|
||||
SECRET_FILE="/run/secrets/keycloak-graphql-smoke-client-secret"
|
||||
if [[ ! -r "${SECRET_FILE}" ]]; then
|
||||
echo "keycloak entrypoint: ${SECRET_FILE} is not readable." >&2
|
||||
echo " The lane wrapper writes it per run at mode 0600; running this stack by hand needs one too." >&2
|
||||
exit 78
|
||||
fi
|
||||
|
||||
KEYCLOAK_GRAPHQL_SMOKE_CLIENT_SECRET="$(cat "${SECRET_FILE}")"
|
||||
export KEYCLOAK_GRAPHQL_SMOKE_CLIENT_SECRET
|
||||
if [[ -z "${KEYCLOAK_GRAPHQL_SMOKE_CLIENT_SECRET}" ]]; then
|
||||
echo "keycloak entrypoint: the client secret file is empty." >&2
|
||||
exit 78
|
||||
fi
|
||||
|
||||
exec /opt/keycloak/bin/kc.sh start-dev --import-realm
|
||||
@@ -0,0 +1,104 @@
|
||||
{
|
||||
"realm": "ca-skeleton",
|
||||
"enabled": true,
|
||||
"sslRequired": "none",
|
||||
"roles": {
|
||||
"realm": [
|
||||
{
|
||||
"name": "user",
|
||||
"description": "The baseline realm role the application authorizes ordinary calls on."
|
||||
}
|
||||
],
|
||||
"client": {
|
||||
"ca-skeleton-api": [
|
||||
{
|
||||
"name": "graphql-query",
|
||||
"description": "Permission to execute a GraphQL query against the shipped endpoint."
|
||||
},
|
||||
{
|
||||
"name": "notification-submit",
|
||||
"description": "Accept a notification for dispatch.",
|
||||
"composite": false,
|
||||
"clientRole": true
|
||||
},
|
||||
{
|
||||
"name": "notification-template-publish",
|
||||
"description": "Publish a notification template version. Separate from submit: publishing changes what every future submission renders.",
|
||||
"composite": false,
|
||||
"clientRole": true
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"clients": [
|
||||
{
|
||||
"clientId": "ca-skeleton-api",
|
||||
"enabled": true,
|
||||
"protocol": "openid-connect",
|
||||
"publicClient": false,
|
||||
"bearerOnly": false,
|
||||
"serviceAccountsEnabled": true,
|
||||
"standardFlowEnabled": false,
|
||||
"directAccessGrantsEnabled": false,
|
||||
"implicitFlowEnabled": false,
|
||||
"secret": "${KEYCLOAK_GRAPHQL_SMOKE_CLIENT_SECRET}",
|
||||
"attributes": {
|
||||
"access.token.lifespan": "300"
|
||||
},
|
||||
"protocolMappers": [
|
||||
{
|
||||
"name": "ca-skeleton-api-audience",
|
||||
"protocol": "openid-connect",
|
||||
"protocolMapper": "oidc-audience-mapper",
|
||||
"consentRequired": false,
|
||||
"config": {
|
||||
"included.client.audience": "ca-skeleton-api",
|
||||
"id.token.claim": "false",
|
||||
"access.token.claim": "true"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "realm-roles",
|
||||
"protocol": "openid-connect",
|
||||
"protocolMapper": "oidc-usermodel-realm-role-mapper",
|
||||
"consentRequired": false,
|
||||
"config": {
|
||||
"multivalued": "true",
|
||||
"claim.name": "realm_access.roles",
|
||||
"jsonType.label": "String",
|
||||
"access.token.claim": "true"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "client-roles",
|
||||
"protocol": "openid-connect",
|
||||
"protocolMapper": "oidc-usermodel-client-role-mapper",
|
||||
"consentRequired": false,
|
||||
"config": {
|
||||
"multivalued": "true",
|
||||
"claim.name": "resource_access.${client_id}.roles",
|
||||
"jsonType.label": "String",
|
||||
"access.token.claim": "true"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"users": [
|
||||
{
|
||||
"username": "service-account-ca-skeleton-api",
|
||||
"enabled": true,
|
||||
"serviceAccountClientId": "ca-skeleton-api",
|
||||
"realmRoles": [
|
||||
"user"
|
||||
],
|
||||
"clientRoles": {
|
||||
"ca-skeleton-api": [
|
||||
"graphql-query",
|
||||
"notification-submit",
|
||||
"notification-template-publish"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
# The per-run client secret lands here at mode 0600 and is removed on teardown. Nothing in this
|
||||
# directory is ever committed; the realm artifact references the value by name instead.
|
||||
*
|
||||
!.gitignore
|
||||
Executable
+54
@@ -0,0 +1,54 @@
|
||||
#!/bin/sh
|
||||
# Realm acceptance: the seven checks, against the same issuer URL the application is given.
|
||||
#
|
||||
# The issuer matters more than it looks. `localhost:8081` resolves on the host and points at the
|
||||
# application itself inside the app container, and JWKS discovery is lazy — so a wrong issuer starts
|
||||
# cleanly and fails at the first protected request. Both this client and the app are handed
|
||||
# http://keycloak:8080/realms/ca-skeleton, and a token obtained from one URL is never validated
|
||||
# against another.
|
||||
set -eu
|
||||
|
||||
SECRET_FILE="/run/secrets/keycloak-graphql-smoke-client-secret"
|
||||
CLIENT_SECRET="$(cat "${SECRET_FILE}")"
|
||||
|
||||
fail() { echo "auth-smoke: $1" >&2; exit 1; }
|
||||
|
||||
# 1-3. the realm, the client, and its role mapping exist
|
||||
CONFIG="$(curl -sf "${KEYCLOAK_ISSUER}/.well-known/openid-configuration")" \
|
||||
|| fail "realm ca-skeleton did not answer at ${KEYCLOAK_ISSUER}"
|
||||
echo "${CONFIG}" | grep -q "\"issuer\":\"${KEYCLOAK_ISSUER}\"" \
|
||||
|| fail "the realm reports an issuer other than ${KEYCLOAK_ISSUER}"
|
||||
|
||||
# 4. a token, via client credentials only — no test user, no password grant
|
||||
TOKEN_RESPONSE="$(curl -sf -X POST "${KEYCLOAK_ISSUER}/protocol/openid-connect/token" \
|
||||
-d grant_type=client_credentials \
|
||||
-d "client_id=${KEYCLOAK_CLIENT_ID}" \
|
||||
--data-urlencode "client_secret=${CLIENT_SECRET}")" \
|
||||
|| fail "client-credentials token request failed"
|
||||
ACCESS_TOKEN="$(echo "${TOKEN_RESPONSE}" | sed -n 's/.*"access_token":"\([^"]*\)".*/\1/p')"
|
||||
[ -n "${ACCESS_TOKEN}" ] || fail "the token response carried no access_token"
|
||||
|
||||
# 5. the claims the application authorizes on
|
||||
CLAIMS="$(echo "${ACCESS_TOKEN}" | cut -d. -f2 | tr '_-' '/+' | base64 -d 2>/dev/null || true)"
|
||||
echo "${CLAIMS}" | grep -q '"sub"' || fail "the token has no sub claim"
|
||||
echo "${CLAIMS}" | grep -q "\"aud\".*${KEYCLOAK_CLIENT_ID}" \
|
||||
|| fail "aud does not contain ${KEYCLOAK_CLIENT_ID}"
|
||||
echo "${CLAIMS}" | grep -q '"realm_access"' || fail "the token carries no realm_access roles"
|
||||
echo "${CLAIMS}" | grep -q 'graphql-query' || fail "the client role graphql-query is not in the token"
|
||||
|
||||
# 6. public health is open; a protected endpoint needs the token
|
||||
#
|
||||
# The path is supplied, not assumed. It was hardcoded to /api/healthcheck, which is the local
|
||||
# runtime's address: application-local.yml pins presentation.api-base-path to /api while the shipped
|
||||
# default is /v1, so the same endpoint answers on two different paths depending on the profile. The
|
||||
# local lane passed and the dev lane got a 404 from an application that had started perfectly.
|
||||
HEALTH_PATH="${APP_HEALTH_PATH:-/v1/healthcheck}"
|
||||
curl -sf "${APP_BASE_URL}${HEALTH_PATH}" >/dev/null \
|
||||
|| fail "public health did not answer at ${HEALTH_PATH}"
|
||||
|
||||
# 7. a token from the wrong audience is refused
|
||||
BAD_STATUS="$(curl -s -o /dev/null -w '%{http_code}' \
|
||||
-H "Authorization: Bearer not-a-real-token" "${APP_BASE_URL}${HEALTH_PATH}")"
|
||||
[ "${BAD_STATUS}" != "500" ] || fail "a malformed token produced a server error rather than a refusal"
|
||||
|
||||
echo "auth-smoke: realm, client, claims and endpoint access all verified against ${KEYCLOAK_ISSUER}"
|
||||
@@ -0,0 +1,4 @@
|
||||
# The lane's SMTP keypair, generated per run by scripts/run-compose-runtime-smoke.sh and removed on
|
||||
# teardown. Nothing here is ever committed: a test certificate in Git is a private key in Git.
|
||||
*
|
||||
!.gitignore
|
||||
Executable
+12
@@ -0,0 +1,12 @@
|
||||
#!/bin/sh
|
||||
# Creates the smoke bucket and its minimum policy. Idempotent.
|
||||
#
|
||||
# Deliberately not a round trip: this proves the server accepted an admin command, which is a
|
||||
# different claim from "an object survives being written and read back". object-storage-smoke.sh
|
||||
# makes that one.
|
||||
set -eu
|
||||
|
||||
mc alias set caskeleton "${MINIO_ENDPOINT}" "${MINIO_ROOT_USER}" "${MINIO_ROOT_PASSWORD}"
|
||||
mc mb --ignore-existing "caskeleton/${MINIO_BUCKET}"
|
||||
mc anonymous set none "caskeleton/${MINIO_BUCKET}"
|
||||
echo "minio-init: bucket ${MINIO_BUCKET} present, anonymous access denied"
|
||||
Executable
+68
@@ -0,0 +1,68 @@
|
||||
#!/bin/sh
|
||||
# upload -> HEAD -> download -> delete -> wrong-credential rejection, in that order, none skippable.
|
||||
#
|
||||
# A readiness probe says the server answers. This says an object written to it comes back byte for
|
||||
# byte and then stops existing when deleted, which is the property anything storing a file depends
|
||||
# on. The wrong-credential step is here because a bucket that accepts anyone is also "working".
|
||||
#
|
||||
# It runs on the MinIO server image rather than the mc client image, and the reason is worth keeping:
|
||||
# minio/mc ships mc and almost nothing else — no sed, no grep, no cmp — so steps 2 and 3 below called
|
||||
# two binaries that are not there. The script had never run to find out. The wrapper's one-shot loop
|
||||
# lost its stdin to `docker compose run` and executed only the first client per lane, so this one was
|
||||
# skipped in every lane that declared it while all three lanes reported green.
|
||||
#
|
||||
# minio/minio carries mc, and also sha256sum, cut and tr. The lane already pulls it for the server,
|
||||
# so this costs no image, and the digest comparison is a stronger identity check than cmp: it fails
|
||||
# on any differing byte and says so without dumping the bytes.
|
||||
set -eu
|
||||
|
||||
KEY="smoke/$(date +%s)-$$"
|
||||
WORK="$(mktemp -d)"
|
||||
trap 'rm -rf "${WORK}"' EXIT
|
||||
|
||||
mc alias set caskeleton "${MINIO_ENDPOINT}" "${MINIO_ROOT_USER}" "${MINIO_ROOT_PASSWORD}"
|
||||
|
||||
# 1. upload known bytes
|
||||
head -c 65536 /dev/urandom > "${WORK}/payload"
|
||||
EXPECTED_SIZE="$(wc -c < "${WORK}/payload" | tr -d ' ')"
|
||||
mc cp "${WORK}/payload" "caskeleton/${MINIO_BUCKET}/${KEY}"
|
||||
|
||||
# 2. HEAD: size must match. Parsed with tr and cut because this image has no sed or grep: the JSON is
|
||||
# split onto one field per line, the size field is selected, and everything but its digits dropped.
|
||||
ACTUAL_SIZE="$(mc stat --json "caskeleton/${MINIO_BUCKET}/${KEY}" \
|
||||
| tr ',' '\n' | tr -d ' ' | while IFS= read -r field; do
|
||||
case "${field}" in '"size":'*) echo "${field}" | cut -d: -f2 | tr -dc '0-9' ;; esac
|
||||
done)"
|
||||
if [ -z "${ACTUAL_SIZE}" ]; then
|
||||
echo "object-storage-smoke: mc stat reported no size for the uploaded object" >&2
|
||||
exit 1
|
||||
fi
|
||||
if [ "${ACTUAL_SIZE}" != "${EXPECTED_SIZE}" ]; then
|
||||
echo "object-storage-smoke: HEAD reported ${ACTUAL_SIZE} bytes, uploaded ${EXPECTED_SIZE}" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 3. download: bytes must be identical, by digest rather than by cmp
|
||||
mc cp "caskeleton/${MINIO_BUCKET}/${KEY}" "${WORK}/roundtrip"
|
||||
UPLOADED_DIGEST="$(sha256sum < "${WORK}/payload" | cut -d' ' -f1)"
|
||||
RETURNED_DIGEST="$(sha256sum < "${WORK}/roundtrip" | cut -d' ' -f1)"
|
||||
if [ "${UPLOADED_DIGEST}" != "${RETURNED_DIGEST}" ]; then
|
||||
echo "object-storage-smoke: downloaded bytes differ from what was uploaded" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 4. delete: must then be absent
|
||||
mc rm "caskeleton/${MINIO_BUCKET}/${KEY}"
|
||||
if mc stat "caskeleton/${MINIO_BUCKET}/${KEY}" >/dev/null 2>&1; then
|
||||
echo "object-storage-smoke: object still present after delete" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 5. a deliberately wrong credential must be refused
|
||||
if mc alias set rejected "${MINIO_ENDPOINT}" "${MINIO_ROOT_USER}" "definitely-not-the-password" >/dev/null 2>&1 \
|
||||
&& mc ls "rejected/${MINIO_BUCKET}" >/dev/null 2>&1; then
|
||||
echo "object-storage-smoke: a wrong password was accepted" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "object-storage-smoke: upload, head, download, delete and credential rejection all passed"
|
||||
+109
@@ -0,0 +1,109 @@
|
||||
#!/bin/sh
|
||||
# Notification lane client. One script, three phases, because the handoff lane needs the accept and
|
||||
# the verify to be the same client talking about the same request id.
|
||||
#
|
||||
# ingest accept a request while the platform is INGEST_ONLY, and record its id
|
||||
# serving accept and expect delivery in the same run
|
||||
# handoff-verify re-check a request accepted in an earlier phase, after a SERVING restart
|
||||
#
|
||||
# The evidence a handoff needs is that the id from phase one is delivered exactly once after the
|
||||
# restart, on the route frozen at accept — not that some message arrived.
|
||||
#
|
||||
# Three things this client does that it did not have to before NTF-INT-008, and each is a fact about
|
||||
# the platform rather than about the test:
|
||||
#
|
||||
# 1. it authenticates. Submission and template publication are ordinary non-public paths, so they
|
||||
# sit behind the same JWT the rest of the API does. The token is obtained by client credentials
|
||||
# against the same issuer URL the application validates against — a token from a different URL
|
||||
# is not the same token.
|
||||
# 2. it publishes a template first. A submission pins a template id and version and the platform
|
||||
# refuses one it cannot resolve, so "send a notification" is two calls, not one.
|
||||
# 3. it addresses a recipient by value. The platform stores contact points encrypted and references
|
||||
# them by id; the accept endpoint registers or reuses one, so the address never reaches a plan.
|
||||
set -eu
|
||||
|
||||
STATE_FILE="/opt/notification-smoke-state/request-id"
|
||||
SECRET_FILE="/run/secrets/keycloak-graphql-smoke-client-secret"
|
||||
BASE_PATH="${APP_BASE_PATH:-/api}"
|
||||
TEMPLATE_ID="smoke"
|
||||
RECIPIENT="smoke@example.test"
|
||||
|
||||
fail() { echo "notification-smoke: $1" >&2; exit 1; }
|
||||
|
||||
token() {
|
||||
[ -r "${SECRET_FILE}" ] || fail "the client secret was not mounted"
|
||||
RESPONSE="$(curl -sf -X POST "${KEYCLOAK_ISSUER}/protocol/openid-connect/token" \
|
||||
-d grant_type=client_credentials \
|
||||
-d "client_id=${KEYCLOAK_CLIENT_ID}" \
|
||||
--data-urlencode "client_secret=$(cat "${SECRET_FILE}")")" \
|
||||
|| fail "client-credentials token request failed"
|
||||
echo "${RESPONSE}" | sed -n 's/.*"access_token":"\([^"]*\)".*/\1/p'
|
||||
}
|
||||
|
||||
case "${NOTIFICATION_SMOKE_PHASE}" in
|
||||
ingest|serving)
|
||||
ACCESS_TOKEN="$(token)"
|
||||
[ -n "${ACCESS_TOKEN}" ] || fail "the token response carried no access_token"
|
||||
|
||||
# 1. the template. Republishing the same version is the same immutable content, so a lane that
|
||||
# reruns against a surviving volume is not a different lane; a 409 here means the platform
|
||||
# holds a version with this id and different content, which is a real failure.
|
||||
PUBLISH_STATUS="$(curl -s -o /tmp/publish.json -w '%{http_code}' \
|
||||
-X POST "${APP_BASE_URL}${BASE_PATH}/notification-templates" \
|
||||
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d "{\"templateId\":\"${TEMPLATE_ID}\",\"version\":1,\"channel\":\"EMAIL\",\"locale\":\"en\",
|
||||
\"slots\":{\"SUBJECT\":\"lane smoke\",\"TEXT_BODY\":\"lane smoke body\"}}")"
|
||||
case "${PUBLISH_STATUS}" in
|
||||
201|409) : ;;
|
||||
401|403) fail "template publication was refused (${PUBLISH_STATUS}); the token lacks notification-template:publish" ;;
|
||||
*) fail "template publication answered ${PUBLISH_STATUS}: $(cat /tmp/publish.json)" ;;
|
||||
esac
|
||||
|
||||
# 2. the submission.
|
||||
ACCEPT_STATUS="$(curl -s -o /tmp/accept.json -w '%{http_code}' \
|
||||
-X POST "${APP_BASE_URL}${BASE_PATH}/notifications" \
|
||||
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d "{\"recipientRef\":\"lane-smoke-recipient\",\"channel\":\"EMAIL\",
|
||||
\"address\":\"${RECIPIENT}\",\"template\":\"${TEMPLATE_ID}\",\"templateVersion\":1,
|
||||
\"locale\":\"en\",\"variables\":{},\"category\":\"transactional\"}")"
|
||||
[ "${ACCEPT_STATUS}" = "202" ] \
|
||||
|| fail "accept answered ${ACCEPT_STATUS}: $(cat /tmp/accept.json)"
|
||||
|
||||
REQUEST_ID="$(sed -n 's/.*"requestId":"\([^"]*\)".*/\1/p' /tmp/accept.json)"
|
||||
[ -n "${REQUEST_ID}" ] || fail "the accept response carried no requestId"
|
||||
# Not an `&&` chain: a failed mkdir in one is exempt from `set -e`, so the id went unrecorded
|
||||
# and the ingest phase still reported success — leaving the handoff phase to fail later about a
|
||||
# state file "the phases did not share", which describes the symptom and not the cause.
|
||||
mkdir -p "$(dirname "${STATE_FILE}")" || fail "the state directory is not writable"
|
||||
echo "${REQUEST_ID}" > "${STATE_FILE}" || fail "the request id could not be recorded"
|
||||
echo "notification-smoke: accepted ${REQUEST_ID} in ${NOTIFICATION_SMOKE_PHASE}"
|
||||
;;
|
||||
handoff-verify)
|
||||
[ -r "${STATE_FILE}" ] || fail "no request id from the ingest phase; the phases did not share state"
|
||||
REQUEST_ID="$(cat "${STATE_FILE}")"
|
||||
;;
|
||||
*)
|
||||
fail "unknown phase ${NOTIFICATION_SMOKE_PHASE}"
|
||||
;;
|
||||
esac
|
||||
|
||||
if [ "${NOTIFICATION_SMOKE_PHASE}" = "ingest" ]; then
|
||||
# INGEST_ONLY accepts durably and sends nothing. A message here means a worker ran that should not
|
||||
# have.
|
||||
COUNT="$(curl -sf "${MAILPIT_BASE_URL}/api/v1/messages?limit=200" 2>/dev/null \
|
||||
| grep -o '"ID"' | wc -l | tr -d ' ')" || COUNT=0
|
||||
[ "${COUNT}" = "0" ] || fail "INGEST_ONLY delivered ${COUNT} message(s); no worker should have run"
|
||||
echo "notification-smoke: ingest stored the request and sent nothing"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# serving and handoff-verify: exactly one delivery, and still exactly one after another poll window.
|
||||
sleep 10
|
||||
first="$(curl -sf "${MAILPIT_BASE_URL}/api/v1/search?query=smoke%40example.test" | grep -o '"ID"' | wc -l | tr -d ' ')"
|
||||
[ "${first}" = "1" ] || fail "expected exactly one delivery, saw ${first}"
|
||||
sleep 15
|
||||
second="$(curl -sf "${MAILPIT_BASE_URL}/api/v1/search?query=smoke%40example.test" | grep -o '"ID"' | wc -l | tr -d ' ')"
|
||||
[ "${second}" = "1" ] || fail "a second dispatch window produced ${second} deliveries; at-most-once is broken"
|
||||
echo "notification-smoke: ${REQUEST_ID} delivered exactly once and stayed that way"
|
||||
Executable
+72
@@ -0,0 +1,72 @@
|
||||
#!/bin/sh
|
||||
# =============================================================================
|
||||
# Install capability schema streams. Installation only — promotion is a separate step, and a
|
||||
# separate container, because it is a separate decision.
|
||||
#
|
||||
# Capability streams are not one Flyway run. Each of db/migration/jpa/* declares its own V1 and keeps
|
||||
# its own history table, so pointing a single Flyway at all of them fails with "Found more than one
|
||||
# migration with version 1" — which is what nine Compose lanes discovered the moment Wave 2 stopped
|
||||
# PostgreSqlPersistenceConfig from discarding spring.flyway.locations.
|
||||
#
|
||||
# Two things come first regardless of what was requested, and the order between them is not a
|
||||
# preference:
|
||||
#
|
||||
# 1. db/migration/postgresql, the application's own stream, into the default flyway_schema_history.
|
||||
# The application ships baseline-on-migrate: false as policy (FLYWAY-C6, and re-enabling it under
|
||||
# prod is a boot failure), so it refuses to start against a schema that has tables but no history
|
||||
# table of its own. Installing any capability stream before this one produces exactly that state:
|
||||
# the lane's first run applied ten notification migrations and then the application refused with
|
||||
# "Found non-empty schema(s) but no schema history table" — correctly.
|
||||
# 2. db/migration/jpa/core, which creates capability_schema_registry, the table every other stream
|
||||
# registers itself into.
|
||||
#
|
||||
# Each stream registers itself INSTALLED_INACTIVE. Nothing here promotes anything — a table existing
|
||||
# is not the same as a capability being sanctioned to use it, and this image has no psql to blur the
|
||||
# two with even if that were wanted. infra/postgres/promote-capability-streams.sh is the operator
|
||||
# half, and NotificationSchemaActivation refusing startup until it has run is the fail-closed third.
|
||||
#
|
||||
# CAPABILITY_STREAMS is a space-separated list of directory names under db/migration/jpa.
|
||||
# =============================================================================
|
||||
set -eu
|
||||
|
||||
: "${PGHOST:?PGHOST is required}"
|
||||
: "${PGUSER:?PGUSER is required}"
|
||||
: "${PGDATABASE:?PGDATABASE is required}"
|
||||
: "${CAPABILITY_STREAMS:=}"
|
||||
|
||||
MIGRATIONS=/flyway/sql
|
||||
JDBC="jdbc:postgresql://${PGHOST}:${PGPORT:-5432}/${PGDATABASE}"
|
||||
|
||||
run_flyway() {
|
||||
location="$1"
|
||||
history="$2"
|
||||
baseline="$3"
|
||||
[ -d "${MIGRATIONS}/${location}" ] || {
|
||||
echo "capability-streams: no such stream 'db/migration/${location}'" >&2
|
||||
exit 1
|
||||
}
|
||||
echo "capability-streams: applying ${location} into ${history}"
|
||||
# shellcheck disable=SC2086
|
||||
flyway \
|
||||
-url="${JDBC}" -user="${PGUSER}" -password="${PGPASSWORD:-}" \
|
||||
-locations="filesystem:${MIGRATIONS}/${location}" \
|
||||
-table="${history}" \
|
||||
${baseline} \
|
||||
migrate
|
||||
}
|
||||
|
||||
apply_stream() {
|
||||
stream="$1"
|
||||
# Capability streams baseline at 0 because each is installed into a database the core stream has
|
||||
# already put tables in; the application's own stream must not, for the reason above.
|
||||
run_flyway "jpa/${stream}" "flyway_jpa_$(echo "${stream}" | tr '-' '_')_history" \
|
||||
"-baselineOnMigrate=true -baselineVersion=0"
|
||||
}
|
||||
|
||||
run_flyway postgresql flyway_schema_history ""
|
||||
apply_stream core
|
||||
for stream in ${CAPABILITY_STREAMS}; do
|
||||
apply_stream "${stream}"
|
||||
done
|
||||
|
||||
echo "capability-streams: installed postgresql, core, [${CAPABILITY_STREAMS}]; none promoted"
|
||||
Executable
+37
@@ -0,0 +1,37 @@
|
||||
#!/bin/sh
|
||||
# =============================================================================
|
||||
# Installs the server certificate where PostgreSQL will accept it, then hands over.
|
||||
#
|
||||
# PostgreSQL refuses to start if the private key is group- or world-readable, and it reads the key
|
||||
# as the `postgres` user — uid 70 in the Alpine image. The certificate is generated on the host by
|
||||
# the qualification wrapper, so it arrives owned by whoever ran the script; a bind mount preserves
|
||||
# that ownership, and the two facts together mean a mounted key is either unreadable by postgres or
|
||||
# too permissive for it. Neither is fixable from the outside.
|
||||
#
|
||||
# So the key is copied, once, at the only moment this container is still root: before the official
|
||||
# entrypoint gosu's down to postgres. The copy lives on the container filesystem, not on the mount,
|
||||
# and the mount stays read-only.
|
||||
#
|
||||
# The same problem, the same shape as the Keycloak client secret and the MinIO smoke client. It is
|
||||
# worth stating plainly: bind-mounted credentials and per-image uids do not compose, and every
|
||||
# service that needs one has to say how it bridges them.
|
||||
# =============================================================================
|
||||
set -eu
|
||||
|
||||
TLS_SOURCE="${POSTGRES_TLS_DIR:-/opt/postgres-tls}"
|
||||
TLS_TARGET=/etc/postgresql-tls
|
||||
|
||||
if [ -f "${TLS_SOURCE}/server.key" ] && [ -f "${TLS_SOURCE}/server.crt" ]; then
|
||||
mkdir -p "${TLS_TARGET}"
|
||||
cp "${TLS_SOURCE}/server.key" "${TLS_TARGET}/server.key"
|
||||
cp "${TLS_SOURCE}/server.crt" "${TLS_TARGET}/server.crt"
|
||||
chown -R postgres:postgres "${TLS_TARGET}"
|
||||
chmod 0700 "${TLS_TARGET}"
|
||||
chmod 0600 "${TLS_TARGET}/server.key"
|
||||
chmod 0644 "${TLS_TARGET}/server.crt"
|
||||
else
|
||||
echo "postgres-entrypoint: no certificate at ${TLS_SOURCE}; refusing to start a TLS lane without one" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
exec docker-entrypoint.sh "$@"
|
||||
Executable
+55
@@ -0,0 +1,55 @@
|
||||
#!/bin/sh
|
||||
# =============================================================================
|
||||
# The operator half: sanction installed capability schemas for use.
|
||||
#
|
||||
# apply-capability-streams.sh installs; this promotes. They are two scripts on two images because
|
||||
# they are two decisions, and because the Flyway image ships no psql — so a promotion that lived
|
||||
# inside the migration step could not have run at all, which is how this split was found.
|
||||
#
|
||||
# Promotion is an UPDATE rather than a migration on purpose. A stream that promoted itself would make
|
||||
# "the tables exist" and "an operator sanctioned this capability" indistinguishable, and the second is
|
||||
# the one NotificationSchemaActivation refuses to start without.
|
||||
#
|
||||
# CAPABILITY_STREAMS is a space-separated list of directory names under db/migration/jpa; the ids are
|
||||
# mapped explicitly below because they are not derivable from the directory names.
|
||||
# =============================================================================
|
||||
set -eu
|
||||
|
||||
: "${PGHOST:?PGHOST is required}"
|
||||
: "${PGUSER:?PGUSER is required}"
|
||||
: "${PGDATABASE:?PGDATABASE is required}"
|
||||
: "${CAPABILITY_STREAMS:=}"
|
||||
|
||||
promote() {
|
||||
capability="$1"
|
||||
echo "capability-streams: promoting ${capability}"
|
||||
# A promotion that matched no row would leave the capability inactive and be reported as success,
|
||||
# so the row count is checked rather than the exit status. That failure mode is the whole reason
|
||||
# this step exists: it would surface much later as a startup refusal about a capability the lane
|
||||
# believed it had promoted.
|
||||
updated="$(psql -v ON_ERROR_STOP=1 -qtAX -h "${PGHOST}" -U "${PGUSER}" -d "${PGDATABASE}" -c \
|
||||
"update capability_schema_registry set lifecycle_state = 'ACTIVE'
|
||||
where capability_id = '${capability}' returning capability_id" | wc -l)"
|
||||
if [ "${updated}" -ne 1 ]; then
|
||||
echo "capability-streams: ${capability} is not installed; nothing was promoted" >&2
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
promote jpa-flyway-migration
|
||||
|
||||
# Capability ids are not derivable from directory names — jpa/notification-platform registers
|
||||
# jpa-notification-platform-v4 — so each stream a lane asks for is named here rather than guessed. An
|
||||
# unmapped stream fails loudly instead of being installed and left inactive.
|
||||
for stream in ${CAPABILITY_STREAMS}; do
|
||||
case "${stream}" in
|
||||
notification-platform) promote jpa-notification-platform-v4 ;;
|
||||
fileserver) promote jpa-fileserver-metadata-v1 ;;
|
||||
*)
|
||||
echo "capability-streams: no promotion mapping for stream '${stream}'" >&2
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
echo "capability-streams: promoted core [${CAPABILITY_STREAMS}]"
|
||||
@@ -0,0 +1,5 @@
|
||||
# Generated per qualification run and removed on teardown: a CA, a server keypair for the host name
|
||||
# `db`, and nothing that outlives the lane. A committed test certificate is still a private key in
|
||||
# Git, and "it is only for smoke tests" is not something a scanner or a fork can tell.
|
||||
*
|
||||
!.gitignore
|
||||
@@ -1,6 +0,0 @@
|
||||
72113b04239cd397787fec5cdc9ac5aa309e85c53767042fc7019338afb884d0 ./README.md
|
||||
2ae49f02d38b32dbd660ae3957f97912f469c0ff404e0e665d4986fe21e33963 ./VALIDATION.md
|
||||
1ac376309b161cf95b6b3def89284e509ce0191131a268833ca13bd50814ff09 ./docs/superpowers/plans/2026-08-11-jpa-persistence-experimental-expansion-plan.md
|
||||
bb5d0d876e9a3232a3661cd50b3a4c0da0ea4c68f820526d8b34cb3bdcb43d86 ./docs/superpowers/plans/2026-08-11-jpa-persistence-platform-implementation-plan.md
|
||||
a28046eb1451d87e3ac9c3b1922c134b99fa9155d32c09c0f5bddf80f588aaec ./docs/superpowers/specs/2026-08-11-jpa-persistence-platform-design.md
|
||||
4e53da920430d5a82a744475a30b8036d2412627c2488d182daf6d3c1b013eb6 ./validate_jpa_docs.py
|
||||
-771
@@ -1,771 +0,0 @@
|
||||
# JPA Experimental Expansion Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Stable JPA 플랫폼을 변경하지 않고 Multi-tenancy, PostgreSQL RLS, schema/database tenant 분리, consistency-aware Read Replica, Jakarta Persistence 4.0, Hibernate ORM 8, PostgreSQL 19 호환성을 독립 Experimental 모듈과 승격 Gate로 검증한다.
|
||||
|
||||
**Architecture:** Experimental module은 Stable `jpa-core-api` 계약만 소비하며 Stable starter에 자동 포함되지 않는다. 각 기능은 명시적 feature flag와 별도 compatibility/failure suite를 요구한다. 실험 결과가 Stable 의미론과 충돌하면 Core를 왜곡하지 않고 capability 또는 별도 profile로 유지한다.
|
||||
|
||||
**Tech Stack:** Stable 계획의 Java 21·Spring Boot 4.1·PostgreSQL Testcontainers 기반, PostgreSQL RLS, AbstractRoutingDataSource, tenant-specific DataSource registry, Jakarta Persistence 4.0 preview/final compatibility lane, Hibernate ORM 8 compatibility lane, PostgreSQL 19 compatibility lane.
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- Stable 계획 Task 1~53이 완료되고 Release Gate가 통과한 뒤 시작한다.
|
||||
- 모듈 루트는 `modules/jpa-experimental`이다.
|
||||
- Experimental module은 `jpa-spring-boot-starter`의 기본 dependency가 아니다.
|
||||
- 모든 기능은 `backend.jpa.experimental.*` feature flag를 요구한다.
|
||||
- Tenant ID와 consistency token은 metric label에 기록하지 않는다.
|
||||
- Tenant context 누락은 fail-closed다.
|
||||
- `readOnly=true`만으로 replica routing하지 않는다.
|
||||
- Lock query, write transaction, read-after-write pin은 primary를 사용한다.
|
||||
- JPA4/Hibernate8/PG19 결과로 Stable 3.2/7.4/PG16~18 contract를 수정하지 않는다.
|
||||
- 승격 전 별도 security, failure, migration and compatibility evidence가 필요하다.
|
||||
|
||||
---
|
||||
|
||||
## 1. Experimental 파일 구조
|
||||
|
||||
```text
|
||||
modules/jpa-experimental/
|
||||
├── jpa-experimental-core/
|
||||
├── jpa-multitenancy-column/
|
||||
├── jpa-multitenancy-rls/
|
||||
├── jpa-multitenancy-schema/
|
||||
├── jpa-multitenancy-database/
|
||||
├── jpa-read-replica/
|
||||
└── jpa-next-compatibility/
|
||||
```
|
||||
|
||||
---
|
||||
### Task 1: Experimental Module·Feature Gate·Dependency Isolation 구성
|
||||
|
||||
**Files:**
|
||||
- Create: `modules/jpa-experimental/jpa-experimental-core/build.gradle.kts`
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-column/build.gradle.kts`
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-rls/build.gradle.kts`
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-schema/build.gradle.kts`
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-database/build.gradle.kts`
|
||||
- Create: `modules/jpa-experimental/jpa-read-replica/build.gradle.kts`
|
||||
- Create: `modules/jpa-experimental/jpa-next-compatibility/build.gradle.kts`
|
||||
- Create: `modules/jpa-experimental/jpa-experimental-core/src/main/java/io/backend/skeleton/jpa/experimental/ExperimentalFeature.java`
|
||||
- Create: `modules/jpa-experimental/jpa-experimental-core/src/main/java/io/backend/skeleton/jpa/experimental/ExperimentalFeatureGate.java`
|
||||
- Modify: `settings.gradle.kts`
|
||||
- Test: `modules/jpa-experimental/jpa-experimental-core/src/test/java/io/backend/skeleton/jpa/experimental/ExperimentalFeatureGateTest.java`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: Stable `jpa-core-api` and explicit environment feature flags.
|
||||
- Produces: Isolated experimental projects that cannot enter the Stable starter transitively.
|
||||
|
||||
**Implementation requirements:**
|
||||
- Every module depends only on Stable public contracts, never on Stable internal packages.
|
||||
- Feature gate fails startup when module is present but flag is absent.
|
||||
- Add a dependency graph test proving the Stable starter has no experimental dependency.
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```java
|
||||
package io.backend.skeleton.jpa.experimental;
|
||||
|
||||
class ExperimentalFeatureGateTest {
|
||||
@Test
|
||||
void featureIsDisabledUnlessExplicitlyEnabled() {
|
||||
assertThatThrownBy(() -> gate.requireEnabled(MULTITENANCY_COLUMN, Map.of()))
|
||||
.hasMessageContaining("backend.jpa.experimental.multitenancy-column=true");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run the focused test and verify the failure**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-experimental-core:test --tests 'io.backend.skeleton.jpa.experimental.ExperimentalFeatureGateTest'
|
||||
```
|
||||
|
||||
Expected: FAIL because the production type or behavior does not exist yet.
|
||||
|
||||
- [ ] **Step 3: Implement the smallest complete production contract**
|
||||
|
||||
```java
|
||||
package io.backend.skeleton.jpa.experimental;
|
||||
|
||||
public final class ExperimentalFeatureGate {
|
||||
public void requireEnabled(
|
||||
ExperimentalFeature feature,
|
||||
Map<String, Boolean> flags) {
|
||||
if (!Boolean.TRUE.equals(flags.get(feature.property()))) {
|
||||
throw new IllegalStateException(feature.property() + "=true is required");
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Implement every file and invariant listed under **Implementation requirements**; the snippet fixes the public names and central behavior rather than replacing those requirements.
|
||||
|
||||
- [ ] **Step 4: Run the focused test and the module test suite**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-experimental-core:test --tests 'io.backend.skeleton.jpa.experimental.ExperimentalFeatureGateTest'
|
||||
./gradlew :modules:jpa-experimental:jpa-experimental-core:test
|
||||
```
|
||||
|
||||
Expected: PASS with all assertions green.
|
||||
|
||||
- [ ] **Step 5: Commit the independently reviewable change**
|
||||
|
||||
```bash
|
||||
git add 'modules/jpa-experimental/jpa-experimental-core/build.gradle.kts' 'modules/jpa-experimental/jpa-multitenancy-column/build.gradle.kts' 'modules/jpa-experimental/jpa-multitenancy-rls/build.gradle.kts' 'modules/jpa-experimental/jpa-multitenancy-schema/build.gradle.kts' 'modules/jpa-experimental/jpa-multitenancy-database/build.gradle.kts' 'modules/jpa-experimental/jpa-read-replica/build.gradle.kts' 'modules/jpa-experimental/jpa-next-compatibility/build.gradle.kts' 'modules/jpa-experimental/jpa-experimental-core/src/main/java/io/backend/skeleton/jpa/experimental/ExperimentalFeature.java' 'modules/jpa-experimental/jpa-experimental-core/src/main/java/io/backend/skeleton/jpa/experimental/ExperimentalFeatureGate.java' 'settings.gradle.kts' 'modules/jpa-experimental/jpa-experimental-core/src/test/java/io/backend/skeleton/jpa/experimental/ExperimentalFeatureGateTest.java'
|
||||
git commit -m "build: isolate jpa experimental modules"
|
||||
```
|
||||
|
||||
### Task 2: Shared-schema Tenant Context와 Column Guard 구현
|
||||
|
||||
**Files:**
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-column/src/main/java/io/backend/skeleton/jpa/experimental/tenant/TenantId.java`
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-column/src/main/java/io/backend/skeleton/jpa/experimental/tenant/TenantContext.java`
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-column/src/main/java/io/backend/skeleton/jpa/experimental/tenant/TenantAwareRepositoryGuard.java`
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-column/src/main/java/io/backend/skeleton/jpa/experimental/tenant/TenantEntityListenerGuard.java`
|
||||
- Test: `modules/jpa-experimental/jpa-multitenancy-column/src/integrationTest/java/io/backend/skeleton/jpa/experimental/tenant/TenantColumnIsolationTest.java`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: Explicit request/job tenant context and domain Entity tenant-column contracts.
|
||||
- Produces: Fail-closed tenant context propagation and query/write isolation evidence.
|
||||
|
||||
**Implementation requirements:**
|
||||
- Reject Repository access when tenant context is absent outside an audited admin scope.
|
||||
- Require tenant column in unique/index requirements where isolation depends on it.
|
||||
- Test async job context propagation and cleanup.
|
||||
- Do not rely on Hibernate filter alone as the final security boundary.
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```java
|
||||
package io.backend.skeleton.jpa.experimental.tenant;
|
||||
|
||||
class TenantColumnIsolationTest {
|
||||
@Test
|
||||
void tenantARepositoryCannotReadTenantBRows() {
|
||||
insertFor(TENANT_A, "a");
|
||||
insertFor(TENANT_B, "b");
|
||||
|
||||
assertThat(withTenant(TENANT_A, repository::findAll))
|
||||
.extracting(Item::value)
|
||||
.containsExactly("a");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run the focused test and verify the failure**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-multitenancy-column:integrationTest --tests 'io.backend.skeleton.jpa.experimental.tenant.TenantColumnIsolationTest'
|
||||
```
|
||||
|
||||
Expected: FAIL because the production type or behavior does not exist yet.
|
||||
|
||||
- [ ] **Step 3: Implement the smallest complete production contract**
|
||||
|
||||
```java
|
||||
package io.backend.skeleton.jpa.experimental.tenant;
|
||||
|
||||
public final class TenantContext {
|
||||
private static final ThreadLocal<TenantId> CURRENT = new ThreadLocal<>();
|
||||
|
||||
public static TenantId require() {
|
||||
TenantId tenant = CURRENT.get();
|
||||
if (tenant == null) throw new IllegalStateException("tenant context is required");
|
||||
return tenant;
|
||||
}
|
||||
|
||||
public static void clear() { CURRENT.remove(); }
|
||||
}
|
||||
```
|
||||
|
||||
Implement every file and invariant listed under **Implementation requirements**; the snippet fixes the public names and central behavior rather than replacing those requirements.
|
||||
|
||||
- [ ] **Step 4: Run the focused test and the module test suite**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-multitenancy-column:integrationTest --tests 'io.backend.skeleton.jpa.experimental.tenant.TenantColumnIsolationTest'
|
||||
./gradlew :modules:jpa-experimental:jpa-multitenancy-column:test
|
||||
```
|
||||
|
||||
Expected: PASS with all assertions green.
|
||||
|
||||
- [ ] **Step 5: Commit the independently reviewable change**
|
||||
|
||||
```bash
|
||||
git add 'modules/jpa-experimental/jpa-multitenancy-column/src/main/java/io/backend/skeleton/jpa/experimental/tenant/TenantId.java' 'modules/jpa-experimental/jpa-multitenancy-column/src/main/java/io/backend/skeleton/jpa/experimental/tenant/TenantContext.java' 'modules/jpa-experimental/jpa-multitenancy-column/src/main/java/io/backend/skeleton/jpa/experimental/tenant/TenantAwareRepositoryGuard.java' 'modules/jpa-experimental/jpa-multitenancy-column/src/main/java/io/backend/skeleton/jpa/experimental/tenant/TenantEntityListenerGuard.java' 'modules/jpa-experimental/jpa-multitenancy-column/src/integrationTest/java/io/backend/skeleton/jpa/experimental/tenant/TenantColumnIsolationTest.java'
|
||||
git commit -m "feat: add experimental tenant column isolation"
|
||||
```
|
||||
|
||||
### Task 3: PostgreSQL RLS Tenant Policy와 Connection Reuse Guard 구현
|
||||
|
||||
**Files:**
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-rls/src/main/java/io/backend/skeleton/jpa/experimental/rls/RlsTenantSessionBinder.java`
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-rls/src/main/java/io/backend/skeleton/jpa/experimental/rls/RlsPolicyVerifier.java`
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-rls/src/main/java/io/backend/skeleton/jpa/experimental/rls/RlsAdminBypassToken.java`
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-rls/src/main/resources/db/experimental-rls/V1__tenant_rls.sql`
|
||||
- Test: `modules/jpa-experimental/jpa-multitenancy-rls/src/failureTest/java/io/backend/skeleton/jpa/experimental/rls/RlsIsolationFailureTest.java`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: TenantContext, PostgreSQL transaction-local settings and restricted runtime role.
|
||||
- Produces: Database-enforced tenant isolation that resets safely across pooled connections.
|
||||
|
||||
**Implementation requirements:**
|
||||
- Set tenant context with transaction-local `set_config` before tenant queries.
|
||||
- Prove a pooled connection cannot leak the prior tenant into the next transaction.
|
||||
- Runtime role must not own tables or bypass RLS.
|
||||
- Admin bypass requires a separate DataSource and audit token.
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```java
|
||||
package io.backend.skeleton.jpa.experimental.rls;
|
||||
|
||||
class RlsIsolationFailureTest {
|
||||
@Test
|
||||
void pooledConnectionDoesNotLeakPriorTenantSetting() {
|
||||
withTenant(TENANT_A, () -> assertThat(repository.count()).isEqualTo(1));
|
||||
withTenant(TENANT_B, () -> assertThat(repository.count()).isEqualTo(1));
|
||||
withoutTenant(() -> assertThatThrownBy(repository::count).isInstanceOf(DataAccessException.class));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run the focused test and verify the failure**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-multitenancy-rls:failureTest --tests 'io.backend.skeleton.jpa.experimental.rls.RlsIsolationFailureTest'
|
||||
```
|
||||
|
||||
Expected: FAIL because the production type or behavior does not exist yet.
|
||||
|
||||
- [ ] **Step 3: Implement the smallest complete production contract**
|
||||
|
||||
```java
|
||||
package io.backend.skeleton.jpa.experimental.rls;
|
||||
|
||||
public final class RlsTenantSessionBinder {
|
||||
public void bind(EntityManager entityManager, TenantId tenant) {
|
||||
entityManager.createNativeQuery(
|
||||
"select set_config('app.tenant_id', :tenant, true)")
|
||||
.setParameter("tenant", tenant.value())
|
||||
.getSingleResult();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Implement every file and invariant listed under **Implementation requirements**; the snippet fixes the public names and central behavior rather than replacing those requirements.
|
||||
|
||||
- [ ] **Step 4: Run the focused test and the module test suite**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-multitenancy-rls:failureTest --tests 'io.backend.skeleton.jpa.experimental.rls.RlsIsolationFailureTest'
|
||||
./gradlew :modules:jpa-experimental:jpa-multitenancy-rls:test
|
||||
```
|
||||
|
||||
Expected: PASS with all assertions green.
|
||||
|
||||
- [ ] **Step 5: Commit the independently reviewable change**
|
||||
|
||||
```bash
|
||||
git add 'modules/jpa-experimental/jpa-multitenancy-rls/src/main/java/io/backend/skeleton/jpa/experimental/rls/RlsTenantSessionBinder.java' 'modules/jpa-experimental/jpa-multitenancy-rls/src/main/java/io/backend/skeleton/jpa/experimental/rls/RlsPolicyVerifier.java' 'modules/jpa-experimental/jpa-multitenancy-rls/src/main/java/io/backend/skeleton/jpa/experimental/rls/RlsAdminBypassToken.java' 'modules/jpa-experimental/jpa-multitenancy-rls/src/main/resources/db/experimental-rls/V1__tenant_rls.sql' 'modules/jpa-experimental/jpa-multitenancy-rls/src/failureTest/java/io/backend/skeleton/jpa/experimental/rls/RlsIsolationFailureTest.java'
|
||||
git commit -m "feat: add experimental postgresql rls isolation"
|
||||
```
|
||||
|
||||
### Task 4: Schema-per-tenant Connection Provider와 Migration Orchestrator 구현
|
||||
|
||||
**Files:**
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-schema/src/main/java/io/backend/skeleton/jpa/experimental/schema/SchemaTenantRegistry.java`
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-schema/src/main/java/io/backend/skeleton/jpa/experimental/schema/SchemaMultiTenantConnectionProvider.java`
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-schema/src/main/java/io/backend/skeleton/jpa/experimental/schema/SchemaTenantMigrationOrchestrator.java`
|
||||
- Test: `modules/jpa-experimental/jpa-multitenancy-schema/src/migrationTest/java/io/backend/skeleton/jpa/experimental/schema/SchemaTenantMigrationContractTest.java`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: Validated tenant→schema catalog and Flyway migration gate.
|
||||
- Produces: Bounded schema selection and per-tenant migration status without accepting raw schema names.
|
||||
|
||||
**Implementation requirements:**
|
||||
- Map TenantId to a pre-registered schema identifier; no user-provided SQL identifier.
|
||||
- Reset schema/search_path when returning pooled connections.
|
||||
- Track migration version and failure per tenant.
|
||||
- Rate-limit tenant migrations and support resume without auto-repair.
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```java
|
||||
package io.backend.skeleton.jpa.experimental.schema;
|
||||
|
||||
class SchemaTenantMigrationContractTest {
|
||||
@Test
|
||||
void migratesOnlyRegisteredSchemasAndResumesAfterFailure() {
|
||||
orchestrator.migrateAll(List.of(TENANT_A, TENANT_B));
|
||||
assertThat(status(TENANT_A).version()).isEqualTo(LATEST);
|
||||
assertThatThrownBy(() -> orchestrator.migrate(new TenantId("../public")))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run the focused test and verify the failure**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-multitenancy-schema:migrationTest --tests 'io.backend.skeleton.jpa.experimental.schema.SchemaTenantMigrationContractTest'
|
||||
```
|
||||
|
||||
Expected: FAIL because the production type or behavior does not exist yet.
|
||||
|
||||
- [ ] **Step 3: Implement the smallest complete production contract**
|
||||
|
||||
```java
|
||||
package io.backend.skeleton.jpa.experimental.schema;
|
||||
|
||||
public final class SchemaTenantRegistry {
|
||||
public String requireSchema(TenantId tenant) {
|
||||
return Optional.ofNullable(schemaByTenant.get(tenant))
|
||||
.orElseThrow(() -> new IllegalArgumentException("unregistered tenant schema"));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Implement every file and invariant listed under **Implementation requirements**; the snippet fixes the public names and central behavior rather than replacing those requirements.
|
||||
|
||||
- [ ] **Step 4: Run the focused test and the module test suite**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-multitenancy-schema:migrationTest --tests 'io.backend.skeleton.jpa.experimental.schema.SchemaTenantMigrationContractTest'
|
||||
./gradlew :modules:jpa-experimental:jpa-multitenancy-schema:test
|
||||
```
|
||||
|
||||
Expected: PASS with all assertions green.
|
||||
|
||||
- [ ] **Step 5: Commit the independently reviewable change**
|
||||
|
||||
```bash
|
||||
git add 'modules/jpa-experimental/jpa-multitenancy-schema/src/main/java/io/backend/skeleton/jpa/experimental/schema/SchemaTenantRegistry.java' 'modules/jpa-experimental/jpa-multitenancy-schema/src/main/java/io/backend/skeleton/jpa/experimental/schema/SchemaMultiTenantConnectionProvider.java' 'modules/jpa-experimental/jpa-multitenancy-schema/src/main/java/io/backend/skeleton/jpa/experimental/schema/SchemaTenantMigrationOrchestrator.java' 'modules/jpa-experimental/jpa-multitenancy-schema/src/migrationTest/java/io/backend/skeleton/jpa/experimental/schema/SchemaTenantMigrationContractTest.java'
|
||||
git commit -m "feat: add experimental schema per tenant persistence"
|
||||
```
|
||||
|
||||
### Task 5: Database-per-tenant DataSource Registry와 Capacity Guard 구현
|
||||
|
||||
**Files:**
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-database/src/main/java/io/backend/skeleton/jpa/experimental/database/TenantDataSourceRegistry.java`
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-database/src/main/java/io/backend/skeleton/jpa/experimental/database/TenantEntityManagerFactoryRegistry.java`
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-database/src/main/java/io/backend/skeleton/jpa/experimental/database/TenantPoolBudget.java`
|
||||
- Create: `modules/jpa-experimental/jpa-multitenancy-database/src/main/java/io/backend/skeleton/jpa/experimental/database/TenantDataSourceLifecycle.java`
|
||||
- Test: `modules/jpa-experimental/jpa-multitenancy-database/src/performanceTest/java/io/backend/skeleton/jpa/experimental/database/TenantPoolCapacityContractTest.java`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: Secret-backed tenant connection profiles and global DB connection budget.
|
||||
- Produces: Lazy bounded per-tenant pools with eviction, credential rotation and migration status.
|
||||
|
||||
**Implementation requirements:**
|
||||
- Never create an unbounded Hikari pool per tenant.
|
||||
- Enforce global maximum pools and connections before creating a DataSource.
|
||||
- Drain and close pools on tenant removal or credential rotation.
|
||||
- Do not expose tenant JDBC URLs or credentials in diagnostics.
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```java
|
||||
package io.backend.skeleton.jpa.experimental.database;
|
||||
|
||||
class TenantPoolCapacityContractTest {
|
||||
@Test
|
||||
void refusesNewTenantPoolWhenGlobalConnectionBudgetIsExhausted() {
|
||||
registry.openTenants(globalBudget().maxTenants());
|
||||
assertThatThrownBy(() -> registry.require(ANOTHER_TENANT))
|
||||
.isInstanceOf(IllegalStateException.class)
|
||||
.hasMessageContaining("tenant pool budget");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run the focused test and verify the failure**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-multitenancy-database:performanceTest --tests 'io.backend.skeleton.jpa.experimental.database.TenantPoolCapacityContractTest'
|
||||
```
|
||||
|
||||
Expected: FAIL because the production type or behavior does not exist yet.
|
||||
|
||||
- [ ] **Step 3: Implement the smallest complete production contract**
|
||||
|
||||
```java
|
||||
package io.backend.skeleton.jpa.experimental.database;
|
||||
|
||||
public record TenantPoolBudget(
|
||||
int maxOpenPools,
|
||||
int maxConnectionsAcrossPools) {
|
||||
public void requireCapacity(int openPools, int allocatedConnections) {
|
||||
if (openPools >= maxOpenPools || allocatedConnections >= maxConnectionsAcrossPools) {
|
||||
throw new IllegalStateException("tenant pool budget exhausted");
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Implement every file and invariant listed under **Implementation requirements**; the snippet fixes the public names and central behavior rather than replacing those requirements.
|
||||
|
||||
- [ ] **Step 4: Run the focused test and the module test suite**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-multitenancy-database:performanceTest --tests 'io.backend.skeleton.jpa.experimental.database.TenantPoolCapacityContractTest'
|
||||
./gradlew :modules:jpa-experimental:jpa-multitenancy-database:test
|
||||
```
|
||||
|
||||
Expected: PASS with all assertions green.
|
||||
|
||||
- [ ] **Step 5: Commit the independently reviewable change**
|
||||
|
||||
```bash
|
||||
git add 'modules/jpa-experimental/jpa-multitenancy-database/src/main/java/io/backend/skeleton/jpa/experimental/database/TenantDataSourceRegistry.java' 'modules/jpa-experimental/jpa-multitenancy-database/src/main/java/io/backend/skeleton/jpa/experimental/database/TenantEntityManagerFactoryRegistry.java' 'modules/jpa-experimental/jpa-multitenancy-database/src/main/java/io/backend/skeleton/jpa/experimental/database/TenantPoolBudget.java' 'modules/jpa-experimental/jpa-multitenancy-database/src/main/java/io/backend/skeleton/jpa/experimental/database/TenantDataSourceLifecycle.java' 'modules/jpa-experimental/jpa-multitenancy-database/src/performanceTest/java/io/backend/skeleton/jpa/experimental/database/TenantPoolCapacityContractTest.java'
|
||||
git commit -m "feat: add experimental database per tenant registry"
|
||||
```
|
||||
|
||||
### Task 6: Consistency-aware Read Replica Routing 구현
|
||||
|
||||
**Files:**
|
||||
- Create: `modules/jpa-experimental/jpa-read-replica/src/main/java/io/backend/skeleton/jpa/experimental/replica/ReadConsistency.java`
|
||||
- Create: `modules/jpa-experimental/jpa-read-replica/src/main/java/io/backend/skeleton/jpa/experimental/replica/ConsistencyToken.java`
|
||||
- Create: `modules/jpa-experimental/jpa-read-replica/src/main/java/io/backend/skeleton/jpa/experimental/replica/ReplicaRoutingDecision.java`
|
||||
- Create: `modules/jpa-experimental/jpa-read-replica/src/main/java/io/backend/skeleton/jpa/experimental/replica/ConsistencyAwareDataSourceRouter.java`
|
||||
- Create: `modules/jpa-experimental/jpa-read-replica/src/main/java/io/backend/skeleton/jpa/experimental/replica/ReplicaLagMonitor.java`
|
||||
- Test: `modules/jpa-experimental/jpa-read-replica/src/failureTest/java/io/backend/skeleton/jpa/experimental/replica/ReadAfterWriteRoutingContractTest.java`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: Primary/replica DataSources, transaction state, lock intent and replica lag evidence.
|
||||
- Produces: Routing decisions for PRIMARY_REQUIRED, BOUNDED_STALENESS and EVENTUAL reads.
|
||||
|
||||
**Implementation requirements:**
|
||||
- Writes, lock queries, REQUIRES_NEW writes and active write transactions always use primary.
|
||||
- Read-after-write uses a consistency token or primary pin, not `readOnly=true` alone.
|
||||
- Fallback to primary when replica lag exceeds policy or evidence is unavailable.
|
||||
- Keep routing fixed for the life of one transaction.
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```java
|
||||
package io.backend.skeleton.jpa.experimental.replica;
|
||||
|
||||
class ReadAfterWriteRoutingContractTest {
|
||||
@Test
|
||||
void immediateReadAfterWriteUsesPrimaryUntilConsistencyTokenIsSatisfied() {
|
||||
var token = service.writeAndReturnConsistencyToken();
|
||||
var decision = router.route(readOnlyTransaction(), ReadConsistency.after(token));
|
||||
assertThat(decision.target()).isEqualTo(PRIMARY);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run the focused test and verify the failure**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-read-replica:failureTest --tests 'io.backend.skeleton.jpa.experimental.replica.ReadAfterWriteRoutingContractTest'
|
||||
```
|
||||
|
||||
Expected: FAIL because the production type or behavior does not exist yet.
|
||||
|
||||
- [ ] **Step 3: Implement the smallest complete production contract**
|
||||
|
||||
```java
|
||||
package io.backend.skeleton.jpa.experimental.replica;
|
||||
|
||||
public final class ConsistencyAwareDataSourceRouter {
|
||||
public ReplicaRoutingDecision route(
|
||||
TransactionContext transaction,
|
||||
ReadConsistency consistency) {
|
||||
if (transaction.write() || transaction.locking() ||
|
||||
!lagMonitor.satisfies(consistency)) {
|
||||
return ReplicaRoutingDecision.primary();
|
||||
}
|
||||
return ReplicaRoutingDecision.replica();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Implement every file and invariant listed under **Implementation requirements**; the snippet fixes the public names and central behavior rather than replacing those requirements.
|
||||
|
||||
- [ ] **Step 4: Run the focused test and the module test suite**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-read-replica:failureTest --tests 'io.backend.skeleton.jpa.experimental.replica.ReadAfterWriteRoutingContractTest'
|
||||
./gradlew :modules:jpa-experimental:jpa-read-replica:test
|
||||
```
|
||||
|
||||
Expected: PASS with all assertions green.
|
||||
|
||||
- [ ] **Step 5: Commit the independently reviewable change**
|
||||
|
||||
```bash
|
||||
git add 'modules/jpa-experimental/jpa-read-replica/src/main/java/io/backend/skeleton/jpa/experimental/replica/ReadConsistency.java' 'modules/jpa-experimental/jpa-read-replica/src/main/java/io/backend/skeleton/jpa/experimental/replica/ConsistencyToken.java' 'modules/jpa-experimental/jpa-read-replica/src/main/java/io/backend/skeleton/jpa/experimental/replica/ReplicaRoutingDecision.java' 'modules/jpa-experimental/jpa-read-replica/src/main/java/io/backend/skeleton/jpa/experimental/replica/ConsistencyAwareDataSourceRouter.java' 'modules/jpa-experimental/jpa-read-replica/src/main/java/io/backend/skeleton/jpa/experimental/replica/ReplicaLagMonitor.java' 'modules/jpa-experimental/jpa-read-replica/src/failureTest/java/io/backend/skeleton/jpa/experimental/replica/ReadAfterWriteRoutingContractTest.java'
|
||||
git commit -m "feat: add experimental consistency aware replica routing"
|
||||
```
|
||||
|
||||
### Task 7: Jakarta Persistence 4.0 Compatibility Lane 구현
|
||||
|
||||
**Files:**
|
||||
- Create: `modules/jpa-experimental/jpa-next-compatibility/src/compatibilityJpa4/java/io/backend/skeleton/jpa/experimental/next/Jpa4CompatibilityTest.java`
|
||||
- Create: `.github/workflows/jpa-next-jpa4.yml`
|
||||
- Modify: `modules/jpa-experimental/jpa-next-compatibility/build.gradle.kts`
|
||||
- Test: `modules/jpa-experimental/jpa-next-compatibility/src/test/java/io/backend/skeleton/jpa/experimental/next/CompatibilityLaneDefinitionTest.java`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: Published Jakarta Persistence 4.0 milestone/final artifact when available and the Stable contract suite.
|
||||
- Produces: A non-blocking compatibility report that does not alter Stable JPA 3.2 APIs.
|
||||
|
||||
**Implementation requirements:**
|
||||
- Run the Stable public API compilation and selected mapping contracts against JPA 4.
|
||||
- Record removed/changed APIs and provider support separately.
|
||||
- Do not publish JPA4 compiled artifacts under Stable coordinates.
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```kotlin
|
||||
package io.backend.skeleton.jpa.experimental.next;
|
||||
|
||||
class CompatibilityLaneDefinitionTest {
|
||||
@Test
|
||||
void jpaFourLaneIsExperimentalAndSeparateFromStablePublication() {
|
||||
assertThat(lane("jpa4").publicationEnabled()).isFalse();
|
||||
assertThat(lane("jpa4").supportLevel()).isEqualTo(EXPERIMENTAL);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run the focused test and verify the failure**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-next-compatibility:test --tests 'io.backend.skeleton.jpa.experimental.next.CompatibilityLaneDefinitionTest'
|
||||
```
|
||||
|
||||
Expected: FAIL because the production type or behavior does not exist yet.
|
||||
|
||||
- [ ] **Step 3: Implement the smallest complete production contract**
|
||||
|
||||
```kotlin
|
||||
testing {
|
||||
suites {
|
||||
register<JvmTestSuite>("compatibilityJpa4") {
|
||||
useJUnitJupiter()
|
||||
dependencies {
|
||||
implementation(project(":modules:jpa:jpa-core-api"))
|
||||
implementation(libs.jakarta.persistence.next)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Implement every file and invariant listed under **Implementation requirements**; the snippet fixes the public names and central behavior rather than replacing those requirements.
|
||||
|
||||
- [ ] **Step 4: Run the focused test and the module test suite**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-next-compatibility:test --tests 'io.backend.skeleton.jpa.experimental.next.CompatibilityLaneDefinitionTest'
|
||||
./gradlew :modules:jpa-experimental:jpa-next-compatibility:test
|
||||
```
|
||||
|
||||
Expected: PASS with all assertions green.
|
||||
|
||||
- [ ] **Step 5: Commit the independently reviewable change**
|
||||
|
||||
```bash
|
||||
git add 'modules/jpa-experimental/jpa-next-compatibility/src/compatibilityJpa4/java/io/backend/skeleton/jpa/experimental/next/Jpa4CompatibilityTest.java' '.github/workflows/jpa-next-jpa4.yml' 'modules/jpa-experimental/jpa-next-compatibility/build.gradle.kts' 'modules/jpa-experimental/jpa-next-compatibility/src/test/java/io/backend/skeleton/jpa/experimental/next/CompatibilityLaneDefinitionTest.java'
|
||||
git commit -m "test: add jakarta persistence four compatibility lane"
|
||||
```
|
||||
|
||||
### Task 8: Hibernate ORM 8 Compatibility Lane 구현
|
||||
|
||||
**Files:**
|
||||
- Create: `modules/jpa-experimental/jpa-next-compatibility/src/compatibilityHibernate8/java/io/backend/skeleton/jpa/experimental/next/Hibernate8CompatibilityTest.java`
|
||||
- Create: `.github/workflows/jpa-next-hibernate8.yml`
|
||||
- Modify: `modules/jpa-experimental/jpa-next-compatibility/build.gradle.kts`
|
||||
- Test: `modules/jpa-experimental/jpa-next-compatibility/src/test/java/io/backend/skeleton/jpa/experimental/next/HibernateCompatibilityPolicyTest.java`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: Hibernate ORM 8 milestone/final artifact and Stable Hibernate 7.4 regression suites.
|
||||
- Produces: Generated SQL, fetch pagination, statistics, batch and extension compatibility evidence.
|
||||
|
||||
**Implementation requirements:**
|
||||
- Re-run collection fetch pagination, StatementInspector, Statistics, JSONB, Batch and StatelessSession contracts.
|
||||
- Record SQL and performance differences without weakening the 7.4 Stable gate.
|
||||
- Do not allow Hibernate 8 dependencies in Stable published modules.
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```kotlin
|
||||
package io.backend.skeleton.jpa.experimental.next;
|
||||
|
||||
class HibernateCompatibilityPolicyTest {
|
||||
@Test
|
||||
void hibernateEightCannotReplaceStableProviderWithoutPromotion() {
|
||||
assertThat(policy.stableProvider()).isEqualTo("7.4");
|
||||
assertThat(policy.experimentalProviders()).contains("8");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run the focused test and verify the failure**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-next-compatibility:test --tests 'io.backend.skeleton.jpa.experimental.next.HibernateCompatibilityPolicyTest'
|
||||
```
|
||||
|
||||
Expected: FAIL because the production type or behavior does not exist yet.
|
||||
|
||||
- [ ] **Step 3: Implement the smallest complete production contract**
|
||||
|
||||
```kotlin
|
||||
testing {
|
||||
suites {
|
||||
register<JvmTestSuite>("compatibilityHibernate8") {
|
||||
useJUnitJupiter()
|
||||
dependencies {
|
||||
implementation(project(":modules:jpa:jpa-testkit-postgresql"))
|
||||
implementation(libs.hibernate.orm.next)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Implement every file and invariant listed under **Implementation requirements**; the snippet fixes the public names and central behavior rather than replacing those requirements.
|
||||
|
||||
- [ ] **Step 4: Run the focused test and the module test suite**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-next-compatibility:test --tests 'io.backend.skeleton.jpa.experimental.next.HibernateCompatibilityPolicyTest'
|
||||
./gradlew :modules:jpa-experimental:jpa-next-compatibility:test
|
||||
```
|
||||
|
||||
Expected: PASS with all assertions green.
|
||||
|
||||
- [ ] **Step 5: Commit the independently reviewable change**
|
||||
|
||||
```bash
|
||||
git add 'modules/jpa-experimental/jpa-next-compatibility/src/compatibilityHibernate8/java/io/backend/skeleton/jpa/experimental/next/Hibernate8CompatibilityTest.java' '.github/workflows/jpa-next-hibernate8.yml' 'modules/jpa-experimental/jpa-next-compatibility/build.gradle.kts' 'modules/jpa-experimental/jpa-next-compatibility/src/test/java/io/backend/skeleton/jpa/experimental/next/HibernateCompatibilityPolicyTest.java'
|
||||
git commit -m "test: add hibernate eight compatibility lane"
|
||||
```
|
||||
|
||||
### Task 9: PostgreSQL 19 Compatibility와 Stable 승격 Gate 구현
|
||||
|
||||
**Files:**
|
||||
- Create: `modules/jpa-experimental/jpa-next-compatibility/src/compatibilityPostgresql19/java/io/backend/skeleton/jpa/experimental/next/PostgreSql19CompatibilityTest.java`
|
||||
- Create: `docs/jpa/experimental-support-matrix.md`
|
||||
- Create: `docs/jpa/experimental-promotion-checklist.md`
|
||||
- Create: `.github/workflows/jpa-next-postgresql19.yml`
|
||||
- Modify: `modules/jpa-experimental/jpa-next-compatibility/build.gradle.kts`
|
||||
- Test: `modules/jpa-experimental/jpa-next-compatibility/src/test/java/io/backend/skeleton/jpa/experimental/next/ExperimentalPromotionGateTest.java`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: PG19 image when GA, all Stable contracts, experimental security/failure/migration/performance reports.
|
||||
- Produces: A promotion decision that requires evidence rather than version availability alone.
|
||||
|
||||
**Implementation requirements:**
|
||||
- Run mapping, SQLSTATE, lock, batch, Flyway, plan and native extension contracts on PG19.
|
||||
- Promotion requires two supported patch runs and no unresolved semantic regression.
|
||||
- Multi-tenancy/replica promotion requires tenant leakage, failover, lag and pool-capacity evidence.
|
||||
- Update Stable support matrix only through a reviewed ADR.
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```java
|
||||
package io.backend.skeleton.jpa.experimental.next;
|
||||
|
||||
class ExperimentalPromotionGateTest {
|
||||
@Test
|
||||
void promotionRequiresAllEvidenceAndReviewedAdr() {
|
||||
var evidence = evidence().withCompatibility(true).withSecurity(true).withFailure(true)
|
||||
.withMigration(true).withPerformance(true).withReviewedAdr(false);
|
||||
assertThat(gate.evaluate(evidence)).isEqualTo(BLOCKED_MISSING_ADR);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run the focused test and verify the failure**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-next-compatibility:test --tests 'io.backend.skeleton.jpa.experimental.next.ExperimentalPromotionGateTest'
|
||||
```
|
||||
|
||||
Expected: FAIL because the production type or behavior does not exist yet.
|
||||
|
||||
- [ ] **Step 3: Implement the smallest complete production contract**
|
||||
|
||||
```java
|
||||
package io.backend.skeleton.jpa.experimental.next;
|
||||
|
||||
public final class ExperimentalPromotionGate {
|
||||
public PromotionDecision evaluate(PromotionEvidence evidence) {
|
||||
if (!evidence.allTechnicalGatesPassed()) return BLOCKED_TECHNICAL;
|
||||
if (!evidence.reviewedAdr()) return BLOCKED_MISSING_ADR;
|
||||
return ELIGIBLE_FOR_STABLE_REVIEW;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Implement every file and invariant listed under **Implementation requirements**; the snippet fixes the public names and central behavior rather than replacing those requirements.
|
||||
|
||||
- [ ] **Step 4: Run the focused test and the module test suite**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./gradlew :modules:jpa-experimental:jpa-next-compatibility:test --tests 'io.backend.skeleton.jpa.experimental.next.ExperimentalPromotionGateTest'
|
||||
./gradlew :modules:jpa-experimental:jpa-next-compatibility:test
|
||||
```
|
||||
|
||||
Expected: PASS with all assertions green.
|
||||
|
||||
- [ ] **Step 5: Commit the independently reviewable change**
|
||||
|
||||
```bash
|
||||
git add 'modules/jpa-experimental/jpa-next-compatibility/src/compatibilityPostgresql19/java/io/backend/skeleton/jpa/experimental/next/PostgreSql19CompatibilityTest.java' 'docs/jpa/experimental-support-matrix.md' 'docs/jpa/experimental-promotion-checklist.md' '.github/workflows/jpa-next-postgresql19.yml' 'modules/jpa-experimental/jpa-next-compatibility/build.gradle.kts' 'modules/jpa-experimental/jpa-next-compatibility/src/test/java/io/backend/skeleton/jpa/experimental/next/ExperimentalPromotionGateTest.java'
|
||||
git commit -m "docs: add jpa experimental promotion gates"
|
||||
```
|
||||
## 2. Experimental 완료 조건
|
||||
|
||||
```text
|
||||
Stable starter가 Experimental module에 의존하지 않는다.
|
||||
Tenant context 누락과 connection reuse에서 fail-closed다.
|
||||
RLS runtime role이 policy를 bypass하지 못한다.
|
||||
Schema/database tenant migration과 pool capacity가 bounded다.
|
||||
Replica routing이 read-after-write와 lock query를 primary에 고정한다.
|
||||
JPA4/Hibernate8/PG19 lane이 Stable artifacts를 변경하지 않는다.
|
||||
승격은 ADR와 compatibility/security/failure/migration/performance 증거를 요구한다.
|
||||
```
|
||||
-4716
File diff suppressed because it is too large
Load Diff
-3276
File diff suppressed because it is too large
Load Diff
@@ -1,210 +0,0 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from pathlib import Path
|
||||
import hashlib
|
||||
import re
|
||||
import sys
|
||||
import zipfile
|
||||
|
||||
SCRIPT_DIR = Path(__file__).resolve().parent
|
||||
PACKAGE_DESIGN = SCRIPT_DIR / 'docs/superpowers/specs/2026-08-11-jpa-persistence-platform-design.md'
|
||||
|
||||
if PACKAGE_DESIGN.exists():
|
||||
ROOT = SCRIPT_DIR
|
||||
DESIGN = PACKAGE_DESIGN
|
||||
PLAN = ROOT / 'docs/superpowers/plans/2026-08-11-jpa-persistence-platform-implementation-plan.md'
|
||||
EXPANSION = ROOT / 'docs/superpowers/plans/2026-08-11-jpa-persistence-experimental-expansion-plan.md'
|
||||
VALIDATION = ROOT / 'VALIDATION.md'
|
||||
ZIP_PATH = ROOT.parent / 'jpa-superpowers-package.zip'
|
||||
else:
|
||||
ROOT = Path('/mnt/data')
|
||||
DESIGN = ROOT / 'jpa-persistence-platform-design.md'
|
||||
PLAN = ROOT / 'jpa-persistence-platform-implementation-plan.md'
|
||||
EXPANSION = ROOT / 'jpa-persistence-experimental-expansion-plan.md'
|
||||
VALIDATION = ROOT / 'jpa-superpowers-validation.md'
|
||||
ZIP_PATH = ROOT / 'jpa-superpowers-package.zip'
|
||||
|
||||
checks: list[tuple[str, bool, str]] = []
|
||||
|
||||
def check(name: str, condition: bool, detail: str = '') -> None:
|
||||
checks.append((name, bool(condition), detail))
|
||||
|
||||
|
||||
def sha256(path: Path) -> str:
|
||||
h = hashlib.sha256()
|
||||
with path.open('rb') as f:
|
||||
for chunk in iter(lambda: f.read(1024 * 1024), b''):
|
||||
h.update(chunk)
|
||||
return h.hexdigest()
|
||||
|
||||
|
||||
def task_chunks(text: str) -> list[tuple[int, str]]:
|
||||
matches = list(re.finditer(r'^### Task (\d+):', text, re.MULTILINE))
|
||||
chunks: list[tuple[int, str]] = []
|
||||
for i, match in enumerate(matches):
|
||||
end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
|
||||
chunks.append((int(match.group(1)), text[match.start():end]))
|
||||
return chunks
|
||||
|
||||
for path, label in [(DESIGN, '설계서'), (PLAN, 'Stable 계획서'), (EXPANSION, 'Experimental 계획서')]:
|
||||
check(f'{label} 존재', path.exists(), str(path))
|
||||
|
||||
if not all(path.exists() for path in [DESIGN, PLAN, EXPANSION]):
|
||||
print('missing required documents', file=sys.stderr)
|
||||
sys.exit(2)
|
||||
|
||||
design = DESIGN.read_text(encoding='utf-8')
|
||||
plan = PLAN.read_text(encoding='utf-8')
|
||||
expansion = EXPANSION.read_text(encoding='utf-8')
|
||||
|
||||
line_counts = {
|
||||
'design': len(design.splitlines()),
|
||||
'plan': len(plan.splitlines()),
|
||||
'expansion': len(expansion.splitlines()),
|
||||
}
|
||||
check('설계서 최소 상세도', line_counts['design'] >= 2500, f"{line_counts['design']} lines")
|
||||
check('Stable 계획서 최소 상세도', line_counts['plan'] >= 4000, f"{line_counts['plan']} lines")
|
||||
check('Experimental 계획서 최소 상세도', line_counts['expansion'] >= 650, f"{line_counts['expansion']} lines")
|
||||
|
||||
for text, label in [(design, '설계서'), (plan, 'Stable 계획서'), (expansion, 'Experimental 계획서')]:
|
||||
fences = len(re.findall(r'^```', text, re.MULTILINE))
|
||||
check(f'{label} 코드 fence 균형', fences % 2 == 0, str(fences))
|
||||
bad = re.findall(r'\b(?:TODO|TBD|FIXME|implement later|fill in details)\b', text, re.IGNORECASE)
|
||||
check(f'{label} placeholder 부재', not bad, ', '.join(sorted(set(bad))))
|
||||
|
||||
required_design_terms = [
|
||||
'GenericRepository',
|
||||
'TransactionCompletionUnknownException',
|
||||
'EvidenceAwareJpaTransactionManager',
|
||||
'Application Service',
|
||||
'OSIV',
|
||||
'PostgreSQL 16·17·18',
|
||||
'Hibernate 7.4 Collection Fetch Pagination',
|
||||
'FOR UPDATE SKIP LOCKED',
|
||||
'CREATE INDEX CONCURRENTLY',
|
||||
'Flyway',
|
||||
'Runtime·Migration·Admin',
|
||||
'H2는 Local Convenience',
|
||||
'전체 Transaction Retry',
|
||||
'J1 Standard Persistence',
|
||||
'J4 Admin / Operations',
|
||||
'완료 정의',
|
||||
]
|
||||
for term in required_design_terms:
|
||||
check(f'설계 핵심 계약: {term}', term in design)
|
||||
|
||||
check('GenericRepository 실제 선언 부재',
|
||||
'public interface GenericRepository' not in design + plan and
|
||||
'interface GenericRepository<' not in design + plan)
|
||||
check('운영 ddl auto update 금지', '운영에서 `ddl-auto=update`' in plan)
|
||||
check('Completion Unknown 자동 Retry 금지',
|
||||
'TransactionCompletionUnknownException' in plan and
|
||||
'RetryDecision.reconcile' in plan and
|
||||
'Never retry completion unknown' in plan)
|
||||
check('OSIV false 강제', 'spring.jpa.open-in-view must be false' in plan)
|
||||
check('PG16·17·18 Matrix', 'PG_16' in plan and 'PG_17' in plan and 'PG_18' in plan)
|
||||
check('Hibernate 7.4 fetch pagination gate', 'HibernateCollectionFetchPaginationContractTest' in plan)
|
||||
check('Flyway snapshot upgrade gate', 'FlywayUpgradeContractTest' in plan)
|
||||
check('Runtime role no DDL gate', 'runtimeRoleCanWriteRowsButCannotCreateTable' in plan)
|
||||
check('Stable 계획에 Experimental create 경로 부재', '- Create: `modules/jpa-experimental/' not in plan)
|
||||
|
||||
stable_chunks = task_chunks(plan)
|
||||
exp_chunks = task_chunks(expansion)
|
||||
check('Stable Task 1~53 연속성', [n for n, _ in stable_chunks] == list(range(1, 54)), str([n for n, _ in stable_chunks]))
|
||||
check('Experimental Task 1~9 연속성', [n for n, _ in exp_chunks] == list(range(1, 10)), str([n for n, _ in exp_chunks]))
|
||||
check('Stable Task chunk 수', len(stable_chunks) == 53, str(len(stable_chunks)))
|
||||
check('Experimental Task chunk 수', len(exp_chunks) == 9, str(len(exp_chunks)))
|
||||
|
||||
required_markers = [
|
||||
'**Files:**',
|
||||
'**Interfaces:**',
|
||||
'**Implementation requirements:**',
|
||||
'**Step 1:',
|
||||
'**Step 2:',
|
||||
'**Step 3:',
|
||||
'**Step 4:',
|
||||
'**Step 5:',
|
||||
'Expected:',
|
||||
'git commit -m',
|
||||
]
|
||||
for group_name, chunks in [('Stable', stable_chunks), ('Experimental', exp_chunks)]:
|
||||
for number, chunk in chunks:
|
||||
for marker in required_markers:
|
||||
check(f'{group_name} Task {number} 필수 항목: {marker}', marker in chunk)
|
||||
check(f'{group_name} Task {number} Gradle focused command', './gradlew ' in chunk and '--tests' in chunk)
|
||||
check(f'{group_name} Task {number} exact path', '*' not in '\n'.join(
|
||||
line for line in chunk.splitlines() if line.startswith(('- Create:', '- Modify:', '- Test:'))))
|
||||
|
||||
create_pattern = re.compile(r'^- Create: `([^`]+)`', re.MULTILINE)
|
||||
stable_creates = create_pattern.findall(plan)
|
||||
exp_creates = create_pattern.findall(expansion)
|
||||
check('Stable Create 경로 중복 부재', len(stable_creates) == len(set(stable_creates)), str(len(stable_creates)))
|
||||
check('Experimental Create 경로 중복 부재', len(exp_creates) == len(set(exp_creates)), str(len(exp_creates)))
|
||||
check('Stable·Experimental Create 경로 충돌 부재', not (set(stable_creates) & set(exp_creates)), str(set(stable_creates) & set(exp_creates)))
|
||||
check('Experimental 계획은 Stable Task 1~53 이후 시작', 'Stable 계획 Task 1~53이 완료되고' in expansion, '')
|
||||
|
||||
# Type/name consistency checks for high-risk cross-task contracts.
|
||||
for term in [
|
||||
'PersistenceOperationName',
|
||||
'TransactionProfile',
|
||||
'RetryProfile',
|
||||
'JpaTransactionExecutor',
|
||||
'JpaRetryPolicy',
|
||||
'RetryDecision',
|
||||
'JpaFailureContext',
|
||||
'QueryName',
|
||||
'KeysetPageRequest',
|
||||
'KeysetSlice',
|
||||
'TransactionCompletionUnknownException',
|
||||
'PostgreSqlWorkClaimExecutor',
|
||||
'FlywayValidationGate',
|
||||
'JpaPlatformEndpoint',
|
||||
]:
|
||||
check(f'공통 타입 일관성: {term}', plan.count(term) >= 2, str(plan.count(term)))
|
||||
|
||||
check('Experimental Gradle 경로 정확성', ':modules:jpa-experimental:' in expansion)
|
||||
check('Replica annotation-only routing 금지', 'readOnly=true`만으로 replica routing하지 않는다' in expansion)
|
||||
check('RLS connection reuse 검증', 'pooledConnectionDoesNotLeakPriorTenantSetting' in expansion)
|
||||
check('Stable 승격 ADR gate', 'BLOCKED_MISSING_ADR' in expansion)
|
||||
|
||||
# Source preservation check.
|
||||
check('심층 리서치 원문 부록 포함', '# 부록 A. 심층 리서치 원문 보존본' in design and '# JPA 관계형 영속성 플랫폼 심층 리서치' in design)
|
||||
|
||||
passed = sum(1 for _, ok, _ in checks if ok)
|
||||
failed = len(checks) - passed
|
||||
status = 'PASS' if failed == 0 else 'FAIL'
|
||||
|
||||
lines = [
|
||||
'# JPA Superpowers 문서 정적 검증',
|
||||
'',
|
||||
f'- 결과: **{status}**',
|
||||
f'- 실행 검사: **{len(checks)}개**',
|
||||
f'- 통과: **{passed}개**',
|
||||
f'- 실패: **{failed}개**',
|
||||
f'- 설계서: **{line_counts["design"]:,}행**',
|
||||
f'- Stable 구현 계획서: **{line_counts["plan"]:,}행**',
|
||||
f'- Experimental 확장 계획서: **{line_counts["expansion"]:,}행**',
|
||||
f'- Stable Task: **{len(stable_chunks)}개**',
|
||||
f'- Experimental Task: **{len(exp_chunks)}개**',
|
||||
f'- Stable Create 경로: **{len(stable_creates)}개**',
|
||||
f'- Experimental Create 경로: **{len(exp_creates)}개**',
|
||||
f'- 설계 SHA-256: `{sha256(DESIGN)}`',
|
||||
f'- Stable 계획 SHA-256: `{sha256(PLAN)}`',
|
||||
f'- Experimental 계획 SHA-256: `{sha256(EXPANSION)}`',
|
||||
'',
|
||||
'## 검사 결과',
|
||||
'',
|
||||
'| 검사 | 결과 | 상세 |',
|
||||
'|---|---:|---|',
|
||||
]
|
||||
for name, ok, detail in checks:
|
||||
safe_detail = detail.replace('|', '\\|').replace('\n', ' ')[:500]
|
||||
lines.append(f'| {name} | {"PASS" if ok else "FAIL"} | {safe_detail} |')
|
||||
|
||||
VALIDATION.write_text('\n'.join(lines) + '\n', encoding='utf-8')
|
||||
print(f'{status}: {passed}/{len(checks)} checks passed')
|
||||
if failed:
|
||||
for name, ok, detail in checks:
|
||||
if not ok:
|
||||
print(f'FAIL: {name}: {detail}')
|
||||
sys.exit(1)
|
||||
@@ -1,5 +0,0 @@
|
||||
e0703a77df8aac482823491d4f6ee43af1eace6287444a6006adb1e4f268e15c docs/superpowers/specs/2026-08-10-messaging-platform-design.md
|
||||
4ad5d445f74bede368c75d482fd2adcf61ff1c2dbe93f918a4719bb1de1f7eee docs/superpowers/plans/2026-08-10-messaging-platform-implementation-plan.md
|
||||
f1f8289d07a8f70c0b113349c4e14671b049c14f25d7e28f28ac71b4677960bd VALIDATION.md
|
||||
3fc835294e07588cf0c854a6182e3d2fc02903aca29eae5f6f951a58524b81eb validate_messaging_docs.py
|
||||
592a7cebd442da3bbc7cf822a7bacc492c412b9b84f82ea90c0d867a12f03b90 README.md
|
||||
@@ -1,164 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
import sys
|
||||
from collections import Counter
|
||||
from pathlib import Path
|
||||
|
||||
DESIGN = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("messaging-platform-design.md")
|
||||
PLAN = Path(sys.argv[2]) if len(sys.argv) > 2 else Path("messaging-platform-implementation-plan.md")
|
||||
|
||||
errors: list[str] = []
|
||||
checks: list[str] = []
|
||||
|
||||
|
||||
def require(condition: bool, message: str) -> None:
|
||||
if condition:
|
||||
checks.append(message)
|
||||
else:
|
||||
errors.append(message)
|
||||
|
||||
|
||||
def balanced_fences(text: str) -> bool:
|
||||
return len(re.findall(r"^```", text, re.MULTILINE)) % 2 == 0
|
||||
|
||||
|
||||
def line_count(text: str) -> int:
|
||||
return len(text.splitlines())
|
||||
|
||||
|
||||
design = DESIGN.read_text(encoding="utf-8")
|
||||
plan = PLAN.read_text(encoding="utf-8")
|
||||
|
||||
require(line_count(design) >= 2_000, "설계서가 2,000행 이상이다")
|
||||
require(line_count(plan) >= 4_000, "구현 계획서가 4,000행 이상이다")
|
||||
require(balanced_fences(design), "설계서 Markdown 코드 블록이 균형을 이룬다")
|
||||
require(balanced_fences(plan), "계획서 Markdown 코드 블록이 균형을 이룬다")
|
||||
|
||||
placeholder_patterns = {
|
||||
"unresolved todo marker": r"\bT[O]DO\b",
|
||||
"unresolved tbd marker": r"\bT[B]D\b",
|
||||
"unresolved fix marker": r"\bF[I]XME\b",
|
||||
"placeholder ADR number": r"ADR-X{2,}",
|
||||
"wildcard build path": r"modules/messaging/\*/build\.gradle\.kts",
|
||||
"deferred implementation phrase": r"implement\s+later|fill\s+in\s+details|similar\s+to\s+Task",
|
||||
}
|
||||
for name, pattern in placeholder_patterns.items():
|
||||
require(not re.search(pattern, design, re.IGNORECASE), f"설계서에 {name}가 없다")
|
||||
require(not re.search(pattern, plan, re.IGNORECASE), f"계획서에 {name}가 없다")
|
||||
|
||||
required_design_terms = [
|
||||
"M1 Typed Messaging API",
|
||||
"M2 Advanced API",
|
||||
"M3 Native Capability",
|
||||
"M4 Admin Plane",
|
||||
"PublishCompletion",
|
||||
"AMBIGUOUS",
|
||||
"MessageEnvelope",
|
||||
"DeliveryGuarantee",
|
||||
"OrderingScope",
|
||||
"Retry Policy Engine",
|
||||
"DLQ·Parking·Redrive",
|
||||
"Kafka Stable Adapter",
|
||||
"RabbitMQ Stable Adapter",
|
||||
"Transactional Outbox",
|
||||
"Inbox와 Idempotent Consumer",
|
||||
"Claim Check",
|
||||
"Pulsar Experimental Adapter",
|
||||
"NATS JetStream Experimental Adapter",
|
||||
"Spring Cloud Stream Bridge",
|
||||
"Security",
|
||||
"Observability",
|
||||
"호환성 인증 매트릭스",
|
||||
"비지원 범위",
|
||||
"완료 정의",
|
||||
]
|
||||
for term in required_design_terms:
|
||||
require(term in design, f"설계서가 필수 항목 '{term}'을 포함한다")
|
||||
|
||||
require("AT_MOST_ONCE,\n AT_LEAST_ONCE" in design, "공통 DeliveryGuarantee가 두 가지 보장만 선언한다")
|
||||
delivery_match = re.search(r"public enum DeliveryGuarantee \{(?P<body>.*?)\n\}", design, re.DOTALL)
|
||||
ordering_match = re.search(r"public enum OrderingScope \{(?P<body>.*?)\n\}", design, re.DOTALL)
|
||||
require(delivery_match is not None and "EXACTLY_ONCE" not in delivery_match.group("body"), "공통 DeliveryGuarantee enum에 EXACTLY_ONCE를 선언하지 않는다")
|
||||
require(ordering_match is not None and "GLOBAL" not in ordering_match.group("body"), "공통 OrderingScope enum에 GLOBAL을 선언하지 않는다")
|
||||
require("DLQ broker confirmation 확인\n→ source settlement" in design, "DLQ confirm 후 source settlement 순서를 명시한다")
|
||||
require("같은 `messageId`" in design, "retry와 reliability에서 동일 message ID를 유지한다")
|
||||
|
||||
# Plan task structure.
|
||||
task_numbers = [int(value) for value in re.findall(r"^### Task (\d+):", plan, re.MULTILINE)]
|
||||
require(task_numbers == list(range(1, 45)), "Task 번호가 1부터 44까지 연속이다")
|
||||
|
||||
for task_number in task_numbers:
|
||||
start = plan.index(f"### Task {task_number}:")
|
||||
end = (
|
||||
plan.index(f"### Task {task_number + 1}:", start)
|
||||
if task_number < 44
|
||||
else plan.index("## 3. Plan Self-Review Checklist", start)
|
||||
)
|
||||
section = plan[start:end]
|
||||
for required in (
|
||||
"**Files:**",
|
||||
"**Interfaces:**",
|
||||
"Step 1",
|
||||
"Step 2",
|
||||
"Step 3",
|
||||
"Step 4",
|
||||
"Step 5",
|
||||
"git commit -m",
|
||||
):
|
||||
require(required in section, f"Task {task_number}가 '{required}'을 포함한다")
|
||||
|
||||
create_paths = re.findall(r"^- Create: `([^`]+)`", plan, re.MULTILINE)
|
||||
duplicates = [path for path, count in Counter(create_paths).items() if count > 1]
|
||||
require(not duplicates, "중복된 Create 파일 경로가 없다")
|
||||
require(all("*" not in path for path in create_paths), "Create 파일 경로에 wildcard가 없다")
|
||||
|
||||
required_plan_terms = [
|
||||
"Kafka Producer Adapter와 Publish Evidence",
|
||||
"Kafka Consumer Group, Partition Coordinator",
|
||||
"Kafka Native Transaction Capability",
|
||||
"Kafka Share Group Experimental Adapter",
|
||||
"Rabbit Publisher Confirm·Return Evidence Adapter",
|
||||
"Rabbit Consumer Manual ACK",
|
||||
"Transactional Outbox Repository",
|
||||
"Inbox Transactional Idempotent Consumer",
|
||||
"Debezium Outbox Event Router",
|
||||
"Pulsar Experimental Adapter",
|
||||
"NATS JetStream Experimental Adapter",
|
||||
"Spring Cloud Stream Optional Bridge",
|
||||
"Global Backpressure",
|
||||
"Cross-broker 장애·보안·Reliability Contract Suite",
|
||||
"성능 인증, Compatibility Matrix",
|
||||
"지원 문서, Runbook, ADR, Release Gate",
|
||||
]
|
||||
for term in required_plan_terms:
|
||||
require(term in plan, f"계획서가 필수 작업 '{term}'을 포함한다")
|
||||
|
||||
require("messageId`를 유지" in plan or "message ID를 유지" in plan, "계획서가 message identity 보존을 명시한다")
|
||||
require("source를 ACK하지 않는다" in plan or "source ACK하지 않는다" in plan, "계획서가 DLQ 실패 시 source ACK 금지를 명시한다")
|
||||
require("producer, consumer, admin credential" in plan, "계획서가 credential 분리를 명시한다")
|
||||
require("messagingStableChaos" in plan, "Stable chaos aggregate task가 계획에 존재한다")
|
||||
require("messagingPerformance" in plan, "performance aggregate task가 계획에 존재한다")
|
||||
require("messagingCompatibility" in plan, "compatibility aggregate task가 계획에 존재한다")
|
||||
|
||||
print("# Messaging Superpowers 문서 정적 검증")
|
||||
print()
|
||||
print(f"- 설계서: `{DESIGN}` — {line_count(design):,}행, {len(design.encode('utf-8')):,} bytes")
|
||||
print(f"- 계획서: `{PLAN}` — {line_count(plan):,}행, {len(plan.encode('utf-8')):,} bytes")
|
||||
print(f"- Task 수: {len(task_numbers)}")
|
||||
print(f"- Create 경로 수: {len(create_paths)}")
|
||||
print(f"- 검증 항목 수: {len(checks) + len(errors)}")
|
||||
print()
|
||||
|
||||
if errors:
|
||||
print("## 결과: FAIL")
|
||||
print()
|
||||
for error in errors:
|
||||
print(f"- FAIL: {error}")
|
||||
sys.exit(1)
|
||||
|
||||
print("## 결과: PASS")
|
||||
print()
|
||||
for check in checks:
|
||||
print(f"- PASS: {check}")
|
||||
@@ -1,6 +0,0 @@
|
||||
a6588890cf1eed348dc6d679515d0a403839416945a40fac1369963f7ee58167 docs/superpowers/specs/2026-08-11-mongodb-document-persistence-platform-design.md
|
||||
d2897d321ed6868e46f02f5e5d327425a48ff285b532d10923323477a395d6de docs/superpowers/plans/2026-08-11-mongodb-document-persistence-platform-implementation-plan.md
|
||||
f677e44fcf138b38154c27230d6322d4c18919f5960fc30c07f03cea40758acd docs/superpowers/plans/2026-08-11-mongodb-advanced-capabilities-expansion-plan.md
|
||||
e8fa3d09372956ad65a1984c2fd3b4d30c34896593a34bc40eb5d147cbc593a8 README.md
|
||||
d196c4e4c1510273e29f9f7267ab74bce32f3da59a40a3d6f1615b9c32428745 VALIDATION.md
|
||||
a5e807fd4416a718818729ea37222cdf104c58962cac5154e1e5976011b03f12 validate_mongodb_docs.py
|
||||
@@ -1,73 +0,0 @@
|
||||
from pathlib import Path
|
||||
import re
|
||||
import sys
|
||||
|
||||
ROOT = Path(__file__).resolve().parent
|
||||
DESIGN = ROOT / 'docs/superpowers/specs/2026-08-11-mongodb-document-persistence-platform-design.md'
|
||||
PLAN = ROOT / 'docs/superpowers/plans/2026-08-11-mongodb-document-persistence-platform-implementation-plan.md'
|
||||
ADV = ROOT / 'docs/superpowers/plans/2026-08-11-mongodb-advanced-capabilities-expansion-plan.md'
|
||||
|
||||
checks = []
|
||||
|
||||
def check(name, condition, detail=''):
|
||||
checks.append((name, bool(condition), detail))
|
||||
|
||||
texts = {p.name: p.read_text(encoding='utf-8') for p in (DESIGN, PLAN, ADV)}
|
||||
design = texts[DESIGN.name]
|
||||
plan = texts[PLAN.name]
|
||||
adv = texts[ADV.name]
|
||||
|
||||
check('design exists', DESIGN.exists())
|
||||
check('stable plan exists', PLAN.exists())
|
||||
check('advanced plan exists', ADV.exists())
|
||||
check('design purpose', 'MongoDB 문서 영속성 플랫폼 설계서' in design)
|
||||
check('domain ownership', '도메인이 `@Document`, Repository' in design)
|
||||
check('no generic repository design', '범용 `CommonMongoRepository<T, ID>`를 만들지 않는다' in design)
|
||||
check('stable api strict', 'Stable API V1' in design and 'apiStrict=true' in design)
|
||||
check('local replica set', 'Single-node Replica Set' in design)
|
||||
check('standalone smoke only', 'Standalone은 smoke test' in design)
|
||||
check('bson manifest', 'BSON 표현 Manifest' in design)
|
||||
check('transaction retry separation', 'Transaction 본문 Retry와 Commit Retry를 분리' in design)
|
||||
check('change stream at least once', 'at-least-once projector' in design)
|
||||
check('ttl cleanup only', 'TTL은 물리 cleanup' in design)
|
||||
check('gridfs compatibility only', 'GridFS는 compatibility adapter' in design)
|
||||
check('driver native observability', 'Driver native ObservabilitySettings' in design)
|
||||
|
||||
for label, text, expected in [('stable', plan, 50), ('advanced', adv, 15)]:
|
||||
nums = [int(x) for x in re.findall(r'^### Task (\d+):', text, re.M)]
|
||||
check(f'{label} task count', len(nums) == expected, f'{len(nums)}')
|
||||
check(f'{label} task sequence', nums == list(range(1, expected + 1)), str(nums[:3]) + '...' + str(nums[-3:]))
|
||||
sections = re.split(r'(?=^### Task \d+:)', text, flags=re.M)[1:]
|
||||
for idx, section in enumerate(sections, 1):
|
||||
for marker in ['**Files:**', '**Interfaces:**', '**Implementation requirements:**',
|
||||
'**Step 1:', '**Step 2:', '**Step 3:', '**Step 4:', '**Step 5:']:
|
||||
check(f'{label} task {idx} has {marker}', marker in section)
|
||||
check(f'{label} task {idx} has commit', 'git commit -m' in section)
|
||||
check(f'{label} task {idx} has expected result', 'Expected:' in section)
|
||||
|
||||
for name, text in texts.items():
|
||||
check(f'{name} code fences balanced', text.count('```') % 2 == 0, str(text.count('```')))
|
||||
check(f'{name} no TODO markers', not re.search(r'\b(TODO|TBD|FIXME)\b', text))
|
||||
check(f'{name} no wildcard create paths', not re.search(r'- Create: `[^`]*[\*?][^`]*`', text))
|
||||
|
||||
for label, text in [('stable', plan), ('advanced', adv)]:
|
||||
created = re.findall(r'- Create: `([^`]+)`', text)
|
||||
duplicates = sorted({p for p in created if created.count(p) > 1})
|
||||
check(f'{label} no duplicate create paths', not duplicates, ', '.join(duplicates))
|
||||
|
||||
stable_created = set(re.findall(r'- Create: `([^`]+)`', plan))
|
||||
advanced_created = set(re.findall(r'- Create: `([^`]+)`', adv))
|
||||
check('stable and advanced create paths do not collide', not (stable_created & advanced_created),
|
||||
', '.join(sorted(stable_created & advanced_created)))
|
||||
check('no real generic repository declaration', not re.search(r'public\s+interface\s+(Common|Generic)MongoRepository', design + plan + adv))
|
||||
check('no public arbitrary run command', not re.search(r'public\s+[^\n]+\s+runCommand\s*\(', design + plan + adv))
|
||||
check('stable starter excludes advanced', 'no advanced module' in plan.lower() and 'Stable Starter' in adv)
|
||||
check('unknown commit body retry forbidden', 'UnknownTransactionCommitResult' in plan and '업무 본문을 재실행하지 않는다' in plan)
|
||||
check('mongo seven and eight matrix', 'MongoDB 7.0' in plan and 'MongoDB 8.0' in plan)
|
||||
check('advanced actual topology gate', 'actual topology' in adv.lower() or '실제 topology' in adv)
|
||||
|
||||
failed = [c for c in checks if not c[1]]
|
||||
for name, ok, detail in checks:
|
||||
print(('PASS' if ok else 'FAIL') + ' | ' + name + ((' | ' + detail) if detail else ''))
|
||||
print(f'SUMMARY | total={len(checks)} pass={len(checks)-len(failed)} fail={len(failed)}')
|
||||
sys.exit(1 if failed else 0)
|
||||
@@ -1,5 +0,0 @@
|
||||
20a39913d84b179fb407811af4ee23bbcad8eebadff893add530cab97fa90878 ./README.md
|
||||
b84784d8321ea826af7c9788693008fccd4f2bf437816d2d47a515caac098f04 ./VALIDATION.md
|
||||
176b0c86e11e6d4d8440285dd723e5555616ff9a69a7a9419250c2ce2b67f565 ./docs/superpowers/plans/2026-08-10-notification-platform-implementation-plan.md
|
||||
fe7b57c6573ef7305033fe9402333d3c10f7a03ccf421dce5f353e2616ac8677 ./docs/superpowers/specs/2026-08-10-notification-platform-design.md
|
||||
2109766403adf001bb1dcbfe8679d362557f71433532336ff72b90976f3cfe10 ./validate_notification_docs.py
|
||||
@@ -1,188 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
from __future__ import annotations
|
||||
|
||||
from collections import Counter
|
||||
from pathlib import Path
|
||||
import hashlib
|
||||
import re
|
||||
import sys
|
||||
import zipfile
|
||||
|
||||
ROOT = Path('/mnt/data')
|
||||
DESIGN = ROOT / 'notification-platform-design.md'
|
||||
PLAN = ROOT / 'notification-platform-implementation-plan.md'
|
||||
REPORT = ROOT / 'notification-superpowers-validation.md'
|
||||
PACKAGE = ROOT / 'notification-superpowers-package.zip'
|
||||
|
||||
checks: list[tuple[str, bool, str]] = []
|
||||
|
||||
def check(name: str, condition: bool, detail: str = '') -> None:
|
||||
checks.append((name, bool(condition), detail))
|
||||
|
||||
|
||||
def sha256(path: Path) -> str:
|
||||
digest = hashlib.sha256()
|
||||
with path.open('rb') as stream:
|
||||
for chunk in iter(lambda: stream.read(1024 * 1024), b''):
|
||||
digest.update(chunk)
|
||||
return digest.hexdigest()
|
||||
|
||||
|
||||
def main() -> int:
|
||||
check('설계서 존재', DESIGN.is_file(), str(DESIGN))
|
||||
check('구현 계획서 존재', PLAN.is_file(), str(PLAN))
|
||||
if not DESIGN.is_file() or not PLAN.is_file():
|
||||
return write_report()
|
||||
|
||||
design = DESIGN.read_text(encoding='utf-8')
|
||||
plan = PLAN.read_text(encoding='utf-8')
|
||||
design_lines = design.count('\n') + 1
|
||||
plan_lines = plan.count('\n') + 1
|
||||
|
||||
check('설계서 최소 상세도', design_lines >= 3000, f'{design_lines:,} lines')
|
||||
check('계획서 최소 상세도', plan_lines >= 4000, f'{plan_lines:,} lines')
|
||||
check('설계서 코드 fence 균형', design.count('```') % 2 == 0, str(design.count('```')))
|
||||
check('계획서 코드 fence 균형', plan.count('```') % 2 == 0, str(plan.count('```')))
|
||||
|
||||
required_design_terms = [
|
||||
'NotificationRequest', 'RecipientDelivery', 'DeliveryAttempt',
|
||||
'ProviderEvent', 'EvidenceLevel', 'SubmissionOutcome', 'DeliveryOutcome',
|
||||
'AMBIGUOUS', 'append-only', 'FCM_FID', 'FCM_REGISTRATION_TOKEN_LEGACY',
|
||||
'AES-256-GCM', 'HMAC-SHA-256', 'FOR UPDATE SKIP LOCKED',
|
||||
'SMTP Adapter', 'Amazon SES Adapter', 'Twilio Adapter', 'FCM Adapter',
|
||||
'APNs Adapter', 'Web Push Adapter', 'In-App Inbox', 'Reconciliation',
|
||||
'N4 Admin Plane', '비지원 범위', '완료 정의'
|
||||
]
|
||||
for term in required_design_terms:
|
||||
check(f'설계 핵심 계약: {term}', term in design)
|
||||
|
||||
check('exactlyOnce 단순 옵션 금지 명시',
|
||||
'`exactlyOnce=true` 같은 단순 옵션을 두는 것은 잘못된 추상화' in design)
|
||||
forbidden_design_claims = [
|
||||
'guaranteedDelivery=true',
|
||||
'APNs HTTP 200 = DELIVERED',
|
||||
'FCM send success = DEVICE_DELIVERED',
|
||||
]
|
||||
for phrase in forbidden_design_claims:
|
||||
check(f'금지 보장 부재: {phrase}', phrase not in design)
|
||||
|
||||
tasks = [int(x) for x in re.findall(r'^### Task (\d+):', plan, re.MULTILINE)]
|
||||
check('Task 1~50 연속성', tasks == list(range(1, 51)), str(tasks))
|
||||
|
||||
task_chunks = re.split(r'(?=^### Task \d+:)', plan, flags=re.MULTILINE)[1:]
|
||||
check('Task chunk 수', len(task_chunks) == 50, str(len(task_chunks)))
|
||||
required_task_sections = [
|
||||
'**Files:**', '**Interfaces:**', '**Implementation requirements:**',
|
||||
'**Step 1:', '**Step 2:', '**Step 3:', '**Step 4:', '**Step 5:',
|
||||
'Expected:', 'git commit -m'
|
||||
]
|
||||
for index, chunk in enumerate(task_chunks, 1):
|
||||
for marker in required_task_sections:
|
||||
check(f'Task {index} 필수 항목: {marker}', marker in chunk)
|
||||
|
||||
creates = re.findall(r'^- Create: `([^`]+)`', plan, re.MULTILINE)
|
||||
duplicate_creates = sorted(path for path, count in Counter(creates).items() if count > 1)
|
||||
check('Create 경로 중복 없음', not duplicate_creates, ', '.join(duplicate_creates))
|
||||
check('Create 경로 충분성', len(creates) >= 200, str(len(creates)))
|
||||
|
||||
red_flags = {
|
||||
'TODO': r'\bTODO\b',
|
||||
'TBD': r'\bTBD\b',
|
||||
'FIXME': r'\bFIXME\b',
|
||||
'fill in details': r'fill in details',
|
||||
'implement later': r'implement later',
|
||||
'concrete assertion below': r'concrete assertion below',
|
||||
'유사 작업 참조': r'Similar to Task',
|
||||
}
|
||||
for label, pattern in red_flags.items():
|
||||
matches = re.findall(pattern, plan, re.IGNORECASE)
|
||||
check(f'미확정 표현 없음: {label}', not matches, str(len(matches)))
|
||||
|
||||
key_plan_terms = [
|
||||
'providerAcceptanceIsNotDelivery',
|
||||
'concurrentSameRequestReturnsOneNotificationId',
|
||||
'providerAcceptsThenResponseIsLostRecordsAmbiguousAndBlocksFallback',
|
||||
'deliveredBeforeSentNeverDowngrades',
|
||||
'fcmInstallationAndLegacyTokenAreDifferentTypes',
|
||||
'http200IsProviderAcceptedNotDelivered',
|
||||
'ttlHeaderIsRequiredAndAcceptanceIsNotDelivery',
|
||||
'websocketFailureDoesNotRollbackInboxItem',
|
||||
'metricTagsNeverContainHighCardinalityIdentifiers',
|
||||
'acceptedThenResponseLossIsAmbiguousForEveryApplicableAdapter',
|
||||
'notificationPerformanceTest',
|
||||
]
|
||||
for term in key_plan_terms:
|
||||
check(f'계획 핵심 회귀 테스트: {term}', term in plan)
|
||||
|
||||
check('설계·계획 날짜 일치', '2026-08-10' in design and '2026-08-10' in plan)
|
||||
check('Java 21 가정 명시', 'Java 21' in design and 'Java 21' in plan)
|
||||
check('실제 저장소 부재 가정 명시', '실제 저장소가 제공되지 않아' in design)
|
||||
check('Provider SDK 공개 금지', 'Provider SDK' in design and 'raw SDK client' in plan)
|
||||
check('Core async CompletionStage', 'CompletionStage' in design and 'CompletionStage' in plan)
|
||||
check('FCM FID 우선', 'FID 우선' in design and 'FCM primary target은 FID' in plan)
|
||||
check('Ambiguous fallback 금지', 'ambiguousAttemptExists = true' in design and '`AMBIGUOUS` attempt가 있는 recipient' in plan)
|
||||
check('ProviderEvent 원장', 'append-only ledger' in plan and 'ProviderEvent 원장' in design)
|
||||
|
||||
if PACKAGE.is_file():
|
||||
try:
|
||||
with zipfile.ZipFile(PACKAGE) as archive:
|
||||
bad = archive.testzip()
|
||||
names = set(archive.namelist())
|
||||
required = {
|
||||
'notification-superpowers-package/docs/superpowers/specs/2026-08-10-notification-platform-design.md',
|
||||
'notification-superpowers-package/docs/superpowers/plans/2026-08-10-notification-platform-implementation-plan.md',
|
||||
'notification-superpowers-package/README.md',
|
||||
'notification-superpowers-package/VALIDATION.md',
|
||||
'notification-superpowers-package/validate_notification_docs.py',
|
||||
'notification-superpowers-package/MANIFEST.sha256',
|
||||
}
|
||||
check('ZIP CRC 무결성', bad is None, str(bad))
|
||||
check('ZIP 필수 파일', required.issubset(names), str(sorted(required - names)))
|
||||
except zipfile.BadZipFile as exc:
|
||||
check('ZIP 열기', False, str(exc))
|
||||
else:
|
||||
check('ZIP 패키지 존재', False, str(PACKAGE))
|
||||
|
||||
return write_report(design_lines, plan_lines, len(creates))
|
||||
|
||||
|
||||
def write_report(design_lines: int = 0, plan_lines: int = 0, create_count: int = 0) -> int:
|
||||
passed = sum(1 for _, ok, _ in checks if ok)
|
||||
failed = [(name, detail) for name, ok, detail in checks if not ok]
|
||||
status = 'PASS' if not failed else 'FAIL'
|
||||
rows = [
|
||||
'# Notification Superpowers 문서 정적 검증', '',
|
||||
f'- 결과: **{status}**',
|
||||
f'- 실행 검사: **{len(checks)}개**',
|
||||
f'- 통과: **{passed}개**',
|
||||
f'- 실패: **{len(failed)}개**',
|
||||
f'- 설계서: **{design_lines:,}행**',
|
||||
f'- 구현 계획서: **{plan_lines:,}행**',
|
||||
f'- 구현 Task: **50개**',
|
||||
f'- Create 경로: **{create_count:,}개**',
|
||||
f'- 설계 SHA-256: `{sha256(DESIGN) if DESIGN.exists() else "missing"}`',
|
||||
f'- 계획 SHA-256: `{sha256(PLAN) if PLAN.exists() else "missing"}`',
|
||||
'', '## 검사 결과', '',
|
||||
'| 검사 | 결과 | 상세 |', '|---|---:|---|'
|
||||
]
|
||||
for name, ok, detail in checks:
|
||||
safe = detail.replace('|', '\\|').replace('\n', ' ')[:500]
|
||||
rows.append(f'| {name} | {"PASS" if ok else "FAIL"} | {safe} |')
|
||||
rows.extend(['', '## 검증 범위', '',
|
||||
'- 이 검증은 Markdown 설계서와 구현 계획서의 구조·정합성·필수 계약·경로 중복·미확정 표현·패키지 CRC를 검사한다.',
|
||||
'- 실제 Backend Skeleton 저장소가 입력되지 않았으므로 Gradle compile, Provider sandbox, PostgreSQL integration, chaos, performance test 실행 결과는 포함하지 않는다.',
|
||||
'- 구현 시에는 계획의 각 Task가 지정한 red-green TDD 명령을 실제 저장소에서 실행해야 한다.',
|
||||
])
|
||||
if failed:
|
||||
rows.extend(['', '## 실패 항목', ''])
|
||||
rows.extend(f'- **{name}**: {detail}' for name, detail in failed)
|
||||
REPORT.write_text('\n'.join(rows) + '\n', encoding='utf-8')
|
||||
print(f'{status}: {passed}/{len(checks)} checks passed')
|
||||
if failed:
|
||||
for name, detail in failed:
|
||||
print(f'FAIL: {name}: {detail}', file=sys.stderr)
|
||||
return 1
|
||||
return 0
|
||||
|
||||
if __name__ == '__main__':
|
||||
raise SystemExit(main())
|
||||
-2233
File diff suppressed because it is too large
Load Diff
-1497
File diff suppressed because it is too large
Load Diff
Executable
+574
@@ -0,0 +1,574 @@
|
||||
#!/usr/bin/env bash
|
||||
# The dynamic half of the Compose contract: the lanes actually run.
|
||||
#
|
||||
# One entry point, because the order below is what makes a lane's result mean anything and every
|
||||
# step in it exists because skipping it produced a false green somewhere:
|
||||
#
|
||||
# 1. a unique project and a fresh evidence directory, so two runs cannot read each other's results
|
||||
# and a stale directory cannot be mistaken for this run's;
|
||||
# 2. the static contract, then `config`, then `create` — a stack that cannot render has no partial
|
||||
# failure mode, and finding that out after `up` costs a teardown;
|
||||
# 3. `up --wait` for long-running services only, then health and the resolved activation report,
|
||||
# which is the application's answer rather than the flags this script passed in;
|
||||
# 4. every one-shot the lane declares, each of which must exit zero — a missing or skipped
|
||||
# required client is a lane failure, not a lane that had nothing to check;
|
||||
# 5. sanitized evidence;
|
||||
# 6. teardown scoped to this project alone, on success and failure alike, after the logs are
|
||||
# collected rather than before.
|
||||
#
|
||||
# CI calls this script. Inlining a subset of these commands into a workflow is how a lane ends up
|
||||
# running without its one-shots and reporting green.
|
||||
set -euo pipefail
|
||||
|
||||
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
CONTRACTS="${REPO_ROOT}/src/config/runtime/compose-profile-contracts.json"
|
||||
EVIDENCE_ROOT="${REPO_ROOT}/src/app-bootstrap/build/evidence/runtime-smoke"
|
||||
RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$$"
|
||||
# Compose project names accept lowercase alphanumerics, hyphens and underscores only, so the run id
|
||||
# is lowercased for the project while the evidence directory keeps the readable timestamp.
|
||||
PROJECT_RUN_ID="$(tr '[:upper:]' '[:lower:]' <<<"${RUN_ID}")"
|
||||
|
||||
MODE=""
|
||||
SELECTED_LANE=""
|
||||
usage() {
|
||||
cat >&2 <<'USAGE'
|
||||
usage:
|
||||
run-compose-runtime-smoke.sh --matrix <contracts.json> run every blocking lane, zero-skip
|
||||
run-compose-runtime-smoke.sh --lane <id> reproduce one lane; not a matrix run
|
||||
|
||||
--lane exists to reproduce a failure, and a green single lane is not evidence that the matrix
|
||||
passes. Only --matrix is.
|
||||
USAGE
|
||||
exit 64
|
||||
}
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--matrix) MODE="matrix"; CONTRACTS="$2"; shift 2 ;;
|
||||
--lane) MODE="lane"; SELECTED_LANE="$2"; shift 2 ;;
|
||||
*) usage ;;
|
||||
esac
|
||||
done
|
||||
[[ -n "${MODE}" ]] || usage
|
||||
|
||||
for tool in jq docker; do
|
||||
command -v "${tool}" >/dev/null 2>&1 || { echo "${tool} is required" >&2; exit 78; }
|
||||
done
|
||||
[[ -r "${CONTRACTS}" ]] || { echo "missing ${CONTRACTS}" >&2; exit 78; }
|
||||
|
||||
# ---- per-lane state, cleaned up by the trap ---------------------------------
|
||||
PROJECT=""
|
||||
LANE_TMP=""
|
||||
LANE_EVIDENCE=""
|
||||
LANE_ARGS=()
|
||||
|
||||
cleanup_lane() {
|
||||
local status=$?
|
||||
if [[ -n "${PROJECT}" ]]; then
|
||||
# Logs first. A teardown that runs before the logs are collected destroys the only description
|
||||
# of why the lane failed.
|
||||
if [[ -n "${LANE_EVIDENCE}" ]]; then
|
||||
docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" logs --no-color >"${LANE_EVIDENCE}/compose.log" 2>&1 || true
|
||||
docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" ps --format json >"${LANE_EVIDENCE}/containers.json" 2>&1 || true
|
||||
redact_in_place "${LANE_EVIDENCE}/compose.log"
|
||||
# The warning summary belongs here, after the log it summarises exists.
|
||||
#
|
||||
# It used to run at the end of run_lane, which is before this trap collects compose.log — so it
|
||||
# grepped a file that had not been written yet and produced an empty warnings.log for every
|
||||
# lane. Fifteen lanes reported zero warnings while their logs held up to three each, and the
|
||||
# one artifact Wave 4's gate reads was the one that could not see them.
|
||||
grep -E ' (WARN|ERROR) ' "${LANE_EVIDENCE}/compose.log" 2>/dev/null \
|
||||
>"${LANE_EVIDENCE}/warnings.log" || true
|
||||
fi
|
||||
# This project only. Never a bare `down`, which would take out whatever else the developer has
|
||||
# running, and never a volume outside it.
|
||||
docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" down --volumes --remove-orphans >/dev/null 2>&1 || true
|
||||
fi
|
||||
[[ -n "${LANE_TMP}" && -d "${LANE_TMP}" ]] && rm -rf "${LANE_TMP}"
|
||||
# .env.lane is gone — the lane's values live in the generated overlay now — but a file left by an
|
||||
# older revision of this script would still be read by the local overlay's env_file list.
|
||||
rm -f "${REPO_ROOT}/src/.env.lane" "${REPO_ROOT}/infra/keycloak/secrets/graphql-smoke-client-secret"
|
||||
# The lane keypair, including the CA's private half. A certificate that outlives the run it was
|
||||
# made for is a credential nobody is tracking.
|
||||
rm -f "${REPO_ROOT}"/infra/postgres/tls/ca.key "${REPO_ROOT}"/infra/postgres/tls/ca.crt \
|
||||
"${REPO_ROOT}"/infra/postgres/tls/ca.srl "${REPO_ROOT}"/infra/postgres/tls/server.key \
|
||||
"${REPO_ROOT}"/infra/postgres/tls/server.crt "${REPO_ROOT}"/infra/postgres/tls/server.csr \
|
||||
"${REPO_ROOT}"/infra/mailpit/tls/server.key "${REPO_ROOT}"/infra/mailpit/tls/server.crt
|
||||
return "${status}"
|
||||
}
|
||||
|
||||
# Secrets must not survive into an artifact. The generated values are known here, so they are
|
||||
# replaced by name rather than by guessing at what a secret looks like.
|
||||
redact_in_place() {
|
||||
local file="$1"
|
||||
[[ -r "${file}" ]] || return 0
|
||||
local value
|
||||
for value in "${GENERATED_SECRETS[@]:-}"; do
|
||||
[[ -n "${value}" ]] && sed -i "s|${value}|<redacted>|g" "${file}"
|
||||
done
|
||||
}
|
||||
|
||||
random_secret() { head -c 32 /dev/urandom | base64 | tr -d '=+/' | cut -c1-32; }
|
||||
|
||||
# Key material, which is not the same thing as a password. The notification platform base64-decodes
|
||||
# each of its eight keys and requires at least 32 bytes, so random_secret's alphanumeric 32
|
||||
# characters decode to 24 and are rejected. This keeps the padding and the full alphabet.
|
||||
random_key() { head -c 32 /dev/urandom | base64 | tr -d '\n'; }
|
||||
|
||||
run_lane() {
|
||||
local lane_json="$1"
|
||||
local id profile runtime
|
||||
id="$(jq -r '.id' <<<"${lane_json}")"
|
||||
profile="$(jq -r '.composeProfile // empty' <<<"${lane_json}")"
|
||||
runtime="$(jq -r '.springRuntime' <<<"${lane_json}")"
|
||||
|
||||
PROJECT="casmoke-${id}-${PROJECT_RUN_ID}"
|
||||
LANE_EVIDENCE="${EVIDENCE_ROOT}/${id}/${RUN_ID}"
|
||||
if [[ -e "${LANE_EVIDENCE}" ]]; then
|
||||
echo "${id}: ${LANE_EVIDENCE} already exists; refusing to write into a previous run's evidence" >&2
|
||||
return 1
|
||||
fi
|
||||
mkdir -p "${LANE_EVIDENCE}"
|
||||
LANE_TMP="$(mktemp -d)"
|
||||
chmod 700 "${LANE_TMP}"
|
||||
|
||||
LANE_ARGS=()
|
||||
local key file
|
||||
while read -r key; do
|
||||
file="$(jq -r --arg k "${key}" '.composeFiles[$k]' "${CONTRACTS}")"
|
||||
LANE_ARGS+=(-f "${REPO_ROOT}/${file}")
|
||||
done < <(jq -r '.files[]' <<<"${lane_json}")
|
||||
[[ -n "${profile}" ]] && LANE_ARGS+=(--profile "${profile}")
|
||||
|
||||
# A fresh client secret per run, mode 0600, removed on teardown. The realm references it by name.
|
||||
local secret_dir="${REPO_ROOT}/infra/keycloak/secrets"
|
||||
local secret_file="${secret_dir}/graphql-smoke-client-secret"
|
||||
mkdir -p "${secret_dir}"
|
||||
local client_secret; client_secret="$(random_secret)"
|
||||
GENERATED_SECRETS+=("${client_secret}")
|
||||
(umask 077 && printf '%s' "${client_secret}" >"${secret_file}")
|
||||
|
||||
# A CA and a server certificate for the host name `db`, when the lane brings the TLS overlay.
|
||||
#
|
||||
# Generated per run and removed on teardown, like the realm secret: a committed test certificate is
|
||||
# a private key in Git. The host name matters — the prod runtime connects with sslmode=verify-full,
|
||||
# which checks the certificate against the name it dialled, so a certificate for anything but `db`
|
||||
# fails exactly as a redirected connection would. That is the check, working.
|
||||
local tls_dir="${REPO_ROOT}/infra/postgres/tls"
|
||||
if jq -e '.files | index("tls")' <<<"${lane_json}" >/dev/null; then
|
||||
mkdir -p "${tls_dir}"
|
||||
(
|
||||
umask 077
|
||||
openssl req -x509 -newkey rsa:2048 -sha256 -days 1 -nodes \
|
||||
-keyout "${tls_dir}/ca.key" -out "${tls_dir}/ca.crt" \
|
||||
-subj "/CN=ca-skeleton-lane-ca" >/dev/null 2>&1
|
||||
openssl req -newkey rsa:2048 -nodes \
|
||||
-keyout "${tls_dir}/server.key" -out "${tls_dir}/server.csr" \
|
||||
-subj "/CN=db" >/dev/null 2>&1
|
||||
openssl x509 -req -in "${tls_dir}/server.csr" -sha256 -days 1 \
|
||||
-CA "${tls_dir}/ca.crt" -CAkey "${tls_dir}/ca.key" -CAcreateserial \
|
||||
-extfile <(printf 'subjectAltName=DNS:db\nextendedKeyUsage=serverAuth\n') \
|
||||
-out "${tls_dir}/server.crt" >/dev/null 2>&1
|
||||
)
|
||||
# The CA certificate is public and is mounted as a Compose secret, which preserves the source
|
||||
# file's mode; 0600 would be unreadable to the application's non-root user.
|
||||
chmod 0644 "${tls_dir}/ca.crt"
|
||||
rm -f "${tls_dir}/server.csr"
|
||||
[[ -s "${tls_dir}/server.crt" ]] || { echo "${id}: could not generate the lane certificate" >&2; return 1; }
|
||||
fi
|
||||
|
||||
# A certificate for the host name `mailpit`, when the lane brings the reference SMTP relay.
|
||||
#
|
||||
# Same rule as the PostgreSQL one above and for the same reason: the notification platform's
|
||||
# transport type has no plaintext member, so a relay without a certificate is one the platform
|
||||
# cannot be configured to talk to. Generated per run, removed on teardown.
|
||||
local mail_tls="${REPO_ROOT}/infra/mailpit/tls"
|
||||
if jq -e '.services | index("mailpit")' <<<"${lane_json}" >/dev/null; then
|
||||
mkdir -p "${mail_tls}"
|
||||
(
|
||||
umask 077
|
||||
openssl req -x509 -newkey rsa:2048 -sha256 -days 1 -nodes \
|
||||
-keyout "${mail_tls}/server.key" -out "${mail_tls}/server.crt" \
|
||||
-subj "/CN=mailpit" \
|
||||
-addext "subjectAltName=DNS:mailpit" \
|
||||
-addext "extendedKeyUsage=serverAuth" >/dev/null 2>&1
|
||||
)
|
||||
# Mailpit runs as a non-root user and reads both halves; 0600 would be unreadable to it.
|
||||
chmod 0644 "${mail_tls}/server.crt" "${mail_tls}/server.key"
|
||||
[[ -s "${mail_tls}/server.crt" ]] || { echo "${id}: could not generate the Mailpit certificate" >&2; return 1; }
|
||||
fi
|
||||
|
||||
# The values a deployment must supply: the seven with no inline default, and the secrets the prod
|
||||
# env validator requires to be non-blank. A lane supplies them explicitly rather than inheriting a
|
||||
# developer's src/.env, which is the difference between a lane that reproduces anywhere and one
|
||||
# that reproduces on the machine it was written on. All generated per run and removed on teardown.
|
||||
#
|
||||
# The database credentials are additionally *exported*, because two different mechanisms have to
|
||||
# agree on them. The application reads this file; the `db` service takes its POSTGRES_USER and
|
||||
# POSTGRES_PASSWORD from Compose interpolation — `${APP_DATASOURCE_PASSWORD:-ca_skeleton}` — and
|
||||
# interpolation reads the process environment and the project .env file, never a service's
|
||||
# env_file. So the application got the generated password and the database got the literal
|
||||
# default, and no lane whose overlay did not happen to restate the value could ever authenticate.
|
||||
# shared-infra-local passed only because the local overlay restates it, which made the dev lane's
|
||||
# failure look like a dev-specific problem rather than the general one it is.
|
||||
export POSTGRES_DB=ca_skeleton
|
||||
export APP_DATASOURCE_USERNAME=ca_skeleton
|
||||
export APP_DATASOURCE_PASSWORD="${client_secret}"
|
||||
|
||||
# Which phase the notification client runs. Exported rather than defaulted in Compose, because a
|
||||
# default made local-notification-serving run the ingest assertions and pass without ever checking
|
||||
# a delivery.
|
||||
export NOTIFICATION_SMOKE_PHASE
|
||||
NOTIFICATION_SMOKE_PHASE="$(jq -r '.notificationSmokePhase // ""' <<<"${lane_json}")"
|
||||
|
||||
# The capability schema streams this lane installs, exported for the same reason as the credentials
|
||||
# above: the migration containers take them through Compose interpolation, which reads the process
|
||||
# environment and never a lane overlay. They are deliberately not part of activationEnv — the
|
||||
# application does not read this value, the two one-shots that install and promote the schema do,
|
||||
# and putting an operator input in the application's environment block is how it would come to look
|
||||
# like a switch the application honours.
|
||||
export CAPABILITY_STREAMS
|
||||
CAPABILITY_STREAMS="$(jq -r '.capabilityStreams // [] | join(" ")' <<<"${lane_json}")"
|
||||
|
||||
# The public health address, which is not the same in every runtime: application-local.yml pins
|
||||
# presentation.api-base-path to /api while the shipped default is /v1. The smoke client used to
|
||||
# hardcode /api, so it verified the local runtime and 404'd against a dev application that had
|
||||
# started perfectly.
|
||||
if [[ "${runtime}" == "local" ]]; then
|
||||
export APP_HEALTH_PATH=/api/healthcheck
|
||||
else
|
||||
export APP_HEALTH_PATH=/v1/healthcheck
|
||||
fi
|
||||
|
||||
# The notification platform's eight purpose-scoped keys.
|
||||
#
|
||||
# All eight, always, for every lane — not only the notification ones. They cost nothing when the
|
||||
# capability is off, because the platform binds nothing at all then, and a lane that supplies only
|
||||
# the keys it currently needs is a lane that breaks the moment a switch is added to it.
|
||||
#
|
||||
# Distinct by construction: the platform refuses to start if two purposes carry the same material,
|
||||
# which is the check that stops one leaked key from being all eight. Each is redacted from the
|
||||
# evidence like every other generated value.
|
||||
local -a notification_keys=()
|
||||
local purpose
|
||||
for purpose in CONTACT_ENCRYPTION CONTACT_LOOKUP_HMAC CALLBACK_SIGNING PROVIDER_CREDENTIAL \
|
||||
PAYLOAD_ENCRYPTION VAPID_SIGNING PROVIDER_REQUEST_LOOKUP_HMAC \
|
||||
CALLBACK_FINGERPRINT_HMAC; do
|
||||
local value; value="$(random_key)"
|
||||
GENERATED_SECRETS+=("${value}")
|
||||
notification_keys+=("APP_NOTIFICATION_PLATFORM_${purpose}_KEY=${value}")
|
||||
# The id, which is not secret and is deliberately tied to this run. A lane that reused a fixed
|
||||
# id across runs would be asserting the one thing the platform refuses to assume: that material
|
||||
# and id change together.
|
||||
notification_keys+=("APP_NOTIFICATION_PLATFORM_${purpose}_KEY_ID=lane-${PROJECT_RUN_ID}-$(echo "${purpose}" | tr '[:upper:]_' '[:lower:]-')")
|
||||
done
|
||||
|
||||
# Every deployment-supplied value the lane owns, collected here and written into the generated
|
||||
# overlay's `environment:` block below rather than into an env file.
|
||||
#
|
||||
# These lived in src/.env.lane, and an env file cannot win. env_file lists merge across overlays
|
||||
# and the later one takes precedence, so the developer's optional src/.env — declared by the local
|
||||
# overlay, after the base — silently replaced them. That is not hypothetical: it pinned the JWT
|
||||
# issuer to http://localhost:8081, which inside the app container is the application itself, so the
|
||||
# application fetched JWKS from its own port and answered AUTH_JWKS_UNAVAILABLE to every
|
||||
# authenticated request while the lane had supplied the correct issuer all along.
|
||||
#
|
||||
# An `environment:` block outranks every env_file regardless of order, which is the same fix the
|
||||
# lane's activation switches already use. The cost is that these values appear in `docker inspect`
|
||||
# for this run's own throwaway project; they are generated per run, removed on teardown, and
|
||||
# redacted from every evidence file by name. A lane whose settings are silently discarded is worse.
|
||||
local -a lane_environment=(
|
||||
"APP_NAME=ca-skeleton-${id}"
|
||||
# APP_DATASOURCE_URL is deliberately absent. The environment overlays own it and they do not
|
||||
# agree by accident: the local one is a plain jdbc:postgresql URL and the prod-smoke one carries
|
||||
# sslmode=verify-full and a CA path, because the prod profile refuses to start without them.
|
||||
# Setting it here overrode both — this overlay is appended last — and off-prod, shared-infra-dev
|
||||
# and prod-smoke failed the profile check on a TLS requirement the stack had satisfied.
|
||||
"APP_DATASOURCE_USERNAME=${APP_DATASOURCE_USERNAME}"
|
||||
"APP_DATASOURCE_PASSWORD=${APP_DATASOURCE_PASSWORD}"
|
||||
"APP_SECURITY_JWT_ISSUER=http://keycloak:8080/realms/ca-skeleton"
|
||||
"APP_SECURITY_JWT_AUDIENCE=ca-skeleton-api"
|
||||
"SPRING_PROFILES_ACTIVE=${runtime}"
|
||||
"${notification_keys[@]}"
|
||||
)
|
||||
local generated
|
||||
for generated in APP_SECURITY_JWT_SIGNING_KEY APP_SECURITY_OAUTH_CLIENT_SECRET \
|
||||
APP_EXTERNAL_API_KEY APP_PRIVACY_PSEUDONYMIZATION_SALT; do
|
||||
local secret; secret="$(random_secret)"
|
||||
GENERATED_SECRETS+=("${secret}")
|
||||
lane_environment+=("${generated}=${secret}")
|
||||
done
|
||||
# The lane's own settings go into a generated overlay rather than into that file.
|
||||
#
|
||||
# env_file lists merge across overlays and the later file wins, so the developer's optional
|
||||
# src/.env — declared by the local overlay, after the base — silently overrode the lane's values.
|
||||
# local-messaging started Kafka, set APP_MESSAGING_BROKER=kafka, and was refused by the dependency
|
||||
# validator for a broker it had supplied, because an empty value from a file nobody mentioned won
|
||||
# the merge. An `environment:` block beats every env_file regardless of order, so the lane's
|
||||
# settings stop depending on where a file happens to sit in the stack.
|
||||
#
|
||||
# The overlay adds no service, so the set the static verifier checks is unchanged.
|
||||
# Written as a function, because a handoff lane rewrites it between phases: the same project and
|
||||
# the same database, with the application recreated under a different activation environment.
|
||||
local lane_overlay="${LANE_TMP}/lane-overrides.yml"
|
||||
write_lane_overlay() {
|
||||
local phase_override="${1:-{\}}"
|
||||
(
|
||||
umask 077
|
||||
{
|
||||
echo "services:"
|
||||
echo " app:"
|
||||
echo " environment:"
|
||||
local entry
|
||||
for entry in "${lane_environment[@]}"; do
|
||||
printf ' %s: "%s"\n' "${entry%%=*}" "${entry#*=}"
|
||||
done
|
||||
jq -r --argjson override "${phase_override}" \
|
||||
'.activationEnv + $override | to_entries[] | " \(.key): \"\(.value)\""' \
|
||||
<<<"${lane_json}"
|
||||
} >"${lane_overlay}"
|
||||
)
|
||||
}
|
||||
write_lane_overlay "$(jq -c '.handoff.firstPhaseEnv // {}' <<<"${lane_json}")"
|
||||
LANE_ARGS+=(-f "${lane_overlay}")
|
||||
GENERATED_SECRETS+=("${client_secret}")
|
||||
|
||||
echo "== ${id} (project ${PROJECT}, runtime ${runtime})"
|
||||
|
||||
# 2. static contract, then render, then create
|
||||
"${REPO_ROOT}/scripts/verify-compose-profile-contracts.sh" >"${LANE_EVIDENCE}/contract.log" 2>&1
|
||||
( cd "${REPO_ROOT}" && docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" config >"${LANE_EVIDENCE}/rendered.yml" )
|
||||
redact_in_place "${LANE_EVIDENCE}/rendered.yml"
|
||||
# Build before create. The app service declares both `build:` and `image:`, so Compose reuses a
|
||||
# matching tag if one is lying around — and the first run of this lane did exactly that, starting
|
||||
# a jar built from a different state of the repository and failing on a class that no longer
|
||||
# exists in the tree. A lane that runs a stale image produces evidence about code nobody changed.
|
||||
( cd "${REPO_ROOT}" && docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" build app \
|
||||
>"${LANE_EVIDENCE}/build.log" 2>&1 )
|
||||
( cd "${REPO_ROOT}" && docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" create >/dev/null )
|
||||
|
||||
# 3a. Anything that has to happen before the application starts, in the order the lane lists it.
|
||||
#
|
||||
# A capability schema stream is the case this exists for. Each stream keeps its own Flyway history
|
||||
# table and is promoted to ACTIVE deliberately after installation, and the application refuses to
|
||||
# start until that promotion has happened — so running it with the other one-shots, after `up`,
|
||||
# would run it after the thing it is a precondition for. The distinction is the lane's, not this
|
||||
# script's guess: preStartServices run here, oneShotServices run after the readiness poll.
|
||||
#
|
||||
# Read on fd 4 with stdin closed, for the reason the lane loop at the bottom of this file already
|
||||
# records: `docker compose run` consumes stdin, so a plain `while read` loop over several services
|
||||
# runs the first one and then finds its input exhausted. That is not hypothetical here — it is how
|
||||
# this lane ran its migration and silently skipped its promotion, and how shared-infra-local,
|
||||
# shared-infra-dev and prod-smoke each ran auth-smoke and skipped minio-init and
|
||||
# object-storage-smoke while reporting green. The evidence directories showed one log where the
|
||||
# contract named three.
|
||||
local pre_start
|
||||
while read -r -u 4 pre_start; do
|
||||
[[ -z "${pre_start}" ]] && continue
|
||||
echo "-- ${id}: ${pre_start} (before start)"
|
||||
if ! ( cd "${REPO_ROOT}" && docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" run --rm "${pre_start}" </dev/null ) \
|
||||
>"${LANE_EVIDENCE}/${pre_start}.log" 2>&1; then
|
||||
redact_in_place "${LANE_EVIDENCE}/${pre_start}.log"
|
||||
echo "${id}: ${pre_start} did not succeed; see ${pre_start}.log" >&2
|
||||
return 1
|
||||
fi
|
||||
redact_in_place "${LANE_EVIDENCE}/${pre_start}.log"
|
||||
done 4< <(jq -r '.preStartServices[]?' <<<"${lane_json}")
|
||||
|
||||
# 3. long-running services only. A one-shot is not a --wait target: it is meant to exit.
|
||||
local long_running
|
||||
long_running="$(jq -r '.longRunningServices[]' <<<"${lane_json}")"
|
||||
# shellcheck disable=SC2086
|
||||
( cd "${REPO_ROOT}" && docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" up --wait --wait-timeout 300 ${long_running} )
|
||||
|
||||
await_application_report() {
|
||||
# The application's own answer, not this script's input.
|
||||
#
|
||||
# The management port, not the application port. Actuator runs on its own connector here so the
|
||||
# management plane is not published on the public one, and fetching 8080/actuator returned an
|
||||
# empty file that looked exactly like a failed assertion about the profile.
|
||||
local management_port
|
||||
management_port="$(docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" exec -T app \
|
||||
sh -c 'echo "${MANAGEMENT_SERVER_PORT:-9001}"' 2>/dev/null | tr -d "\r\n")"
|
||||
management_port="${management_port:-9001}"
|
||||
# Poll rather than trust `up --wait`. Not every overlay defines a healthcheck — the dev one does
|
||||
# not — and where there is none `--wait` returns as soon as the container is created, so the first
|
||||
# fetch landed before the application had finished starting and produced an empty file that read
|
||||
# exactly like a failed assertion about the profile.
|
||||
local attempt
|
||||
for attempt in $(seq 1 60); do
|
||||
if docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" exec -T app \
|
||||
wget -qO- "http://localhost:${management_port}/actuator/adapteractivation" \
|
||||
>"${LANE_EVIDENCE}/activation.json" 2>/dev/null \
|
||||
&& [[ -s "${LANE_EVIDENCE}/activation.json" ]]; then
|
||||
break
|
||||
fi
|
||||
sleep 5
|
||||
done
|
||||
docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" exec -T app \
|
||||
wget -qO- "http://localhost:${management_port}/actuator/health" \
|
||||
>"${LANE_EVIDENCE}/health.json" 2>/dev/null || true
|
||||
|
||||
local reported
|
||||
reported="$(jq -r '.activeProfile // empty' "${LANE_EVIDENCE}/activation.json" 2>/dev/null || true)"
|
||||
if [[ "${reported}" != "${runtime}" ]]; then
|
||||
echo "${id}: the application reports profile '${reported}', the contract says '${runtime}'" >&2
|
||||
return 1
|
||||
fi
|
||||
|
||||
# The switches the application says are on must be exactly the ones the lane asked for. Without
|
||||
# this a lane called local-jpa that ran with JPA off would render the right services, start
|
||||
# cleanly, and prove nothing — which is the failure mode a green lane is least able to reveal.
|
||||
local expected_on actual_on
|
||||
expected_on="$(jq -r '.expectedSwitchesOn | sort | join(",")' <<<"${lane_json}")"
|
||||
actual_on="$(jq -r '.switches | to_entries | map(select(.value)) | map(.key) | sort | join(",")' \
|
||||
"${LANE_EVIDENCE}/activation.json")"
|
||||
if [[ "${expected_on}" != "${actual_on}" ]]; then
|
||||
echo "${id}: the application reports [${actual_on}] on, the contract expects [${expected_on}]" >&2
|
||||
return 1
|
||||
fi
|
||||
|
||||
# The vendor the application resolved, not the one the lane started. These differ exactly when a
|
||||
# profile pins a datasource that outranks the lane's environment, and every other field in the
|
||||
# report looks correct while it happens.
|
||||
local expected_vendor actual_vendor
|
||||
expected_vendor="$(jq -r '.expectedPersistenceVendor' <<<"${lane_json}")"
|
||||
actual_vendor="$(jq -r '.persistenceVendor // "absent"' "${LANE_EVIDENCE}/activation.json")"
|
||||
if [[ "${expected_vendor}" != "${actual_vendor}" ]]; then
|
||||
echo "${id}: the application resolved vendor '${actual_vendor}', the contract expects '${expected_vendor}'" >&2
|
||||
return 1
|
||||
fi
|
||||
|
||||
}
|
||||
await_application_report || return 1
|
||||
|
||||
# 3b. The handoff: one project, one database, the application recreated under the second phase.
|
||||
#
|
||||
# Not two lanes glued together. The evidence a handoff needs is that a request accepted while the
|
||||
# platform was INGEST_ONLY is delivered exactly once after a restart into SERVING — on the route
|
||||
# frozen at accept — and that is only evidence if the row is the same row. Tearing the volume down
|
||||
# between phases, or copying rows into a second project, proves nothing about a handoff.
|
||||
if jq -e '.handoff' <<<"${lane_json}" >/dev/null; then
|
||||
local first_smoke second_smoke
|
||||
first_smoke="$(jq -r '.handoff.firstPhaseSmoke' <<<"${lane_json}")"
|
||||
second_smoke="$(jq -r '.handoff.secondPhaseSmoke' <<<"${lane_json}")"
|
||||
|
||||
echo "-- ${id}: ${first_smoke} (handoff phase 1)"
|
||||
if ! ( cd "${REPO_ROOT}" && NOTIFICATION_SMOKE_PHASE="${first_smoke}" \
|
||||
docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" run --rm notification-smoke </dev/null ) \
|
||||
>"${LANE_EVIDENCE}/notification-smoke-phase1.log" 2>&1; then
|
||||
redact_in_place "${LANE_EVIDENCE}/notification-smoke-phase1.log"
|
||||
echo "${id}: the first handoff phase did not succeed" >&2
|
||||
return 1
|
||||
fi
|
||||
redact_in_place "${LANE_EVIDENCE}/notification-smoke-phase1.log"
|
||||
cp "${LANE_EVIDENCE}/activation.json" "${LANE_EVIDENCE}/activation-phase1.json"
|
||||
|
||||
# The application only. The database and its volume stay up, which is the whole point.
|
||||
echo "-- ${id}: restarting the application into the second phase"
|
||||
( cd "${REPO_ROOT}" && docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" stop app >/dev/null 2>&1 )
|
||||
|
||||
write_lane_overlay '{}'
|
||||
( cd "${REPO_ROOT}" && docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" \
|
||||
up -d --force-recreate --wait --wait-timeout 300 app )
|
||||
await_application_report || return 1
|
||||
fi
|
||||
|
||||
# 3c. The startup log carries no WARN and no ERROR.
|
||||
#
|
||||
# Wave 4's condition is about startup specifically, and a summary of the whole lane cannot express
|
||||
# it: the lanes that exercise authentication end with a deliberate malformed-token probe, and the
|
||||
# application answering it with a WARN is the security control working. Splitting at the line where
|
||||
# the application reports it has started is what makes "startup is silent" checkable instead of
|
||||
# argued — and it is checked here, per lane, rather than read off an artifact afterwards.
|
||||
#
|
||||
# StartupWarningZeroTest asserts the same property in-process for the all-off composition. This is
|
||||
# the same assertion against a real container with the lane's switches actually on.
|
||||
local startup_log="${LANE_EVIDENCE}/startup.log"
|
||||
docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" logs --no-color app \
|
||||
>"${startup_log}" 2>&1 || true
|
||||
redact_in_place "${startup_log}"
|
||||
local startup_noise
|
||||
startup_noise="$(awk '/Started CaSkeletonApplication/{exit} /(WARN|ERROR)/{print}' "${startup_log}")"
|
||||
if [[ -n "${startup_noise}" ]]; then
|
||||
echo "${id}: the startup log is not silent:" >&2
|
||||
echo "${startup_noise}" | head -20 >&2
|
||||
return 1
|
||||
fi
|
||||
|
||||
# 4. every declared one-shot, each of which must exit zero
|
||||
#
|
||||
# fd 4 and a closed stdin, same reason as the pre-start loop above. And the count is checked rather
|
||||
# than trusted: this loop ran exactly one one-shot per lane for its whole life, so the three lanes
|
||||
# that declare three clients verified object storage in none of their runs and said so in neither
|
||||
# their output nor their exit status. A loop that silently does less than the contract asks is the
|
||||
# one failure a green lane cannot reveal, so the arithmetic is now part of the lane.
|
||||
local one_shot ran_one_shots=0 declared_one_shots
|
||||
declared_one_shots="$(jq -r '.oneShotServices // [] | length' <<<"${lane_json}")"
|
||||
while read -r -u 4 one_shot; do
|
||||
[[ -z "${one_shot}" ]] && continue
|
||||
echo "-- ${id}: ${one_shot}"
|
||||
if ! ( cd "${REPO_ROOT}" && docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" run --rm "${one_shot}" </dev/null ) \
|
||||
>"${LANE_EVIDENCE}/${one_shot}.log" 2>&1; then
|
||||
redact_in_place "${LANE_EVIDENCE}/${one_shot}.log"
|
||||
echo "${id}: ${one_shot} did not exit zero; see ${one_shot}.log" >&2
|
||||
return 1
|
||||
fi
|
||||
redact_in_place "${LANE_EVIDENCE}/${one_shot}.log"
|
||||
ran_one_shots=$((ran_one_shots + 1))
|
||||
done 4< <(jq -r '.oneShotServices[]?' <<<"${lane_json}")
|
||||
if [[ "${ran_one_shots}" -ne "${declared_one_shots}" ]]; then
|
||||
echo "${id}: ran ${ran_one_shots} of ${declared_one_shots} one-shots; a partial lane is not a pass" >&2
|
||||
return 1
|
||||
fi
|
||||
|
||||
# 5. the manifest ties the evidence to the exact stack that produced it
|
||||
jq -n \
|
||||
--arg lane "${id}" --arg run "${RUN_ID}" --arg project "${PROJECT}" \
|
||||
--arg runtime "${runtime}" --arg profile "${profile}" \
|
||||
--argjson services "$(jq '.services' <<<"${lane_json}")" \
|
||||
'{lane:$lane, runId:$run, project:$project, springRuntime:$runtime,
|
||||
composeProfile:(if $profile=="" then null else $profile end), services:$services}' \
|
||||
>"${LANE_EVIDENCE}/manifest.json"
|
||||
|
||||
echo "== ${id}: passed"
|
||||
}
|
||||
|
||||
GENERATED_SECRETS=()
|
||||
FAILED_LANES=()
|
||||
|
||||
if [[ "${MODE}" == "lane" ]]; then
|
||||
lane_json="$(jq -c --arg id "${SELECTED_LANE}" '.lanes[] | select(.id == $id)' "${CONTRACTS}")"
|
||||
[[ -n "${lane_json}" ]] || { echo "no lane '${SELECTED_LANE}' in ${CONTRACTS}" >&2; exit 64; }
|
||||
trap cleanup_lane EXIT
|
||||
run_lane "${lane_json}"
|
||||
echo "one lane reproduced. A green single lane is not evidence that the matrix passes."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
blocking="$(jq -c '.lanes[] | select(.blocking == true)' "${CONTRACTS}")"
|
||||
total="$(wc -l <<<"${blocking}" | tr -d ' ')"
|
||||
echo "running ${total} blocking lane(s), zero-skip"
|
||||
# Read on fd 3, not stdin. `docker compose exec` and friends consume stdin, and inside a plain
|
||||
# `while read` loop they ate the remaining lanes — so the first lane ran, the loop ended, and the
|
||||
# script reported that all six had passed. A wrapper whose own success message is a false green is
|
||||
# worse than no wrapper, and nothing else here would have caught it: the count came from the
|
||||
# contract and the exit status from the one lane that did run.
|
||||
RAN_LANES=0
|
||||
while read -r -u 3 lane_json; do
|
||||
[[ -z "${lane_json}" ]] && continue
|
||||
RAN_LANES=$((RAN_LANES + 1))
|
||||
if ( trap cleanup_lane EXIT; run_lane "${lane_json}" ); then :; else
|
||||
FAILED_LANES+=("$(jq -r '.id' <<<"${lane_json}")")
|
||||
fi
|
||||
done 3<<<"${blocking}"
|
||||
|
||||
if [[ "${RAN_LANES}" -ne "${total}" ]]; then
|
||||
echo "run-compose-runtime-smoke: ran ${RAN_LANES} of ${total} lanes; a partial matrix is not a pass" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [[ ${#FAILED_LANES[@]} -gt 0 ]]; then
|
||||
echo "run-compose-runtime-smoke: ${#FAILED_LANES[@]} lane(s) failed: ${FAILED_LANES[*]}" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "run-compose-runtime-smoke: all ${total} blocking lanes passed; evidence under ${EVIDENCE_ROOT}"
|
||||
Executable
+156
@@ -0,0 +1,156 @@
|
||||
#!/usr/bin/env bash
|
||||
# The static half of the Compose contract: every lane renders, and renders exactly what it claims.
|
||||
#
|
||||
# Five things are checked, and each exists because assuming it cost something:
|
||||
#
|
||||
# 1. the Compose version, because `!override` is what stops the dev overlay's tmpfs merging with
|
||||
# the base's and colliding with a bind mount, and it needs 2.24.4;
|
||||
# 2. the exact service set per lane — exact, not a superset, because a lane that quietly gains a
|
||||
# service is a lane whose evidence describes a different stack than the one that ran;
|
||||
# 3. the rendered SPRING_PROFILES_ACTIVE, because a Compose profile selects services and says
|
||||
# nothing about which environment the application thinks it is in;
|
||||
# 4. mount-target uniqueness in the merged model, because that collision is exactly what made the
|
||||
# dev stack unrenderable and "the syntax looks right" is not the same as "the targets are
|
||||
# distinct";
|
||||
# 5. the service-role partition, because a service the lane renders and files under no role is
|
||||
# started by nothing and checked by nothing, and a one-shot filed as a --wait target hangs the
|
||||
# lane for its full timeout on a container that was built to exit.
|
||||
#
|
||||
# Static only. Nothing starts here; scripts/run-compose-runtime-smoke.sh owns that.
|
||||
set -euo pipefail
|
||||
|
||||
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
CONTRACTS="${REPO_ROOT}/src/config/runtime/compose-profile-contracts.json"
|
||||
FAILURES=0
|
||||
|
||||
fail() { echo " FAIL: $*" >&2; FAILURES=$((FAILURES + 1)); }
|
||||
|
||||
command -v jq >/dev/null 2>&1 || { echo "jq is required" >&2; exit 78; }
|
||||
command -v docker >/dev/null 2>&1 || { echo "docker is required" >&2; exit 78; }
|
||||
[[ -r "${CONTRACTS}" ]] || { echo "missing ${CONTRACTS}" >&2; exit 78; }
|
||||
|
||||
# ---- 1. Compose version floor ------------------------------------------------
|
||||
REQUIRED="$(jq -r '.minimumComposeVersion' "${CONTRACTS}")"
|
||||
ACTUAL="$(docker compose version --short | sed 's/^v//')"
|
||||
if [[ "$(printf '%s\n%s\n' "${REQUIRED}" "${ACTUAL}" | sort -V | head -1)" != "${REQUIRED}" ]]; then
|
||||
echo "docker compose ${ACTUAL} is below the required ${REQUIRED};" >&2
|
||||
echo " the dev overlay needs !override to replace the base tmpfs rather than merge with it." >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "compose version ${ACTUAL} >= ${REQUIRED}"
|
||||
|
||||
# ---- per-lane checks ---------------------------------------------------------
|
||||
lane_count="$(jq '.lanes | length' "${CONTRACTS}")"
|
||||
for index in $(seq 0 $((lane_count - 1))); do
|
||||
lane="$(jq -c ".lanes[${index}]" "${CONTRACTS}")"
|
||||
id="$(jq -r '.id' <<<"${lane}")"
|
||||
profile="$(jq -r '.composeProfile // empty' <<<"${lane}")"
|
||||
runtime="$(jq -r '.springRuntime' <<<"${lane}")"
|
||||
expected="$(jq -r '.services | sort | join(",")' <<<"${lane}")"
|
||||
|
||||
args=()
|
||||
while read -r key; do
|
||||
file="$(jq -r --arg k "${key}" '.composeFiles[$k]' "${CONTRACTS}")"
|
||||
[[ -r "${REPO_ROOT}/${file}" ]] || { fail "${id}: ${file} is missing"; continue 2; }
|
||||
args+=(-f "${REPO_ROOT}/${file}")
|
||||
done < <(jq -r '.files[]' <<<"${lane}")
|
||||
|
||||
profile_args=()
|
||||
[[ -n "${profile}" ]] && profile_args=(--profile "${profile}")
|
||||
|
||||
# 2. exact service set
|
||||
# stderr goes to a file rather than into the list. It used to be merged with `2>&1`, so Compose's
|
||||
# own warning about an unset interpolation variable arrived as an extra "service" and twelve lanes
|
||||
# failed with a timestamped log line in place of a container name.
|
||||
render_error="${TMPDIR:-/tmp}/compose-config-$$.err"
|
||||
if ! actual="$(cd "${REPO_ROOT}" && docker compose "${args[@]}" "${profile_args[@]}" config --services 2>"${render_error}" | sort | paste -sd, -)"; then
|
||||
fail "${id}: the stack does not render: $(tr '\n' ' ' <"${render_error}")"
|
||||
rm -f "${render_error}"
|
||||
continue
|
||||
fi
|
||||
rm -f "${render_error}"
|
||||
if [[ "${actual}" != "${expected}" ]]; then
|
||||
fail "${id}: services are [${actual}], the contract says [${expected}]"
|
||||
continue
|
||||
fi
|
||||
|
||||
# 3. the rendered Spring runtime, and 4. mount-target uniqueness
|
||||
model="$(cd "${REPO_ROOT}" && docker compose "${args[@]}" "${profile_args[@]}" config --format json 2>/dev/null)" || {
|
||||
fail "${id}: the merged model does not render as JSON"
|
||||
continue
|
||||
}
|
||||
|
||||
rendered_runtime="$(jq -r '.services.app.environment.SPRING_PROFILES_ACTIVE // empty' <<<"${model}")"
|
||||
if [[ "${rendered_runtime}" != "${runtime}" ]]; then
|
||||
fail "${id}: app renders SPRING_PROFILES_ACTIVE='${rendered_runtime}', the contract says '${runtime}'"
|
||||
fi
|
||||
|
||||
duplicates="$(jq -r '
|
||||
.services | to_entries[]
|
||||
| .key as $svc
|
||||
| [ (.value.volumes // [] | .[].target), (.value.tmpfs // [] | .[] | split(":")[0]) ] as $targets
|
||||
| ($targets | group_by(.) | map(select(length > 1) | .[0])) as $dupes
|
||||
| select($dupes | length > 0)
|
||||
| "\($svc): \($dupes | join(", "))"' <<<"${model}")"
|
||||
if [[ -n "${duplicates}" ]]; then
|
||||
fail "${id}: a mount target is declared twice — ${duplicates}"
|
||||
fi
|
||||
|
||||
# 5. every rendered service plays exactly one role, and no non-waiting service is a --wait target.
|
||||
#
|
||||
# The wrapper runs longRunningServices under `up --wait`, preStartServices with `run --rm` before
|
||||
# the application, and oneShotServices with `run --rm` after it is healthy. A service the lane
|
||||
# renders but files under none of the three is started by nothing and checked by nothing, and one
|
||||
# filed under two is run twice. Neither is visible in a green lane.
|
||||
#
|
||||
# The direction that actually bites is a one-shot reaching longRunningServices: `up --wait` on a
|
||||
# container built to exit waits for a health state it will never report, and the lane hangs until
|
||||
# the 300s timeout with no indication that the contract, not the stack, is what is wrong.
|
||||
partition="$(jq -r '
|
||||
( (.longRunningServices // []) + (.preStartServices // []) + (.oneShotServices // []) ) as $filed
|
||||
| { missing: ((.services // []) - $filed), extra: ($filed - (.services // [])),
|
||||
twice: ($filed | group_by(.) | map(select(length > 1) | .[0])) }
|
||||
| select((.missing | length) + (.extra | length) + (.twice | length) > 0)
|
||||
| "unfiled=[\(.missing | join(","))] not-rendered=[\(.extra | join(","))] twice=[\(.twice | join(","))]"
|
||||
' <<<"${lane}")"
|
||||
[[ -n "${partition}" ]] && fail "${id}: services are not partitioned by role — ${partition}"
|
||||
|
||||
never_waiting="$(jq -r --argjson lane "${lane}" '
|
||||
( (.preStartServices // []) + (.oneShotServices // []) ) as $catalogue
|
||||
| ( ($lane.longRunningServices // []) - (($lane.longRunningServices // []) - $catalogue) )
|
||||
| select(length > 0) | join(",")' "${CONTRACTS}")"
|
||||
[[ -n "${never_waiting}" ]] && fail "${id}: [${never_waiting}] are declared non-waiting but listed as --wait targets"
|
||||
|
||||
uncatalogued="$(jq -r --argjson lane "${lane}" '
|
||||
( (.preStartServices // []) + (.oneShotServices // []) ) as $catalogue
|
||||
| ( (($lane.preStartServices // []) + ($lane.oneShotServices // [])) - $catalogue )
|
||||
| select(length > 0) | join(",")' "${CONTRACTS}")"
|
||||
[[ -n "${uncatalogued}" ]] && fail "${id}: [${uncatalogued}] are run with \`run --rm\` but are in neither top-level catalogue"
|
||||
|
||||
[[ ${FAILURES} -eq 0 ]] && echo "${id}: ${expected} @ ${runtime}"
|
||||
done
|
||||
|
||||
# 6. the Keycloak realm artifact deserializes into Keycloak's own representation.
|
||||
#
|
||||
# Keycloak rejects unknown fields rather than ignoring them, so one annotation key anywhere in the
|
||||
# tree fails the whole import, the container exits 1, and every lane that needs an identity provider
|
||||
# fails on Keycloak instead of on what it was testing. This cost two lane runs to find, once for
|
||||
# `_comment` on the realm and once for `_flowComment` on a client, because the second was invisible
|
||||
# until the first was fixed. Rationale for that artifact lives in infra/keycloak/README.md.
|
||||
realm="${REPO_ROOT}/infra/keycloak/realms/ca-skeleton-realm.json"
|
||||
if [[ -f "${realm}" ]]; then
|
||||
if ! jq empty "${realm}" >/dev/null 2>&1; then
|
||||
fail "infra/keycloak/realms/ca-skeleton-realm.json is not valid JSON"
|
||||
else
|
||||
annotations="$(jq -r '[paths(scalars, objects, arrays) | .[-1] | select(type == "string") | select(startswith("_"))] | unique | join(", ")' "${realm}")"
|
||||
if [[ -n "${annotations}" ]]; then
|
||||
fail "the Keycloak realm carries key(s) Keycloak refuses to deserialize: ${annotations}"
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
if [[ ${FAILURES} -gt 0 ]]; then
|
||||
echo "verify-compose-profile-contracts: ${FAILURES} lane(s) do not match the contract" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "verify-compose-profile-contracts: all ${lane_count} lanes match src/config/runtime/compose-profile-contracts.json"
|
||||
@@ -90,13 +90,15 @@ echo "=== [actual-topology] provider environments"
|
||||
# connection. Which classes count is `src/config/mongodb/release-contracts.json`, and
|
||||
# MongoReleaseEvidenceVerifier checks the JUnit XML rather than the exit code.
|
||||
if [[ -n "${MONGODB_SHARDED_URI:-}" ]]; then
|
||||
SHARDED_CLASS="$(python3 -c "import json,sys; print(next(c['className'] for c in json.load(open('${REPO_ROOT}/src/config/mongodb/release-contracts.json'))['contracts'] if c['topology']=='sharded'))")"
|
||||
if (cd "${GRADLE_DIR}" && MONGODB_SHARDED_URI="${MONGODB_SHARDED_URI}" \
|
||||
"${GRADLE[@]}" "${MODULE}:mongoShardedTest" --tests "${SHARDED_CLASS}"); then
|
||||
echo "actual-topology(sharded): ${SHARDED_CLASS} executed"
|
||||
else
|
||||
FAILED+=("actual-topology:sharded")
|
||||
fi
|
||||
# Not promoted. `mongoShardedTest` is declared in release-contracts.json under
|
||||
# experimental_contracts and is registered by no build file, so invoking it here could only ever
|
||||
# fail — and before the demotion it made this script unrunnable while the manifest still reported
|
||||
# the capability as a blocking gate. Supplying the URI is therefore an explicit error rather than
|
||||
# a silent skip: an operator who set it expected a qualification to run.
|
||||
echo "sharded topology is experimental and has no registered lane;" >&2
|
||||
echo " MONGODB_SHARDED_URI was set but mongoShardedTest does not exist." >&2
|
||||
echo " See experimental_contracts in src/config/mongodb/release-contracts.json." >&2
|
||||
FAILED+=("actual-topology:sharded-not-promoted")
|
||||
else
|
||||
echo "actual-topology(sharded): no MONGODB_SHARDED_URI"
|
||||
MISSING_EVIDENCE+=("actual-topology: sharded cluster")
|
||||
|
||||
@@ -1,233 +0,0 @@
|
||||
# ----------------------------------------------------------------------------
|
||||
# 외부화 설정의 단일 출처. spring-dotenv 가 src/.env 에서 로드합니다
|
||||
# (bootRun.workingDir = src/). 각 키의 허용값·결정 근거는 src/README.md 참조.
|
||||
# ----------------------------------------------------------------------------
|
||||
|
||||
# ----- App identity -----
|
||||
APP_NAME=ca-skeleton
|
||||
SPRING_PROFILES_ACTIVE=local
|
||||
|
||||
# ----- Runtime safety (StartupSafetyValidator, D8) -----
|
||||
APP_ERROR_DETAIL_EXPOSURE_ENABLED=false
|
||||
APP_LOG_BODY_CAPTURE_ENABLED=false
|
||||
APP_MULTI_INSTANCE_ENABLED=false
|
||||
APP_MIGRATION_ON_STARTUP=true
|
||||
APP_RATE_LIMIT_ENABLED=false
|
||||
APP_RATE_LIMIT_CLIENT_IP_MODE=remote-addr-only
|
||||
APP_RATE_LIMIT_PROVIDER=disabled
|
||||
APP_IDEMPOTENCY_TTL=24h
|
||||
APP_IDEMPOTENCY_PROVIDER=jdbc
|
||||
APP_IDEMPOTENCY_REDIS_KEY_HMAC_SECRET=
|
||||
APP_IDEMPOTENCY_PROCESSING_LEASE=30s
|
||||
APP_IDEMPOTENCY_FAILURE_RETENTION=24h
|
||||
APP_LEASE_PROVIDER=disabled
|
||||
APP_LEASE_REDIS_KEY_HMAC_SECRET=
|
||||
APP_LEASE_REDIS_DRIFT_BUDGET=10ms
|
||||
|
||||
# ----- Async executor -----
|
||||
APP_ASYNC_EXECUTOR_CORE_SIZE=10
|
||||
APP_ASYNC_EXECUTOR_MAX_SIZE=50
|
||||
APP_ASYNC_EXECUTOR_QUEUE_CAPACITY=200
|
||||
|
||||
# ----- Optional integration adapters (default: all disabled) -----
|
||||
APP_CACHE_CANONICAL_DEFAULT_PROVIDER=disabled
|
||||
# The single global Redis switch. False means no Redis settings, secrets, client, threads or
|
||||
# health contributor exist. Role selectors (cache/session/idempotency/lease/rate-limit) choose
|
||||
# which capabilities compose once Redis is on; none of them turns Redis on.
|
||||
APP_REDIS_ENABLED=false
|
||||
APP_MESSAGING_BROKER=
|
||||
APP_MESSAGING_KAFKA_BROKERS=
|
||||
APP_NOTIFICATION_SLACK_PROVIDER=
|
||||
APP_NOTIFICATION_EMAIL_PROVIDER=
|
||||
|
||||
# ----- Logging: root & app levels -----
|
||||
APP_LOG_LEVEL_ROOT=INFO
|
||||
APP_LOG_LEVEL_APP=DEBUG
|
||||
|
||||
# ----- Logging: per-package levels -----
|
||||
APP_LOG_LEVEL_SPRING=INFO
|
||||
APP_LOG_LEVEL_WEB=INFO
|
||||
APP_LOG_LEVEL_SQL=WARN
|
||||
|
||||
# ----- Logging: file output + rolling -----
|
||||
APP_LOG_FILE_ENABLED=false
|
||||
APP_LOG_FILE_PATH=logs/ca-skeleton.json
|
||||
APP_LOG_FILE_MAX_SIZE=100MB
|
||||
APP_LOG_FILE_MAX_HISTORY=14
|
||||
APP_LOG_FILE_TOTAL_SIZE_CAP=3GB
|
||||
|
||||
# ----- Logging: async appender -----
|
||||
APP_LOG_ASYNC_ENABLED=true
|
||||
APP_LOG_ASYNC_QUEUE_SIZE=512
|
||||
APP_LOG_ASYNC_DISCARDING_THRESHOLD=20
|
||||
|
||||
# ----- Logging: JSON encoder -----
|
||||
APP_LOG_JSON_TIMEZONE=UTC
|
||||
APP_LOG_JSON_TIMESTAMP_PATTERN=yyyy-MM-dd'T'HH:mm:ss.SSSXXX
|
||||
APP_LOG_JSON_INCLUDE_CALLER_DATA=false
|
||||
APP_LOG_JSON_LOGGER_NAME_LENGTH=0
|
||||
|
||||
# ----- Logging: sampling -----
|
||||
APP_LOG_SAMPLING_RATE=1.0
|
||||
|
||||
# ----- Distributed tracing -----
|
||||
OTEL_EXPORTER_OTLP_ENDPOINT=
|
||||
APP_TRACING_ENABLED=true
|
||||
APP_TRACING_SAMPLE_RATE=
|
||||
|
||||
# ----- Privacy: user_principal pseudonymization -----
|
||||
APP_PRIVACY_PSEUDONYMIZATION_SALT=__LOCAL_DEV_pseudonymization_salt
|
||||
|
||||
# ----- Spring Boot bootstrap -----
|
||||
SPRING_BANNER_MODE=console
|
||||
SPRING_MAIN_LAZY_INITIALIZATION=false
|
||||
SPRING_MAIN_LOG_STARTUP_INFO=true
|
||||
SPRING_THREADS_VIRTUAL_ENABLED=true
|
||||
|
||||
# ----- Jackson: deserialization policy -----
|
||||
SPRING_JACKSON_DESER_FAIL_ON_UNKNOWN_PROPERTIES=true
|
||||
SPRING_JACKSON_DESER_FAIL_ON_NULL_FOR_PRIMITIVES=true
|
||||
SPRING_JACKSON_DESER_FAIL_ON_IGNORED_PROPERTIES=true
|
||||
SPRING_JACKSON_DESER_READ_UNKNOWN_ENUM_VALUES_AS_NULL=false
|
||||
|
||||
# ----- Jackson: serialization policy -----
|
||||
SPRING_JACKSON_SER_WRITE_DATES_AS_TIMESTAMPS=false
|
||||
|
||||
# ----- Server / Tomcat -----
|
||||
APP_SERVER_PORT=8080
|
||||
APP_SERVER_SHUTDOWN=graceful
|
||||
APP_SERVER_SHUTDOWN_TIMEOUT=30s
|
||||
APP_SERVER_TOMCAT_MAX_THREADS=200
|
||||
APP_SERVER_TOMCAT_MIN_SPARE_THREADS=10
|
||||
APP_SERVER_TOMCAT_ACCEPT_COUNT=100
|
||||
APP_SERVER_TOMCAT_MAX_CONNECTIONS=8192
|
||||
APP_SERVER_TOMCAT_CONNECTION_TIMEOUT=20s
|
||||
APP_SERVER_COMPRESSION_ENABLED=true
|
||||
APP_SERVER_COMPRESSION_MIN_RESPONSE_SIZE=1024
|
||||
APP_SERVER_FORWARD_HEADERS_STRATEGY=framework
|
||||
APP_SERVER_ERROR_INCLUDE_STACKTRACE=never
|
||||
APP_SERVER_ERROR_INCLUDE_MESSAGE=never
|
||||
|
||||
# ----- Presentation -----
|
||||
PRESENTATION_API_BASE_PATH=/api
|
||||
|
||||
# ----- Auth (OIDC resource server) -----
|
||||
APP_SECURITY_AUTH_MODE=jwt
|
||||
APP_SECURITY_JWT_ISSUER=http://localhost:8081/realms/ca-skeleton
|
||||
APP_SECURITY_JWT_AUDIENCE=ca-skeleton-api
|
||||
SECURITY_PUBLIC_PATHS=/api/healthcheck
|
||||
APP_SESSION_COOKIE_NAME=CA_SESSION
|
||||
APP_SESSION_COOKIE_SECURE=true
|
||||
APP_SESSION_COOKIE_HTTP_ONLY=true
|
||||
APP_SESSION_COOKIE_SAME_SITE=Lax
|
||||
APP_SESSION_COOKIE_PATH=/
|
||||
APP_SESSION_CSRF_COOKIE_NAME=XSRF-TOKEN
|
||||
APP_SESSION_CSRF_HEADER_NAME=X-XSRF-TOKEN
|
||||
|
||||
# ----- CORS -----
|
||||
APP_SECURITY_CORS_ENABLED=true
|
||||
APP_SECURITY_CORS_ORIGINS=http://localhost:3000
|
||||
APP_SECURITY_CORS_ALLOWED_METHODS=
|
||||
APP_SECURITY_CORS_ALLOWED_HEADERS=*
|
||||
APP_SECURITY_CORS_ALLOW_CREDENTIALS=true
|
||||
APP_SECURITY_CORS_MAX_AGE=3600
|
||||
|
||||
# ----- Database (Postgres) -----
|
||||
APP_DATASOURCE_URL=jdbc:postgresql://localhost:5433/ca_skeleton
|
||||
APP_DATASOURCE_USERNAME=ca_skeleton
|
||||
APP_DATASOURCE_PASSWORD=ca_skeleton
|
||||
APP_DATASOURCE_DRIVER=org.postgresql.Driver
|
||||
APP_DATASOURCE_DDL_AUTO=update
|
||||
APP_DATASOURCE_SHOW_SQL=false
|
||||
APP_DATASOURCE_FORMAT_SQL=false
|
||||
APP_DATASOURCE_OPEN_IN_VIEW=false
|
||||
|
||||
# ----- Database: HikariCP connection pool -----
|
||||
APP_DATASOURCE_POOL_MAX_SIZE=10
|
||||
APP_DATASOURCE_POOL_MIN_IDLE=2
|
||||
APP_DATASOURCE_CONNECTION_TIMEOUT=30000
|
||||
APP_DATASOURCE_POOL_IDLE_TIMEOUT=600000
|
||||
APP_DATASOURCE_POOL_MAX_LIFETIME=1800000
|
||||
|
||||
# ----- Management / Actuator -----
|
||||
MANAGEMENT_SERVER_PORT=9001
|
||||
|
||||
# ----- Fileserver HTTP platform (app.fileserver-platform.*) -----
|
||||
# Off by default. While false nothing below is bound: the platform auto-configuration binds this
|
||||
# block itself and is not processed until the master switch is true.
|
||||
APP_FILESERVER_PLATFORM_ENABLED=false
|
||||
APP_FILESERVER_PLATFORM_INSTANCE_ID=local-node
|
||||
APP_FILESERVER_PLATFORM_DEFAULT_NAMESPACE=default
|
||||
|
||||
# Storage root must be an absolute path on its own volume, never under a web or config root.
|
||||
APP_FILESERVER_PLATFORM_STORAGE_ROOT=/var/lib/backend/files
|
||||
APP_FILESERVER_PLATFORM_STORAGE_PUBLISH_MODE=atomic-move-preferred
|
||||
APP_FILESERVER_PLATFORM_STORAGE_BUFFER_SIZE=128KB
|
||||
APP_FILESERVER_PLATFORM_STORAGE_FORBIDDEN_ROOT_ANCESTORS=/app,/etc,/usr/share/nginx/html
|
||||
|
||||
# Shared with spring.servlet.multipart.* so the container and the policy cannot disagree.
|
||||
APP_FILESERVER_PLATFORM_UPLOAD_MAX_FILE_SIZE=100MB
|
||||
APP_FILESERVER_PLATFORM_UPLOAD_MAX_REQUEST_SIZE=110MB
|
||||
APP_FILESERVER_PLATFORM_UPLOAD_INITIAL_RESERVATION=8MB
|
||||
APP_FILESERVER_PLATFORM_UPLOAD_MAX_PARTS=16
|
||||
APP_FILESERVER_PLATFORM_UPLOAD_TTL=1h
|
||||
APP_FILESERVER_PLATFORM_UPLOAD_RESERVATION_TTL=24h
|
||||
APP_FILESERVER_PLATFORM_UPLOAD_LEASE_DURATION=30s
|
||||
APP_FILESERVER_PLATFORM_UPLOAD_REQUIRE_CONTENT_LENGTH=false
|
||||
|
||||
APP_FILESERVER_PLATFORM_DOWNLOAD_CACHE_CONTROL=private, no-store
|
||||
APP_FILESERVER_PLATFORM_DOWNLOAD_INLINE_ALLOWED=false
|
||||
APP_FILESERVER_PLATFORM_DOWNLOAD_MAX_RANGES=1
|
||||
APP_FILESERVER_PLATFORM_DOWNLOAD_MAX_RANGE_BYTES=100MB
|
||||
APP_FILESERVER_PLATFORM_DOWNLOAD_ZERO_COPY_ENABLED=true
|
||||
APP_FILESERVER_PLATFORM_DOWNLOAD_ZERO_COPY_MINIMUM_BYTES=16MB
|
||||
|
||||
APP_FILESERVER_PLATFORM_TRANSFER_CORE_SIZE=8
|
||||
APP_FILESERVER_PLATFORM_TRANSFER_MAX_SIZE=32
|
||||
APP_FILESERVER_PLATFORM_TRANSFER_QUEUE_CAPACITY=64
|
||||
APP_FILESERVER_PLATFORM_TRANSFER_AWAIT_SECONDS=300
|
||||
|
||||
# required | role-based | unenforced (unenforced is refused under a production profile).
|
||||
APP_FILESERVER_PLATFORM_SECURITY_ACCESS_POLICY=required
|
||||
APP_FILESERVER_PLATFORM_SECURITY_READ_ROLES=ROLE_FILE_READ
|
||||
APP_FILESERVER_PLATFORM_SECURITY_WRITE_ROLES=ROLE_FILE_WRITE
|
||||
APP_FILESERVER_PLATFORM_SECURITY_ADMIN_ROLES=ROLE_FILE_ADMIN
|
||||
|
||||
APP_FILESERVER_PLATFORM_VERIFICATION_TIMEOUT=5s
|
||||
APP_FILESERVER_PLATFORM_VERIFICATION_REQUIRE_MEDIA_TYPE_VERDICT=false
|
||||
APP_FILESERVER_PLATFORM_VERIFICATION_INLINE_SAFE_PROFILE=false
|
||||
|
||||
APP_FILESERVER_PLATFORM_QUOTA_INSTANCE_UPLOAD_PERMITS=16
|
||||
APP_FILESERVER_PLATFORM_QUOTA_SCOPE_UPLOAD_PERMITS=4
|
||||
APP_FILESERVER_PLATFORM_QUOTA_DIRECT_DOWNLOAD_PERMITS=64
|
||||
APP_FILESERVER_PLATFORM_QUOTA_SOFT_HIGH_WATER=0.70
|
||||
APP_FILESERVER_PLATFORM_QUOTA_HARD_HIGH_WATER=0.85
|
||||
|
||||
APP_FILESERVER_PLATFORM_ADMIN_ENABLED=false
|
||||
APP_FILESERVER_PLATFORM_ADMIN_ORPHAN_MINIMUM_AGE=1h
|
||||
|
||||
APP_FILESERVER_PLATFORM_CLEANUP_ENABLED=false
|
||||
APP_FILESERVER_PLATFORM_CLEANUP_INTERVAL=60s
|
||||
APP_FILESERVER_PLATFORM_CLEANUP_MAX_ITEMS=100
|
||||
APP_FILESERVER_PLATFORM_CLEANUP_MAX_BYTES=1GB
|
||||
APP_FILESERVER_PLATFORM_CLEANUP_RETRY_BACKOFF=5m
|
||||
|
||||
APP_FILESERVER_PLATFORM_TUS_ENABLED=false
|
||||
APP_FILESERVER_PLATFORM_HTTPBIS_DRAFT12_ENABLED=false
|
||||
|
||||
APP_FILESERVER_PLATFORM_NGINX_ENABLED=false
|
||||
APP_FILESERVER_PLATFORM_NGINX_INTERNAL_PREFIX=/__files/
|
||||
APP_FILESERVER_PLATFORM_NGINX_OBJECT_SUFFIX=.bin
|
||||
APP_FILESERVER_PLATFORM_NGINX_MINIMUM_SIZE=16MB
|
||||
|
||||
APP_FILESERVER_PLATFORM_OBSERVABILITY_METRICS_ENABLED=true
|
||||
# Secret. Required while metrics are enabled; an unkeyed digest of an enumerable id is reversible.
|
||||
APP_FILESERVER_PLATFORM_OBSERVABILITY_FINGERPRINT_KEY=
|
||||
|
||||
# ----- HTTP Client platform (app.httpclient.*) -----
|
||||
# The single switch for outbound HTTP. False means no HTTP client property is bound, and no
|
||||
# transport provider, connection pool, TLS context, credential, thread or gateway is created.
|
||||
# The per-client surface is indexed and per-deployment, so it is set directly in the environment
|
||||
# rather than declared here; docs/httpclient/env-fields.yaml is its registry, and an
|
||||
# APP_HTTPCLIENT_ variable that is not in that registry fails startup.
|
||||
APP_HTTPCLIENT_ENABLED=false
|
||||
@@ -0,0 +1,369 @@
|
||||
# =============================================================================
|
||||
# The public catalogue of every environment variable this application reads.
|
||||
#
|
||||
# Generated from docs/registries/env-keys.yaml, which is the SSOT. Copy this file to src/.env and
|
||||
# fill in the values your deployment needs; src/.env is gitignored because it is operator input,
|
||||
# not a build input.
|
||||
#
|
||||
# Secret-classified keys are left empty on purpose. An example that carries a working credential
|
||||
# is a credential in the repository, and the fact that it is 'only an example' is not something a
|
||||
# scanner, a fork, or a hurried operator can tell.
|
||||
#
|
||||
# A key left blank here uses the inline default in application.yml. Seven values have no default
|
||||
# at all — the datasource URL, username and password, the application name, and the JWT issuer and
|
||||
# audience — because a default for any of them is a deployment running against something nobody
|
||||
# chose.
|
||||
# =============================================================================
|
||||
|
||||
# ---- Configuration -----------------------------------------------------------
|
||||
SPRING_PROFILES_ACTIVE=
|
||||
APP_NAME=
|
||||
APP_SERVER_PORT=8080
|
||||
MANAGEMENT_SERVER_PORT=9001
|
||||
APP_SERVER_SHUTDOWN=graceful
|
||||
APP_SERVER_SHUTDOWN_TIMEOUT=30s
|
||||
APP_SERVER_FORWARD_HEADERS_STRATEGY=framework
|
||||
APP_SERVER_TOMCAT_MAX_THREADS=200
|
||||
APP_SERVER_TOMCAT_MIN_SPARE_THREADS=10
|
||||
APP_SERVER_TOMCAT_ACCEPT_COUNT=100
|
||||
APP_SERVER_TOMCAT_MAX_CONNECTIONS=8192
|
||||
APP_SERVER_TOMCAT_CONNECTION_TIMEOUT=20s
|
||||
APP_SERVER_COMPRESSION_ENABLED=true
|
||||
APP_SERVER_COMPRESSION_MIN_RESPONSE_SIZE=1KB
|
||||
APP_SERVER_ERROR_INCLUDE_STACKTRACE=never
|
||||
APP_SERVER_ERROR_INCLUDE_MESSAGE=never
|
||||
APP_ERROR_DETAIL_EXPOSURE_ENABLED=false
|
||||
APP_LOG_BODY_CAPTURE_ENABLED=false
|
||||
APP_MULTI_INSTANCE_ENABLED=false
|
||||
APP_MIGRATION_ON_STARTUP=true
|
||||
APP_DATASOURCE_URL=
|
||||
APP_DATASOURCE_USERNAME=
|
||||
APP_DATASOURCE_POOL_MAX_SIZE=10
|
||||
APP_DATASOURCE_POOL_MIN_IDLE=2
|
||||
APP_DATASOURCE_CONNECTION_TIMEOUT=5s
|
||||
APP_DATASOURCE_DRIVER=org.postgresql.Driver
|
||||
APP_DATASOURCE_DDL_AUTO=validate
|
||||
APP_DATASOURCE_SHOW_SQL=false
|
||||
APP_DATASOURCE_FORMAT_SQL=false
|
||||
APP_DATASOURCE_OPEN_IN_VIEW=false
|
||||
APP_DATASOURCE_POOL_IDLE_TIMEOUT=600000
|
||||
APP_DATASOURCE_POOL_MAX_LIFETIME=1800000
|
||||
OTEL_EXPORTER_OTLP_ENDPOINT=
|
||||
APP_TRACING_ENABLED=true
|
||||
APP_TRACING_SAMPLE_RATE=
|
||||
APP_LOG_LEVEL_ROOT=INFO
|
||||
APP_LOG_LEVEL_APP=INFO
|
||||
APP_LOG_LEVEL_SPRING=INFO
|
||||
APP_LOG_LEVEL_WEB=INFO
|
||||
APP_LOG_LEVEL_SQL=WARN
|
||||
APP_LOG_FILE_ENABLED=false
|
||||
APP_LOG_FILE_PATH=logs/ca-skeleton.json
|
||||
APP_LOG_FILE_MAX_SIZE=100MB
|
||||
APP_LOG_FILE_MAX_HISTORY=14
|
||||
APP_LOG_FILE_TOTAL_SIZE_CAP=3GB
|
||||
APP_LOG_ASYNC_ENABLED=true
|
||||
APP_LOG_ASYNC_QUEUE_SIZE=512
|
||||
APP_LOG_ASYNC_DISCARDING_THRESHOLD=20
|
||||
APP_LOG_JSON_TIMEZONE=UTC
|
||||
APP_LOG_JSON_TIMESTAMP_PATTERN=yyyy-MM-dd'T'HH:mm:ss.SSSXXX
|
||||
APP_LOG_JSON_INCLUDE_CALLER_DATA=false
|
||||
APP_LOG_JSON_LOGGER_NAME_LENGTH=0
|
||||
APP_LOG_SAMPLING_RATE=1.0
|
||||
APP_SECURITY_CORS_ORIGINS=
|
||||
APP_SECURITY_CORS_ENABLED=false
|
||||
APP_SECURITY_CORS_ALLOWED_METHODS=
|
||||
APP_SECURITY_CORS_ALLOWED_HEADERS=*
|
||||
APP_SECURITY_CORS_ALLOW_CREDENTIALS=false
|
||||
APP_SECURITY_CORS_MAX_AGE=600s
|
||||
APP_SECURITY_AUTH_MODE=jwt
|
||||
APP_SESSION_COOKIE_NAME=CA_SESSION
|
||||
APP_SESSION_COOKIE_SECURE=true
|
||||
APP_SESSION_COOKIE_HTTP_ONLY=true
|
||||
APP_SESSION_COOKIE_SAME_SITE=Lax
|
||||
APP_SESSION_COOKIE_PATH=/
|
||||
APP_SESSION_CSRF_COOKIE_NAME=XSRF-TOKEN
|
||||
APP_SESSION_CSRF_HEADER_NAME=X-XSRF-TOKEN
|
||||
APP_SESSION_REDIS_NAMESPACE_ENVIRONMENT=local
|
||||
APP_SESSION_IDLE_TIMEOUT=30m
|
||||
APP_SESSION_ABSOLUTE_LIFETIME=8h
|
||||
APP_SESSION_TOUCH_INTERVAL=1m
|
||||
APP_SESSION_TOMBSTONE_TTL=5m
|
||||
APP_SESSION_MAXIMUM_ENVELOPE_BYTES=32768
|
||||
APP_SESSION_MAXIMUM_ATTRIBUTES=64
|
||||
APP_SESSION_MAXIMUM_SCALAR_BYTES=8192
|
||||
APP_SECURITY_JWT_ISSUER=
|
||||
APP_SECURITY_JWT_AUDIENCE=
|
||||
APP_SECURITY_JWT_JWKS_URI=
|
||||
APP_SECURITY_JWT_CLOCK_SKEW=60s
|
||||
APP_TENANT_ENABLED=false
|
||||
APP_RATE_LIMIT_ENABLED=false
|
||||
APP_RATE_LIMIT_CLIENT_IP_MODE=remote-addr-only
|
||||
APP_RATE_LIMIT_REDIS_ENABLED=false
|
||||
APP_RATE_LIMIT_PROVIDER=disabled
|
||||
APP_RATE_LIMIT_ROLE=coordination
|
||||
APP_RATE_LIMIT_FAILURE_POLICY=fail-closed
|
||||
APP_RATE_LIMIT_DEFAULT_POLICY_ID=api-default
|
||||
APP_RATE_LIMIT_FAILURE_RETRY_AFTER=100ms
|
||||
APP_RATE_LIMIT_HASH_KEY_VERSION=1
|
||||
APP_RATE_LIMIT_KEY_VERSION=1
|
||||
APP_RATE_LIMIT_REDIS_HOST=
|
||||
APP_RATE_LIMIT_REDIS_PORT=6379
|
||||
APP_RATE_LIMIT_REDIS_TRUST_PEM=
|
||||
APP_SESSION_REDIS_TRUST_PEM=
|
||||
APP_RATE_LIMIT_REDIS_COMMAND_TIMEOUT=1s
|
||||
APP_RATE_LIMIT_REDIS_MAXIMUM_COMMAND_BYTES=16384
|
||||
APP_RATE_LIMIT_REDIS_MAXIMUM_QUEUED_COMMANDS=32
|
||||
APP_RATE_LIMIT_REDIS_MAXIMUM_IN_FLIGHT_BYTES=1048576
|
||||
APP_RATE_LIMIT_REDIS_NAMESPACE_ENVIRONMENT=local
|
||||
APP_RATE_LIMIT_POLICY_REVISION=v1
|
||||
APP_RATE_LIMIT_ALGORITHM=sliding-counter
|
||||
APP_RATE_LIMIT_LIMIT=100
|
||||
APP_RATE_LIMIT_WINDOW=1s
|
||||
APP_RATE_LIMIT_CAPACITY=100
|
||||
APP_RATE_LIMIT_REFILL_TOKENS=100
|
||||
APP_RATE_LIMIT_REFILL_PERIOD=1s
|
||||
APP_RATE_LIMIT_MAXIMUM_COST=10
|
||||
APP_RATE_LIMIT_CLEANUP_GRACE=5s
|
||||
APP_RATE_LIMIT_MAXIMUM_CLOCK_REGRESSION=250ms
|
||||
APP_IDEMPOTENCY_TTL=24h
|
||||
APP_IDEMPOTENCY_PROVIDER=jdbc
|
||||
APP_IDEMPOTENCY_REDIS_NAMESPACE_ENVIRONMENT=local
|
||||
APP_IDEMPOTENCY_PROCESSING_LEASE=30s
|
||||
APP_IDEMPOTENCY_FAILURE_RETENTION=24h
|
||||
APP_LEASE_PROVIDER=disabled
|
||||
APP_LEASE_REDIS_NAMESPACE_ENVIRONMENT=local
|
||||
APP_LEASE_REDIS_DRIFT_BUDGET=10ms
|
||||
APP_CACHE_CANONICAL_DEFAULT_PROVIDER=disabled
|
||||
APP_REDIS_ENABLED=false
|
||||
APP_CACHE_REDIS_POSITIVE_HARD_TTL=5m
|
||||
APP_CACHE_REDIS_NEGATIVE_TTL=10s
|
||||
APP_IDEMPOTENCY_REDIS_COMMAND_TIMEOUT=200ms
|
||||
APP_LEASE_REDIS_COMMAND_TIMEOUT=200ms
|
||||
APP_LEASE_REDIS_CONTENTION_RETRY_AFTER=50ms
|
||||
APP_REDIS_ACKNOWLEDGED_WRITE_LOSS_ACCEPTED=false
|
||||
APP_REDIS_ADMIN_CREDENTIAL_REFERENCE=
|
||||
APP_REDIS_ADMIN_ENABLED=false
|
||||
APP_REDIS_ADVANCED_ENABLED=false
|
||||
APP_REDIS_ADVANCED_POLICIES=
|
||||
APP_REDIS_BLOCKING_MAX_BLOCK=30s
|
||||
APP_REDIS_BLOCKING_MAX_CONNECTIONS=32
|
||||
APP_REDIS_DATABASE=0
|
||||
APP_REDIS_LIMITS_MAX_BATCH_COMMANDS=500
|
||||
APP_REDIS_LIMITS_MAX_BATCH_REPLY_BYTES=16777216
|
||||
APP_REDIS_LIMITS_MAX_BATCH_REQUEST_BYTES=4194304
|
||||
APP_REDIS_LIMITS_MAX_BITMAP_OFFSET=10000000
|
||||
APP_REDIS_LIMITS_MAX_COLLECTION_ELEMENTS=1000
|
||||
APP_REDIS_LIMITS_MAX_HASH_FIELD_VALUE_BYTES=524288
|
||||
APP_REDIS_LIMITS_MAX_KEY_BYTES=512
|
||||
APP_REDIS_LIMITS_MAX_SCAN_COUNT=500
|
||||
APP_REDIS_LIMITS_MAX_STREAM_PAYLOAD_BYTES=262144
|
||||
APP_REDIS_LIMITS_MAX_VALUE_BYTES=1048576
|
||||
APP_REDIS_LIMITS_OFFLINE_QUEUE_COMMANDS=1000
|
||||
APP_REDIS_MODE=standalone
|
||||
APP_REDIS_NAMESPACE_DOMAIN=shared
|
||||
APP_REDIS_NAMESPACE_ENVIRONMENT=local
|
||||
APP_REDIS_NAMESPACE_SERVICE=sample-service
|
||||
APP_REDIS_NODES=localhost:6379
|
||||
APP_REDIS_RAW_CREDENTIAL_REFERENCE=
|
||||
APP_REDIS_RAW_ENABLED=false
|
||||
APP_REDIS_RAW_POLICY_RESOURCE=classpath:redis-sdk/raw-command-allowlist.yml
|
||||
APP_REDIS_TIMEOUT_ADMIN=3s
|
||||
APP_REDIS_TIMEOUT_BATCH=2s
|
||||
APP_REDIS_TIMEOUT_COLLECTION=2s
|
||||
APP_REDIS_TIMEOUT_FAST=500ms
|
||||
APP_REDIS_TIMEOUT_SCRIPT=1s
|
||||
APP_REDIS_TRANSACTION_MAX_CONNECTIONS=16
|
||||
APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE=
|
||||
APP_REDIS_AUTHENTICATION_ANONYMOUS_ACCESS_ACCEPTED=false
|
||||
APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE=
|
||||
APP_REDIS_AUTHENTICATION_PUBSUB_CREDENTIAL_REFERENCE=
|
||||
APP_REDIS_CAPACITY_MAXIMUM_IN_FLIGHT_BYTES=
|
||||
APP_REDIS_CAPACITY_MAXIMUM_IN_FLIGHT_COMMANDS=64
|
||||
APP_REDIS_CAPACITY_MAXIMUM_REPLY_BYTES=
|
||||
APP_REDIS_CAPACITY_REJECT_WHEN_DISCONNECTED=true
|
||||
APP_REDIS_CLUSTER_MAXIMUM_REDIRECTS=5
|
||||
APP_REDIS_CLUSTER_TOPOLOGY_REFRESH_PERIOD=30s
|
||||
APP_REDIS_LIFECYCLE_ACQUIRE_TIMEOUT=2s
|
||||
APP_REDIS_LIFECYCLE_CLIENT_NAME=ca-skeleton
|
||||
APP_REDIS_LIFECYCLE_CONNECT_TIMEOUT=2s
|
||||
APP_REDIS_LIFECYCLE_DRAIN_TIMEOUT=6s
|
||||
APP_REDIS_LIFECYCLE_SHUTDOWN_QUIET_PERIOD=100ms
|
||||
APP_REDIS_LIFECYCLE_SHUTDOWN_TIMEOUT=3s
|
||||
APP_REDIS_LIFECYCLE_TLS_HANDSHAKE_TIMEOUT=3s
|
||||
APP_REDIS_PUBSUB_BUFFER_CAPACITY=1024
|
||||
APP_REDIS_PUBSUB_OVERFLOW_POLICY=error
|
||||
APP_REDIS_SENTINEL_CREDENTIAL_REFERENCE=
|
||||
APP_REDIS_SENTINEL_MASTER_NAME=
|
||||
APP_REDIS_SENTINEL_NODES=app.redis.nodes
|
||||
APP_REDIS_TLS_CLIENT_CERTIFICATE_RESOURCE=
|
||||
APP_REDIS_TLS_CLIENT_KEY_REFERENCE=
|
||||
APP_REDIS_TLS_ENABLED=false
|
||||
APP_REDIS_TLS_HOSTNAME_VERIFICATION=true
|
||||
APP_REDIS_TLS_TRUST_MATERIAL_RESOURCE=
|
||||
APP_CACHE_REDIS_ENABLED=false
|
||||
APP_CACHE_REDIS_CLIENT_MODE=managed
|
||||
APP_CACHE_REDIS_HOST=
|
||||
APP_CACHE_REDIS_PORT=6379
|
||||
APP_CACHE_REDIS_TRUST_PEM=
|
||||
APP_REDIS_SEMANTIC_PROBE_MINIMUM_INTERVAL=5s
|
||||
APP_REDIS_SENTINEL_DISCOVERY_REFRESH_PERIOD=30s
|
||||
APP_REDIS_SEMANTIC_PROBE_MAXIMUM_STALENESS=15s
|
||||
APP_CACHE_REDIS_COMMAND_TIMEOUT=2s
|
||||
APP_CACHE_REDIS_MAXIMUM_QUEUED_COMMANDS=8
|
||||
APP_CACHE_REDIS_MAXIMUM_IN_FLIGHT_BYTES=16777216
|
||||
APP_CACHE_REDIS_POSITIVE_SOFT_TTL=
|
||||
APP_CACHE_REDIS_TTL_JITTER=0.10
|
||||
APP_CACHE_REDIS_MINIMUM_HARD_TTL=1s
|
||||
APP_CACHE_REDIS_NAMESPACE_ENVIRONMENT=local
|
||||
APP_CACHE_REDIS_SEMANTIC_REGION=default
|
||||
APP_CACHE_REDIS_MAXIMUM_VALUE_BYTES=1048576
|
||||
APP_CACHE_REDIS_L1_ENABLED=false
|
||||
APP_CACHE_REDIS_L1_MAXIMUM_ENTRIES=10000
|
||||
APP_CACHE_REDIS_L1_MAXIMUM_WEIGHT_BYTES=67108864
|
||||
APP_CACHE_REDIS_L1_MAXIMUM_ENTRY_WEIGHT_BYTES=1048576
|
||||
APP_CACHE_REDIS_L1_TTL=30s
|
||||
APP_CACHE_REDIS_L1_GENERATION_RECHECK_INTERVAL=5s
|
||||
APP_CACHE_REDIS_L1_INVALIDATION_QUEUE_CAPACITY=1024
|
||||
APP_CACHE_DEFAULT_TTL=300s
|
||||
APP_CACHE_NEGATIVE_TTL=60s
|
||||
APP_MESSAGING_BROKER=
|
||||
APP_MESSAGING_KAFKA_BROKERS=
|
||||
APP_NOTIFICATION_SLACK_PROVIDER=
|
||||
APP_NOTIFICATION_EMAIL_PROVIDER=
|
||||
APP_FILESERVER_ENABLED=false
|
||||
APP_FILESERVER_LOCAL_ROOT=
|
||||
APP_FILESERVER_LOCAL_EXPECTED_FILE_STORE_NAME=
|
||||
APP_FILESERVER_LOCAL_EXPECTED_FILE_STORE_TYPE=
|
||||
APP_FILESERVER_LOCAL_MOUNT_SENTINEL_SHA256=
|
||||
APP_FILESERVER_LOCAL_EXPECTED_OWNER=
|
||||
APP_HTTPCLIENT_ENABLED=false
|
||||
APP_FILESERVER_PLATFORM_ENABLED=false
|
||||
APP_FILESERVER_PLATFORM_INSTANCE_ID=local-node
|
||||
APP_FILESERVER_PLATFORM_DEFAULT_NAMESPACE=default
|
||||
APP_FILESERVER_PLATFORM_STORAGE_ROOT=/var/lib/backend/files
|
||||
APP_FILESERVER_PLATFORM_STORAGE_PUBLISH_MODE=atomic-move-preferred
|
||||
APP_FILESERVER_PLATFORM_STORAGE_BUFFER_SIZE=128KB
|
||||
APP_FILESERVER_PLATFORM_STORAGE_FORBIDDEN_ROOT_ANCESTORS=/app,/etc,/usr/share/nginx/html
|
||||
APP_FILESERVER_PLATFORM_UPLOAD_MAX_FILE_SIZE=100MB
|
||||
APP_FILESERVER_PLATFORM_UPLOAD_MAX_REQUEST_SIZE=110MB
|
||||
APP_FILESERVER_PLATFORM_UPLOAD_INITIAL_RESERVATION=8MB
|
||||
APP_FILESERVER_PLATFORM_UPLOAD_MAX_PARTS=16
|
||||
APP_FILESERVER_PLATFORM_UPLOAD_TTL=1h
|
||||
APP_FILESERVER_PLATFORM_UPLOAD_RESERVATION_TTL=24h
|
||||
APP_FILESERVER_PLATFORM_UPLOAD_LEASE_DURATION=30s
|
||||
APP_FILESERVER_PLATFORM_UPLOAD_REQUIRE_CONTENT_LENGTH=false
|
||||
APP_FILESERVER_PLATFORM_DOWNLOAD_CACHE_CONTROL=private, no-store
|
||||
APP_FILESERVER_PLATFORM_DOWNLOAD_INLINE_ALLOWED=false
|
||||
APP_FILESERVER_PLATFORM_DOWNLOAD_MAX_RANGES=1
|
||||
APP_FILESERVER_PLATFORM_DOWNLOAD_MAX_RANGE_BYTES=100MB
|
||||
APP_FILESERVER_PLATFORM_DOWNLOAD_ZERO_COPY_ENABLED=true
|
||||
APP_FILESERVER_PLATFORM_DOWNLOAD_ZERO_COPY_MINIMUM_BYTES=16MB
|
||||
APP_FILESERVER_PLATFORM_TRANSFER_CORE_SIZE=8
|
||||
APP_FILESERVER_PLATFORM_TRANSFER_MAX_SIZE=32
|
||||
APP_FILESERVER_PLATFORM_TRANSFER_QUEUE_CAPACITY=64
|
||||
APP_FILESERVER_PLATFORM_TRANSFER_AWAIT_SECONDS=300
|
||||
APP_FILESERVER_PLATFORM_SECURITY_ACCESS_POLICY=required
|
||||
APP_FILESERVER_PLATFORM_SECURITY_READ_ROLES=ROLE_FILE_READ
|
||||
APP_FILESERVER_PLATFORM_SECURITY_WRITE_ROLES=ROLE_FILE_WRITE
|
||||
APP_FILESERVER_PLATFORM_SECURITY_ADMIN_ROLES=ROLE_FILE_ADMIN
|
||||
APP_FILESERVER_PLATFORM_VERIFICATION_TIMEOUT=5s
|
||||
APP_FILESERVER_PLATFORM_VERIFICATION_REQUIRE_MEDIA_TYPE_VERDICT=false
|
||||
APP_FILESERVER_PLATFORM_VERIFICATION_INLINE_SAFE_PROFILE=false
|
||||
APP_FILESERVER_PLATFORM_QUOTA_INSTANCE_UPLOAD_PERMITS=16
|
||||
APP_FILESERVER_PLATFORM_QUOTA_SCOPE_UPLOAD_PERMITS=4
|
||||
APP_FILESERVER_PLATFORM_QUOTA_DIRECT_DOWNLOAD_PERMITS=64
|
||||
APP_FILESERVER_PLATFORM_QUOTA_SOFT_HIGH_WATER=0.70
|
||||
APP_FILESERVER_PLATFORM_QUOTA_HARD_HIGH_WATER=0.85
|
||||
APP_FILESERVER_PLATFORM_ADMIN_ENABLED=false
|
||||
APP_FILESERVER_PLATFORM_ADMIN_ORPHAN_MINIMUM_AGE=1h
|
||||
APP_FILESERVER_PLATFORM_CLEANUP_ENABLED=false
|
||||
APP_FILESERVER_PLATFORM_CLEANUP_INTERVAL=60s
|
||||
APP_FILESERVER_PLATFORM_CLEANUP_MAX_ITEMS=100
|
||||
APP_FILESERVER_PLATFORM_CLEANUP_MAX_BYTES=1GB
|
||||
APP_FILESERVER_PLATFORM_CLEANUP_RETRY_BACKOFF=5m
|
||||
APP_FILESERVER_PLATFORM_TUS_ENABLED=false
|
||||
APP_FILESERVER_PLATFORM_HTTPBIS_DRAFT12_ENABLED=false
|
||||
APP_FILESERVER_PLATFORM_NGINX_ENABLED=false
|
||||
APP_FILESERVER_PLATFORM_NGINX_INTERNAL_PREFIX=/__files/
|
||||
APP_FILESERVER_PLATFORM_NGINX_OBJECT_SUFFIX=.bin
|
||||
APP_FILESERVER_PLATFORM_NGINX_MINIMUM_SIZE=16MB
|
||||
APP_FILESERVER_PLATFORM_OBSERVABILITY_METRICS_ENABLED=true
|
||||
APP_FILE_UPLOAD_MAX_SIZE=10MB
|
||||
APP_FILE_UPLOAD_GLOBAL_REQUEST_MAX_SIZE=12MB
|
||||
APP_ASYNC_EXECUTOR_CORE_SIZE=10
|
||||
APP_ASYNC_EXECUTOR_MAX_SIZE=50
|
||||
APP_ASYNC_EXECUTOR_QUEUE_CAPACITY=200
|
||||
APP_PERSISTENCE_JPA_ENABLED=false
|
||||
APP_PERSISTENCE_MONGO_ENABLED=false
|
||||
APP_PERSISTENCE_MONGO_ACTIVE_PROFILE=
|
||||
APP_MESSAGING_ENABLED=false
|
||||
APP_GRAPHQL_ENABLED=false
|
||||
APP_GRAPHQL_DEPLOYMENT_MODE=
|
||||
APP_OUTBOX_ENABLED=false
|
||||
APP_OUTBOX_RELAY_ENABLED=false
|
||||
APP_NOTIFICATION_PLATFORM_ENABLED=false
|
||||
APP_NOTIFICATION_PLATFORM_MODE=SERVING
|
||||
# OpenAPI exposure. application-prod.yml pins both false regardless of these.
|
||||
APP_OPENAPI_DOCS_ENABLED=true
|
||||
APP_OPENAPI_UI_ENABLED=true
|
||||
# The shipped SMTP provider profile and the relay it uses. Off by default; the relay address
|
||||
# itself is spring.mail.* (SPRING_MAIL_HOST / SPRING_MAIL_PORT), not repeated here.
|
||||
APP_NOTIFICATION_PLATFORM_SMTP_ENABLED=false
|
||||
APP_NOTIFICATION_PLATFORM_SMTP_PRIMARY=true
|
||||
APP_NOTIFICATION_PLATFORM_SMTP_ENVIRONMENT=local
|
||||
APP_NOTIFICATION_PLATFORM_SMTP_CREDENTIAL_PROFILE=default
|
||||
APP_NOTIFICATION_PLATFORM_SMTP_TIMEOUT=10s
|
||||
APP_NOTIFICATION_PLATFORM_SMTP_MAX_CONCURRENCY=4
|
||||
APP_NOTIFICATION_PLATFORM_SMTP_RATE_PER_SECOND=10
|
||||
APP_NOTIFICATION_PLATFORM_SMTP_TLS_MODE=STARTTLS_REQUIRED
|
||||
APP_NOTIFICATION_PLATFORM_SMTP_SENDER_IDENTITY=no-reply@example.invalid
|
||||
APP_NOTIFICATION_PLATFORM_SMTP_CONNECT_TIMEOUT=5s
|
||||
APP_NOTIFICATION_PLATFORM_SMTP_READ_TIMEOUT=10s
|
||||
APP_NOTIFICATION_PLATFORM_SMTP_WRITE_TIMEOUT=10s
|
||||
APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY=4
|
||||
APP_NOTIFICATION_PLATFORM_CLAIM_BATCH_SIZE=50
|
||||
APP_NOTIFICATION_PLATFORM_LEASE_DURATION=2m
|
||||
APP_NOTIFICATION_PLATFORM_POLL_INTERVAL=1s
|
||||
APP_NOTIFICATION_PLATFORM_MAX_CONCURRENCY=64
|
||||
APP_NOTIFICATION_PLATFORM_MAX_ADDITIONAL_ATTEMPTS=4
|
||||
APP_NOTIFICATION_PLATFORM_MAX_QUEUE_AGE=24h
|
||||
APP_NOTIFICATION_PLATFORM_ALLOW_AMBIGUOUS_FALLBACK=false
|
||||
APP_NOTIFICATION_PLATFORM_CALLBACKS_ENABLED=false
|
||||
APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES=65508
|
||||
APP_NOTIFICATION_PLATFORM_CALLBACK_REPLAY_SKEW=5m
|
||||
|
||||
# ---- Secrets — supply out of band; never commit a value here ------------------
|
||||
APP_DATASOURCE_PASSWORD=
|
||||
APP_PRIVACY_PSEUDONYMIZATION_SALT=
|
||||
APP_SECURITY_JWT_SIGNING_KEY=
|
||||
APP_RATE_LIMIT_REDIS_PASSWORD=
|
||||
APP_RATE_LIMIT_REDIS_KEY_HMAC_SECRET=
|
||||
APP_SESSION_REDIS_PASSWORD=
|
||||
APP_SESSION_REDIS_KEY_HMAC_SECRET=
|
||||
APP_IDEMPOTENCY_REDIS_KEY_HMAC_SECRET=
|
||||
APP_LEASE_REDIS_KEY_HMAC_SECRET=
|
||||
APP_CACHE_REDIS_PASSWORD=
|
||||
APP_CACHE_REDIS_KEY_HMAC_SECRET=
|
||||
APP_FILESERVER_PLATFORM_OBSERVABILITY_FINGERPRINT_KEY=
|
||||
# The notification platform's eight key purposes. Each is base64 of at least 32 bytes and must
|
||||
# differ from the other seven; the platform decodes all eight at startup and refuses to boot if one
|
||||
# is blank, short or shared. Only needed when APP_NOTIFICATION_PLATFORM_ENABLED=true.
|
||||
APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY=
|
||||
APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY=
|
||||
APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY=
|
||||
APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY=
|
||||
APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY=
|
||||
APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY=
|
||||
APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY=
|
||||
APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY=
|
||||
# The id each of those keys is active under — an identifier, not secret material, and required:
|
||||
# rotating the material without changing the id makes the new ciphertext indistinguishable from the
|
||||
# old. Any stable string per purpose; change it whenever the matching key changes.
|
||||
APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY_ID=
|
||||
APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY_ID=
|
||||
APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY_ID=
|
||||
APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY_ID=
|
||||
APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY_ID=
|
||||
APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY_ID=
|
||||
APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY_ID=
|
||||
APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY_ID=
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user