DDP, Driver and Socket name three different things, and the fields don't match them

[diegolmello]

What

CONTEXT.md draws a clear line between two of these:

• Driver — the realtime transport behind a Client, speaking one wire protocol to the server. Explicitly not a Socket.
• Socket — the raw websocket inside a Driver.

DDP is the third word in play. In CONTEXT.md it is only ever a qualifier on the wire vocabulary — DDP message, DDP response, DDP error, DDP subscription — never a name for an object. But in the code it is used as a field name for objects, and for two different ones.

Where the names don't line up

• Driver.ddp holds a Socket. So the field named after the protocol holds the raw websocket.
• RocketChatClient.ddp holds a Driver. Same field name, one level up, different type.
• RocketChatClient implements ISocket, so the Client also claims to be a Socket, which by CONTEXT.md it is not.
• Until recently RocketChatClient also carried a socket field that held a Driver — a third name for the same thing, under the one word CONTEXT.md reserves for the websocket. That field is being removed (see refactor: hold the Driver directly as ddp, instead of an always-resolved socket Promise #336), which is what surfaced the wider problem.

The result is that client.ddp.ddp is the Socket, and no field name predicts its own type. Reading a call site does not tell you which layer you are on.

Why it matters

The layers behave very differently — a Driver reconnects, tracks DDP subscriptions and speaks method calls; a Socket opens, closes and carries frames. Code that reaches the wrong one compiles fine and misbehaves at runtime. Rocket.Chat.ReactNative already reaches across the boundary (sdk.current.ddp for driver-level health checks), so the naming is load-bearing outside this repo too.

What to decide

• Whether DDP should name an object at all, or stay a qualifier on wire vocabulary as CONTEXT.md has it.
• What Driver's field for its Socket should be called.
• What a Client's field for its Driver should be called, given ddp is the name consumers already use.
• Whether RocketChatClient should keep implements ISocket.
• Whether any rename can land without breaking Rocket.Chat.ReactNative, and what the migration looks like if not.

This is a naming and layering review, not a bug — worth settling before more code is written against the current names.

[diegolmello]

This was generated by AI during triage.

Triage: verified, enhancement + ready-for-human

Every claim in the description checks out against the code on mobile:

• Driver.ddp is typed and constructed as a Socket (lib/drivers/driver.ts:23, :42).
• RocketChatClient.ddp is a Driver (lib/clients/Rocketchat.ts:10, :15). Same field name, inverted meaning one layer up — client.ddp.ddp really is the Socket.
• RocketChatClient extends ClientRest implements ISocket (lib/clients/Rocketchat.ts:6), while Driver implements ISocket, IDriver (lib/drivers/driver.ts:20). Both layers claim to be a Socket.
• One correction: socket has not been removed yet. socket: Promise<ISocket | IDriver> still exists (lib/clients/Rocketchat.ts:9), resolved to the Driver at :16, and every delegating method still goes through await this.socket with casts. refactor: hold the Driver directly as ddp, instead of an always-resolved socket Promise #336 is still an open PR, so ddp and socket currently coexist as two names for the same Driver.
• CONTEXT.md backs the complaint: Driver's entry explicitly says avoid "Socket", Client "owns a Driver; is not one", and every DDP* term is message-level vocabulary. Nothing sanctions ddp as an object name.

No existing ADR covers Driver/Socket naming or layering (docs/adr/ runs 0001–0006), so this would land as a new one.

Why ready-for-human, not ready-for-agent

The description ends in five open decisions, not a specification. The blocking one is external: sdk.current.ddp is the name Rocket.Chat.ReactNative already reaches through for driver-level health checks, so any rename is a coordinated cross-repo API change with a deprecation window — a judgment call about consumer breakage, not a mechanical refactor.

Suggested order once the decisions are made:

1. Land refactor: hold the Driver directly as ddp, instead of an always-resolved socket Promise #336 first, so there is one field for the Driver instead of ddp plus a socket Promise.
2. Settle the vocabulary and record it as an ADR plus a CONTEXT.md update: does DDP name an object at all, what a Driver calls its Socket, what a Client calls its Driver, and whether RocketChatClient keeps implements ISocket.
3. Only then rename, with whatever aliasing the mobile app needs to migrate without a hard break.

Steps 1 and 3 are delegable once step 2 is decided.

[diegolmello]

This was generated by AI during triage.

Correction: #336 is merged

#336 landed on mobile, so my earlier note about socket still existing is out of date. Re-checked against origin/mobile:

• socket: Promise<ISocket | IDriver> and all the await this.socket casts are gone. RocketChatClient now holds only ddp: Driver (lib/clients/Rocketchat.ts:9, :14), and every delegating method calls it directly.
• Everything else in this issue is unchanged: Driver.ddp is still a Socket (lib/drivers/driver.ts:23, :42), and both RocketChatClient (lib/clients/Rocketchat.ts:6) and Driver (lib/drivers/driver.ts:20) still implements ISocket.

Net effect: step 1 of the suggested order is done, and the three-names-for-one-thing problem has collapsed into the two-layer inversion — ddp means Driver on the Client and Socket on the Driver. The open decisions and the cross-repo migration question are untouched, so this stays ready-for-human.

[diegolmello]

This was generated by AI during triage.

Decisions

The naming questions are settled. The starting premise was partly wrong, so the correction matters as much as the decisions.

The layering is four deep, not three: Client -> Driver -> Socket -> Transport. The class Socket is not a websocket — it performs the DDP handshake (send({ msg: 'connect' })), answers pings with { msg: 'pong' }, and holds subscriptions and lastPing. It owns the raw websocket as connection.

CONTEXT.md's body was already consistent with that. Transport open says "what the websocket itself says about a Socket ... its transport reports it open"; Liveness chain, Probe, Detached socket, Connected echo and Reopen all treat a Socket as the DDP layer that owns a transport. Exactly one line disagreed — the Driver entry's _Avoid_: Socket (that is the raw websocket inside a driver). That parenthetical was the defect, not the five entries.

Decided:

1. DDP stays a qualifier on wire vocabulary. No object is named ddp.
2. Driver.ddp -> socket — it holds a Socket, which is now a defined domain term.
3. RocketChatClient.ddp -> driver — a Client owns a Driver.
4. RocketChatClient drops implements ISocket. No IClient until something needs to type against it.
5. ISocket keeps its name. A Driver presenting the same realtime surface by delegation is ordinary delegation.
6. No deprecation alias, and the renames land alongside the consuming app's update rather than ahead of it.

Done in this pass (docs and comments only, no renames)

• CONTEXT.md: corrected the Driver entry's parenthetical, and added Socket and Transport as glossary entries so all four layers are named.
• Comments in lib/drivers/driver.ts, lib/drivers/socket.ts and lib/drivers/__tests__/driver.spec.ts that called the Socket "the raw socket" or described it as a websocket handler.
• The ADRs needed no change — 0001, 0003, 0004, 0005 and 0006 already use Socket for the DDP layer and "transport"/WebSocket for the raw one.

164 driver tests pass; lint is unchanged.

What is left

The renames themselves (items 2-4). They are not free: the consuming app reads both fields by name — sdk.current?.ddp for socket health and call recovery, and driver.ddp.open() / .subscriptions / .lastPing / .send() in its integration tests. That app types this SDK through a loose module declaration, so a rename does not fail at compile time — it fails at runtime as undefined. Both repos therefore need to move together, which is why this stays ready-for-human.

[diegolmello]

This was generated by AI during triage.

Decision 7: the Socket is private to the Driver

Driver.ddp becomes private readonly socket: Socket, not just socket.

Nothing in the consuming app's production code needs it. The Driver already forwards every member that app reaches for: connected, checkAndReopen, reopenNow, probe, lastPing, pingInterval, config and waitForNotifyUserMediaSubs. Its two real call sites stay at the Driver.

The only readers below the Driver are tests, in this repo and in the app. They keep working — and keep their types — through bracket access, driver['socket'].subscriptions, which TypeScript permits on a private member. private is compile-time only, so runtime behaviour and the loosely-typed consumer are unaffected.

Rejected: #socket, which breaks bracket access and would force test rewrites in both repos for no gain against accidental reach; and an /** @internal */ tag alone, which enforces nothing.

Cost: the app's integration tests must move to bracket access, so the rename touches one more file there.

Also done in this pass

Deleted clients/Rocketchat.ts. It was a tracked one-line export * from '../lib/clients/Rocketchat' that nothing imported — index.ts imports the module directly, and the app's only deep imports go to lib/drivers. It was already inert regardless: export * does not re-export a default, and that module's only meaningful export is its default.

tsc --noEmit is clean and all 176 tests pass.