Glossary
Here you’ll find Ditto-specific terms and their definitions, as well as links to related information.
A
actor
Used by conflict-free replicated data types (CRDTs) to identify the source or author of a data mutation, an actor is made up of a SiteID and the site’s current epoch.
Apple Wireless Direct Link
A proprietary Apple-developoed technology that establishes a point-to-point Wi-Fi connection between two Apple devices. When available in their environment, Small Peers utilize Apple Wireless Direct Link (AWDL) to create a mesh network connection and replicate data.
application
A logical container, referred to as a namespace, that holds all the data associated with your app.
Small Peers are limited to utilizing one Application concurrently, a specification included in the Identity. On the other hand, Ditto Servercan support multiple Applications simultaneously. Application IDs consist of strings, with lower-case UUIDs being the prevalent choice.
attachment
The Ditto component which deals with storing large binary files for users (associated with a document as an attachment). Attachments are referenced by documents but must be explicitly downloaded. Attachments use a different transfer mechanism from regular replication.
authentication WebHook
An HTTP service hosted by the developer which receives credentials and responds with metadata about the user and which permissions they should have. The Identity Service uses this information to dynamically produce the required certificates. Configured through the Portal.
AWDL
See Apple Wireless Direct Link.
AWMap
Add Wins Map. One of our CRDT.
B
backend
The underlying key-value store which Ditto uses for database-like persistence.
Big Peer
Previous name for Ditto Server.
blob store
An internal component which offers general blob storage. Used by any internal Ditto components which need to persist “files”. “Files” is in quotes as the blob store does not necessarily require a true filesystem and might be operating purely in memory.
bus
A public service offered by the Ditto SDK for establishing raw byte streams between peers using the Ditto mesh. This technology enables many use cases beyond Ditto’s document replication . Examples include voice chat, game data, syncing other non-Ditto DBs over our mesh network, VPN over Ditto, etc. Under the hood it is a thin wrapper around Channels.
BYOC
Bring Your Own Cloud. A model for deploying the Ditto Platform managed by Ditto in your own cloud account where you (the customer) share responsibility and control over the account and therefore the cost and security and compliance needs with Ditto.
C
CA
CDC
See change data capture.
Change Data Capture
channel
A bidirectional message-oriented data flow running over the top of a Virtual Conn. These can offer reliable or lossy delivery characteristics and be opened either mutually or as a client/server type relationship. Channels are protocol-agnostic, like TCP/UDP, and are consumed by Services.
chooser
Also known as the “Mesh Chooser”, a stateful algorithm which decides at any moment which outgoing connections we should make. This considers the peers we’re currently connected to, the peers whose advertisements have been detected by transports, and past failures.
certificate authority
The cryptographic root of trust for all identities and certificates within a Ditto Application. Originally this was a standard X.509 CA for peer TLS certificates but its role has expanded to include JWT and In-Band Certificate signatures. It is by knowing the public keys of the CA that one offline peer can verify the authenticity of another offline peer.
Collection
A grouping of documents (the fundamental Ditto type) under a name. Loosely equivalent to a table in SQL terms. An app may have many collections.
conflict-free replicated data type
An advanced class of data type designed to manage and replicate data changes in a way that allow multiple distributed peers to make updates concurrently without the need to reach consensus to form a single meaningful value for merge. For more information, see Ditto’s blog post: An Inside Look at Ditto’s Delta State CRDTs.
CRDT
See conflict-free replicated data type.
D
database
The Small Peer’s implementation of the Ditto store.
data transfer object
Represents a structured data object that contains information to be transmitted from one peer to another.
document
A schema-flexible unit of data contained in a collection; analogous to a row in a table.
Ditto address
An SDK-layer type which targets some peer in the mesh for a Bus connection or similar. It opaquely wraps whatever identifying information is needed.
Ditto routing protocol
A custom OSPF-esque shortest-path-first interior routing protocol used to route multi-hop packets within a ditto mesh. Uses Presence as a data source.
Ditto Server
A cluster of servers that can run on-premises or in the cloud, that augments the SDK’s local-first capabilities with cloud-based synchronization, identity management, monitoring and data integration features.
DTO
See data transfer object.
E
epoch
A concept which identifies a “version” of a peer’s CRDT knowledge. Used by replication and CRDT to identify whenever a peer has changed in some fundamental way that obsoletes our prior knowledge of them. Today, an Epoch changes each time a peer performs data Eviction .
eviction
The process a peer takes to “forget” data. This is different to removing data in the sense that data is not actually deleted, it is merely forgotten by the peer and jettisoned by that app. Important for use cases like cabin crew apps where data from the last flight is not needed on the next flight.
G
GATT
See Generic ATTribute Profile.
Generic ATTribute Profile
An older, slower mode of Bluetooth LE data transfer which has typical speed of 3 to 6 kB/s. Works back to very old Android and iOS phones. Where possible the bluetooth transport upgrades a connection to L2CAP.
H
hybrid logical clock
Used to track when mutations occurred to a CRDT, or component thereof. A Ditto HLC combines a physical clock portion (the local time stamp on a peer as unix milliseconds) together with a logical portion (a number unique to each peer and increases by one with each change they make).
HLC
See hybrid logical clock.
I
identify
A complex parameter passed to Ditto at startup which defines how you will authenticate yourself and verify who other peers are, and whether they’re using the same Application as you. Modes include OfflinePlayground, OnlinePlayground, OnlineWithAuthentication, and SharedKey. Some of these rely on the application having a common CA.
identity data
The data which the CA asserts about an participant in the mesh. It includes their Peer Key, site ID, permissions, and other arbitrary data returned by the authentication webhook such as email address, job title, and so on.
identity service
The part of the Ditto Server which handles login requests, invoking Authentication Webhooks if required, and generating the cryptographic material for peers to authenticate each other by acting as the CA. In code, this basically means AuthServer.
in-band certificate
A bespoke binary format that a Certificate Authority (CA) can sign to assert that a given Identity Data is valid and matches a particular key. Plays the role of a TLS X.509 certificate in non-TLS situations.
K
keyspace
As per the Random Slicing algorithm, we think of the keyspace as the range 0 to 1. We take the capacity of the cluster, and divide 1 by it. This determines how much of the keyspace each partition owns.
L
L2CAP
See logical link control adaptation protocol.
link
An encrypted connection between two peers who are not directly connected, with traffic routed via intermediate peers. Used for multihop sync via Query Overlap Groups, and Ditto Bus.
live query
The object that the observe callback function returns when changes to the local database match a given query and then monitors changes to that query over time.
logical link control and adaptation protocol
A faster mode of Bluetooth LE transport. This is at a lower level/complexity than GATT. Platforms that support it have much faster speeds (~20 kB/s).
M
metadata
-
In a CRDT context, metadata refers to the field by the same name in a CRDT Document. CRDT metadata tracks the actor which the current site uses when performing mutations, and tracks all the summaries for the CRDT.
-
In a replication context, metadata is all the information which replication uses to keep track of the state of other peers in a Ditto mesh. A large part of this consists of CRDT metadata as above.
-
In a storage context, metadata might refer to the internal abstraction which provides key-value storage optimized for metadata using any supported Ditto backend. These metadata stores can be created standalone, but every also comes with a special associated metadata store for tracking backend-specific info (transction numbers, version info, etc.).
multiplexer
A synchronous machine inside a Virtual Connection to a single remote peer, performing packet fragmentation and reassembly for all of the Physical Connections arriving from various transports.
O
online playground
A type of Identity where peers do not need unique credentials to log in and everybody has read and write access to everything.
P
peer-to-peer Wi-Fi
Any mechanism for establishing direct WiFi connections between devices without needing a router in between. AWDL is one such technology for Apple devices, and WiFi Aware is another for Android devices.
peer key
A P-256 private key generated and persisted on every device that runs Ditto. This is the primary unique identifier for each peer and its ECDSA signatures are used to prove authenticity. It is unrelated to CRDT actor IDs.
permission
A specification of which documents a given peer can read or write. This is presented as a list of specific collection names, and a sublist of query strings for each collection. Documents must match one of those DittoQL (DQL) queries to be readable or writable. If using an online authenticated Identity these can be locked down; other identity types have no CA and let everybody access anything.
portal
Self-service website (https://portal.ditto.live/) used to create and manage Applications hosted on Ditto’s cloud.
presence viewer
The part of Ditto responsible for building a picture of all peers in the surrounding mesh, including rich peer info such as SDK version, device names, and which transports are active. This information is used as the basis for routing and can be visualized with the presence viewer.
R
replication query
A query that runs on connected peers that results in changes being sent back to the initial peer when changes are made to the remote peers’ local SmallPeer database.
S
service
Handles Channels to provide a particular functionality. The most important example is the Replication service, which performs document sync.
SiteID
A unique identifier for a peer which identifies any CRDT document mutations they author. Also has been used as unique peer identifier generally, but this is being phased out in favor of the Peer Key.
subscription
A query from the replication perspective, whereby one peer requests any data that matches this query from other peers to synchronize.
T
transports
The part of Ditto which involves the physical transport mechanisms such as bluetooth, WebSockets, AWDL , LAN, and so on. Transports are concerned with finding other Ditto peers and establishing secured connections. These lowest level transports are then weaved together at a higher level to form a Ditto mesh.
U
Unique Universally Stable Timestamp
The unique identifier assigned to every write transaction indicates its order in the sequence of events, a causal relationship to other events, conflict resolution mechanisms to handle concurrency conflicts, and enable non-blocking reads.