<title>The Fossil Sync Protocol</title>

This document describes the wire protocol used to synchronize
content between two Fossil repositories.

<h2>1.0 Overview</h2>

The global state of a fossil repository consists of an unordered
[./fileformat.wiki|collection of artifacts].  Each artifact is 
identified by a cryptographic
hash of its content, expressed as a lower-case hexadecimal string.
Synchronization is the process of sharing artifacts between
repositories so that all repositories have copies of all artifacts.  Because
artifacts are unordered, the order in which artifacts are received
is unimportant.  It is assumed that the hash names
of artifacts are unique - that every artifact has a different hash.
To a first approximation, synchronization proceeds by sharing lists
of hashes for available artifacts, then sharing the content of artifacts
whose names are missing from one side or the other of the connection.
In practice, a repository might contain millions of artifacts.  The list of
hash names for this many artifacts can be large.  So optimizations are
employed that usually reduce the number of hashes that need to be
shared to a few dozen.

Each repository also has local state.  The local state determines
the web-page formatting preferences, authorized users, ticket formats,
and similar information that varies from one repository to another.
The local state is not usually transferred during a sync.  Except,
some local state is transferred during a [/help?cmd=clone|clone]
in order to initialize the local state of the new repository.  Also,

All communication between client and server is via HTTP requests.
The server is listening for incoming HTTP requests.  The client
issues one or more HTTP requests and receives replies for each
request.

The server might be running as an independent server
using the [/help?cmd=server|"fossil server" command], or it
might be launched from inetd or xinetd using the
["fossil http" command|/help?cmd=http].  Or the server might
be [./server/any/cgi.md|launched from CGI] or from
[./server/any/scgi.md|SCGI].
(See "[./server/|How To Configure A Fossil Server]" for details.)
The specifics of how the server listens
for incoming HTTP requests is immaterial to this protocol.
The important point is that the server is listening for requests and
the client is the issuer of the requests.

A single [/help?cmd=push|push], 
[/help?cmd=pull|pull], or [/help?cmd=sync|sync]
might involve multiple HTTP requests.
The client maintains state between all requests.  But on the server
side, each request is independent.  The server does not preserve
any information about the client from one request to the next.

Note: Throughout this article, we use the terms "server" and "client"
to represent the listener and initiator of the interaction, respectively.
Nothing in this protocol requires that the server actually be a back-room
processor housed in a datacenter, nor does the client need to be a desktop
or handheld device.  For the purposes of this article "client" simply means
the repository that initiates the conversation and "server" is the repository
that responds.  Nothing more.

<h4>2.0.1 HTTPS Transport</h4>

HTTPS differs from HTTP only in that the HTTPS protocol is
encrypted as it travels over the wire.  The underlying protocol
is the same.  This document describes only the underlying, unencrypted
messages that go client to server and back to client.
Whether or not those messages are encrypted does not come into play
in this document.

Fossil includes built-in 

[./ssl-server.md|support for HTTPS encryption] in both client and server.

<h4>2.0.2 SSH Transport</h4>

When doing a sync using an "ssh:..." URL, the same HTTP transport protocol
is used.  Fossil simply uses [https://en.wikipedia.org/wiki/Secure_Shell|ssh]
to start an instance of the [/help?cmd=test-http|fossil test-http] command
running on the remote machine.  It then sends HTTP requests and gets back HTTP

that the nonce matches the SHA1 hash of the remainder of the
message.  It then checks the signature hash to make sure the
signature matches.  If everything
checks out, then the client is granted all privileges of the
specified user.

Privileges are cumulative.  There can be multiple successful
login cards.  The session privilege is the union of all
privileges from all login cards.

<h3>3.3 File Cards</h3>

Artifacts are transferred using either "file" cards, or "cfile"
or "uvfile" cards.
The name "file" card comes from the fact that most artifacts correspond to
files that are under version control.
The "cfile" name is an abbreviation for "compressed file".
The "uvfile" name is an abbreviation for "unversioned file".


<h4>3.3.1 Ordinary File Cards</h4>

For sync protocols, artifacts are transferred using "file"
cards.  File cards come in two different formats depending
on whether the artifact is sent directly or as a 
[../delta_format.wiki|delta] from some
other artifact.

<blockquote>
<b>file</b> <i>artifact-id size</i> <b>\n</b> <i>content</i><br>
<b>file</b> <i>artifact-id delta-artifact-id size</i> <b>\n</b> <i>content</i>
</blockquote>

The first argument of a file card is the ID of the artifact that
is being transferred.  The artifact ID is the lower-case hexadecimal
representation of the name hash for the artifact.
The last argument of the file card is the number of bytes of
payload that immediately follow the file card.  If the file
card has only two arguments, that means the payload is the
complete content of the artifact.  If the file card has three
arguments, then the payload is a 
[../delta_format.wiki|delta] and second argument is
the ID of another artifact that is the source of the delta.

File cards are sent in both directions: client to server and
server to client.  A delta might be sent before the source of
the delta, so both client and server should remember deltas
and be able to apply them when their source arrives.

The receiver should only accept the uvfile card if the hash and
size match the content and if the mtime is newer than any existing
instance of the same file held by the receiver.  The sender will not
normally transmit a uvfile card unless all these constraints are true,
but the receiver should double-check.

A server will only accept uvfile cards if the login user has
the "y" write-unversioned permission.

Servers send uvfile cards in response to uvgimme cards received from
the client.  Clients send uvfile cards when they determine that the server
needs the content based on uvigot cards previously received from the server.

<h3>3.4 Push and Pull Cards</h3>