Feature Specification: Spring Boot 4.1 Upgrade¶
Metadata¶
Status: Done Author: nguyenhuuca Date: 2026-10-28 Related PRD: PRD-spring-boot-4-upgrade Related ADR: ADR-0033 Spring Boot 4.1 with a direct Jackson 3 migration Sequence diagrams: sequence-spring-boot-4-upgrade
Overview¶
The backend (api/) moves from Spring Boot 3.5.0 to the latest 4.1.x on Java 24. All Jackson API usage moves to Jackson 3 (tools.jackson), and jjwt moves to the jjwt-orgjson JSON backend. Every HTTP endpoint, JWT, database table and scheduled job behaves the same for clients, apart from the two accepted differences in Rule 2 (property order) and Rule 4 (trailing tokens).
Business Rules¶
Rule 1 — Supported baseline¶
spring-boot-starter-parent is the latest 4.1.x GA at implementation time.
These must not be pinned to a version the Boot 4.1 BOM already manages:
- Spring Security
- the Spring Boot Maven plugin
- Micrometer (including
micrometer-java21) - Liquibase
- Jackson
Java stays on 24 with --enable-preview.
Rule 2 — JSON responses are semantically unchanged¶
For every response body (success wrappers ResultObjectInfo<T> / ResultListInfo<T>, ResultErrorInfo, the UnauthorizedException body, SSE payloads), the 4.1 output must equal the 3.5 output as a JSON value:
- the same property names
- the same values and value types
nullpresent or absent in the same places- the same
Instant/ date string format
Property order may change. Jackson 3 sorts properties alphabetically by default, and that is accepted.
Rule 3 — Lenient request reading is kept where clients may rely on it¶
Request and external-payload deserialization must keep these 3.5 behaviors, for both the Spring MVC mapper and every mapper the code builds itself:
- a JSON
nullfor a primitive field (int,long,boolean…) maps to the type's default (0,false) and does not fail (FAIL_ON_NULL_FOR_PRIMITIVES = false); - unknown properties are ignored and do not fail (
FAIL_ON_UNKNOWN_PROPERTIES = false).
Rule 4 — Trailing tokens follow the Jackson 3 default¶
A request body with extra content after the root JSON value (e.g. {"a":1} x) is rejected the same way as any other malformed JSON body (400). This is the one accepted request-side behavior change.
Rule 5 — Existing JWTs stay valid¶
A token issued by the 3.5 build, still within its exp and signed with the same JWT_SECRET, must be accepted by the 4.1 build.
- It must produce the same
UserDetailDto:id,email,role,permissions,credentialsVersion. - A token without a
cvclaim still maps tocredentialsVersion = 0.
Rule 6 — No schema change¶
The upgrade adds no Liquibase changeset. On startup against a database migrated by the 3.5 build, Liquibase must report zero pending changesets.
Functional Requirements¶
FR-1: Dependency baseline¶
api/pom.xmlparent must bespring-boot-starter-parent4.1.x.- The
spring-security.versionproperty must be removed. - The explicit
<version>onspring-boot-maven-plugin,micrometer-java21andliquibase-coremust be removed, so the BOM manages them. springdoc-openapi-starter-webmvc-uimust use the springdoc 3.x line that supports Boot 4.hypersistence-utils-hibernate-63must be removed (no usage inapi/src/main/java).spring-boot-properties-migratormay be present while migrating and must be removed before the final commit.
FR-2: Boot 4 modular starters¶
Every feature auto-configured on 3.5 must still auto-configure on 4.1. Add the Boot 4 starter or module where auto-config moved out of the core:
- Liquibase (
spring.liquibase.*inapplication.yaml) - Mail (
spring-boot-starter-mail) - Actuator health and Prometheus
- Validation
- Security
- Data JPA
FR-3: Jackson 3 migration¶
- Every import of
com.fasterxml.jackson.databind|core|dataformatinapi/src/mainandapi/src/testmust move to itstools.jackson.*equivalent. com.fasterxml.jackson.annotation.*imports stay unchanged.jackson-dataformat-yamlmoves to its Jackson 3 artifact if the code uses YAML through Jackson. Otherwise it must be removed.- Code that caught
JsonProcessingException(checked) must catchtools.jackson.core.JacksonException(unchecked) where the old catch handled a real failure, and keep the same fallback behavior. throws JsonProcessingExceptionclauses that no longer apply must be removed.MaskingUtilsmust dropJavaTimeModuleregistration, because Jackson 3 supports java.time natively, and must produce the same masked output.
FR-4: One mapper configuration¶
The JSON mapper used by Spring MVC must be configured once, through spring.jackson.* properties or a JsonMapperBuilderCustomizer, with:
DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES = falseDeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES = false- whatever date/time settings are needed to keep
Instantoutput identical to 3.5 (Rule 2)
The four classes that call new ObjectMapper() must get a mapper with the same settings, either injected or built through one shared factory:
aop/MaskingUtilsclient/YtDlpClientImplexception/UnauthorizedExceptionservice/impl/ShareServiceImpl
The other ObjectMapper users must do the same:
JdkGitHubIssueClientChatGptServiceImplGitHubWebhookServiceImpl- the three notification listeners
UnauthorizedException.toJson() must still emit {"status":"FAILED","error":{…}}, with Error.timestamp in pattern dd-MM-yyyy hh:mm:ss.
FR-5: JWT JSON backend¶
jjwt-jacksonmust be replaced byjjwt-orgjson, keepingjjwt-apiandjjwt-implon the same version.JwtProvidermust not change its claim names, signing key derivation, or expiry logic.JwtProvider.warmUp()must keep warming the JSON reader. After the swap that means the org.json-backed reader/writer, so class init still happens on the main thread before Tomcat accepts requests (prod deadlock fix 2026-10-15 / 2026-10-24).
FR-6: Framework 7 / Security 7 / Hibernate 7 compile fixes¶
Code changes in this area are limited to what is needed to compile and to keep behavior:
- removed or renamed APIs
- the new
SecurityFilterChainDSL requirements - Hibernate 7 query and type changes
The effective security config must stay the same:
- public endpoints
- JWT filter order
- CORS allowed origins and methods, including PATCH/PUT in
WebSecurityConfig.setAllowedMethods - the stateless session policy
FR-7: Serialization baseline tests¶
Before the version bump, a test class (e.g. JsonContractTest) must capture the JSON produced on 3.5 for:
- one representative response DTO for each of the 20
@RestControllerclasses inweb/; ResultObjectInfo,ResultListInfo,ResultErrorInfo,Error, and theUnauthorizedException.toJson()body.
Each DTO is filled with fixed values (including Instant fields and nulls for @JsonInclude(NON_NULL) fields). The expected JSON is stored as test fixtures (src/test/resources/json-contract/*.json).
After the bump, the same test must pass when compared semantically, ignoring property order (Rule 2). Fixtures must not be edited during the upgrade commit.
FR-8: Tech strategy update¶
In .claude/rules/tech-strategy.md, change Spring Boot 3.x to Spring Boot 4.x (Java Golden Path table) and note Jackson 3 under the backend stack. In CLAUDE.md, change the project overview "Spring Boot 3.x" to "4.x".
API Changes¶
New Endpoints¶
None.
Modified Endpoints¶
None. Paths under /v1/funny-app, HTTP methods, status codes, headers (including Range / Content-Range / Accept-Ranges on VideoStreamController) and response shapes are unchanged.
Only these differences are allowed:
| Area | Before (3.5) | After (4.1) | Allowed by |
|---|---|---|---|
| JSON property order | declaration order | alphabetical (Jackson 3 default) | Rule 2 |
| Request body with trailing tokens | accepted, extra ignored | 400 malformed body | Rule 4 |
Error responses keep the current format (ResultErrorInfo / Error, produced by the existing @ControllerAdvice). No new error code.
Database Changes¶
New Tables¶
None.
Modified Tables¶
None.
No Changes¶
No migration file. Liquibase runs the existing db/changelog/db.changelog-master.yaml and must find no pending changesets (Rule 6). Hibernate 7 must keep ddl-auto off / validate as today; create and update are prohibited by the tech strategy.
Security Requirements¶
Authentication¶
- JWT Bearer, unchanged. Tokens issued before the deploy stay valid (Rule 5).
- Magic-link, password login and TOTP MFA flows are unchanged.
Authorization¶
Role and permission checks are unchanged. Spring Security 7 must enforce the same rules on the same paths. Verify this with the existing security tests plus FR-6.
Data Validation¶
- Bean Validation (Jakarta Validation from Boot 4.1) and
Contract/ContractDSLbehave the same. - Request JSON reading follows Rules 3 and 4.
Sensitive Data¶
MaskingUtils must mask the same fields as before (FR-3), and logs must not start printing secrets or tokens. The dependency diff must add no HIGH or CRITICAL CVE compared with 3.5.0 (PRD NFR-4).
Caching Impact¶
None. The Guava caches (VideoCacheImpl, ChunkIndexCacheImpl, StatsCacheImpl, MFASessionStoreImpl) are not serialized with Jackson, and their keys and values do not change.
Assumption: none of the Guava caches store Jackson-serialized strings; confirm with a grep during implementation.
Frontend Changes¶
New Routes¶
None.
Modified Components¶
None. webapp/ reads JSON by property name, so the property-order change in Rule 2 does not affect it.
State Management¶
None. React Query keys and cached shapes are unchanged.
Event / Job Changes¶
Domain Events¶
The after-commit notification listeners (NotificationEventListener, ReportNotificationListener, SuggestionNotificationListener) keep:
- the same event types
- the same SSE / email payloads (Rule 2)
Their mapper follows FR-4.
Scheduled Jobs¶
AppScheduler and the DynamicJobScheduler jobs (ADR-0023) keep:
- the same cron expressions
- the same behavior
No job is added or removed.
Non-Functional Requirements¶
Performance¶
| Operation | Target |
|---|---|
JVM startup to Started log, same machine, 3.5 vs 4.1 |
≤ +10% |
p95 latency of GET video list, video stream first chunk, user info |
≤ +10% vs 3.5 baseline |
| Heap at idle after startup | fits -Xmx256m with no OOM; K8s limit 600Mi unchanged |
Availability¶
- Rollback means redeploying the previous 3.5 artifact (JAR on the VM / image tag in Helm) within 10 minutes. No DB step is needed (Rule 6).
- After deploy,
/actuator/healthmust beUPwithin the usual startup time, and the first authenticated requests must not hang (FR-5 warm-up).
Scalability¶
Unchanged: one replica (HPA 1–1), virtual threads, HikariCP pool size from DB_POOL_SIZE.
Edge Cases¶
EC-1: Token issued before the upgrade¶
A JWT created by 3.5 with claims id, email, permissions, role, cv → 4.1 verifyToken returns the same UserDetailDto. Numeric claims parsed by org.json (Integer / Long / BigDecimal) must still convert:
id→Longpermissions→intviaInteger.parseInt(String.valueOf(…))cv→intviaNumber.intValue()
EC-2: Token without cv¶
A pre-PW-4 token with no cv claim → credentialsVersion = 0, as today.
EC-3: Expired or tampered token¶
- Expired →
UnauthorizedException("TOKEN_EXPIRED", 602). - Bad signature or malformed →
UnauthorizedException("TOKEN_INVALID", 601).
The response body format is the same as before (FR-4).
EC-4: null sent for a primitive field¶
e.g. {"duration": null} into a long field → value 0, no error (Rule 3).
EC-5: Unknown property¶
- In a client request → ignored (Rule 3).
- In an external payload (YouTube API, yt-dlp
--dump-json, GitHub webhook, ChatGPT response) → ignored as well, so a provider adding fields does not break parsing.
EC-6: Trailing tokens in a request body¶
{"a":1} garbage → 400 with the same error body as other malformed JSON (Rule 4).
EC-7: Instant fields¶
The 38 Instant fields in DTOs serialize to the same ISO-8601 strings as on 3.5, not numeric timestamps. null Instant follows the field's @JsonInclude as before.
EC-8: Error.timestamp¶
It keeps the pattern dd-MM-yyyy hh:mm:ss (12-hour hh, unchanged on purpose: changing it would alter the wire format).
EC-9: First requests after deploy on the 1 vCPU VM¶
A burst of authenticated requests right after startup must not deadlock. The org.json JSON reader and the jjwt classes are initialised in JwtProvider.warmUp() on the main thread before Tomcat accepts traffic (FR-5).
EC-10: Third-party Jackson 2 on the classpath¶
The Google API client and ff-java-server-sdk may still pull com.fasterxml.jackson.databind transitively. Our code must not import it (FR-3), and Spring MVC must use only the Jackson 3 mapper. A Jackson 2 jar on the classpath is allowed.
Acceptance Criteria¶
- [ ]
api/pom.xmlparent is Spring Boot 4.1.x and contains none of the removed pins or dependencies (FR-1) - [ ]
grep -rE "com\.fasterxml\.jackson\.(databind|core|dataformat)" api/srcreturns nothing (FR-3) - [ ]
JsonContractTestfixtures were committed before the version bump and pass unchanged after it, compared semantically (FR-7, Rule 2) - [ ] Unit tests cover EC-1 … EC-8 (JWT from a 3.5 fixture token, missing
cv, expired/tampered, null primitive, unknown property, trailing tokens,Instant,Error.timestamp) - [ ]
mvn verifygreen; LINE coverage ≥api/.coverage-threshold(90%);BeanConstructorTestpasses - [ ] Local boot against Postgres: Liquibase reports no pending changesets;
/actuator/health=UP;/actuator/prometheusserves metrics; Swagger UI loads on the dev profile - [ ] CORS preflight for PATCH and PUT from the webapp origin returns the same allow headers as 3.5
- [ ] Prod smoke test after deploy: magic-link login, password login + MFA, a user logged in before the deploy stays logged in, video list and Range streaming, YouTube import, admin pages, notifications SSE
- [ ]
tech-strategy.mdandCLAUDE.mdsay Spring Boot 4.x (FR-8) - [ ] No incident attributed to the upgrade within 7 days of the prod deploy
Open Questions¶
None blocking. Resolved in this spec:
- Wire-format strictness → semantic equality, order may change (Rule 2).
- Request leniency → keep null-for-primitive and unknown-property leniency; trailing tokens strict (Rules 3–4).
- Snapshot baseline → DTO serialization tests per controller, run in CI (FR-7).
- jjwt backend →
jjwt-orgjson(ADR-0033). If a Jackson 3jjwt-jacksonis available at implementation time, either is acceptable; record the choice in the ADR changelog.
Version History¶
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0 | 2026-10-28 | nguyenhuuca | Initial draft |