Skip to content

Commit dc4502e

Browse files
SplatcrafterSplatcrafter
authored
Merge pull request #22 from aether-framework/feature/spring-boot-integration
Refine documentation and enforce consistent null checks
2 parents a38d32f + c7f49c9 commit dc4502e

47 files changed

Lines changed: 12616 additions & 13 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CHANGELOG.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,78 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
66

77
---
88

9+
## [0.4.0] - 2026-01-09
10+
11+
### Added
12+
13+
#### Spring Boot Starter Module (`aether-datafixers-spring-boot-starter`)
14+
15+
New module providing seamless Spring Boot integration with auto-configuration, fluent migration API, and observability features.
16+
17+
**Auto-Configuration (`spring.autoconfigure`):**
18+
- `AetherDataFixersAutoConfiguration` — Main entry point coordinating all sub-configurations
19+
- `DynamicOpsAutoConfiguration` — Auto-configures `GsonOps` and `JacksonOps` beans based on classpath
20+
- `DataFixerAutoConfiguration` — Creates `AetherDataFixer` beans from `DataFixerBootstrap` definitions
21+
- `MigrationServiceAutoConfiguration` — Configures the `MigrationService` with metrics integration
22+
- `ActuatorAutoConfiguration` — Configures health indicators, info contributors, and custom endpoints
23+
- Conditional activation via `aether.datafixers.enabled` property (default: `true`)
24+
- Version resolution from properties, bootstrap `CURRENT_VERSION` constant, or global default
25+
26+
**Configuration Properties (`spring.config`):**
27+
- `AetherDataFixersProperties` — Root configuration with `aether.datafixers.*` prefix
28+
- `DataFixerDomainProperties` — Per-domain configuration (version, primary, description)
29+
- `DynamicOpsFormat` — Enum for selecting default serialization format (GSON, JACKSON)
30+
- `ActuatorProperties` — Control schema/fix detail exposure in actuator responses
31+
- `MetricsProperties` — Configure timing, counting, and domain tag name
32+
33+
**Migration Service (`spring.service`):**
34+
- `MigrationService` — High-level interface with fluent builder API
35+
- `MigrationService.MigrationRequestBuilder` — Builder for configuring migrations
36+
- `DefaultMigrationService` — Thread-safe implementation with metrics integration
37+
- `MigrationResult` — Immutable result object with success/failure, data, versions, duration, error
38+
- Fluent API: `.migrate(data).from(version).to(version).execute()`
39+
- Domain selection: `.usingDomain("game")` for multi-domain setups
40+
- Latest version resolution: `.toLatest()` resolves at execution time
41+
- Async execution: `.executeAsync()` returns `CompletableFuture<MigrationResult>`
42+
- Custom DynamicOps: `.withOps(ops)` for custom serialization
43+
44+
**Multi-Domain Support (`spring.autoconfigure`):**
45+
- `DataFixerRegistry` — Thread-safe registry for managing multiple DataFixer instances
46+
- Support for `@Qualifier` annotated bootstrap beans
47+
- `createQualifiedFixer()` factory method for domain-specific DataFixer creation
48+
- Domain availability checking via `hasDomain()` and `getAvailableDomains()`
49+
- Default domain ("default") for single-bootstrap setups
50+
51+
**Actuator Integration (`spring.actuator`):**
52+
- `DataFixerHealthIndicator` — Reports UP/DOWN/UNKNOWN based on DataFixer operational status
53+
- `DataFixerInfoContributor` — Adds `aether-datafixers` section to `/actuator/info`
54+
- `DataFixerEndpoint` — Custom endpoint at `/actuator/datafixers` with domain details
55+
- Per-domain health status and version information
56+
- Domain-specific endpoint: `/actuator/datafixers/{domain}`
57+
- Fail-fast on first domain error with detailed error message
58+
59+
**Micrometer Metrics (`spring.metrics`):**
60+
- `MigrationMetrics` — Records migration metrics using Micrometer
61+
- `aether.datafixers.migrations.success` — Counter for successful migrations (tagged by domain)
62+
- `aether.datafixers.migrations.failure` — Counter for failed migrations (tagged by domain, error_type)
63+
- `aether.datafixers.migrations.duration` — Timer for migration execution time
64+
- `aether.datafixers.migrations.version.span` — Distribution summary of version spans
65+
- Automatic metric recording in `DefaultMigrationService`
66+
- Thread-safe meter caching per domain
67+
68+
### Documentation
69+
70+
- Added comprehensive Spring Boot Integration documentation
71+
- Quick Start Guide with complete code examples
72+
- Configuration Reference for all `aether.datafixers.*` properties
73+
- MigrationService API documentation with sync/async patterns
74+
- Multi-Domain Setup guide with `@Qualifier` examples
75+
- Actuator Integration guide with security recommendations
76+
- Metrics Integration guide with PromQL queries, Grafana dashboard, and alerting rules
77+
- Updated main documentation with Spring Boot module links
78+
79+
---
80+
981
## [0.3.0] - 2026-01-08
1082

