Chapter 21 — Runtime Lifecycle and Traffic Admission
Chapter objective: After this chapter, a developer can define deployment lifecycle through Runtime state, registry freeze, readiness, and shutdown order without treating the presence of a Spring Context as DSM readiness.
Learning objectives
- Explain
CREATED → STARTING → RUNNING → STOPPING → CLOSED. - Explain why collection registration freezes at startup.
- Distinguish liveness, readiness, and diagnostics.
- Order ingress, background tasks, membership, and resource release during shutdown.
Prerequisites
- Runtime lifecycle from Chapter 2 and Spring assembly from Chapter 16 are complete.
- Diagnostics and last error from Chapter 19 are understood.
- The deployment platform can read readiness independently of process liveness.
Case progress
The fulfillment service begins a rolling deployment. An old instance stops taking new work before releasing resources; a new instance receives traffic only after collection freeze, membership/sync startup, and RUNNING. This avoids a window where the application process exists while the coordination plane is unready.
The state machine is a permission table
| State | Principal allowed action | Deployment meaning |
|---|---|---|
CREATED |
register collections and read static identity | no business traffic |
STARTING |
freeze registry and start lifecycle components | readiness false |
RUNNING |
serve local operations and background collaboration | isReady() true |
STOPPING |
stop ingress and background tasks | remove from load balancing |
CLOSED |
no further Runtime use | resources released |
ERROR |
read lastErrorMessage and recover |
no traffic; never report ready |
Why startup freezes the registry
A collection descriptor participates in capability/descriptor advertisement and sync routing. Adding one after communication begins creates a dynamic window in which some peers know the contract and others do not. Default registry freezes on start and rejects later registration. Dynamic registration would require an explicit migration protocol.
Liveness and readiness differ
- Liveness: process and main thread remain alive.
- Readiness: Runtime is RUNNING with required configuration and collections.
- Diagnostics: explains unready state such as ERROR and last error.
A context under construction, STARTING Runtime, or ERROR Runtime does
not report ready. DsmRuntimeLifecycle stops Runtime on
context close, while the deployment platform still removes traffic
first; a JVM shutdown hook alone is not a graceful-deployment
protocol.
Business meaning of shutdown order
- Set readiness false and stop new traffic.
- Drain local business requests and short tasks.
- Stop subscription consumers and repair/sync scheduler ingress.
- Close Runtime, membership, and transport resources.
- Record incomplete, uncertain, or compensating business actions.
DSM close releases local resources. It does not roll back committed order transactions or external effects.
Counterexample and fault injection
- Register a collection after Runtime start and expect registry-freeze rejection.
- Return HTTP 200 readiness during STARTING and identify the invalid traffic window.
- Close Spring Context and confirm Runtime is no longer RUNNING.
- Check only liveness after startup failure and observe how an ERROR node could receive traffic.
Experiment
cd submodule/dsm
mvn -q -pl dsm-runtime,dsm-spring-boot-autoconfigure -am \
-Dtest=DefaultDsmRuntimeTest,DefaultDsmCollectionRegistryTest,DsmAutoConfigurationTest,DsmSpringBootSmokeTest \
-Dsurefire.failIfNoSpecifiedTests=false testComplete lifecycle-drill.json with allowed action,
readiness, and failure handling for each state.
Experiment acceptance card
| Field | Content |
|---|---|
| Command | The focused Runtime registry and Spring lifecycle tests above |
| Input or fault | start, registration after freeze, context close, and startup failure |
| Observable result | explicit transitions; late registration rejected; lifecycle stopped after close |
| Evidence level | E2: real Runtime and Spring ApplicationContext lifecycle |
| This experiment does not prove | Deployment drain, real load-balancer removal, long-transaction compensation, or forced container termination |
Review
- CREATED/STARTING cannot take traffic; readiness begins at RUNNING.
- Registry freeze fixes the collection protocol surface after startup.
- Diagnostics explains ERROR; liveness does not admit it into the service pool.
- Graceful shutdown also depends on business ingress and deployment automation.
Next
Chapter 22 defines capacity evidence with a specific JMH hot path instead of converting one short-run number into a production SLA.