fix(api): start lifecycle subscriptions from live events

[ogulcancelik]

Summary

• start lifecycle subscriptions at one request boundary instead of replaying retained history
• preserve setup-window events, live delivery, and state-aware subscription behavior
• document gap-free snapshot bootstrap ordering

Testing

• just check

Refs #1270

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: cfb99c57-ccb9-4cc1-b0fa-da6dc4cedc96

📥 Commits

Reviewing files that changed from the base of the PR and between c9601b9 and fcc4a26.

📒 Files selected for processing (8)

• docs/next/CHANGELOG.md
• docs/next/website/src/content/docs/ja/socket-api.mdx
• docs/next/website/src/content/docs/socket-api.mdx
• docs/next/website/src/content/docs/zh-cn/socket-api.mdx
• src/api/server.rs
• src/api/subscriptions.rs
• src/api/wait.rs
• tests/api_ping.rs

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

Lifecycle subscriptions now start from the event sequence captured during setup. Earlier retained events are not replayed. Tests cover setup-time and later events. Socket API documentation describes the new subscription and snapshot bootstrap behavior.

Changes

Subscription Event Boundary

Layer / File(s)	Summary
Capture and apply the event sequence baseline src/api/server.rs, src/api/subscriptions.rs, src/api/wait.rs	Subscription entry points capture the current event sequence. ActiveSubscription uses it for all event subscriptions.
Validate retained-event exclusion and live delivery src/api/subscriptions.rs, tests/api_ping.rs	Tests verify that earlier events are skipped and setup-time or later events are delivered.
Document snapshot bootstrap and subscription timing docs/next/CHANGELOG.md, docs/next/website/src/content/docs/...	Socket API documentation describes event buffering during snapshot bootstrap and the lifecycle subscription start boundary in three languages.

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

Merge Risk: ⚪ Minimal · up to fcc4a

This change is merge-ready after normal checks and review; no actionable merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 4 files. (4 skipped: 4 unsupported.)	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly and concisely describes the main change: lifecycle subscriptions now start from live events.
Description check	✅ Passed	The description accurately summarizes the subscription boundary, event preservation, snapshot bootstrap, testing, and issue reference.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue/1270-events-subscribe-live-only

---

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

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

[greptile-apps]

Greptile Summary

The PR changes lifecycle subscriptions to begin at a shared request-time event sequence rather than replaying retained history, while preserving events emitted during setup and subsequent live delivery.

• Captures one EventHub sequence boundary for all lifecycle subscriptions in an events.subscribe request.
• Passes the new constructor argument through subscription and wait call sites.
• Adds unit and integration coverage for history exclusion and setup-window delivery.
• Documents gap-free snapshot bootstrap ordering and the live-only lifecycle contract in English, Japanese, and Chinese documentation.

Confidence Score: 5/5

The PR appears safe to merge, with lifecycle history exclusion and setup-window continuity aligned with the EventHub sequence semantics.

The shared watermark excludes events at or before request handling while strict greater-than polling retains every event published after that boundary; the changed wait call does not alter its supported state-aware branch.

Important Files Changed

Filename	Overview
src/api/server.rs	Captures one event sequence at lifecycle subscription request handling and shares it across subscription construction.
src/api/subscriptions.rs	Initializes lifecycle event subscriptions from the supplied sequence boundary and adds coverage proving retained history is skipped while setup and live events are delivered.
src/api/wait.rs	Updates the subscription constructor call; the supported event-wait branch retains its existing state-aware sequence and snapshot behavior.
tests/api_ping.rs	Extends integration coverage to ensure a new lifecycle stream does not replay the root pane creation event.
docs/next/website/src/content/docs/socket-api.mdx	Documents live-only lifecycle subscriptions and the subscribe-buffer-snapshot bootstrap ordering.

Sequence Diagram

sequenceDiagram
  participant C as Client
  participant S as API server
  participant H as EventHub
  participant A as Application
  C->>S: events.subscribe
  S->>H: current_sequence()
  H-->>S: request boundary N
  A->>H: publish setup event N+1
  S-->>C: subscription_started
  S->>H: events_after(N)
  H-->>S: event N+1
  S-->>C: setup event
  A->>H: publish live event N+2
  S->>H: events_after(N+1)
  H-->>S: event N+2
  S-->>C: live event

Loading

_{Reviews (1): Last reviewed commit: "fix(api): start lifecycle subscriptions ..." | Re-trigger Greptile}