Write state propagation outbox row on namespace transitions
What does this MR do and why?
Problem: When a group is archived or scheduled for deletion, its subgroups should follow. The pieces to do that already exist (an outbox table, Namespaces::StatePropagationService, Namespaces::StatePropagationWorker), but nothing ever writes to the outbox. So today subgroups never get their parent's new state.
Solution: When a group's state changes, write one outbox row describing the change, in the same transaction, and start the worker after commit. The worker then walks the subgroups and updates them.
How a state change reaches subgroups
sequenceDiagram
participant U as User action
participant G as Group (state machine)
participant O as Outbox table
participant W as StatePropagationWorker
participant D as Subgroups
U->>G: archive
activate G
Note over G,O: one transaction
G->>G: state = archived
G->>O: insert row (source: ancestor_inherited, target: archived)
deactivate G
G-->>W: perform_async (only after commit)
W->>O: read and claim row
W->>D: move matching subgroups to archived
W->>O: delete rowBecause the state change and the row are written in one transaction, they either both happen or neither does (ADR 003). The worker is only enqueued once the commit succeeds, so it never runs for a change that was rolled back.
What the row records
Each row stores two states:
target_state: the group's new state.source_state: the state the subgroups currently have from this group. The worker uses it to decide which subgroups to change, and (since !258166 (merged)) whether to save or clear their previous state.
Usually source_state is simply the state the group just left. The exception is the short-lived "in progress" states (deletion_in_progress, transfer_scheduled, transfer_in_progress). Subgroups never get these states, so the group's previous state is the one that matters. That state is already saved when the group enters the in-progress state, and this MR reads it from there.
Example: cancelling a deletion that already started
stateDiagram-v2
direction LR
ancestor_inherited --> deletion_scheduled: schedule deletion
deletion_scheduled --> deletion_in_progress: start deletion
deletion_in_progress --> ancestor_inherited: cancel deletionIf the row used the state the group just left, it would say source: deletion_in_progress. The worker can't use that (subgroups were never in it), so it would drop the row:
Using the state just left (source_state = deletion_in_progress):
Parent (deletion_in_progress → ancestor_inherited)
└── Subgroup (deletion_scheduled) → ❌ stays deletion_scheduled
With it (source_state = deletion_scheduled, saved at "start deletion"):
Parent (deletion_in_progress → ancestor_inherited)
└── Subgroup (deletion_scheduled) → ✅ ancestor_inheritedWhen no row is written
A row is only written when it can change a subgroup:
| Case | Example | Why no row |
|---|---|---|
| Group returns to the state subgroups already have | reschedule_deletion after start_deletion on a deletion_scheduled group; cancel_transfer on an archived group |
Subgroups already match. A row would make the worker walk the whole subtree for nothing. |
Group goes back to ancestor_inherited from an in-progress state with no saved state |
cancel_transfer from transfer_scheduled when nothing was saved |
Subgroups never took the in-progress state, so there is nothing to undo. The worker would log an error and drop the row. |
| Group enters an in-progress state | start_deletion, schedule_transfer, start_transfer |
These states are never passed to subgroups. |
| Project namespace | archiving a project | It has no subgroups. |
| Feature flag off | See below. |
Other details
- Gated by the
namespace_state_propagation_outboxfeature flag (gitlab_com_derisk, default off). It is checked againstroot_ancestor, so a whole hierarchy is enabled at once. - If a
pendingorprocessingrow already exists for the same group and target, the insert does nothing and the transition still succeeds. The worker is still enqueued, and its deduplication handles repeats. The existing row keeps its originalsource_state. exists?+create!was avoided because it is racy, and aRecordNotUniquewould roll back the state change (this is what happened in the closed !247075 (closed)).create_or_find_by!was avoided because it uses subtransactions.- The callback writes to another table on purpose: the outbox pattern requires the row to be in the same transaction as the state change.
Database queries
INSERT INTO "namespace_state_propagations"
("namespace_id", "source_state", "target_state", "status", "created_at", "updated_at")
VALUES (<namespace_id>, 0, 1, 0, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
ON CONFLICT ("namespace_id", "target_state") WHERE (status = ANY (ARRAY[0, 1])) DO NOTHING
RETURNING "id"Insert on public.namespace_state_propagations (cost=0.00..0.02 rows=1 width=46) (actual time=0.780..0.782 rows=1 loops=1)
Conflict Resolution: NOTHING
Conflict Arbiter Indexes: idx_namespace_state_propagations_unique_pending_processing
Buffers: shared hit=37 read=5 dirtied=12 written=6
WAL: records=14 fpi=0 bytes=1228
I/O Timings: read=0.143 write=0.088
-> Result (cost=0.00..0.02 rows=1 width=46) (actual time=0.147..0.147 rows=1 loops=1)
Buffers: shared hit=17 dirtied=1
Trigger RI_ConstraintTrigger_<redacted> for constraint fk_9798d3f752: time=21.015 calls=1- Cold: 22.2 ms (5 buffers read, ~40 KiB), mostly the foreign key check on
namespaces. Warm: 3.3 ms (41 hits, 2.8 ms of it the foreign key check). - Plan: https://console.postgres.ai/gitlab/projects/gitlab-production-main/sessions/70310/commands/174589
Known follow-ups (out of scope)
Overlapping state propagations for the same nam... (#635402 - closed)
References
- #599305 (closed)
- Blocked by #633441 (closed)
- Builds on !258166 (merged) (merged), which reads
source_stateto save or clear subgroup states - ADR 003: State propagation model
- ADR 006: State preservation
- Epic: &21923
Screenshots or screen recordings
Not applicable (backend only).
How to set up and validate locally
bin/rspec spec/models/concerns/namespaces/stateful_spec.rb \
spec/services/namespaces/state_propagation_service_spec.rb \
spec/workers/namespaces/state_propagation_worker_spec.rbOr in a Rails console:
parent = Group.find(...) # a group with at least one subgroup
child = parent.children.first
Feature.enable(:namespace_state_propagation_outbox, parent.root_ancestor)
parent.archive(transition_user: User.first)
Namespaces::StatePropagation.where(namespace_id: parent.id).last
# => pending row, source_state: "ancestor_inherited", target_state: "archived"
Namespaces::StatePropagationWorker.new.perform(parent.id, 'archived')
child.reload.state_name
# => :archivedMR 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.