D 2026-10-13T02:27:53.168
L Bridge
N text/x-markdown
U dmestas
W 2817
# Bridge
A proxy that translates NATS messages to Fossil's HTTP `/xfer` protocol.
## Data Flow
``` pikchr
right
N: cylinder "NATS" color white fill 0x2a4a6b width 1.0 height 0.5 rad 5px
move 0.2
arrow color white thick "subscribe" above
move 0.1
B: box "Bridge" color white fill 0x6b5a2a width 1.2 height 0.5 rad 5px
move 0.2
arrow color white thick "HTTP POST" above
move 0.1
F: box "Fossil Server" color white fill 0x6b2a2a width 1.5 height 0.5 rad 5px
```
## How It Works
1. Connects to NATS
2. Subscribes to `<prefix>.<project-code>.sync`
3. For each message:
- Decodes the xfer request
- Forwards to Fossil server via HTTP POST (`Content-Type: application/x-fossil`)
- Encodes the response, replies via NATS
4. On decode/HTTP error: responds with empty message (never leaves the leaf hanging)
5. `SIGINT`/`SIGTERM` graceful shutdown
## HTTP Protocol
The bridge POSTs to the Fossil server's **root URL**, not `/xfer`. Fossil routes to the xfer handler based on the `Content-Type: application/x-fossil` header.
Body format: 4-byte big-endian uncompressed size prefix + zlib-compressed xfer cards.
## Usage
```
bridge --fossil http://fossil-server:8080 \
--project <project-code> \
--nats nats://localhost:4222 \
--prefix fossil
```
| Flag | Env Var | Default | Description |
|------|---------|---------|-------------|
| `--fossil` | `BRIDGE_FOSSIL_URL` | (required) | Fossil server URL |
| `--project` | `BRIDGE_PROJECT_CODE` | (required) | Project code |
| `--nats` | `BRIDGE_NATS_URL` | `nats://localhost:4222` | NATS URL |
| `--prefix` | `BRIDGE_PREFIX` | `fossil` | Subject prefix |
Finding the project code:
```
fossil sql -R /path/to/repo.fossil "SELECT value FROM config WHERE name='project-code'"
```
## Deployment
One bridge per project. Multiple leaves share the same NATS subject:
``` pikchr
right
down
A: box "Leaf A" color white fill 0x2a6b3a width 1.0 height 0.35 rad 5px
move 0.15
B: box "Leaf B" color white fill 0x2a6b3a width 1.0 height 0.35 rad 5px
move 0.15
C: box "Leaf C" color white fill 0x2a6b3a width 1.0 height 0.35 rad 5px
N: cylinder "NATS" color white fill 0x2a4a6b width 0.9 height 0.5 rad 5px \
at 1.8 right of B
BR: box "Bridge" color white fill 0x6b5a2a width 1.0 height 0.35 rad 5px \
at 1.8 right of N
FS: box "Fossil" color white fill 0x6b2a2a width 1.0 height 0.35 rad 5px \
at 1.8 right of BR
arrow from A.e to N.nw color white
arrow from B.e to N.w color white thick
arrow from C.e to N.sw color white
arrow from N.e to BR.w color white thick
arrow from BR.e to FS.w color white thick
```
## See Also
- [Leaf Agent](wiki:Leaf%20Agent) — the other half
- [Home](wiki:index) — architecture overview
Z b0df5b5e1cef493142746c0b28a4a709