Plugin Directory: Add an API to block a release from being served

[obenland]

Summary

Adds the mechanism for holding a release out of the update API: API_Update_Updater::block_release() records a release_block on the release meta, and update_single_plugin() refuses to serve a blocked version — the previously served version keeps being served, and the serve deferred to cooldown-end is cancelled rather than postponed, so a block outlasts the cooldown. The existing reviewer force_release() clears the hold via add_release()'s new unblock flag.

This is the mechanism half of the release-block work, without any UI: block_release() has no callers yet. The scan-driven caller (a high max_risk_score verdict blocking the scanned release) follows in #777 once this lands.

Blocks are deliberately scoped to a single release: a new version escapes the hold, so an author can ship a fixed release without plugin-review-team intervention, while unblocking the held version itself requires a reviewer force-release.

How it works

• block_release( $slug, $block ) refuses when the version cannot be held: no plugin, no release record, the version already being served, or the block failing to persist. Blocking an already-held release is an idempotent no-op success that preserves the existing block (a second record would merge into the first). On success it stamps blocked_at, records the block, and re-runs update_single_plugin() so a serve scheduled for cooldown-end is cancelled now. Capability checks and audit logging are deliberately the caller's.
• is_release_blocked( $release ) is the single predicate update_single_plugin() and callers share.
• get_served_version( $slug ) exposes the row's version for callers' precondition checks.
• Status changes made while a version is held (a closure, a reopen) still reach the row immediately through Plugin Directory: Sync plugin status to the update API during a release cooldown #783's partial sync.

Testing

The cooldown suite and the new block tests are merged into tests/Update_Source_Hold_Test.php (16 tests). The block half: a block holds an unserved version and cancels the deferred serve (scheduled first, so the cancellation is actually exercised); the block, not the cooldown clock, holds the version — proven with the cooldown cleared for both a staged and a first-ever release; served (including varchar(128)-truncated) and unknown releases refuse to block, without touching the network; re-blocking an already-held release is a no-op success that preserves the first block; a status change reaches the row while held; force-release clears the hold and serves the version, both alone and combined with an active cooldown (covering the combined audit message). Both block gates in update_single_plugin() were mutation-tested: removing the is_release_blocked() early return or its wp_clear_scheduled_hook() call fails the suite, as does reverting the cooldown gate's varchar(128) truncation allowance or breaking the combined force-release log assembly.

🤖 Generated with Claude Code

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props obenland.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[Copilot]

Pull request overview

This PR adds a “release block” mechanism to prevent a specific plugin release from being served via the update API, while continuing to serve the previously-served version and canceling any scheduled cooldown-based serve. It also wires force-release to clear an existing block and includes tests for both cooldown syncing behavior and release blocking.

Changes:

• Add API_Update_Updater::block_release(), is_release_blocked(), and get_served_version() plus update gating in update_single_plugin() to keep blocked versions out of update_source.
• Extend Plugin_Directory::add_release() to support an unblock flag used by force-release to clear a block.
• Add PHPUnit coverage for cooldown status syncing and release blocking/force-release behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
wordpress.org/public_html/wp-content/plugins/plugin-directory/jobs/class-api-update-updater.php	Adds release-block API and updates update_single_plugin() to keep blocked versions from being served while still syncing availability fields.
wordpress.org/public_html/wp-content/plugins/plugin-directory/class-plugin-directory.php	Adds unblock handling in add_release() to clear release_block metadata.
wordpress.org/public_html/wp-content/plugins/plugin-directory/tests/Update_Source_Cooldown_Test.php	Tests that cooldown defers only the version bump while status changes sync to update_source.
wordpress.org/public_html/wp-content/plugins/plugin-directory/tests/Release_Block_Test.php	Tests that blocking holds an unserved version, cancels deferred serve, outlasts cooldown, and force-release clears the block.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (5)

wordpress.org/public_html/wp-content/plugins/plugin-directory/jobs/class-api-update-updater.php:477

• force_release() doesn’t check whether Plugin_Directory::add_release() succeeded. If that write fails, the method can still return true (because update_single_plugin() is largely idempotent), even though the cooldown/block wasn’t actually cleared.

		Plugin_Directory::add_release(
			$post,
			array(
				'tag'           => $release['tag'],
				'release_delay' => 0,
				// Clear any release block so update_single_plugin() serves the version.
				'unblock'       => true,
			)
		);

		return self::update_single_plugin( $plugin_slug );
	}

wordpress.org/public_html/wp-content/plugins/plugin-directory/tests/Release_Block_Test.php:254

• force_release() requires $_SERVER['REMOTE_ADDR'] for audit logging. After moving the REMOTE_ADDR setup out of setUp(), set it just for this test and restore/unset it afterwards to avoid global leakage.

	public function test_force_release_clears_block(): void {
		$this->insert_served_row();
		$this->assertTrue( $this->block() );

		$this->assertTrue( API_Update_Updater::force_release( $this->plugin->post_name, 'Reviewed; false positive.' ) );

wordpress.org/public_html/wp-content/plugins/plugin-directory/jobs/class-api-update-updater.php:291

• block_release() returns true even if Plugin_Directory::add_release() fails to persist the release_block. In that failure mode the release is not actually held, and the subsequent update_single_plugin() call won’t cancel any deferred serve because is_release_blocked() will still be false.

This issue also appears on line 466 of the same file.

		$block['blocked_at'] = time();

		Plugin_Directory::add_release(
			$post,
			array(
				'tag'           => $release['tag'],
				'release_block' => $block,
			)
		);

		// Cancel a serve scheduled for cooldown-end; the row keeps the previous version.
		self::update_single_plugin( $plugin_slug );

		return true;

wordpress.org/public_html/wp-content/plugins/plugin-directory/tests/Release_Block_Test.php:158

• This test asserts that the deferred serve cron is cancelled, but it never schedules the cooldown cron in the first place (so wp_next_scheduled() would be false even if the block logic didn’t clear anything). Set up the cooldown schedule via update_single_plugin() before blocking, then assert it gets cleared.

	public function test_block_holds_unserved_version(): void {
		$this->insert_served_row();

		$this->assertTrue( $this->block() );
		$this->assertTrue( API_Update_Updater::is_release_blocked( $this->get_release() ) );

wordpress.org/public_html/wp-content/plugins/plugin-directory/tests/Release_Block_Test.php:54

• setUp() unconditionally overwrites $_SERVER['REMOTE_ADDR'], which can leak global state into other tests. Since it’s only needed for force_release() (audit logging), set it locally in test_force_release_clears_block() and restore/unset it afterwards.

This issue also appears on line 249 of the same file.

		wp_cache_flush();

		// Tools::audit_log() reads it unguarded.
		$_SERVER['REMOTE_ADDR'] = '127.0.0.1';

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.