Add state machine transitions for namespace maintenance mode (Step 1)

Chen Zhangrequested to merge
duo-edit-20260307-155643 into master

What does this MR do and why?

This MR implements Step 1 of the POC for read-only mode for top-level groups, as tracked in #590009 (closed) (task #591688).

It adds enter_maintenance and exit_maintenance events to the Namespaces::Stateful state machine, enabling namespaces to be placed into a maintenance state. This is the foundation that Steps 2-4 (middleware, error page, GraphQL enforcement) will build upon.

Changes

State Machine (app/models/concerns/namespaces/stateful.rb)

  • enter_maintenance event: transitions from ancestor_inherited or archived to maintenance
  • exit_maintenance event: transitions from maintenance back to the preserved previous state
  • Requires transition_user for enter_maintenance (follows schedule_deletion / start_transfer pattern)

State Preservation (app/models/concerns/namespaces/stateful/state_preservation.rb)

  • Added enter_maintenance: :exit_maintenance to STATE_MEMORY_CONFIG
  • Added restore_to_archived_on_exit_maintenance? guard method
  • When a namespace enters maintenance from :archived, exiting maintenance restores it to :archived (not :ancestor_inherited)

Transition Validation (app/models/concerns/namespaces/stateful/transition_validation.rb)

  • Added maintenance to FORBIDDEN_ANCESTOR_STATES for archive, unarchive, schedule_deletion, and enter_maintenance
  • Prevents child namespaces from being archived, deleted, or entering maintenance when an ancestor is already in maintenance

Usage (Rails console) 

# Enter maintenance mode
namespace.enter_maintenance!(transition_user: current_user)

# Exit maintenance mode (restores previous state)
namespace.exit_maintenance!

How to set up and validate locally

  1. Open Rails console
  2. Find a namespace: ns = Namespace.find_by_path('my-group')
  3. Enter maintenance: ns.enter_maintenance!(transition_user: User.first)
  4. Verify state: ns.state_name # => :maintenance
  5. Verify preservation: ns.state_metadata.dig('preserved_states', 'enter_maintenance') # => "ancestor_inherited"
  6. Exit maintenance: ns.exit_maintenance!
  7. Verify restored: ns.state_name # => :ancestor_inherited

Related issues

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Merge request reports