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:
```yaml
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