share / sharedb / 1450 / 3

97%

master: 97%

Build Type

push

travis-ci

Committed by Alec Gibson

Commit Message

Held ops

# Introduction

This change adds support for a "held op". Held ops are ops which are:

 - Only applied locally
 - Not necessarily submitted to the server
 - May be submtted to the server at some later time
 - Will be lost at the end of a "session" if not flushed (since they
   haven't been submitted to the server)

# Motivation

Held ops allow for some level of disconnect with the server, whilst
keeping the `Doc` "live". The primary use case this was designed for is
for when a `Doc` is in a "confirming" state: that is, some change has
been made to the `Doc`, but we're waiting for some confirmation that
this change should be comitted to the server (eg user input).

This sort of thing can be achieved with `pause()` and `resume()`, but:

 - Pausing a document will stop all ops from being submitted, even if
   those other ops don't need confirmation
 - Resuming a `Doc` is not fool-proof. It would be a much nicer failure
   mode to only fail to commit the changes that require confirmation,
   rather than all subsequent changes

We could try to address these issues by having a side-channel: a second
`Connection` which we funnel all ops that need confirmation, which we
can safely pause, but this has its own issues:

 - Can't flush individual ops (unless we keep opening more
   side-channels)
 - We now have two clients to handle, which can cause confusion around
   how to merge data, and what constitutes a "local" op (ie everything
   submitted down the pauseable connection, will look remote to the
   mainline channel, even though it came from our own machine)

Held ops attempts to solve this issue by providing a mechanism for
submitting everything through a single client, and holding ops that can
be individually flushed to the server.

Note that one other possible (ab)use for held ops is to simply have
local-only data, which benefits from type transformations, although it
should be possible to achieve something like that with Presence.

# API

We a... (continued)

Run Details

1439 of 1664 branches covered (86.48%)

3131 of 3216 relevant lines covered (97.36%)

187.68 hits per line