fix(subscriptions): stop a subscription delete from disconnecting its subscribers

[yordis]

• Deleting a subscription tore down the process that every one of its subscribers shares, so a caller holding none of it could destroy a live subscription and erase the checkpoint it was working through. The subscribers found out only from the resulting :DOWN, which is indistinguishable from the event store going away.
• A name is the only thing a caller needs to delete a subscription, and names are shared: concurrent subscribers all connect to one, and an unrelated process can pick a name someone else already holds. Deletion has to be refused while anyone is still attached, otherwise holding a subscription guarantees nothing.
• A delete that used to answer :ok while subscribers were connected now answers {:error, :subscription_has_subscribers}, which the callback already declared as possible. Callers that relied on it to force a disconnect must unsubscribe first.

[cursor]

PR Summary

Medium Risk
Changes subscription lifecycle and delete API semantics (:subscribers_connected), with unbounded waits during stop/checkpoint that could affect callers expecting immediate :ok on delete.

Overview
Deleting a persistent subscription no longer kills the shared subscription process while subscribers are attached. delete_subscription / delete_all_streams_subscription now return {:error, :subscribers_connected} when any subscriber is still connected; callers must unsubscribe first. Stopping goes through a new cooperative Subscription.stop/1 (infinite timeout) instead of DynamicSupervisor.terminate_child, and the supervisor waits for the process to exit so a final checkpoint in terminate/2 can finish before the DB row is removed.

Subscription checkpoint writes are now observable via telemetry. Each persisted checkpoint emits [:eventstore, :subscription_checkpoint, ...] with stream_uuid, subscription_name, and last_seen; subscribe passes telemetry_metadata into the subscription process. Usage guide and tests cover delete races, checkpoint timing, and telemetry for refused deletes and checkpoints.

^{Reviewed by Cursor Bugbot for commit 2aa0d16. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: b537daaf-22e1-453d-b720-366cc6c12396

📥 Commits

Reviewing files that changed from the base of the PR and between e75ad72 and f4517a1.

📒 Files selected for processing (3)

• lib/event_store.ex
• lib/event_store/subscriptions/subscription.ex
• test/subscriptions/subscribe_to_stream_test.exs

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Walkthrough

The change updates subscription deletion to stop a subscription only when no subscribers remain. It reports {:error, :still_subscribed} for connected subscribers and adds tests for termination, cleanup, and connection races.

Changes

Subscription deletion coordination

Layer / File(s)	Summary
Termination contract and callback results lib/event_store.ex, lib/event_store/subscriptions/subscription.ex	Callback specifications use {:error, :still_subscribed}. The subscription process stops only when its subscriber map is empty.
Coordinated subscription termination lib/event_store/subscriptions/supervisor.ex	stop_subscription/3 monitors the process, requests conditional termination, handles already-terminating processes, and waits for the process to exit.
Deletion behavior validation test/subscriptions/subscribe_to_stream_test.exs, test/telemetry_test.exs	Tests cover connected and concurrent subscribers, empty and terminating subscriptions, storage cleanup, connection races, helper setup, and telemetry deletion setup.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant EventStore
  participant Supervisor
  participant Subscription
  EventStore->>Supervisor: stop_subscription/3
  Supervisor->>Subscription: stop_unless_subscribed
  Subscription-->>Supervisor: termination result
  Supervisor-->>EventStore: deletion result

Loading

Merge Risk: ⚪ Minimal · up to f4517

The deletion result is consistent with the intentional public contract, and deletion waits for shutdown before checking process liveness. No actionable merge risk remains.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 5 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: subscription deletion no longer disconnects active subscribers.
Description check	✅ Passed	The description explains why deletion must be refused while subscribers remain connected and describes the resulting behavior change. It uses an outdated error atom compared with the changeset, but it…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit reads each line,
The patch grows clear beneath the moon,
Small changes hop in place,
Tests guard the garden path,
Reviews bloom before the dawn.}

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 739df40. Configure here.}