CFTunnels/docs/OPENREWRITE-PLAN.md

OpenRewrite Monthly Rolling Updates Plan for CFTunnels

Overview

Configuration for OpenRewrite to provide automatic monthly rolling updates for the CFTunnels Spring Boot application with safety-first approach.

1. Core Configuration Files to Create/Modify

build.gradle modifications:

• Add OpenRewrite plugin
• Configure safe update recipes
• Add dependency management
• Set up monthly scheduling hook

rewrite.yml (new file):

• Custom safety recipes for CFTunnels
• Spring Boot specific update rules
• OAuth2 and OpenAPI compatibility checks

.gitea/workflows/rewrite-updates.yml (new workflow):

• Monthly trigger (1st of each month)
• Safe update execution
• Test validation
• Rollback mechanisms

2. Safety-First Update Strategy

Monthly Update Process:

1. Dry Run Mode - Preview all changes without applying
2. Compatibility Checks - Verify Spring Boot alignment
3. Test Suite Validation - Run all tests before applying
4. Staged Application - Apply in phases with verification
5. Automatic Rollback - Revert if any test fails

Update Scope (Monthly):

• ✅ Security patches (immediate priority)
• ✅ Minor version updates (Spring Boot 3.4.x → 3.5.x)
• ✅ Dependency alignment (Spring ecosystem)
• ❌ Major version updates (manual review required)
• ❌ Experimental features (disabled)

3. Specific Recipes for CFTunnels

Core Recipes:

recipeList:
  - org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_5
  - org.openrewrite.maven.spring.UpgradeExplicitSpringBootDependencies
  - org.openrewrite.java.dependencies.UpgradeDependencyVersion:
      groupId: org.springdoc
      newVersion: latest.release
  - org.openrewrite.java.dependencies.UpgradeDependencyVersion:
      groupId: org.springframework.boot
      newVersion: 3.5.x

Safety Exclusions:

• Experimental Spring Boot features
• Breaking Jakarta EE changes
• Database schema migrations
• OAuth2 provider configuration changes

4. CI/CD Integration Plan

New Workflow: .gitea/workflows/rewrite-updates.yml

• Schedule: Cron for monthly execution (1st of month, 2 AM UTC)
• Triggers: Manual dispatch for urgent security updates
• Steps:
  1. Run rewriteDryRun to preview changes
  2. Execute test suite with current dependencies
  3. Apply updates with rewriteRun
  4. Run full test suite again
  5. Create PR with changes for review
  6. Auto-merge if all tests pass

Rollback Mechanism:

• Automatic revert if any test fails
• Previous version tagging before updates
• Deployment rollback capability

5. Configuration Specifics

Critical Dependencies to Update:

• Spring Boot (3.4.5 → latest 3.5.x)
• SpringDoc OpenAPI (2.8.5 → latest compatible)
• PostgreSQL Driver (latest compatible)
• Hibernate Validator
• OAuth2 Client

Protected Configurations:

• Cloudflare API integration
• Database connection settings
• OAuth2 provider endpoints
• Custom security configurations

6. Monitoring & Notification Strategy

Pre-Update Notifications:

• 3 days before monthly update
• Preview of planned changes
• Security vulnerability summary

Post-Update Reports:

• List of applied updates
• Test results summary
• Performance impact assessment
• Any manual intervention required

7. Implementation Files Summary

Files to create:

• rewrite.yml - Custom recipe configuration
• .gitea/workflows/rewrite-updates.yml - Monthly automation
• scripts/rewrite-safety-check.sh - Safety validation script

Files to modify:

• build.gradle - Add OpenRewrite plugin and configuration
• docker-compose.yaml - Add safety environment variables

Files to create for monitoring:

• .github/ISSUE_TEMPLATE/rollback-request.md - Emergency rollback
• docs/UPDATE-PROCESS.md - Documentation

8. Current Project Analysis

• Project Type: Spring Boot 3.4.5 with Gradle build system
• Java Version: 17 (with toolchain)
• CI/CD: Gitea workflows (similar to GitHub Actions)
• Current Dependencies: Spring Boot starter, OAuth2, PostgreSQL, SpringDoc OpenAPI

9. Pending Configuration Decisions

Security Patch Priority:

Should security patches be applied immediately (outside monthly schedule) or wait for the monthly cycle?

Pull Request Strategy:

• Auto-merge successful updates?
• Always create PR for manual review?
• Auto-merge only for patch versions?

Notification Method:

• Gitea notifications?
• Email summary?
• Slack/Discord integration?

Test Validation:

• Full test suite required?
• Skip integration tests for dependency-only changes?
• Performance baseline validation?

Backup Strategy:

• Tag before each update?
• Keep rolling history of last 3 versions?

10. Next Steps

Once the above decisions are made, proceed with:

1. Create all configuration files
2. Update build.gradle with OpenRewrite plugin
3. Set up monthly workflow
4. Configure safety mechanisms
5. Test dry-run execution
6. Monitor first automated update

11. Rollback Procedures

Emergency Rollback:

1. Identify last working tag
2. Revert to previous version
3. Update docker-compose with rollback image tag
4. Restart services
5. Verify functionality

Manual Override:

• Disable automatic updates temporarily
• Manual version pinning in build.gradle
• Custom update execution as needed

12. Success Metrics

Metrics to Track:

• Number of successful automated updates
• Failed update rate
• Time to recovery from failed updates
• Security vulnerability reduction
• Dependency currency score

Monitoring Alerts:

• Failed update notifications
• Security patch availability
• Breaking change warnings
• Performance regression alerts