Glossary#

These are the sync terms calendaring-sync’s pages use. Design explains why each part works the way it does, and Adapters explains what each term means for a given protocol.

adapter#: The part that connects calendaring-sync to one kind of server. It asks the server what changed, hands the answer to the core as a change set, and sends your pushes. Some ship with calendaring-sync, and you can write your own.
change feed#: The numbered list of what syncs, resolved conflicts and dropped scopes changed in the store, which your application reads from its cursor.
change set#: What an adapter hands the core after asking the server what changed in one scope: the objects that changed or were removed, the sync token it was fetched from, and the token it leads to.
checkpoint#: The sync token a truncated page ends at. The next request continues from it.
claim#: To mark a pending edit in flight before it’s pushed, in one step that fails if another process got there first. Why an object has five states shows a record’s states and what moves it between them.
conflict#: An object where your pending edit and the server disagree: both sides changed it, one side deleted it while the other edited it, the server refused your create or change because another object holds its logical key, or the server won’t take your edit as you sent it. calendaring-sync reports it and leaves the decision to you.
conflict record#: What the core stores for one conflict: the synced copy, your local edit, the server’s copy, and the kind of conflict. It stays open until you resolve it or it resolves itself.
container#: A calendar, or another grouping, that an object belongs to. One object can belong to more than one.
content#: An object’s data, exactly as the server sent it or as you recorded it in an edit.
core#: calendaring-sync itself: the part that keeps sync state and knows nothing about any server or protocol.
cursor#: The number of the last change feed entry a part of your application has handled.
drop#: To delete a scope and everything the store holds for it.
fingerprint#: A value computed from an object’s content, leaving out what a server rewrites on its own. Two copies with the same fingerprint differ at most in what a server rewrites.
fingerprint scheme#: The name of the function that computed a scope’s fingerprints. Fingerprints from different schemes can’t be compared.
full listing#: A change set that lists every object in a scope, not only the ones that changed.
in flight#: The state of a push that was claimed, until the adapter reports how it ended or the next complete ingest settles it.
incremental change set#: A change set that holds only what changed since the scope’s sync token.
ingest#: To apply a change set to the store in one transaction. An ingest is complete when it applies a complete change set, or the last page of a truncated one.
local key#: An identifier the core gives each record, which never changes.
logical key#: An identifier taken from an object’s content, such as its UID. Unlike an object id, several objects can share one.
object#: One item a scope holds, such as one event or one task.
object id#: The identifier the server uses for an object, unique within its scope. It’s the object’s identity.
pending edit#
local edit#
edit#: A change, delete or create you’ve recorded for an object that hasn’t reached the server yet. The next sync pushes it.
purge#: To delete removed records from the store for good, up to a point your application chooses.
push#: To send one pending edit to the server. PushOutcome lists how a push can end.
record#: Everything the core stores about one object, including its current state.
reset#: To forget a scope’s sync token, so that the next sync of that scope is a full listing.
resolver#: A function you write and pass to resolve_conflicts(). It receives each open conflict record and says how to resolve it.
scope#: The set of objects one sync token covers, such as one calendar.
server’s copy#: The server’s newer copy of an object you edited, which conflicts with your local edit. A record in conflict holds it in Record.conflict, in the fields whose names start with remote_.
session#: One sync of one scope: it ingests every page first, then pushes your pending edits.
storage#: What a store keeps its data in, such as a SQLite file, behind the Storage interface. Write one to keep sync state somewhere new.
store#: Where the core keeps each scope’s sync token, its records, your pending edits, open conflicts, and the change feed.
sync token#
token#: A marker the server gives out that stands for one point in a scope’s history. The adapter sends it back to ask what changed since then. The core only stores and compares it.
synced copy#: An object as both sides last agreed on it, at the end of the last sync. A record holds it in its fields from version to logical_key.
truncated page#
page#: One part of a change set that arrives in several parts. The last page completes the change set.
UID#: The identifier an event or task carries inside its own data. Copies of it in other calendars carry the same UID.
version#: A marker the server gives each object, which changes when the object does. The core only checks whether two versions are equal.