1183
### Added

‎README.md‎

Lines changed: 150 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ inspired by Minecraft's DataFixer Upper (DFU), with a focus on **simplicity**, *
2020
- ✅ **Testkit** — Fluent test data builders, custom assertions, and test harnesses for DataFix testing
2121
- ✅ **CLI Tool** — Migrate and validate data files from the command line with batch processing
2222
- ✅ **Schema Tools** — Schema diffing, validation, migration analysis, and type introspection
23+
- ✅ **Spring Boot 3.x** — Auto-configuration, MigrationService with fluent API, Actuator integration
2324
- ✅ **Migration Diagnostics** — Opt-in structured reports with timing, applied fixes, and snapshots
2425
- ✅ **Extended Rewrite Rules** — Batch operations, path-based transforms, conditional rules
2526
- ✅ **High-Performance APIs** — `Rules.batch()` for single-pass multi-operation transforms
@@ -35,6 +36,7 @@ inspired by Minecraft's DataFixer Upper (DFU), with a focus on **simplicity**, *
3536
- **aether-datafixers-testkit** — Testing utilities for DataFix, Schema, and migration testing
3637
- **aether-datafixers-cli** — Command-line interface for data migration and validation
3738
- **aether-datafixers-schema-tools** — Schema analysis, validation, diffing, and introspection
39+
- **aether-datafixers-spring-boot-starter** — Spring Boot 3.x auto-configuration with Actuator support
3840
- **aether-datafixers-examples** — Practical examples demonstrating real-world usage
3941
- **aether-datafixers-bom** — Bill of Materials for coordinated dependency management
4042

