refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md
- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
(compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용
삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
208077fddf
commit
6d27356e2b
@@ -8,8 +8,7 @@
|
||||
# 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;
|
||||
# 3. `up --wait` for long-running services only, then the application's own health answer;
|
||||
# 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;
|
||||
@@ -28,6 +27,29 @@ RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$$"
|
||||
# is lowercased for the project while the evidence directory keeps the readable timestamp.
|
||||
PROJECT_RUN_ID="$(tr '[:upper:]' '[:lower:]' <<<"${RUN_ID}")"
|
||||
|
||||
# The lanes boot the qualification image: the application with every capability module on the
|
||||
# classpath (src/Dockerfile COMPOSITION, app-bootstrap qualificationBootJar). The default image is
|
||||
# the composition a service ships and carries none of them, so a lane that switches JPA or Kafka on
|
||||
# would have nothing to switch. docker-compose.yml passes this to the build and puts it in the tag.
|
||||
export COMPOSITION=qualification
|
||||
|
||||
# Every capability is on while its module is present, so each lane starts from all of them off and
|
||||
# its activationEnv turns on what it is about. The off-* lanes therefore prove that a present but
|
||||
# switched-off capability needs no infrastructure at all.
|
||||
CAPABILITIES_OFF='{
|
||||
"APP_PERSISTENCE_JPA_ENABLED": "false",
|
||||
"APP_REDIS_ENABLED": "false",
|
||||
"APP_MESSAGING_ENABLED": "false",
|
||||
"APP_PERSISTENCE_MONGO_ENABLED": "false",
|
||||
"APP_GRAPHQL_ENABLED": "false",
|
||||
"APP_HTTPCLIENT_ENABLED": "false",
|
||||
"APP_OBJECTSTORAGE_ENABLED": "false",
|
||||
"APP_WEBSOCKET_ENABLED": "false",
|
||||
"CASKELETON_GRPC_ENABLED": "false",
|
||||
"APP_FILESERVER_PLATFORM_ENABLED": "false",
|
||||
"APP_NOTIFICATION_PLATFORM_ENABLED": "false"
|
||||
}'
|
||||
|
||||
MODE=""
|
||||
SELECTED_LANE=""
|
||||
usage() {
|
||||
@@ -321,8 +343,8 @@ run_lane() {
|
||||
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)\""' \
|
||||
jq -r --argjson off "${CAPABILITIES_OFF}" --argjson override "${phase_override}" \
|
||||
'$off + .activationEnv + $override | to_entries[] | " \(.key): \"\(.value)\""' \
|
||||
<<<"${lane_json}"
|
||||
} >"${lane_overlay}"
|
||||
)
|
||||
@@ -384,59 +406,25 @@ run_lane() {
|
||||
#
|
||||
# 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.
|
||||
# empty file that looked exactly like a failed assertion.
|
||||
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.
|
||||
# not — and where there is none `--wait` returns as soon as the container is created.
|
||||
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
|
||||
wget -qO- "http://localhost:${management_port}/actuator/health" \
|
||||
>"${LANE_EVIDENCE}/health.json" 2>/dev/null \
|
||||
&& [[ -s "${LANE_EVIDENCE}/health.json" ]]; then
|
||||
return 0
|
||||
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
|
||||
|
||||
echo "${id}: the application never answered /actuator/health on port ${management_port}" >&2
|
||||
return 1
|
||||
}
|
||||
await_application_report || return 1
|
||||
|
||||
@@ -460,7 +448,7 @@ run_lane() {
|
||||
return 1
|
||||
fi
|
||||
redact_in_place "${LANE_EVIDENCE}/notification-smoke-phase1.log"
|
||||
cp "${LANE_EVIDENCE}/activation.json" "${LANE_EVIDENCE}/activation-phase1.json"
|
||||
cp "${LANE_EVIDENCE}/health.json" "${LANE_EVIDENCE}/health-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"
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
"""Fail when the HTTP Client Platform's code and documentation have drifted.
|
||||
|
||||
The design (§33 "Documentation") requires the support matrix, configuration reference, security
|
||||
guide, runbook, and migration guide to match the code. Review cannot hold that line by itself, so
|
||||
guide and runbook to match the code. Review cannot hold that line by itself, so
|
||||
this verifier extracts the names that are part of the public contract -- stable exceptions, metric
|
||||
names, configuration properties, startup violation codes, and transports -- and fails when one
|
||||
exists in code but nowhere in the documentation.
|
||||
@@ -30,7 +30,6 @@ REQUIRED_DOCS = [
|
||||
"security.md",
|
||||
"streaming.md",
|
||||
"operations.md",
|
||||
"migration-guide.md",
|
||||
"release-checklist.md",
|
||||
"performance-baseline.md",
|
||||
"repository-adaptation.md",
|
||||
|
||||
@@ -6,20 +6,18 @@
|
||||
# without provider infrastructure, and then reports -- explicitly -- which promotion evidence it
|
||||
# could NOT produce.
|
||||
#
|
||||
# Required promotion categories (MongoAdvancedPromotionEvidence.REQUIRED):
|
||||
# Required promotion categories (docs/adr/ADR-MONGO-ADV-001-capability-promotion.md):
|
||||
#
|
||||
# stable-platform, actual-topology, security, migration, failure, runbook
|
||||
#
|
||||
# `actual-topology` is the one that cannot be substituted. A container gives a functional pass for
|
||||
# sharding, search, vector and encryption while exercising none of the behaviour that makes them
|
||||
# Advanced rather than Stable: real shard distribution, a real analyzer, a real KMS. Atlas Local is
|
||||
# a pull-request convenience and is not release evidence -- see
|
||||
# MongoAtlasCapabilityContractSuite.Environment.
|
||||
# sharding and encryption while exercising none of the behaviour that makes them Advanced rather
|
||||
# than Stable: real shard distribution, a real KMS.
|
||||
#
|
||||
# Usage:
|
||||
# bash scripts/verify-mongodb-advanced.sh
|
||||
# MONGODB_DOCKER=1 bash scripts/verify-mongodb-advanced.sh
|
||||
# MONGODB_SHARDED_URI=... MONGODB_ATLAS_URI=... MONGODB_KMS=... bash scripts/verify-mongodb-advanced.sh
|
||||
# MONGODB_SHARDED_URI=... MONGODB_KMS=... bash scripts/verify-mongodb-advanced.sh
|
||||
#
|
||||
set -euo pipefail
|
||||
|
||||
@@ -52,8 +50,7 @@ fi
|
||||
|
||||
# --- failure + runbook (hermetic) -------------------------------------------------------------
|
||||
# Every Advanced refusal contract: disabled capability refuses construction, CSFLE/QE cannot share a
|
||||
# collection, QE substring/prefix/suffix unsupported on 8.0, a non-READY search index cannot serve,
|
||||
# undeclared scatter-gather is rejected, a dimension mismatch is refused.
|
||||
# collection, QE substring/prefix/suffix unsupported on 8.0, undeclared scatter-gather is rejected.
|
||||
echo ""
|
||||
echo "=== [failure] Advanced contract tests"
|
||||
if (cd "${GRADLE_DIR}" && "${GRADLE[@]}" "${MODULE}:test" --tests '*advanced*'); then
|
||||
@@ -64,7 +61,7 @@ fi
|
||||
|
||||
echo ""
|
||||
echo "=== [runbook] capability documentation"
|
||||
for doc in sharding time-series encryption search-vector multi-tenancy gridfs-migration; do
|
||||
for doc in sharding encryption multi-tenancy; do
|
||||
path="${REPO_ROOT}/docs/mongodb/advanced/${doc}.md"
|
||||
if [[ -f "${path}" ]]; then
|
||||
echo " + ${doc}.md"
|
||||
@@ -106,15 +103,7 @@ fi
|
||||
|
||||
# Present is not exercised. An environment variable proves somebody exported a string; the
|
||||
# contract is satisfied by a lane that ran against the deployment it names, which is why this
|
||||
# records the variable as *not yet* evidence until MONGO-REL-011's class has run.
|
||||
if [[ -n "${MONGODB_ATLAS_URI:-}" ]]; then
|
||||
echo "actual-topology(search/vector): MONGODB_ATLAS_URI present (lane not yet implemented)"
|
||||
MISSING_EVIDENCE+=("actual-topology: MONGO-REL-011 has no lane; an exported URI is not a run")
|
||||
else
|
||||
echo "actual-topology(search/vector): no MONGODB_ATLAS_URI"
|
||||
MISSING_EVIDENCE+=("actual-topology: search/vector on the actual target deployment")
|
||||
fi
|
||||
|
||||
# records the variable as *not yet* evidence until MONGO-REL-012's class has run.
|
||||
if [[ -n "${MONGODB_KMS:-}" ]]; then
|
||||
echo "actual-topology(encryption): MONGODB_KMS present (lane not yet implemented)"
|
||||
MISSING_EVIDENCE+=("actual-topology: MONGO-REL-012 has no lane; an exported KMS is not a run")
|
||||
@@ -154,8 +143,7 @@ if (( ${#MISSING_EVIDENCE[@]} > 0 )); then
|
||||
for entry in "${MISSING_EVIDENCE[@]}"; do echo " ~ ${entry}"; done
|
||||
echo ""
|
||||
echo "A capability stays opt-in until every category in"
|
||||
echo "MongoAdvancedPromotionEvidence.REQUIRED is supplied. See"
|
||||
echo "docs/adr/ADR-MONGO-ADV-001-capability-promotion.md."
|
||||
echo "docs/adr/ADR-MONGO-ADV-001-capability-promotion.md is supplied."
|
||||
echo "---------------------------------------------------------------"
|
||||
exit 2
|
||||
fi
|
||||
|
||||
@@ -99,7 +99,7 @@ echo "repository: ${REPO_ROOT}"
|
||||
# --- Always-on lanes -------------------------------------------------------------------------
|
||||
# Static analysis, architecture boundaries, unit and hermetic contract tests. These produce the
|
||||
# mapping, transaction, migration, change-stream and security evidence that does not need a server.
|
||||
run_lane "static-analysis" "check" -x "mongoStableContractTest" -x "verifyMongoReleaseContractLanes"
|
||||
run_lane "static-analysis" "check" -x "mongoStableContractTest"
|
||||
run_lane "mapping+transaction+migration+change-stream+security" "mongoStableContractTest"
|
||||
|
||||
# --- Container lanes -------------------------------------------------------------------------
|
||||
|
||||
Reference in New Issue
Block a user