Map: realtime vocabulary and the suspended connection

Open
  • Is something wrong?
#233 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
30/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Quiet
Tech stack
typescript
Domain
api, distributed-systems

Research direction

Start with the realtime drivers in lib/drivers/, the vocabulary in CONTEXT.md, and the pinning tests under lib/drivers/tests/. Resolve the unspecified public-surface and reconnect-budget decisions, then document and test the agreed Open, Connected, Logged in, Suspended, Heartbeat, timeout, Probe, and Lost signal behavior without renaming emitted events.

Written by the indexing model from the issue text.

Description

wayfinder:map

Destination

The realtime layer's names match what the code does, and a suspended connection cannot pass as a healthy one.

Notes

Domain: the DDP realtime layer (lib/drivers/) and the vocabulary in CONTEXT.md. Consumed by Rocket.Chat.ReactNative; the SDK ships TypeScript source with no build step, so every exported name is public API to that app.

Standing constraints for this effort:

  • Mobile backgrounding is the driving case. iOS freezes the TCP socket silently — no close, no error — so connected keeps returning true and send() hangs awaiting 'open'. Android keeps listeners alive and delivers a burst on foreground. Same staleness number, opposite meanings.
  • VoIP has a hard 10s deadline to reconnect and get a DDP event to the server. Every wait on the reconnect path spends from that one budget.
  • Chat-history sync is out of scope — the consuming app already fetches messages since its last fetch over REST.
  • lib/drivers/__tests__/ is a pinning suite: it locks current behaviour, quirks included. Identifier renames are mechanical there; behaviour changes are not.
  • Skills: /domain-modeling for every glossary ticket, /grilling for the decisions.

Prior art consulted: the DDP spec, Meteor's client, @rocket.chat/ddp-client, and ten realtime chat SDKs (Matrix, Stream, Sendbird, Twilio, Slack, Pusher, Ably, Centrifugo, Phoenix, Strophe).

Decisions so far

  • Connection states are named Open / Connected / Logged in.
  • "Liveness chain" is dropped for Heartbeat, keeping upstream's three-way split: ping/pong are wire frames, heartbeat is the local timer, timeout is the dead-connection trigger. Probe stays — it has no upstream equivalent.
  • Two kinds of message loss, and only one belongs here. Lost signal — an event sent between sub and the server's ready, gone permanently, no backfill possible, only avoidable by waiting for the ack — is this SDK's concern. Chat-history gaps are the consumer's and already handled.
  • Suspended is adopted for a socket the OS froze that still reads as open. This unnamed state is the VoIP bug.
  • Rocket.Chat's Impl suffix, no-I-prefix convention, uid, and its server-side "publication" term are not borrowed. Consistency with this repo wins, and "publication" has no referent here.
  • Emitted event names are not renamed in this effort — they are wire-observable and pinned.

Not yet specified

  • Whether the SDK should surface a "you were suspended" signal to the consuming app at all, or keep it internal to the reconnect path.
  • Whether probe belongs on the public surface once Suspended is a named state.
  • Whether the reconnect path needs a stated budget split per leg, which depends on what the measurements show.

Out of scope

  • Chat-history gap recovery — the consuming app already syncs messages since its last fetch over REST. Building it here would duplicate it in the wrong layer.
Dominant language
TypeScript
Stars
146
Forks
101
No merged PRs in 30d

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from RocketChat/Rocket.Chat.js.SDK

All issues in RocketChat/Rocket.Chat.js.SDK

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.