feat(core): WordPress core update rollback (0.1.3.3)

[randhirinsta]

Summary

• Adds the consumer-side surface for WordPress core rollback to the instawp-connect plugin: version bump to 0.1.3.3, readme.txt changelog entry under "Beta", and new doc/core-update.md covering the REST payload shape (forward + rollback), the instawp_last_core_version snapshot, and the delegation flow.
• Core/Updater changes live upstream now. The plugin consumes instawp/connect-helpers via composer (dev-main), so the actual Updater.php changes have been moved to feat(updater): WordPress core rollback via core_downgrade + snapshot (v1.1.1) connect-helpers#17 (v1.1.1). This branch carried them transiently in vendor/ for early testing; they've been reverted from vendor/ here in commit b6ceee0b. After connect-helpers#17 merges, composer update instawp/connect-helpers will bring v1.1.1 back into vendor/ here, sourced properly from the package — to be committed as a follow-up build: commit on this branch.

REST contract (consumer endpoint)

POST /wp-json/instawp-connect/v2/manage/update

Forward:

[{ "type": "core", "slug": "wordpress", "version": "6.9.4" }]

Rollback (caller pins exact target; plugin verifies against snapshot):

[{ "type": "core", "slug": "wordpress", "version": "6.8.2", "action": "rollback" }]

allow_downgrade: true works equivalently to action: "rollback".

Test plan

• connect-helpers#17 merged + composer update instawp/connect-helpers committed here.
• Forward update from UI on a site downgraded to 6.8.2 → installs target, instawp_last_core_version snapshot is written.
• Rollback from UI to the recorded previous_version → installs the rollback target via the same Core_Upgrader path.
• Rollback with a version that does NOT match the snapshot → rejected before any install attempt.
• Rollback when no snapshot exists → rejected.
• Filters on (pre_)site_transient_update_core are removed after both success and failure.

Related

• Upstream: feat(updater): WordPress core rollback via core_downgrade + snapshot (v1.1.1) connect-helpers#17

🤖 Generated with Claude Code

[claude]

Claude finished @randhirinsta's task —— View job

---

Code Review Complete ✅

Comprehensive review of WordPress core rollback functionality (v0.1.3.3)

Review Checklist

• Load developer context and project guidelines
• Analyze changed files for architectural compliance
• Review for security concerns
• Check performance considerations
• Verify WordPress coding standards
• Test coverage and error handling review
• Backward compatibility assessment
• Final review summary

---

✅ OVERALL ASSESSMENT: EXCELLENT IMPLEMENTATION

This PR demonstrates excellent adherence to architectural principles and security best practices. The core rollback implementation is well-designed with proper delegation, error handling, and security measures.

---

🏗️ ARCHITECTURAL PRINCIPLES COMPLIANCE

✅ 1. Data Layer Abstraction - EXCELLENT

• Direct storage usage: Uses wp_options table directly via update_option()/get_option() with autoload=false
• Avoids high-level abstractions: No reliance on WordPress version APIs that might cache or abstract the underlying data
• Complete data capture: Snapshot approach ensures authoritative rollback source independent of caller claims

