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