D 2026-10-13T02:27:51.614
L index
N text/x-markdown
U dmestas
W 3631
# go-libfossil

Pure Go library for working with [Fossil SCM](https://fossil-scm.org/) repositories. No CGo, no external dependencies beyond `modernc.org/sqlite`.

## What It Does

Read, write, and sync Fossil repositories from Go — without shelling out to the `fossil` binary.

- Create repos, store blobs, create checkins
- Parse and serialize Fossil manifests (all 20 card types)
- Encode/decode the xfer sync protocol (all 19 card types + zlib)
- Run multi-round sync sessions against Fossil servers
- Transport-agnostic — plug in HTTP, NATS, or your own transport

## Package Structure

```
go-libfossil/
├── types.go, errors.go, julian.go   # foundation: FslID, TimeToJulian()
├── db/                               # SQLite wrapper: DB, Tx, Querier
├── hash/                             # content addressing: SHA1(), SHA3()
├── delta/                            # Fossil delta codec: Create(), Apply()
├── blob/                             # blob storage: Store(), Load(), Exists()
├── content/                          # delta chain expansion: Expand(), Verify()
├── repo/                             # repo lifecycle: Create(), Open(), Close()
├── testutil/                         # Fossil CLI oracle: HasFossil(), FossilRebuild()
├── deck/                             # manifest format (no DB): Parse(), Marshal()
├── manifest/                         # checkin ops: Checkin(), GetManifest(), ListFiles()
├── xfer/                             # sync wire format (no DB): EncodeCard(), DecodeCard()
└── sync/                             # sync engine: Sync(), Transport interface
```

Dependencies flow downward. `deck/` and `xfer/` have no database dependency — pure format layers.

## Transport Interface

The sync engine uses a pluggable `Transport`:

``` pikchr
    right
    SE: box "sync.Sync()" color white fill 0x6b5a2a width 1.3 height 0.45 rad 5px
    move 0.3
    I: box "Transport" color white fill 0x3a3a3a width 1.2 height 0.45 rad 5px
    arrow from SE.e to I.w color white thick

    HT: box "HTTP" color white fill 0x2a6b3a width 0.9 height 0.35 rad 5px \
        at 1.5 right of I + (0, 0.45)
    NT: box "NATS" color white fill 0x2a4a6b width 0.9 height 0.35 rad 5px \
        at 1.5 right of I
    MT: box "Mock" color white fill 0x3a3a3a width 0.9 height 0.35 rad 5px \
        at 1.5 right of I + (0, -0.45)

    arrow from I.e to HT.w color white
    arrow from I.e to NT.w color white thick
    arrow from I.e to MT.w color white
```

Built-in: `HTTPTransport` (talks to fossil server), `MockTransport` (testing).
External: `NATSTransport` in [EdgeSync](https://fossil.craftdesign.group/edgesync) leaf agent.

## Protocol Notes

- Fossil's `blob_compress` prepends a **4-byte big-endian size prefix** before zlib data
- `HTTPTransport` POSTs to the repo root URL — Fossil routes by `Content-Type: application/x-fossil`, not URL path
- All 19 xfer card types supported

## Performance (Apple M4 Pro)

| Operation | Time |
|-----------|------|
| Checkin (10 files, 1KB each) | 2.5ms |
| ListFiles (50 files) | 52us |
| Deck Marshal (50 F-cards) | 8.4us |
| Deck Parse (50 F-cards) | 15us |
| Xfer Message Encode (50 cards) | 62us |
| Xfer Message Decode (50 cards) | 14us |
| Full sync round-trip | ~150ms |

## Related

- **[EdgeSync](https://fossil.craftdesign.group/edgesync)** — Leaf agent + bridge built on this library
- **[Fossil SCM](https://fossil-scm.org/)** — The version control system this library speaks

## Clone

```
fossil clone https://fossil.craftdesign.group/go-libfossil go-libfossil.fossil
```

Z 6281c1cf0b6ae0fb6a4c5b19e15d260d