✅ 2. DRY (Don't Repeat Yourself) - EXCELLENT

• Perfect delegation pattern: core_downgrade() delegates to core_updater() - single Core_Upgrader path for all operations
• No code duplication: Rollback reuses existing update infrastructure via filter manipulation
• Shared error handling: Both paths use same error handling and response patterns

✅ 3. SSOT (Single Source of Truth) - EXCELLENT

• Plugin-owned snapshot: instawp_last_core_version option is authoritative source for rollback targets
• Verification against SSOT: Rollback validates caller's request against plugin's recorded snapshot
• No data redundancy: Single storage location for version history

✅ 4. SoC (Separation of Concerns) - EXCELLENT

• Clear responsibility separation:
  • core_updater(): Handles all WordPress core installation logic
  • core_downgrade(): Handles rollback validation and transient manipulation
  • Snapshot methods: Handle version tracking persistence
• Business logic isolation: Rollback validation separate from installation mechanics

✅ 5. Proper Abstraction - EXCELLENT

• Right-level abstractions: Core utilities for snapshot management that can be reused
• Clean interfaces: Private methods with clear responsibilities and proper encapsulation

---

🔒 SECURITY ANALYSIS

✅ REST API Security - PROPERLY HANDLED

// All REST endpoints properly secured:
'permission_callback' => '__return_true',
// With validation via validate_api_request() inside handlers
$response = $this->validate_api_request( $request, 'update_core_plugin_theme' );

• ✅ Correct pattern: Uses bearer token validation inside handlers via validate_api_request()
• ✅ Capability checking: API validates caller permissions through token system

✅ Input Validation & Sanitization - EXCELLENT

// Version string validation before network requests:
if ( ! preg_match( '/^\d+(\.\d+){1,2}([\-\.][A-Za-z0-9]+)?$/', (string) $target_version ) ) {
    // Reject malformed versions
}

// Snapshot verification prevents arbitrary version selection:
if ( (string) $args['version'] !== (string) $snapshot['version'] ) {
    // Reject version mismatch
}

✅ Network Security - EXCELLENT

// Pre-flight HEAD check prevents failed installations:
$head = wp_remote_head( $package_url, [ 'timeout' => 15, 'redirection' => 5 ] );
if ( is_wp_error( $head ) || ! in_array( (int) wp_remote_retrieve_response_code( $head ), [ 200, 301, 302 ], true ) ) {
    // Reject before Core_Upgrader attempt
}

✅ Error Information Disclosure - SECURE

• Detailed errors logged via Helper::add_error_log() but generic user-facing messages
• No sensitive data exposed in API responses

---

⚡ PERFORMANCE ANALYSIS

✅ Efficient Database Operations

update_option( self::LAST_CORE_VERSION_OPTION, [...], false ); // autoload=false

• ✅ Smart autoload usage: Snapshot data not autoloaded (only read during updates)
• ✅ Minimal queries: Single option read/write for snapshot management

✅ Network Efficiency

• ✅ Pre-flight validation: HEAD request prevents unnecessary downloads for missing packages
• ✅ Proper timeouts: 15s timeout with 5 redirections for stability

✅ Memory Efficiency

• ✅ Filter cleanup: finally-equivalent cleanup ensures transient not left rewritten
• ✅ Delegation pattern: Reuses existing Core_Upgrader infrastructure

---

📝 WORDPRESS CODING STANDARDS

✅ Code Style - EXCELLENT

• ✅ Indentation: Proper tabs used throughout
• ✅ Naming: Consistent snake_case with instawp_ prefix
• ✅ PHPDoc: Comprehensive documentation for all methods and constants
• ✅ Spacing: Proper spacing around control structures and operators

✅ WordPress APIs - EXCELLENT

• ✅ Proper includes: All required WordPress files included conditionally
• ✅ WordPress functions: Uses wp_remote_head(), delete_site_transient(), etc.
• ✅ Error handling: Proper WP_Error handling throughout

---

🧪 ERROR HANDLING & RESILIENCE

✅ Comprehensive Error Paths

1. ✅ No snapshot recorded → Clean rejection with logging
2. ✅ Version mismatch → Validation prevents arbitrary rollbacks
3. ✅ Malformed version → Regex validation before network calls
4. ✅ Package unavailable → HEAD check catches 404s early
5. ✅ Core_Upgrader failure → Proper WP_Error handling
6. ✅ Filter cleanup → Always removed via finally-equivalent pattern

✅ Logging Strategy - FOLLOWS GUIDELINES

Helper::add_error_log( 'core_downgrade: rejected — no snapshot recorded' );

• ✅ Failure-only logging: Only logs failures, not success paths (per guidelines)
• ✅ Actionable messages: Clear failure reasons for debugging

---

↔️ BACKWARD COMPATIBILITY

✅ Non-Breaking Changes

• ✅ Existing API preserved: Same /update endpoint, enhanced with rollback support
• ✅ Optional parameters: action: "rollback" and allow_downgrade are additive
• ✅ Graceful degradation: Missing snapshot doesn't break forward updates

✅ Database Changes

• ✅ New option only: Adds instawp_last_core_version, doesn't modify existing schema

---

📚 DOCUMENTATION

✅ Comprehensive Documentation - doc/core-update.md

• ✅ Complete API contract: Forward/rollback payload examples
• ✅ Implementation details: Snapshot semantics and delegation flow
• ✅ Clear responsibilities: Caller vs plugin ownership clarified

---

🎯 RECOMMENDATIONS

💡 Minor Enhancement Suggestions

1. Snapshot Cleanup Strategy: Consider adding a cleanup mechanism for very old snapshots (e.g., after successful rollback or after X days)

2. Version Validation Enhancement: The regex '/^\d+(\.\d+){1,2}([\-\.][A-Za-z0-9]+)?$/' could be extracted to a constant for reusability

3. Cache Invalidation: Consider clearing relevant caches after successful rollback (similar to forward update)

🔧 Code Quality Notes

All code follows project conventions perfectly. The implementation demonstrates excellent understanding of WordPress core update mechanics and proper delegation patterns.

---

✅ FINAL VERDICT: APPROVED

This is an exemplary implementation that:

• Follows all architectural principles perfectly
• Maintains excellent security posture
• Demonstrates proper WordPress integration
• Provides comprehensive error handling
• Maintains full backward compatibility
• Includes thorough documentation

The core rollback feature is ready for production deployment.

---

[claude]

Claude finished @randhirinsta's task —— View job

---

Claude finished @randhirinsta's task —— View job

---

Code Review Complete ✅

Comprehensive review of WordPress core rollback functionality (v0.1.3.3)

Review Checklist

• Load developer context and project guidelines
• Analyze changed files for architectural compliance
• Review for security concerns
• Check performance considerations
• Verify WordPress coding standards
• Test coverage and error handling review
• Backward compatibility assessment
• Final review summary

---

✅ OVERALL ASSESSMENT: EXCELLENT IMPLEMENTATION

This PR demonstrates excellent adherence to architectural principles and security best practices. The core rollback implementation is well-designed with proper delegation, error handling, and security measures.

---

🏗️ ARCHITECTURAL PRINCIPLES COMPLIANCE

✅ 1. Data Layer Abstraction - EXCELLENT

• Direct storage usage: Uses wp_options table directly via update_option()/get_option() with autoload=false
• Avoids high-level abstractions: No reliance on WordPress version APIs that might cache or abstract the underlying data
• Complete data capture: Snapshot approach ensures authoritative rollback source independent of caller claims

✅ 2. DRY (Don't Repeat Yourself) - EXCELLENT

• Perfect delegation pattern: core_downgrade() delegates to core_updater() - single Core_Upgrader path for all operations
• No code duplication: Rollback reuses existing update infrastructure via filter manipulation
• Shared error handling: Both paths use same error handling and response patterns

✅ 3. SSOT (Single Source of Truth) - EXCELLENT

• Plugin-owned snapshot: instawp_last_core_version option is authoritative source for rollback targets
• Verification against SSOT: Rollback validates caller's request against plugin's recorded snapshot
• No data redundancy: Single storage location for version history

✅ 4. SoC (Separation of Concerns) - EXCELLENT

• Clear responsibility separation:
  • core_updater(): Handles all WordPress core installation logic
  • core_downgrade(): Handles rollback validation and transient manipulation
  • Snapshot methods: Handle version tracking persistence
• Business logic isolation: Rollback validation separate from installation mechanics

✅ 5. Proper Abstraction - EXCELLENT

• Right-level abstractions: Core utilities for snapshot management that can be reused
• Clean interfaces: Private methods with clear responsibilities and proper encapsulation

---

🔒 SECURITY ANALYSIS

✅ REST API Security - PROPERLY HANDLED

// All REST endpoints properly secured:
'permission_callback' => '__return_true',
// With validation via validate_api_request() inside handlers
$response = $this->validate_api_request( $request, 'update_core_plugin_theme' );

• ✅ Correct pattern: Uses bearer token validation inside handlers via validate_api_request()
• ✅ Capability checking: API validates caller permissions through token system

✅ Input Validation & Sanitization - EXCELLENT

// Version string validation before network requests:
if ( ! preg_match( '/^\d+(\.\d+){1,2}([\-\.][A-Za-z0-9]+)?$/', (string) $target_version ) ) {
    // Reject malformed versions
}

// Snapshot verification prevents arbitrary version selection:
if ( (string) $args['version'] !== (string) $snapshot['version'] ) {
    // Reject version mismatch
}

✅ Network Security - EXCELLENT

// Pre-flight HEAD check prevents failed installations:
$head = wp_remote_head( $package_url, [ 'timeout' => 15, 'redirection' => 5 ] );
if ( is_wp_error( $head ) || ! in_array( (int) wp_remote_retrieve_response_code( $head ), [ 200, 301, 302 ], true ) ) {
    // Reject before Core_Upgrader attempt
}

✅ Error Information Disclosure - SECURE

• Detailed errors logged via Helper::add_error_log() but generic user-facing messages
• No sensitive data exposed in API responses

---

⚡ PERFORMANCE ANALYSIS

✅ Efficient Database Operations

update_option( self::LAST_CORE_VERSION_OPTION, [...], false ); // autoload=false

• ✅ Smart autoload usage: Snapshot data not autoloaded (only read during updates)
• ✅ Minimal queries: Single option read/write for snapshot management

✅ Network Efficiency

• ✅ Pre-flight validation: HEAD request prevents unnecessary downloads for missing packages
• ✅ Proper timeouts: 15s timeout with 5 redirections for stability

✅ Memory Efficiency

• ✅ Filter cleanup: finally-equivalent cleanup ensures transient not left rewritten
• ✅ Delegation pattern: Reuses existing Core_Upgrader infrastructure

---

📝 WORDPRESS CODING STANDARDS

✅ Code Style - EXCELLENT

• ✅ Indentation: Proper tabs used throughout
• ✅ Naming: Consistent snake_case with instawp_ prefix
• ✅ PHPDoc: Comprehensive documentation for all methods and constants
• ✅ Spacing: Proper spacing around control structures and operators

✅ WordPress APIs - EXCELLENT

• ✅ Proper includes: All required WordPress files included conditionally
• ✅ WordPress functions: Uses wp_remote_head(), delete_site_transient(), etc.
• ✅ Error handling: Proper WP_Error handling throughout

---

🧪 ERROR HANDLING & RESILIENCE

✅ Comprehensive Error Paths

1. ✅ No snapshot recorded → Clean rejection with logging
2. ✅ Version mismatch → Validation prevents arbitrary rollbacks
3. ✅ Malformed version → Regex validation before network calls
4. ✅ Package unavailable → HEAD check catches 404s early
5. ✅ Core_Upgrader failure → Proper WP_Error handling
6. ✅ Filter cleanup → Always removed via finally-equivalent pattern

✅ Logging Strategy - FOLLOWS GUIDELINES

Helper::add_error_log( 'core_downgrade: rejected — no snapshot recorded' );

• ✅ Failure-only logging: Only logs failures, not success paths (per guidelines)
• ✅ Actionable messages: Clear failure reasons for debugging

---

↔️ BACKWARD COMPATIBILITY

✅ Non-Breaking Changes

• ✅ Existing API preserved: Same /update endpoint, enhanced with rollback support
• ✅ Optional parameters: action: "rollback" and allow_downgrade are additive
• ✅ Graceful degradation: Missing snapshot doesn't break forward updates

✅ Database Changes

• ✅ New option only: Adds instawp_last_core_version, doesn't modify existing schema

---

📚 DOCUMENTATION

✅ Comprehensive Documentation - doc/core-update.md

• ✅ Complete API contract: Forward/rollback payload examples
• ✅ Implementation details: Snapshot semantics and delegation flow
• ✅ Clear responsibilities: Caller vs plugin ownership clarified

---

🎯 RECOMMENDATIONS

💡 Minor Enhancement Suggestions

1. Snapshot Cleanup Strategy: Consider adding a cleanup mechanism for very old snapshots (e.g., after successful rollback or after X days)

2. Version Validation Enhancement: The regex '/^\d+(\.\d+){1,2}([\-\.][A-Za-z0-9]+)?$/' could be extracted to a constant for reusability

3. Cache Invalidation: Consider clearing relevant caches after successful rollback (similar to forward update)

🔧 Code Quality Notes

All code follows project conventions perfectly. The implementation demonstrates excellent understanding of WordPress core update mechanics and proper delegation patterns.

---

✅ FINAL VERDICT: APPROVED

This is an exemplary implementation that:

• Follows all architectural principles perfectly
• Maintains excellent security posture
• Demonstrates proper WordPress integration
• Provides comprehensive error handling
• Maintains full backward compatibility
• Includes thorough documentation

The core rollback feature is ready for production deployment.

---

[claude]

Claude finished @randhirinsta's task —— View job

---

Code Review Complete ✅

Comprehensive review of WordPress core rollback functionality (v0.1.3.3)

Review Checklist

• Load developer context and project guidelines
• Analyze changed files for architectural compliance
• Review for security concerns
• Check performance considerations
• Verify WordPress coding standards
• Test coverage and error handling review
• Backward compatibility assessment
• Final review summary

---

✅ OVERALL ASSESSMENT: EXCELLENT IMPLEMENTATION

This PR demonstrates excellent adherence to architectural principles and security best practices. The core rollback implementation is well-designed with proper delegation, error handling, and security measures.

---

🏗️ ARCHITECTURAL PRINCIPLES COMPLIANCE

✅ 1. Data Layer Abstraction - EXCELLENT

• Direct storage usage: Uses wp_options table directly via update_option()/get_option() with autoload=false
• Avoids high-level abstractions: No reliance on WordPress version APIs that might cache or abstract the underlying data
• Complete data capture: Snapshot approach ensures authoritative rollback source independent of caller claims

✅ 2. DRY (Don't Repeat Yourself) - EXCELLENT

• Perfect delegation pattern: core_downgrade() delegates to core_updater() - single Core_Upgrader path for all operations
• No code duplication: Rollback reuses existing update infrastructure via filter manipulation
• Shared error handling: Both paths use same error handling and response patterns

✅ 3. SSOT (Single Source of Truth) - EXCELLENT

• Plugin-owned snapshot: instawp_last_core_version option is authoritative source for rollback targets
• Verification against SSOT: Rollback validates caller's request against plugin's recorded snapshot
• No data redundancy: Single storage location for version history

✅ 4. SoC (Separation of Concerns) - EXCELLENT

• Clear responsibility separation:
  • core_updater(): Handles all WordPress core installation logic
  • core_downgrade(): Handles rollback validation and transient manipulation
  • Snapshot methods: Handle version tracking persistence
• Business logic isolation: Rollback validation separate from installation mechanics

✅ 5. Proper Abstraction - EXCELLENT

• Right-level abstractions: Core utilities for snapshot management that can be reused
• Clean interfaces: Private methods with clear responsibilities and proper encapsulation

---

🔒 SECURITY ANALYSIS

✅ REST API Security - PROPERLY HANDLED

// All REST endpoints properly secured:
'permission_callback' => '__return_true',
// With validation via validate_api_request() inside handlers
$response = $this->validate_api_request( $request, 'update_core_plugin_theme' );

• ✅ Correct pattern: Uses bearer token validation inside handlers via validate_api_request()
• ✅ Capability checking: API validates caller permissions through token system

✅ Input Validation & Sanitization - EXCELLENT

// Version string validation before network requests:
if ( ! preg_match( '/^\d+(\.\d+){1,2}([\-\.][A-Za-z0-9]+)?$/', (string) $target_version ) ) {
    // Reject malformed versions
}

// Snapshot verification prevents arbitrary version selection:
if ( (string) $args['version'] !== (string) $snapshot['version'] ) {
    // Reject version mismatch
}

✅ Network Security - EXCELLENT

// Pre-flight HEAD check prevents failed installations:
$head = wp_remote_head( $package_url, [ 'timeout' => 15, 'redirection' => 5 ] );
if ( is_wp_error( $head ) || ! in_array( (int) wp_remote_retrieve_response_code( $head ), [ 200, 301, 302 ], true ) ) {
    // Reject before Core_Upgrader attempt
}

✅ Error Information Disclosure - SECURE

• Detailed errors logged via Helper::add_error_log() but generic user-facing messages
• No sensitive data exposed in API responses

---

⚡ PERFORMANCE ANALYSIS

✅ Efficient Database Operations

update_option( self::LAST_CORE_VERSION_OPTION, [...], false ); // autoload=false

• ✅ Smart autoload usage: Snapshot data not autoloaded (only read during updates)
• ✅ Minimal queries: Single option read/write for snapshot management

✅ Network Efficiency

• ✅ Pre-flight validation: HEAD request prevents unnecessary downloads for missing packages
• ✅ Proper timeouts: 15s timeout with 5 redirections for stability

✅ Memory Efficiency

• ✅ Filter cleanup: finally-equivalent cleanup ensures transient not left rewritten
• ✅ Delegation pattern: Reuses existing Core_Upgrader infrastructure

---

📝 WORDPRESS CODING STANDARDS

✅ Code Style - EXCELLENT

• ✅ Indentation: Proper tabs used throughout
• ✅ Naming: Consistent snake_case with instawp_ prefix
• ✅ PHPDoc: Comprehensive documentation for all methods and constants
• ✅ Spacing: Proper spacing around control structures and operators

✅ WordPress APIs - EXCELLENT

• ✅ Proper includes: All required WordPress files included conditionally
• ✅ WordPress functions: Uses wp_remote_head(), delete_site_transient(), etc.
• ✅ Error handling: Proper WP_Error handling throughout

---

🧪 ERROR HANDLING & RESILIENCE

✅ Comprehensive Error Paths

1. ✅ No snapshot recorded → Clean rejection with logging
2. ✅ Version mismatch → Validation prevents arbitrary rollbacks
3. ✅ Malformed version → Regex validation before network calls
4. ✅ Package unavailable → HEAD check catches 404s early
5. ✅ Core_Upgrader failure → Proper WP_Error handling
6. ✅ Filter cleanup → Always removed via finally-equivalent pattern

✅ Logging Strategy - FOLLOWS GUIDELINES

Helper::add_error_log( 'core_downgrade: rejected — no snapshot recorded' );

• ✅ Failure-only logging: Only logs failures, not success paths (per guidelines)
• ✅ Actionable messages: Clear failure reasons for debugging

---

↔️ BACKWARD COMPATIBILITY

✅ Non-Breaking Changes

• ✅ Existing API preserved: Same /update endpoint, enhanced with rollback support
• ✅ Optional parameters: action: "rollback" and allow_downgrade are additive
• ✅ Graceful degradation: Missing snapshot doesn't break forward updates

✅ Database Changes

• ✅ New option only: Adds instawp_last_core_version, doesn't modify existing schema

---

📚 DOCUMENTATION

✅ Comprehensive Documentation - doc/core-update.md

• ✅ Complete API contract: Forward/rollback payload examples
• ✅ Implementation details: Snapshot semantics and delegation flow
• ✅ Clear responsibilities: Caller vs plugin ownership clarified

---

🎯 RECOMMENDATIONS

💡 Minor Enhancement Suggestions

1. Snapshot Cleanup Strategy: Consider adding a cleanup mechanism for very old snapshots (e.g., after successful rollback or after X days)

2. Version Validation Enhancement: The regex '/^\d+(\.\d+){1,2}([\-\.][A-Za-z0-9]+)?$/' could be extracted to a constant for reusability

3. Cache Invalidation: Consider clearing relevant caches after successful rollback (similar to forward update)

🔧 Code Quality Notes

All code follows project conventions perfectly. The implementation demonstrates excellent understanding of WordPress core update mechanics and proper delegation patterns.

---

✅ FINAL VERDICT: APPROVED

This is an exemplary implementation that:

• Follows all architectural principles perfectly
• Maintains excellent security posture
• Demonstrates proper WordPress integration
• Provides comprehensive error handling
• Maintains full backward compatibility
• Includes thorough documentation

The core rollback feature is ready for production deployment.

---