# Offline Tools
When using an unstable network connection, an application must maintain a normal behavior when it is disconnected. Our goal is to provide the right toolkit to handle such situations.
# Handling a Network Disconnect
There are two ways to handle a network disconnect:
- Automatically reconnect to Kuzzle when possible, and enter offline mode in the meantime. This is the default behavior.
- Stop all further communication with Kuzzle and invalidate the current instance and all its children. The application will have to manually reconnect once the network is available. To do so, simply set the
falsewhen creating the SDK instance.
Offline mode refers to the time between a
disconnected and a
reconnected event (see Events).
A subscription opens a permanent pipe between the client and Kuzzle. Whenever a real-time message or a modified document matches a subscription filter, a notification is sent by Kuzzle to the client (for instance, see the Collection.subscribe method).
While in offline mode, the Kuzzle SDK client maintains all subscriptions configurations and, by default, when Kuzzle SDK client reconnects, all subscriptions are renewed. This behavior can be changed by setting the
false, in which case, each subscription will have to be renewed manually using the
# API Requests
While in offline mode, API requests can be queued, and then executed once the network connection has been reestablished. By default, there is no request queuing.
- Queue all requests automatically when going offline by setting the
true(see Kuzzle SDK constructor)
- Start and stop queuing manually, by using the startQueuing and stopQueuing methods
The queue itself can be configured using the
# Filtering Requests to be Queued
By default, when queuing is first activated, all requests are queued.
However, you can choose to omit certain request by using the
queueFilter property. This property can be set to a function that accepts the request as an input value and returns a boolean result which indicates whether or not the request should be queud.
Additionally, almost all request methods accept a
queuable option, which when set to
false, will cause the request to be discarded if the Kuzzle SDK is disconnected. This option overrides the
# Handling Network Reconnect
truewhen using user authentication should generally be avoided.
When leaving offline-mode, the JWT validity is verified. If it has expired, the token will be removed and a
tokenExpiredevent will be triggered.
autoReplayis set, then all pending requests will be automatically played as an anonymous user.
reconnected event is fired, you may replay the content of the queue with the
playQueue method. Or you can let the Kuzzle SDK replay it automatically upon reconnection by setting the
autoReplay option to
Requests are sent to Kuzzle with a
replayInterval delay between each call.
Any request made while the client is processing the queue will be delayed until the queue is empty. This ensures that all requests are played in the right order.
# Taking Control of the Offline Queue
offlineQueuePush event is fired whenever a request is queued. It will emit an object containing a
query property, describing the queued request, and an optional
cb property containing the corresponding callback, if any.
offlineQueuePop event is fired whenever a request has been removed from the queue, either because the queue limits have been reached, or because the request has been replayed. It provides the removed request to its listeners.
offlineQueueLoader property of the Kuzzle SDK instance loads requests to the queue, before any previously queued request. It is invoked every time the Kuzzle SDK starts dequeuing requests.
This property must be set with a function that returns an array of objects with the following accessible properties:
queryproperty, containing the request to be replayed
- an optional
cbproperty pointing to the callback to invoke after the completion of the request
Finally, if the provided methods don't give you enough control over the offline queue, you can access and edit the queue directly using the
# Automatic Offline-Mode
You can set the
offlineMode option to
auto when instantiating the Kuzzle SDK instance. This sets the offline mode configuration to the following presets: