Platform Manual

Glossary

This topic provides 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

An Apple-developed proprietary technology that establishes a point-to-point Wi-Fi connection between two Apple devices. If available in their environment, Small Peers utilize AWDL to create a mesh network connection and replicate data. For additional details, refer to Peer-to-Peer Wi-Fi.

A proprietary technology Apple developed to establish point-to-point Wi-Fi connection between two Apple devices. When available to SmallPeer devices, Ditto leverages AWDL to establish a mesh network connection and sync data. For more information, see Peer-to-Peer Wi-Fi

application

A logical container, or 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, the Big Peer has the capacity to support multiple Applications simultaneously. Application IDs consist of strings, with lower-case UUIDs being the prevalent choice.

application. A Small Peer can use only one Application at a time, which is specified as part of the Identity. The Big Peer can service multiple Applications at a time. Application IDs are strings, almost always a lower-case UUID.

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

AWMap

Add Wins Map. One of our CRDT.

B

backend

The underlying key-value store which Ditto uses for database-like persistence.

Big Peer

Broadly refers to the Ditto Cloud in its role "as" a peer. A Big Peer is unique in the sense that has highly durable and scalable storage and typically greedily replicates all data from smaller peers. A Big Peer typically deals with a company’s (or app's) entire dataset which may be substantially larger than the partial dataset any given Small Peer might be operating on.

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

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.

DTO

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

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

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 Big Peer 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

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.

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.

Z

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.

Updated 11 Mar 2024
Did this page help you?