@@ -84,7 +86,7 @@ Dynamic<?> updated = fixer.update(
8486

8587
```xml
8688
<dependency>
87-
<groupId>de.splatgames.aether</groupId>
89+
<groupId>de.splatgames.aether.datafixers</groupId>
8890
<artifactId>aether-datafixers-core</artifactId>
8991
<version>0.3.0</version>
9092
</dependency>
@@ -94,15 +96,15 @@ Dynamic<?> updated = fixer.update(
9496

9597
```groovy
9698
dependencies {
97-
implementation 'de.splatgames.aether:aether-datafixers-core:0.3.0'
99+
implementation 'de.splatgames.aether.datafixers:aether-datafixers-core:0.3.0'
98100
}
99101
```
100102

101103
**Gradle (Kotlin)**
102104

103105
```kotlin
104106
dependencies {
105-
implementation("de.splatgames.aether:aether-datafixers-core:0.3.0")
107+
implementation("de.splatgames.aether.datafixers:aether-datafixers-core:0.3.0")
106108
}
107109
```
108110

@@ -120,7 +122,7 @@ The Bill of Materials (BOM) ensures consistent versions across all Aether Datafi
120122
<dependencyManagement>
121123
<dependencies>
122124
<dependency>
123-
<groupId>de.splatgames.aether</groupId>
125+
<groupId>de.splatgames.aether.datafixers</groupId>
124126
<artifactId>aether-datafixers-bom</artifactId>
125127
<version>0.3.0</version>
126128
<type>pom</type>
@@ -132,11 +134,11 @@ The Bill of Materials (BOM) ensures consistent versions across all Aether Datafi
132134
<dependencies>
133135
<!-- No version needed -->
134136
<dependency>
135-
<groupId>de.splatgames.aether</groupId>
137+
<groupId>de.splatgames.aether.datafixers</groupId>
136138
<artifactId>aether-datafixers-core</artifactId>
137139
</dependency>
138140
<dependency>
139-
<groupId>de.splatgames.aether</groupId>
141+
<groupId>de.splatgames.aether.datafixers</groupId>
140142
<artifactId>aether-datafixers-codec</artifactId>
141143
</dependency>
142144
</dependencies>
@@ -146,23 +148,23 @@ The Bill of Materials (BOM) ensures consistent versions across all Aether Datafi
146148

147149
```groovy
148150
dependencies {
149-
implementation platform('de.splatgames.aether:aether-datafixers-bom:0.3.0')
151+
implementation platform('de.splatgames.aether.datafixers:aether-datafixers-bom:0.3.0')
150152
151153
// No version needed
152-
implementation 'de.splatgames.aether:aether-datafixers-core'
153-
implementation 'de.splatgames.aether:aether-datafixers-codec'
154+
implementation 'de.splatgames.aether.datafixers:aether-datafixers-core'
155+
implementation 'de.splatgames.aether.datafixers:aether-datafixers-codec'
154156
}
155157
```
156158

157159
**Gradle (Kotlin)**
158160

159161
```kotlin
160162
dependencies {
161-
implementation(platform("de.splatgames.aether:aether-datafixers-bom:0.3.0"))
163+
implementation(platform("de.splatgames.aether.datafixers:aether-datafixers-bom:0.3.0"))
162164

163165
// No version needed
164-
implementation("de.splatgames.aether:aether-datafixers-core")
165-
implementation("de.splatgames.aether:aether-datafixers-codec")
166+
implementation("de.splatgames.aether.datafixers:aether-datafixers-core")
167+
implementation("de.splatgames.aether.datafixers:aether-datafixers-codec")
166168
}
167169
```
168170

@@ -351,6 +353,138 @@ Add to your project:
351353

352354
---
353355

356+
## 🍃 Spring Boot Integration
357+
358+
The `aether-datafixers-spring-boot-starter` provides comprehensive Spring Boot 3.x integration.
359+
360+
### Installation
361+
362+
**Maven**
363+
364+
```xml
365+
<dependency>
366+
<groupId>de.splatgames.aether.datafixers</groupId>
367+
<artifactId>aether-datafixers-spring-boot-starter</artifactId>
368+
<version>0.4.0</version>
369+
</dependency>
370+
```
371+
372+
**Gradle (Kotlin)**
373+
374+
```kotlin
375+
implementation("de.splatgames.aether.datafixers:aether-datafixers-spring-boot-starter:0.4.0")
376+
```
377+
378+
### Quick Start
379+
380+
1. **Create a DataFixerBootstrap bean:**
381+
382+
```java
383+
@Configuration
384+
public class DataFixerConfig {
385+
@Bean
386+
public DataFixerBootstrap gameBootstrap() {
387+
return new GameDataBootstrap();
388+
}
389+
}
390+
```
391+
392+
2. **Inject and use MigrationService:**
393+
394+
```java
395+
@Service
396+
public class GameService {
397+
private final MigrationService migrationService;
398+
399+
public GameService(MigrationService migrationService) {
400+
this.migrationService = migrationService;
401+
}
402+
403+
public Dynamic<?> migratePlayerData(Dynamic<?> data, int fromVersion) {
404+
MigrationResult result = migrationService
405+
.migrate(data)
406+
.from(fromVersion)
407+
.toLatest()
408+
.execute();
409+
410+
if (result.isSuccess()) {
411+
return result.getData();
412+
}
413+
throw new MigrationException(result.getErrorMessage());
414+
}
415+
}
416+
```
417+
418+
### Configuration Properties
419+
420+
```yaml
421+
aether:
422+
datafixers:
423+
enabled: true # Enable/disable auto-config
424+
default-format: gson # gson | jackson
425+
default-current-version: 200 # Fallback version
426+
domains:
427+
game:
428+
current-version: 200
429+
primary: true
430+
user:
431+
current-version: 150
432+
actuator:
433+
include-schema-details: true
434+
include-fix-details: true
435+
metrics:
436+
timing: true
437+
counting: true
438+
```
439+
440+
### Multi-Domain Support
441+
442+
Support multiple DataFixers with `@Qualifier`:
443+
444+
```java
445+
@Configuration
446+
public class DataFixerConfig {
447+
@Bean
448+
@Qualifier("game")
449+
public DataFixerBootstrap gameBootstrap() {
450+
return new GameDataBootstrap();
451+
}
452+
453+
@Bean
454+
@Qualifier("user")
455+
public DataFixerBootstrap userBootstrap() {
456+
return new UserDataBootstrap();
457+
}
458+
}
459+
460+
// Usage
461+
MigrationResult result = migrationService
462+
.migrate(data)
463+
.usingDomain("game") // Select domain
464+
.from(100)
465+
.toLatest()
466+
.execute();
467+
```
468+
469+
### Actuator Endpoints
470+
471+
| Endpoint | Description |
472+
|------------------------|-------------------------------------------|
473+
| `/actuator/health` | Health indicator showing DataFixer status |
474+
| `/actuator/info` | Schema version information |
475+
| `/actuator/datafixers` | Detailed domain and version info |
476+
477+
### Micrometer Metrics
478+
479+
| Metric | Type | Description |
480+
|---------------------------------------------|--------------|-------------------------|
481+
| `aether.datafixers.migrations.success` | Counter | Successful migrations |
482+
| `aether.datafixers.migrations.failure` | Counter | Failed migrations |
483+
| `aether.datafixers.migrations.duration` | Timer | Migration duration |
484+
| `aether.datafixers.migrations.version.span` | Distribution | Version span statistics |
485+
486+
---
487+
354488
## 📖 Examples
355489

356490
The `aether-datafixers-examples` module provides a complete, runnable example demonstrating real-world usage patterns.
@@ -428,7 +562,10 @@ mvn test
428562
- **Convention checking** — Enforce naming conventions for types, fields, and classes
429563

430564
- **v0.4.0** (next)
431-
- **Spring Boot integration** — Auto-configuration for DataFixer in Spring apps
565+
- **Spring Boot Starter** — Auto-configuration, MigrationService with fluent API
566+
- **Actuator integration** — Health indicator, info contributor, custom endpoint, Micrometer metrics
567+
- **Multi-domain support** — Multiple DataFixers with @Qualifier annotations
568+
- **DynamicOps auto-configuration** — Conditional GsonOps/JacksonOps beans
432569
- **Extra ops modules** — Optional YAML/TOML support (format adapters)
433570
- **Debug utilities** — Pretty printers / tree diff for Dynamic structures (dev-facing)
434571

‎aether-datafixers-bom/pom.xml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,11 @@
4747
<artifactId>aether-datafixers-cli</artifactId>
4848
<version>${project.version}</version>
4949
</dependency>
50+
<dependency>
51+
<groupId>de.splatgames.aether.datafixers</groupId>
52+
<artifactId>aether-datafixers-spring-boot-starter</artifactId>
53+
<version>${project.version}</version>
54+
</dependency>
5055
</dependencies>
5156
</dependencyManagement>
5257
</project>

0 commit comments

Comments
 (0)