Chapter 30
One SDK, many platforms
If the client half is written once for iOS, once for Android and once for desktop, there are three separate sets of bugs. What should be written only once, and what has to stay on each platform?
This chapter is a first draft. The author is still checking it, and its text and numbers may change.
From chapter 3 until now, the client half has collected quite a few rules: the outbox and resends, message IDs, ordering by seq and filling gaps, syncing conversation records, one transaction per page, uploading in chunks, a read position that only moves up, heartbeats, backing off on reconnect… Together they are the IM SDKIM SDKThe client library inside every app: the outbox and retries, sync, the local database, and the API the app uses.See the glossary: the client library inside every app.
v3’s app has three native versions, iOS, Android and desktop, plus the web. The most natural approach is for each platform’s team to write its own, in its own language.
This chapter’s question: should the client half be written again for each platform?
1. One rule, three ways to write it
Take one rule from chapter 7: when filling a gap, a page of messages and the cursor it moves (which records “filled up to here”) are committed in the same transaction. A transaction is a group of writes that either all take effect or none do.
Three teams each read the rule, and wrote it differently:
- Android: commits each message separately, and moves the cursor first;
- iOS: commits once per page, also moving the cursor first;
- Desktop: a page of messages and the cursor in one transaction.
Take chapter 7’s busy evening again: 227 messages in three groups, fetched in 6 pages, and the app killed at 1.2 seconds. Chapter 7’s simulator runs once for each way of writing it:
| Platform | How it is written | Messages lost (killed at 1.2 s) | Share of possible kill moments that lose messages |
|---|---|---|---|
| Android | Commit per message, cursor first | 31 | 85.2% |
| iOS | Commit per page, cursor first | 29 | 4.3% |
| Desktop | Page and cursor in one transaction | 0 | 0 |
Moving the cursor first goes wrong between two commits: the cursor already says “filled up to here”, the messages after it are not written yet, and the app is killed. On the next start the app fetches from the cursor onwards, so the ones that were never written are skipped. The last column tries every kill moment from start to end and shows what share of them lose messages.
The same Ana is missing 31 messages on her phone and none on her computer, and the missing ones will never be fetched again. The Android team fixes it; iOS’s 4.3% is still there, waiting for another team to find it on its own.
That is just one rule. By this chapter, the client has about 14 rules that must be followed exactly; with three native apps each writing them, that is 42 implementations, any of which may differ from the others.
2. Write it once: one core library
v3 splits the client in two:
The core, written once and built into every native app:
- connection management: connect, authenticate, heartbeat, reconnect with backoff and randomness after a refusal (chapters 23–25);
- sending: the outbox, message IDs, resends, uploads (chapters 3, 4 and 8);
- sync: conversation records, seqs and gap filling, the read position (chapters 5, 6, 11 and 14);
- the local databaselocal database本地数据库The phone’s own copy of messages, conversations and the sync cursor, usually SQLite. The screen reads only it, and everything from the network is written into it first; a cursor is committed in the same transaction as the messages it stands for.See the glossary and its transactions (chapter 7).
The platform layer, one thin layer per platform, holding only what depends on the operating system:
- push: hand the OS push token to the core; when the user taps a notification, tell the core “sync now” (chapter 17);
- foreground, background and network-change events, handed to the core to disconnect, reconnect and sync (chapter 26);
- where files are kept, storing tokens in the system keychain, and the UI thread.
That way the 14 rules have only 14 implementations, plus 3 platform layers; the web is a separate matter (section 4). The transaction rule from section 1 is fixed once, and all three apps carry the fix in their next release.
The public examples differ in which language the core is written in:
- Telegram’s TDLib is in C++ and calls itself “a cross-platform, fully functional Telegram client”; networking, encryption and local storage are all inside it. It offers a JSON interface that any language able to call C functions can use.
- The open-source OpenIM SDK core is in Go; the connection and heartbeat, local storage and message sync are all in the core, which is built into separate libraries for iOS, Android, Windows, macOS, Linux and the web (WebAssembly).
3. The interface at the boundary
Between the core and the app there is a boundary: two languages, two sets of threads. How the interface is drawn decides how expensive it is to cross and how easy it is to misuse.
- Calls are asynchronous. The app says “send this” or “open this conversation” and the call returns at once; the result comes back later through a callback. The core has its own threads and does not block the UI.
- Events go through listeners. “A message arrived”, “a conversation changed”, “the connection state changed”: the core tells the app.
- Notify per page, not per message. On the busy evening, one notification per message means crossing the boundary 227 times; in chapter 7’s unit of commit, one per page, it is only 6. The UI too only needs to refresh once after each page commits.
- Callbacks come back on the UI thread. That is the platform layer’s job: the core notifies on its own thread, the platform layer moves it to the UI thread, and the app does not have to think about it.
Data crosses the boundary as serialised structures (JSON or Protobuf, side trip W2), or through bindings generated for each language.
4. What about the web?
The web is not like a native app: there is no SQLite, only the browser’s IndexedDB, and JavaScript’s threading model is different too (chapter 27). Two paths:
- Build the same core to WebAssembly, with IndexedDB underneath. OpenIM does this; its repository has a
wasm/indexdbdirectory. - Write a separate TypeScript client for the web, sharing the message definitions (side trip W2) and the same test traces with the core.
Either way, the same test traces apply: the messages, packet losses and kill moments produced from the same random seed must give the same results in every implementation. Take section 1’s evening: 227 messages, 6 pages, killed at 1.2 seconds, started again; every implementation must end with nothing missing, and section 1’s Android and iOS versions fail on that trace. This site does the same: the TypeScript simulators in the pages and the Python simulators in demo.py are compared line by line by a script.
5. The numbers
- Implementations: 14 rules, written once in each of three native apps, are 42 implementations; one core is 14, plus 3 platform layers. A separate web client adds another 14.
- Boundary crossings: on the busy evening, 227 with a notification per message, 6 with one per page.
- The fallback when a migration fails: if a local database upgrade breaks, delete it and rebuild: conversation records are fetched again from the server, 7.8 KB for Ben’s 200 conversations and 78 KB for Ana’s 2,000 (39 bytes a row, chapters 11 and 14), and chat history is fetched again as each conversation is opened. Only the messages still unsent in the outbox are not on the server, so they have to be moved out before deleting.
6. The cost
- One build per platform. The same code has to be built into an iOS framework, an Android library package (AAR), desktop libraries, and sometimes WebAssembly too; the build toolchain itself needs someone to maintain it.
- Every call crosses a boundary. Serialising takes time; when something goes wrong, half the call stack is in the app’s language and half in the core’s.
- The app gets bigger. The core and its runtime ship inside every app.
- Every upgrade means a migration. The local database’s schema is changed only once, in the core, but every release runs that migration on each of millions of phones. Migrations should only add, never change, and on failure rebuild (section 5), saving the outbox first.
- Platform teams lose some freedom. A new feature has to wait for the core to be done first.
7. Other answers
- Each platform writes its own, kept in line by the same test traces. Each platform uses the language and database it likes best; the cost is 3 to 4 implementations of every rule, with tests to catch the differences.
- Share only the hardest part. Signal’s libsignal implements the encryption protocol in Rust for use from Java, Swift and TypeScript; its Android, iOS and desktop apps are three separate repositories.
- Share the whole client. TDLib puts the whole client in the core, and the app is left with little more than the UI. Telegram itself does both: among the clients it lists, Telegram X for Android is built on TDLib, while the official Android, iOS and desktop apps are three separate repositories.
- The web follows the core, or goes its own way (section 4).
8. This chapter’s decision
Fix the core once and all three apps carry the fix. But users do not all upgrade on the same day: an app from two years ago is still out there. What happens when it receives a new kind of message it does not recognise? Next: old apps, new servers.
Comments
Comments live in GitHub Discussions and need a GitHub account.