Status: Done
Author: nguyenhuuca
Date: 2026-10-28
Tracking:docs/tracking.md row "Spring Boot 4.1 Upgrade"; TASKS.md section "Spring Boot 4.1 upgrade"
Related PRD:PRD-spring-boot-4-upgradeRelated ADR:ADR-0033Spec:spec-spring-boot-4-upgrade (cited as Rule n / FR-n / EC-n)
Sequence:sequence-spring-boot-4-upgrade (flows 1–6)
Size: Medium. 5 tasks, about 1,500 LOC including tests. SB4-4 is larger than the usual 400-LOC unit, because a half-done framework bump does not compile (see Key Decisions).
Move api/ from Spring Boot 3.5.0 to 4.1.2, the latest GA (2026-10-22). With it come:
Component
Version
Spring Framework
7.0.10
Spring Security
7.1.2
Hibernate ORM
7.4.13.Final
Jackson
3.1.7
Liquibase
5.0.4
Micrometer
1.17.2
Lombok
1.18.48
Java stays on 24. Every change that can land safely on 3.5 is shipped first and verified in prod, so the final bump commit holds only what cannot exist without Boot 4.
Ship the 3.5-compatible parts first (SB4-1 … SB4-3), each merged and deployed alone
Each lands on main on its own and lowers the risk of the final bump. A JWT problem shows up in SB4-2 on a known-good framework, not mixed into the bump
SB4-4 is one atomic commit (~600 LOC)
Parent POM, Jackson annotations used by MVC, test-slice packages and Security 7 APIs must all change together, or the build breaks. A trunk-based unit cannot be split there
Contract fixtures are committed in SB4-1 and never edited later
They are the proof for Rule 2. Editing them in the bump commit would hide a wire-format change
SB4-3 has a fallback
Jackson 3.1.7 next to Boot 3.5's Jackson 2.19 needs a newer jackson-annotations (shared by both). If mvn verify on 3.5 fails because of that, SB4-3's code moves into SB4-4 instead, with no other plan change
Target 4.1.2, not 4.1.x "latest" at merge time
Pin an exact version for a reproducible build. A later 4.1.x patch is a separate one-line bump
Liquibase 5
The Boot BOM moves Liquibase 4.32 → 5.0.4. Check its license and changelog compatibility in SB4-4 step 1. If either is a problem, pin liquibase.version to the last 4.x that Boot 4.1's auto-config supports and record that in ADR-0033
ResultObjectInfo, ResultListInfo, ResultErrorInfo (timestamp fixed or ignored)
Error through RestExceptionHandler ({"error":{…}}; timestamp matched by the regex \d{2}-\d{2}-\d{4} \d{2}:\d{2}:\d{2})
UnauthorizedException.toJson()
Other fixtures:
The notification payload JSON written to the DB (Map<String,String>), because it is persisted and must stay readable.
One Page<T> fixture, to pin the PageImpl shape (Spring Data 4 may change it).
Assertion: JSONAssert.assertEquals(expected, actual, JSONCompareMode.NON_EXTENSIBLE) (already on the classpath through spring-boot-starter-test). Never use LENIENT, which would accept extra fields.
[ ] Step 1.2: Legacy JWT fixture: a token signed with the test secret, exp = 2099, claims id, email, role, permissions, cv (and a second one without cv), generated once on 3.5 and stored as a fixture string
Files: filter/JwtProviderTest.java (new cases), src/test/resources/json-contract/legacy-jwt.txt
Covers EC-1 and EC-2.
[ ] Step 1.3: Request-leniency tests on the MVC mapper: null → primitive is OK, unknown property is ignored (Rule 3, EC-4, EC-5). Add the trailing-token case with the expectation @Disabled("enabled in SB4-4: Jackson 3 rejects, Rule 4").
Files: api/pom.xml, filter/JwtProvider.java only if needed (ServiceLoader picks the backend up). JwtProviderTest: warm-up still signs and parses once; legacy tokens from step 1.2 verify; numeric claims from org.json (Integer/Long/BigDecimal) convert (EC-1).
[ ] Step 2.2 (SB4-2): Remove the unused hypersistence-utils-hibernate-63 and jackson-dataformat-yaml (no imports in src/).
[ ] Step 2.3 (SB4-3): Add tools.jackson.core:jackson-databind:3.1.7 and a JsonMappers holder. It provides one JsonMapper with the FR-4 settings:
FAIL_ON_NULL_FOR_PRIMITIVES=false
FAIL_ON_UNKNOWN_PROPERTIES=false
WRITE_DATES_AS_TIMESTAMPS=false
The holder is exposed as a bean for injected sites. Static sites (MaskingUtils, YtDlpClientImpl, ShareServiceImpl) call a package-visible factory method JsonMappers.create(), so their tests can build the same mapper without Spring.
On Boot 3.5 a Jackson 3 JsonMapper bean is a different type from Jackson 2's ObjectMapper. Boot's JacksonAutoConfiguration (which only backs off for an ObjectMapper bean) and Spring MVC ignore it, so SB4-3 cannot change the HTTP wire format.
[ ] Step 2.4 (SB4-3): Move internal Jackson usage to tools.jackson. Catch blocks keep the same fallback (the inventory is in the explorer notes below).
Static or per-call mappers:
aop/MaskingUtils (drop JavaTimeModule; keep the "<unserializable …>" fallback)
client/YtDlpClientImpl (catch IOException → catch JacksonException, still ImportException(EXTRACTOR_ERROR))
service/impl/GitHubWebhookServiceImpl (still IllegalArgumentException("body is not JSON"))
service/impl/ChatGptServiceImpl
service/notification/NotificationEventListener, ReportNotificationListener, SuggestionNotificationListener (the payload fixture from step 1.1 must still pass)
client/YouTubeApiClientImpl (JsonNode through the RestTemplate Jackson 2 converter)
Tests: the matching tests (JdkGitHubIssueClientTest, ChatGptServiceImplTest, GitHubWebhookServiceImplTest, the three listener tests, UserSettingsServiceImplTest).
Fallback trigger (any one of these, checked before committing SB4-3):
mvn -f api/pom.xml dependency:tree -Dincludes=com.fasterxml.jackson.core:jackson-annotations shows more than one version, or a version different from Boot 3.5.0's managed one;
any test fails with a Jackson linkage error (NoSuchMethodError, NoClassDefFoundError, ClassNotFoundException naming a com.fasterxml.jackson or tools.jackson class);
making it work needs a jackson-bom / jackson-annotations version override that changes Boot 3.5's managed Jackson 2 versions.
On trigger: discard all SB4-3 changes (git restore/git clean on the SB4-3 files; nothing is committed), mark the SB4-3 row "folded into SB4-4" in this table and in TASKS.md (with the trigger that fired), and carry steps 2.3–2.4 into SB4-4. No half state lands on main.
[ ] Step 3.1: Check Liquibase 5.0.4: license and changelog compatibility with db/changelog/db.changelog-master.yaml. If either is a problem, decide on a 4.x pin (see Key Decisions). Record the decision in the ADR-0033 changelog before editing the pom, because a pin changes step 3.2.
[ ] Step 3.2: Update api/pom.xml:
Version changes:
parent → 4.1.2
springdoc-openapi.version → 3.2.0
Dependency swaps:
liquibase-core → spring-boot-starter-liquibase
add spring-boot-jackson if spring-boot-starter-web no longer brings it (check with dependency:tree)
drop the explicit Jackson 3 version from SB4-3 (now BOM-managed)
Pins to remove:
spring-security.version
<version> on spring-boot-maven-plugin, micrometer-java21, mockito-core, byte-buddy
lombok.version property (BOM 1.18.48). pom.xml:379 uses ${lombok.version} in the compiler plugin's annotationProcessorPaths; Boot's parent still defines lombok.version, so the reference keeps working once the local override is gone. Confirm with mvn help:evaluate -Dexpression=lombok.version
maven-compiler-plugin 3.11.0 and the surefire pin (BOM 3.15.0 / 3.5.6)
Migration helper: keep spring-boot-properties-migrator for step 3.6.
[ ] Step 3.3: Finish Jackson 3 (Error and MVC side):
exception/Error: @JsonSerialize/@JsonDeserialize with the jsr310 LocalDateTime (de)serializer. Use Jackson 3's built-in java.time and keep @JsonFormat("dd-MM-yyyy hh:mm:ss") (EC-8).
JsonMapperBuilderCustomizer bean applying the same FR-4 settings to the MVC mapper. JsonMappers and MVC share one source of settings.
Tests: RestExceptionHandlerTest, YouTubeApiClientImplTest, CommentControllerTest and UserSettingsControllerTest (@Autowired JsonMapper).
Contract test code (not fixtures):contract/JsonContractSupport.java:3-5,10,35, contract/JsonReadContractTest.java:3, contract/JsonContractTest.java:43 and exception/ErrorJsonContractTest, service/notification/NotificationPayloadContractTest move to tools.jackson / JsonMapper and Boot 4's JacksonAutoConfiguration package. They may change only so that the same assertions run against the Boot 4 MVC mapper.
src/test/resources/json-contract/** is read-only. If a fixture comparison fails, fix the mapper configuration or the annotations, never the fixture. Check: git diff --exit-code <SB4-3 commit> -- api/src/test/resources/json-contract.
3.5 quirks the fixtures pin; SB4-4 must keep them. The customizer preserves Boot 3.5's visibility and null-inclusion behavior (null fields are written; field visibility as in Jackson 2 defaults):
Error.timestamp written with the 12-hour pattern dd-MM-yyyy hh:mm:ss (Error.java:29), e.g. 15:04 → 03:04 (error-code.json);
ApiSubError sub-errors serialize only field and rejectedValue (it has no getters for object / message) (error-field-sub-errors.json, error-constraint-violation.json);
[ ] Step 3.4: Compile fixes, limited to what the build needs (FR-6):
Test slices (15 @WebMvcTest files): the WebMvcTest import moves to the Boot 4 test module package (add the spring-boot-webmvc-test dependency if needed); the TaskExecutionAutoConfiguration import moves in config/AsyncExecutorVirtualThreadTest.
config/ConfigBean:RestTemplateBuilder and MeterRegistryCustomizer package moves.
filter/WebSecurityConfig: the DefaultMethodSecurityExpressionHandler.createEvaluationContext override (:92-105) on Security 7; string requestMatchers (:55-58) keep the same effect under Security 7's path-pattern matching, so check AppConstant.WebIgnoringConfig paths for pattern-syntax changes; CORS unchanged. WebSecurityConfigAdminMatcherTest and the 4 *PermissionTest classes must pass with unchanged assertions.
exception/Error:110: Hibernate Validator internal PathImpl. Replace it with the public jakarta.validation.Path API, with the same field name in the output.
Entities: for the 5 entities with @GeneratedValue and no strategy (UserEmailRequest, AppReport, VideoCollection, VideoComment, VideoAccessStats), confirm that Hibernate 7 resolves the same sequence / identity as Liquibase created. Set it explicitly only if it does not.
[ ] Step 3.5: Remove @Disabled from JsonReadContractTest.trailingTokens_throw (:41) without changing its assertion: reading a body with trailing tokens through the Boot 4 MVC mapper must throw (Jackson 3 default FAIL_ON_TRAILING_TOKENS=true; the customizer must not turn it off) (spec Rule 4, EC-6). Contract fixtures from SB4-1 must pass unchanged.
[ ] Step 3.6: Boot locally against Postgres (./startLocal.sh):
Liquibase: 0 pending changesets.
Local DB only: create one row each for UserEmailRequest, AppReport, VideoCollection, VideoComment, VideoAccessStats through the app (implicit @GeneratedValue); ids must come from the Liquibase-created sequences/identity with no Hibernate error.
[x] Step 4.1: After push approval, watch CI ("Funny App Build and Deploy"). Confirm the prod VM starts with the existing startServer.sh flags (sequence flow 1).
[x] Step 4.2: Prod smoke test:
magic-link login, password login + MFA
a session from before the deploy is still logged in
video list and Range streaming
YouTube import, admin pages
notifications SSE
CORS PATCH/PUT from the webapp
[x] Step 4.3: 7-day watch (owner closed it early on 2026-10-29, after a clean prod start and smoke pass). Then set the tracking row to ✅ and the PRD/ADR/plan statuses to Done.
mvn verify green on 3.5; fixtures cover every JSON-returning controller, wrappers, Error, UnauthorizedException, notification payload, Page; uses NON_EXTENSIBLE
SB4-2
jjwt 0.13.0 + jjwt-orgjson; drop unused deps (on 3.5)
SB4-1
120
Both legacy JWT fixtures verify (with-cv → credentialsVersion=3, without-cv → 0); warm-up test passes; expired/tampered still 602/601; mvn dependency:tree shows no jjwt-jackson / hypersistence / dataformat-yaml; prod: users stay logged in after deploy
SB4-3
Folded into SB4-4 (2026-10-28: fallback triggers 2+3, Jackson 3.1.7 needs jackson-annotations 2.21 vs Boot 3.5.0's 2.19.0). Was: internal Jackson → Jackson 3 + JsonMappers (on 3.5, with fallback)
SB4-2
400
grep -rlE "com\.fasterxml\.jackson\.(databind\|core)" api/src/main lists only exception/Error.java, exception/LowerCaseClassNameResolver.java, exception/UnauthorizedException.java, client/YouTubeApiClientImpl.java; same catch fallbacks (tests); contract + payload fixtures pass; none of the step 2.4 fallback triggers fired (else: folded into SB4-4)
grep -rE "com\.fasterxml\.jackson\.(databind\|core\|dataformat)" api/src is empty (main and test); git diff --exit-code <SB4-3 commit> -- api/src/test/resources/json-contract is clean and every contract test is green, including the three pinned quirks (step 3.3); trailingTokens_throw enabled with its assertion unchanged and passing; security matcher/permission tests unchanged and green; coverage ≥ 90%; BeanConstructorTest green; local boot checklist (step 3.6) done; tech-strategy and CLAUDE.md updated
SB4-5
Deploy, prod smoke test, 7-day watch
SB4-4
0
Smoke list in step 4.2 passes; no incident in 7 days; tracking ✅
Every task is its own commit on main, so rolling back SB4-4 does not undo SB4-1 … SB4-3.
For a prod problem after SB4-4: redeploy the previous artifact (VM JAR / Helm image tag from SB4-3). No DB step is needed, because there is no schema change and the Liquibase changelog is untouched.
Verify /actuator/health UP, a login, and video playback; then git revert the SB4-4 commit on main so CI does not redeploy it.
Explorer findings (2026-10-28): 18 main + 12 test files use Jackson. No @SpringBootTest. No @MockBean left (already @MockitoBean). jjwt-jackson 0.13.0 depends on Jackson 2 only. The SSE unread payload is a hand-built string, not Jackson, so it is unaffected. No Guava cache stores Jackson output.
Pre-existing, not changed here: MaskingUtils.maskSensitiveFields returns the unmasked object when cloning fails (fail-open). It is worth a separate fix.