# Sync RFC Brief
## Mission
Draft the protocol document:
**The Fossil Distributed Version Control System: Sync Protocol**
This document specifies the current Fossil wire version for synchronising content-addressed artifacts between repositories over HTTP and equivalent transports.
## Front matter
- Use the title above.
- Intended status is Proposed Standard.
- The abstract should state that the protocol synchronises content-addressed artifacts between two repositories over HTTP and specifies transport, card vocabulary, authentication, and synchronisation strategy for the current wire version.
## Required sections
### 1. Introduction
Cover synchronisation as convergence of two artifact sets, including the phantom and cluster model.
### 2. Terminology
Add these sync-specific terms on top of Artifact terminology:
- servercode
- projectcode
- phantom
- cluster
- unclustered table
- gimme
- igot
### 3. Protocol operation
This section is mandatory and must be implementable as a client algorithm, not a descriptive overview.
It must specify:
#### Round structure
- what the client sends in the first request,
- what it sends in later requests,
- how a round-`N` reply determines the round-`N+1` request,
- which `igot`, `gimme`, and content each side emits as a function of current state.
#### Phantom resolution
Specify the loop explicitly:
- an `igot` for absent content records a phantom,
- the phantom is requested with `gimme` in a later round,
- the loop exits only when a round adds no new phantom.
#### Clone loop
Specify the current clone loop explicitly:
- client sends `clone <protocol> <seqno>`,
- server replies with `clone_seqno`,
- client repeats until `clone_seqno 0`,
- the text must state what receipt of `0` obligates next.
#### Carried state
Enumerate carried values such as:
- phantom set,
- names already sent,
- sync cookie,
- clone sequence numbers,
- any per-round, per-session, or persistent state required to drive the exchange.
#### Request/response pragmas
Specify ordering and failure behavior for:
- `ci-lock`
- `ci-lock-fail`
- `ci-unlock`
- catalog / cluster-related pragmas
#### Termination
State the exact convergence condition under which the client concludes the sync is complete and the server stops.
#### Worked exchange
Require one observed, message-by-message appendix trace of a small sync, including:
- every HTTP request and response body,
- phantom-resolution round,
- terminating round.
### 4. Transport
Specify:
- HTTP POST carrying the sync message body,
- HTTP/1.1 as the mandatory minimum,
- `application/x-fossil` for compressed transport,
- `application/x-fossil-debug` for uncompressed transport,
- HTTPS, SSH, and FILE transports as alternate carriers of the same payload.
State the request-target rule exactly as implemented:
- the client POSTs to the repository URL path unchanged,
- it does **not** append `/xfer`,
- the server routes requests by sync content type regardless of path,
- `/xfer` is only an additionally accepted endpoint, not the client's required target.
### 5. Card format
Cover the sync card vocabulary:
- `login`
- `push`
- `pull`
- `clone`
- `file`
- `cfile`
- `uvfile`
- `private`
- `igot`
- `uvigot`
- `gimme`
- `uvgimme`
- `cookie`
- `reqconfig`
- `config`
- `pragma`
- `error`
- `message`
- `clone_seqno`
- `comment`
For repository-configuration transfer, specify only the wire envelope:
- `reqconfig` names a `/`-prefixed configuration group,
- `config` carries `config NAME SIZE` followed by `SIZE` bytes,
- the content serialization inside that blob is outside this specification's scope.
### 6. Authentication
Specify:
- `login` card fields,
- nonce as SHA-1 of the message remainder,
- signature as SHA-1 of nonce plus password,
- one login card per message,
- login cookie carried in the `x-f-l-c` header.
### 7. Content transfer
Cover:
- `file`, `cfile`, and `uvfile`,
- direct content and delta content,
- byte-counted payload framing,
- private-content marking.
Make byte framing explicit per card family:
- for `file` and `cfile`, the next operator begins immediately after the last payload byte,
- for `config`, the content is followed by a `0x0a` newline that the receiver skips,
- payloads are opaque bytes and may contain `0x0a` or other non-text bytes.
State the dangling-delta rule explicitly:
- a delta-form `file` or `cfile` may arrive before its source during clone,
- the receiver retains the delta against its named source,
- reconstruction is deferred until the source arrives,
- receipt order is therefore not significant.
### 8. Clone
Specify the current clone version using `cfile` cards and `clone_seqno` sequencing.
### 9. Synchronisation strategies
Specify pull, push, sync, and unversioned-file sync as ordered card exchanges, including phantom creation and server-side cluster creation.
### 10. Pragmas
Cover at least:
- `send-private`
- `send-catalog`
- `uv-hash`
- `uv-pull-only`
- `uv-push-ok`
- `ci-lock`
- `ci-lock-fail`
- `ci-unlock`
- `req-clusters`
Unknown pragmas are ignored.
### 11. Error handling
Specify:
- `error` card aborts the session,
- `message` card is non-fatal.
### 12. Security Considerations
Carry the original pack's security themes:
- artifact integrity by content hash and preimage assumptions,
- nonce-based password authentication rather than PKI,
- no payload encryption at this layer,
- confidentiality delegated to HTTPS,
- capability-letter authorization,
- shunning as repository-local removal rather than cryptographic redaction,
- SHA-1 collision exposure and SHA3-256 as current default,
- AP-mode behavior under partition.
### 13. IANA Considerations
Register:
- `application/x-fossil`
- `application/x-fossil-debug`
Do not request a port or service-name registration.
## Required appendices
- **A. Examples** — login signature and nonce computation.
- **B. ABNF** — collected protocol card grammar.
- **Observed sync trace appendix** — if kept separate from Appendix A, it is still mandatory.
## Sync-specific boundaries
- This document covers the **current** wire version only.
- Keep the `cfile` / `clone_seqno` path.
- Omit the older uncompressed `send_file` clone path.
- Omit pre-2.27 login handling, but record the actual version/date boundary after checking the implementation.
- Do not specify repository-configuration blob serialization; only specify its wire envelope.
## High-risk Fossil specifics to preserve
- client request target is the repository URL path unchanged, not a synthesized `/xfer` path,
- payload-bearing cards do not all share the same trailing separator rule,
- dangling delta content can arrive before its source during clone,
- sync completion is a convergence property, not the receipt of any single card,
- the document must include a capability-completeness check so no hard case is only narrated.