Offline-first and sync

Offline vs partitioned: what is the difference?

A device is offline when it has no working network connection at all. A network is partitioned when it splits into groups that can each still communicate internally but cannot reach each other. A phone with no internet can still be in a working local network with the phones around it, so it is cut off from the cloud without being offline.

TL;DR

Design for partitions, since an offline device is a partition of one, and let devices in the same group keep sharing changes while the server is out of reach. Neither navigator.onLine nor Android's network flags prove that a particular server or peer is reachable, so track reachability per destination. Test internet loss separately from peer-link loss.

Learning objectives

After reading this article you will be able to:

  • Distinguish a device that is offline from a network that is partitioned
  • Explain why navigator.onLine and Android network flags do not prove reachability
  • Describe how to test internet loss and peer-link loss separately

Offline vs partitioned networks

“No connection” covers two situations that look alike in a status bar but behave very differently: an offline device can reach nobody, while a partitioned one can still reach the devices in its group.

A device is offline when it has no working network path at all. It cannot reach a server, and it cannot reach the device next to it either. Everything it does in that state is local to it.

A network is partitioned when it splits into groups. Inside each group, devices can still reach each other; across groups, nothing gets through. A technician’s phone in a basement might have no internet but still talk to the phones of colleagues nearby over Bluetooth. That phone is not offline. It is in a partition that does not include the cloud.

OpenThread’s primer describes the same thing in a Thread mesh: a network can be composed of partitions when a group of devices can no longer communicate with another group, each partition carries on as its own network, and partitions merge when they regain connectivity. What is a network partition? covers the general idea.

Partition-aware app behaviour

An app that understands partitions can let a team cut off from the cloud, such as technicians in a basement, keep working together, while an app designed only for “online” and “offline” will treat them as a set of isolated devices.

OfflinePartitioned
Who you can reachNobodyThe devices in your group
What can continueLocal reads and writesLocal work plus sharing within the group
Changes to sync laterOne device’sA whole group’s, possibly from several people
Conflicts on reconnectBetween this device and the restBetween groups that each kept editing
Authority, such as a serverUnreachableReachable only if it is in your group

The last two rows are where the design work is. When a single device comes back online, its queued changes meet everything that happened elsewhere. When two groups reconnect, both sides may have made many changes to shared data, so the sync conflict rules need to cope with merges at that scale.

Partitions also bring the trade-off described by the CAP theorem. Gilbert and Lynch put it as a choice between consistency and availability while servers are split into groups that cannot communicate. Each group either keeps accepting changes and reconciles later, or holds back operations it cannot confirm. Offline devices face the same choice, but a partition makes it sharper, because each side looks like a working network to the people inside it.

A device can also be online and partitioned at once. A phone with mobile data but Bluetooth switched off can reach the server but not the colleague beside it.

Offline and partition detection

An app tells offline from partitioned by checking reachability per destination, because operating systems report the state of the device’s own network interfaces, not whether a particular peer or server is reachable.

  • In a browser, navigator.onLine returns false if the browser is definitely offline, disconnected from the network, and true if it might be online, according to the HTML Standard. True does not mean a server will answer.
  • On Android, a network can have the NET_CAPABILITY_INTERNET capability, meaning it is set up to reach the internet, without NET_CAPABILITY_VALIDATED, which means the system actually probed it and found internet access. Android’s docs note that a local peer-to-peer Wi-Fi network typically lacks the internet capability, and that even a validated network can lose connectivity suddenly.

So treat reachability per destination. The server is reachable if a request to it succeeds now. A peer is reachable if a message to it is acknowledged. Track each separately, and show people what they can and cannot reach, rather than a single online or offline flag.

Designing and testing for partitions

Design for the partition, and the offline case mostly follows, because an offline device is a partition of one.

  • Store changes locally first and send them through an outbox that retries per destination.
  • Let devices in the same group share changes directly, without waiting for the server.
  • Decide per operation what happens when the authority is in another group: proceed and reconcile, or wait.
  • Where no path exists for a long time, carry data store-and-forward. RFC 4838 describes an architecture for networks that suffer frequent partitions and may have no end-to-end path.

Test the two cases separately, because each exercises different code. Switching off every radio removes every path at once and only tests the offline case. Removing internet while leaving local links up tests a partition from the cloud; removing local links while leaving internet up tests the reverse. Offline Protocol’s platform docs give the same advice for apps built on its mesh SDK: test internet loss separately from peer-link loss.

Frequently asked questions

Can a device be online and partitioned at the same time?

Yes. A phone with mobile data can reach the cloud while Bluetooth is off or its nearby peers have moved out of range. It is online, but cut off from the local group it was working with.

Does navigator.onLine tell a web app whether it can reach its server?

No. The HTML Standard says it returns false only when the browser is definitely offline, and true when it might be online. The only reliable test is to contact the server and get an answer.

What does NET_CAPABILITY_VALIDATED mean on Android?

It means the system actually probed the network and found internet access. A network can have NET_CAPABILITY_INTERNET, meaning it is set up to reach the internet, without being validated, and even a validated network can lose connectivity suddenly.

Does switching off every radio test a partitioned network?

No. It removes every path at once and only tests the offline case. To test a partition, remove internet while leaving local links up, and separately remove local links while leaving internet up.

How does the CAP theorem relate to network partitions?

Gilbert and Lynch put it as a choice between consistency and availability while servers are split into groups that cannot communicate. Each group either keeps accepting changes and reconciles later, or holds back operations it cannot confirm.

What happens to a Thread mesh network when it splits?

OpenThread's primer says each partition carries on as its own network when a group of devices can no longer communicate with another group, and partitions merge when they regain connectivity.

Sources

Build it with Offline Protocol

The Offline Protocol platforms page lists the transports available on each surface and the checks to run on real hardware before deploying, including testing internet loss separately from peer-link loss.

Read the platforms and transports page