xfer

package
v0.6.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 13, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package xfer implements Fossil's sync protocol card codec. It encodes and decodes the line-oriented "xfer card" format used by Fossil's /xfer HTTP endpoint, with NO database dependency.

Index

Examples

Constants

View Source
const (
	UVFlagDeletion       = 0x0001                                // File is a deletion tombstone.
	UVFlagContentOmitted = 0x0004                                // Content not included in this card.
	UVFlagNoPayload      = UVFlagDeletion | UVFlagContentOmitted // Mask: no payload expected.
)

UV file flag constants.

Variables

This section is empty.

Functions

func EncodeCard

func EncodeCard(w *bytes.Buffer, c Card) error

EncodeCard writes the wire-format representation of a Card to w.

Types

type CFileCard

type CFileCard struct {
	UUID     string
	DeltaSrc string
	USize    int
	Content  []byte
}

CFileCard represents a "cfile" card (compressed file with uncompressed size).

func (*CFileCard) Type

func (c *CFileCard) Type() CardType

type Card

type Card interface {
	Type() CardType
}

Card is the interface implemented by every xfer card type.

func DecodeCard

func DecodeCard(r *bufio.Reader) (Card, error)

DecodeCard reads one card from r. It skips comment lines (starting with #) and empty lines. Returns io.EOF when the reader is exhausted. Unrecognized command words produce an *UnknownCard (not an error).

type CardType

type CardType int

CardType enumerates the 24 card types in Fossil's sync protocol.

const (
	CardFile       CardType = iota // 0  — file
	CardCFile                      // 1  — cfile (compressed file)
	CardIGot                       // 2  — igot
	CardGimme                      // 3  — gimme
	CardLogin                      // 4  — login
	CardPush                       // 5  — push
	CardPull                       // 6  — pull
	CardCookie                     // 7  — cookie
	CardClone                      // 8  — clone
	CardCloneSeqNo                 // 9  — clone_seqno (undocumented)
	CardConfig                     // 10 — config
	CardReqConfig                  // 11 — reqconfig
	CardPrivate                    // 12 — private
	CardUVFile                     // 13 — uvfile
	CardUVGimme                    // 14 — uvgimme
	CardUVIGot                     // 15 — uvigot
	CardPragma                     // 16 — pragma
	CardError                      // 17 — error
	CardMessage                    // 18 — message
	CardUnknown                    // 19 — unrecognized card
	CardSchema                     // 20 — schema (table sync)
	CardXIGot                      // 21 — xigot (table sync row announcement)
	CardXGimme                     // 22 — xgimme (table sync row request)
	CardXRow                       // 23 — xrow (table sync row payload)
	CardXDelete                    // 24 — xdelete (table sync row deletion)
)

type CloneCard

type CloneCard struct {
	Version int
	SeqNo   int
}

CloneCard represents a "clone" card. Version and SeqNo may be zero for legacy clone requests.

func (*CloneCard) Type

func (c *CloneCard) Type() CardType

type CloneSeqNoCard

type CloneSeqNoCard struct {
	SeqNo int
}

CloneSeqNoCard represents a "clone_seqno" card.

func (*CloneSeqNoCard) Type

func (c *CloneSeqNoCard) Type() CardType

type ConfigCard

type ConfigCard struct {
	Name    string
	Content []byte
}

ConfigCard represents a "config" card carrying configuration data.

func (*ConfigCard) Type

func (c *ConfigCard) Type() CardType

type CookieCard

type CookieCard struct {
	Value string
}

CookieCard carries a session cookie value.

func (*CookieCard) Type

func (c *CookieCard) Type() CardType

type ErrorCard

type ErrorCard struct {
	Message string // plain text (defossilized)
}

ErrorCard carries an error message from the server.

func (*ErrorCard) Type

func (c *ErrorCard) Type() CardType

type FileCard

type FileCard struct {
	UUID     string
	DeltaSrc string // empty when not a delta
	Content  []byte
}

FileCard represents a "file" card carrying an artifact payload.

func (*FileCard) Type

func (c *FileCard) Type() CardType

type GimmeCard

type GimmeCard struct {
	UUID string
}

GimmeCard represents a "gimme" card — the sender wants this artifact.

func (*GimmeCard) Type

func (c *GimmeCard) Type() CardType

type IGotCard

type IGotCard struct {
	UUID      string
	IsPrivate bool // true when second arg is "1"
}

IGotCard represents an "igot" card — the sender has this artifact.

func (*IGotCard) Type

func (c *IGotCard) Type() CardType

type LoginCard

type LoginCard struct {
	User      string // plain text (defossilized)
	Nonce     string
	Signature string
}

LoginCard represents a "login" card for authentication. User is stored as plain text (Fossil-decoded).

func (*LoginCard) Type

func (c *LoginCard) Type() CardType

type Message

type Message struct {
	Cards []Card
}

Message is a sequence of cards forming one xfer request or response.

func Decode

func Decode(data []byte) (*Message, error)

Decode decodes an xfer message. It tries three formats in order:

  1. Raw zlib (Fossil HTTP sync wire format — no size prefix).
  2. 4-byte BE size prefix + zlib (Fossil blob compression / our Encode format).
  3. Uncompressed card data (clone protocol v3, x-fossil-uncompressed).

The first format that successfully decompresses wins.

func DecodeUncompressed

func DecodeUncompressed(data []byte) (*Message, error)

DecodeUncompressed decodes cards from uncompressed data.

func (*Message) Encode

func (m *Message) Encode() ([]byte, error)

Encode serializes all cards and zlib-compresses the result. Uses Fossil's compression format: 4-byte big-endian uncompressed size prefix followed by standard zlib data.

Example
package main

import (
	"fmt"

	"github.com/danmestas/libfossil/internal/xfer"
)

func main() {
	msg := &xfer.Message{
		Cards: []xfer.Card{
			&xfer.PushCard{ProjectCode: "abc123"},
			&xfer.PullCard{ProjectCode: "abc123", ServerCode: "def456"},
			&xfer.IGotCard{UUID: "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d"},
		},
	}

	wire, err := msg.Encode()
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	// Wire format is zlib-compressed xfer cards.
	fmt.Printf("compressed: %v\n", len(wire) > 0)

	// Decode round-trips back to a Message.
	decoded, err := xfer.Decode(wire)
	if err != nil {
		fmt.Println("error:", err)
		return
	}
	fmt.Printf("cards: %d\n", len(decoded.Cards))
}
Output:
compressed: true
cards: 3

func (*Message) EncodeUncompressed

func (m *Message) EncodeUncompressed() ([]byte, error)

EncodeUncompressed serializes all cards without zlib compression.

type MessageCard

type MessageCard struct {
	Message string // plain text (defossilized)
}

MessageCard carries an informational message.

func (*MessageCard) Type

func (c *MessageCard) Type() CardType

type PragmaCard

type PragmaCard struct {
	Name   string
	Values []string
}

PragmaCard represents a "pragma" card for protocol negotiation.

func (*PragmaCard) Type

func (c *PragmaCard) Type() CardType

type PrivateCard

type PrivateCard struct{}

PrivateCard signals that subsequent igot cards are private.

func (*PrivateCard) Type

func (c *PrivateCard) Type() CardType

type PullCard

type PullCard struct {
	ServerCode  string
	ProjectCode string
}

PullCard represents a "pull" card sent by the client to begin a pull.

func (*PullCard) Type

func (c *PullCard) Type() CardType

type PushCard

type PushCard struct {
	ServerCode  string
	ProjectCode string
}

PushCard represents a "push" card sent by the client to begin a push.

func (*PushCard) Type

func (c *PushCard) Type() CardType

type ReqConfigCard

type ReqConfigCard struct {
	Name string
}

ReqConfigCard requests a named configuration section.

func (*ReqConfigCard) Type

func (c *ReqConfigCard) Type() CardType

type SchemaCard

type SchemaCard struct {
	Table   string // table name (without x_ prefix)
	Version int
	Hash    string // SHA1 of canonical schema definition
	MTime   int64
	Content []byte // raw JSON schema definition
}

SchemaCard declares a synced extension table. Wire: schema TABLE VERSION HASH MTIME SIZE\nJSON

func (*SchemaCard) Type

func (c *SchemaCard) Type() CardType

type UVFileCard

type UVFileCard struct {
	Name    string
	MTime   int64
	Hash    string
	Size    int
	Flags   int
	Content []byte
}

UVFileCard represents an "uvfile" card for unversioned file content.

func (*UVFileCard) Type

func (c *UVFileCard) Type() CardType

type UVGimmeCard

type UVGimmeCard struct {
	Name string
}

UVGimmeCard requests an unversioned file by name.

func (*UVGimmeCard) Type

func (c *UVGimmeCard) Type() CardType

type UVIGotCard

type UVIGotCard struct {
	Name  string
	MTime int64
	Hash  string
	Size  int
}

UVIGotCard announces possession of an unversioned file.

func (*UVIGotCard) Type

func (c *UVIGotCard) Type() CardType

type UnknownCard

type UnknownCard struct {
	Command string
	Args    []string
}

UnknownCard captures any unrecognized card command.

func (*UnknownCard) Type

func (c *UnknownCard) Type() CardType

type XDeleteCard

type XDeleteCard struct {
	Table  string
	PKHash string
	MTime  int64
	PKData []byte // JSON-encoded PK column values
}

XDeleteCard marks a table sync row as deleted (tombstone). Wire: xdelete TABLE PK_HASH MTIME SIZE\nJSON_PK_DATA

func (*XDeleteCard) Type

func (c *XDeleteCard) Type() CardType

type XGimmeCard

type XGimmeCard struct {
	Table  string
	PKHash string
}

XGimmeCard requests a table sync row. Wire: xgimme TABLE PK_HASH

func (*XGimmeCard) Type

func (c *XGimmeCard) Type() CardType

type XIGotCard

type XIGotCard struct {
	Table  string
	PKHash string
	MTime  int64
}

XIGotCard announces possession of a table sync row. Wire: xigot TABLE PK_HASH MTIME

func (*XIGotCard) Type

func (c *XIGotCard) Type() CardType

type XRowCard

type XRowCard struct {
	Table   string
	PKHash  string
	MTime   int64
	Content []byte // raw JSON row data
}

XRowCard carries a table sync row payload. Wire: xrow TABLE PK_HASH MTIME SIZE\nJSON

func (*XRowCard) Type

func (c *XRowCard) Type() CardType

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL