83 lines
3.5 KiB
Markdown
83 lines
3.5 KiB
Markdown
# Multi-instance Runtime Contract
|
|
|
|
## Goal
|
|
|
|
Close tech-lead finding C2 without inventing placeholder coordination beans.
|
|
|
|
ca-skeleton.runtime.multi-instance-enabled must describe a runtime capability that the shipped
|
|
composition can actually provide.
|
|
|
|
## Current defect
|
|
|
|
StartupSafetyValidator treats multi-instance mode as a promise that five named beans exist:
|
|
|
|
- distributedLockProvider
|
|
- cacheStampedeProtection
|
|
- outboxLeaderElection
|
|
- distributedRateLimiter
|
|
- migrationStartupRunner
|
|
|
|
Two names have no production definition at all. The unit test hides that by registering five plain
|
|
Object beans, and the shipped distributed-lock system test had to register unrelated fake siblings
|
|
just to prove the real JDBC lock composition.
|
|
|
|
The list also conflates unrelated concerns:
|
|
|
|
- cache refresh coordination is explicitly optional efficiency, not a correctness lock;
|
|
- edge rate limiting has its own transport/provider activation contract;
|
|
- outbox owns its own SKIP LOCKED coordination when the outbox capability is enabled;
|
|
- migration startup is not an instance-coordination provider.
|
|
|
|
## Canonical meaning
|
|
|
|
multi-instance-enabled=true selects the cross-instance implementation of the application
|
|
DistributedLockPort.
|
|
|
|
Therefore the runtime contract is:
|
|
|
|
1. capability dependency validation requires JPA/relational persistence;
|
|
2. persistence-jpa creates jdbcDistributedLock;
|
|
3. bootstrap creates the primary distributedLockProvider decorator;
|
|
4. StartupSafetyValidator verifies that the shipped distributed-lock provider exists and is a
|
|
DistributedLockPort.
|
|
|
|
No other capability is implicitly enabled by this switch.
|
|
|
|
Capability-specific distributed guarantees remain capability-specific:
|
|
|
|
- Redis edge rate limiting is required only when edge rate limiting is enabled and its provider is
|
|
selected;
|
|
- cache refresh coordination remains disabled unless a real CacheRefreshCoordinationPort
|
|
implementation is explicitly composed in a future slice;
|
|
- outbox coordination exists only with the outbox capability;
|
|
- migration startup follows the migration setting.
|
|
|
|
## Fail-closed behavior
|
|
|
|
When multi-instance mode is enabled but the distributed lock provider is absent or has the wrong
|
|
type, startup fails through the existing ADAPTER_ENABLEMENT / exit-72 path.
|
|
|
|
The validator does not accept arbitrary bean names as evidence for unrelated capabilities.
|
|
|
|
## Verification
|
|
|
|
- unit: missing/wrong-type distributedLockProvider fails; correct typed provider passes;
|
|
- system: real shipped H2/JPA composition starts with multi-instance enabled without any fake
|
|
cache/rate-limit/outbox coordination beans, and exposes both jdbcDistributedLock and the metered
|
|
distributedLockProvider;
|
|
- existing JPA-off dependency failure remains;
|
|
- app-bootstrap unit/system/architecture regressions stay green.
|
|
|
|
## Verified result
|
|
|
|
- the shipped system proof first failed exactly because the stale five-bean validator still required nonexistent sibling capabilities;
|
|
- StartupSafetyValidator now validates only the real distributedLockProvider contract and requires the bean to implement DistributedLockPort;
|
|
- name-only Object placeholders fail closed;
|
|
- the fake five-bean unit fixture is removed;
|
|
- the shipped H2/JPA composition starts with multi-instance mode enabled without fake cache, rate-limit, outbox, or migration siblings;
|
|
- CapabilityDependencyValidator still requires JPA when multi-instance mode is enabled;
|
|
- persistence-jpa distributed-lock tests: PASS;
|
|
- app-bootstrap Spotless, full test, full systemTest and architectureTest: PASS;
|
|
- stale phantom-bean contract scan: 0;
|
|
- git diff --check: PASS.
|