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

Also define the repository-derived views that Sync defers to RepoState:

• branch
• ordinary tag
• closed marker
• leaf
• current-trunk

The terminology section must state that the sync protocol does not carry a separate branch, tag, leaf, closed-marker, or current-trunk state channel. It transfers and stores the artifacts from which each peer derives those views locally, with the derivation rules owned by RepoState.

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

Derived repository views

Require an explicit subsection stating that:

• igot, gimme, file, and cfile are not independent branch/tag operations,
• branch, ordinary tag, leaf, closed-marker, and current-trunk views are derived only after the relevant structural artifacts have been stored and repository crosslink/tag-state processing has run,
• Artifact owns the T-card syntax and tag-operation vocabulary,
• RepoState owns the derivation of branch, tag, leaf, closed-marker, and current-trunk views from those stored artifacts,
• current-trunk is not a pure wire-synchronized value because each peer derives it locally using its own main-branch setting,
• unresolved phantoms or missing delta bases can postpone final derived-view answers without constituting a separate sync error.

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.