v1.3.0: bridge and relay servers, Docker support

## What's New

**Bridge origin server** — `tltv bridge` takes external streaming sources (HLS URLs, M3U playlists, XMLTV guides, local directories) and publishes them as TLTV channels with Ed25519 identities, signed metadata, and the full protocol HTTP API. Supports private channels with token authentication and automatic re-polling.

**Relay node** — `tltv relay` re-serves existing TLTV channels from upstream nodes with full signature verification. Documents served verbatim (raw bytes preserved). Refuses private, on-demand, and retired channels per spec. Follows migration chains. Participates in peer exchange with validated gossip.

**Docker** — Multi-stage Dockerfile produces a ~10 MB image from scratch. All flags work as environment variables. CI pushes `:dev` on every push, releases push `:vX.Y.Z` and `:latest`.

```bash
docker run -p 8000:8000 -v keys:/data tltv bridge \
  --stream http://provider.example.com/channels.m3u

docker run -p 8000:8000 tltv relay \
  --node origin.example.com:443
```

**84 new tests** — 58 bridge tests (source parsing, manifest rewriting, path traversal, upstream proxy, private channels, concurrency) and 26 relay tests (fetch+verify, access checks, migration, endpoints, access transitions). 159 total.

Author: pfarnsworth

.dockerignore

@@ -0,0 +1,5 @@
+dist/
+tltv
+*.key
+AGENTS.md
+.git

.github/workflows/ci.yml

@@ -6,6 +6,10 @@ on:
   pull_request:
     branches: [main, dev]
 
+permissions:
+  contents: read
+  packages: write
+
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -44,3 +48,56 @@ jobs:
 
       - name: Test (race detector)
         run: go test -race -count=1 ./...
+
+  push:
+    needs: [test, race]
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Docker
+        run: |
+          if ! command -v docker >/dev/null 2>&1; then
+            curl -fsSL https://download.docker.com/linux/static/stable/x86_64/docker-27.5.1.tgz \
+              | tar xz --strip-components=1 -C /usr/local/bin docker/docker
+          fi
+          if ! docker info >/dev/null 2>&1; then
+            export DOCKER_HOST=tcp://docker-proxy:2375
+            echo "DOCKER_HOST=tcp://docker-proxy:2375" >> "$GITHUB_ENV"
+          fi
+          docker info >/dev/null
+
+      - name: Detect registry
+        id: detect
+        run: |
+          SERVER="${{ github.server_url }}"
+          REPO="${{ github.repository }}"
+          BRANCH="${{ github.ref_name }}"
+          if echo "$SERVER" | grep -q "github\.com"; then
+            echo "registry=ghcr.io" >> "$GITHUB_OUTPUT"
+            echo "image=ghcr.io/${REPO}" >> "$GITHUB_OUTPUT"
+          else
+            HOST="${FORGEJO_REGISTRY:-$(echo "$SERVER" | sed 's|https\?://||' | sed 's|:[0-9]*$||')}"
+            echo "registry=${HOST}" >> "$GITHUB_OUTPUT"
+            echo "image=${HOST}/${REPO}" >> "$GITHUB_OUTPUT"
+          fi
+          if [ "$BRANCH" = "dev" ]; then
+            echo "tag=dev" >> "$GITHUB_OUTPUT"
+          elif [ "$BRANCH" = "main" ]; then
+            echo "tag=latest" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Login to registry
+        run: |
+          TOKEN="${{ secrets.PACKAGES_TOKEN || secrets.GITHUB_TOKEN }}"
+          echo "${TOKEN}" | \
+            docker login "${{ steps.detect.outputs.registry }}" \
+              -u "${{ github.repository_owner }}" --password-stdin
+
+      - name: Build and push image
+        run: |
+          IMAGE="${{ steps.detect.outputs.image }}"
+          TAG="${{ steps.detect.outputs.tag }}"
+          docker build --build-arg VERSION=${TAG} -t "${IMAGE}:${TAG}" .
+          docker push "${IMAGE}:${TAG}"

.github/workflows/release.yml

@@ -7,6 +7,7 @@ on:
 
 permissions:
   contents: write
+  packages: write
 
 jobs:
   release:
@@ -66,9 +67,14 @@ jobs:
           if echo "$SERVER" | grep -q "github\.com"; then
             echo "api_base=https://api.github.com/repos/${REPO}" >> "$GITHUB_OUTPUT"
             echo "upload_mode=github" >> "$GITHUB_OUTPUT"
+            echo "registry=ghcr.io" >> "$GITHUB_OUTPUT"
+            echo "image=ghcr.io/${REPO}" >> "$GITHUB_OUTPUT"
           else
+            HOST="${FORGEJO_REGISTRY:-$(echo "$SERVER" | sed 's|https\?://||' | sed 's|:[0-9]*$||')}"
             echo "api_base=${SERVER}/api/v1/repos/${REPO}" >> "$GITHUB_OUTPUT"
             echo "upload_mode=forgejo" >> "$GITHUB_OUTPUT"
+            echo "registry=${HOST}" >> "$GITHUB_OUTPUT"
+            echo "image=${HOST}/${REPO}" >> "$GITHUB_OUTPUT"
           fi
 
           PRERELEASE=false
@@ -121,31 +127,15 @@ jobs:
             exit 1
           fi
 
-          BODY="## tltv-cli ${TAG}
+          # Use the tagged commit message body as release notes.
+          # First line is the title (ignored), rest is the body.
+          BODY=$(git log -1 --format='%b' "${TAG}")
 
-          Single static binary. Zero dependencies.
+          # Fallback if commit has no body
+          if [ -z "$(echo "$BODY" | tr -d '[:space:]')" ]; then
+            BODY="## What's New
 
-          \`\`\`bash
-          curl -sSL https://raw.githubusercontent.com/tltv-org/cli/main/install.sh | sh
-          \`\`\`
-
-          Pre-built for Linux, macOS, Windows (amd64 + arm64) and FreeBSD (amd64)."
-
-          # Auto-generate changelog on GitHub
-          if [ "$UPLOAD_MODE" = "github" ]; then
-            AUTO_NOTES=$(curl -sS -X POST \
-              -H "Authorization: token ${TOKEN}" \
-              -H "Content-Type: application/json" \
-              -d "{\"tag_name\":\"${TAG}\"}" \
-              "${API_BASE}/releases/generate-notes" 2>/dev/null \
-              | python3 -c "import sys,json; print(json.load(sys.stdin).get('body',''))" 2>/dev/null || true)
-            if [ -n "$AUTO_NOTES" ]; then
-              BODY="${BODY}
-
-          ---
-
-          ${AUTO_NOTES}"
-            fi
+          See commit history for details."
           fi
 
           BODY_JSON=$(echo "$BODY" | python3 -c "import sys,json; print(json.dumps(sys.stdin.read()))")
@@ -207,3 +197,33 @@ jobs:
           done
 
           echo "Uploaded $(ls dist/* | wc -l) assets"
+
+      - name: Setup Docker
+        run: |
+          if ! command -v docker >/dev/null 2>&1; then
+            curl -fsSL https://download.docker.com/linux/static/stable/x86_64/docker-27.5.1.tgz \
+              | tar xz --strip-components=1 -C /usr/local/bin docker/docker
+          fi
+          if ! docker info >/dev/null 2>&1; then
+            export DOCKER_HOST=tcp://docker-proxy:2375
+            echo "DOCKER_HOST=tcp://docker-proxy:2375" >> "$GITHUB_ENV"
+          fi
+          docker info >/dev/null
+
+      - name: Login to registry
+        run: |
+          TOKEN="${{ secrets.PACKAGES_TOKEN || secrets.GITHUB_TOKEN }}"
+          echo "${TOKEN}" | \
+            docker login "${{ steps.detect.outputs.registry }}" \
+              -u "${{ github.repository_owner }}" --password-stdin
+
+      - name: Build and push Docker image
+        env:
+          TAG: ${{ github.ref_name }}
+          IMAGE: ${{ steps.detect.outputs.image }}
+        run: |
+          docker build --build-arg VERSION=${TAG} \
+            -t "${IMAGE}:${TAG}" \
+            -t "${IMAGE}:latest" .
+          docker push "${IMAGE}:${TAG}"
+          docker push "${IMAGE}:latest"

Dockerfile

@@ -0,0 +1,13 @@
+FROM golang:1.22-alpine AS builder
+ARG VERSION=dev
+WORKDIR /src
+COPY go.mod ./
+COPY *.go ./
+RUN CGO_ENABLED=0 go build -ldflags "-s -w -X main.version=${VERSION}" -o /tltv .
+
+FROM scratch
+COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
+COPY --from=builder /tltv /tltv
+EXPOSE 8000
+WORKDIR /data
+ENTRYPOINT ["/tltv"]

README.md

@@ -16,6 +16,18 @@ curl -sSL https://raw.githubusercontent.com/tltv-org/cli/main/install.sh | sh
 
 Download the latest `.zip` from the [releases page](https://github.com/tltv-org/cli/releases/latest) and add `tltv.exe` to your PATH.
 
+### Docker
+
+```bash
+docker run --rm -v tltv-keys:/data -p 8000:8000 tltv bridge \
+  --stream http://provider.example.com/channels.m3u
+
+docker run --rm -v tltv-data:/data -p 8000:8000 tltv relay \
+  --node origin.example.com:443
+```
+
+Or build locally: `docker build -t tltv .`
+
 ### From source
 
 Requires [Go](https://go.dev/dl/) 1.22+:
@@ -69,6 +81,12 @@ tltv stream "tltv://TVabc...@example.com:443"
 # Discover channels across the network
 tltv crawl example.com
 
+# Bridge external streams as TLTV channels
+tltv bridge --stream http://provider.com/channels.m3u --guide http://provider.com/guide.xml
+
+# Relay channels from another TLTV node
+tltv relay --node origin.example.com:443
+
 # Install shell completions
 tltv completion --install zsh
 ```
@@ -110,6 +128,13 @@ tltv completion --install zsh
 | `stream <uri\|id@host>` | Check HLS stream availability. Shows stream URL, segment count, target duration. Use `--url` to print only the stream URL for piping. |
 | `crawl <host>` | BFS-crawl the gossip network starting from a host. Discovers channels across nodes via peer exchange. Use `--depth` (`-d`) to set max depth. |
 
+### Server
+
+| Command | Description |
+|---|---|
+| `bridge` | Start a bridge origin server. Takes external streaming sources (HLS URLs, M3U playlists, JSON channel lists, directories of .m3u8 files) and publishes them as TLTV channels with Ed25519 identities and signed metadata. Supports private channels with token authentication, XMLTV guide output, and automatic re-polling. All flags also work as environment variables for Docker. |
+| `relay` | Start a relay node. Re-serves existing TLTV channels from upstream nodes with full signature verification. Serves upstream-signed documents verbatim (preserves unknown fields). Refuses private, on-demand, and retired channels per spec. Participates in peer exchange with validated gossip. Supports `--channels` (specific URIs), `--node` (relay all from a node), and `--config` (JSON config file). |
+
 ### Operations
 
 | Command | Description |
@@ -215,6 +240,94 @@ tltv --json peers example.com | jq '.peers[].id'
 tltv --json crawl example.com | jq '.channels | length'
 ```
 
+## Bridge
+
+The bridge is a long-running origin server that takes external streaming sources and publishes them as first-class TLTV channels with Ed25519 identities, signed metadata, and the full protocol HTTP API.
+
+```bash
+# Bridge a single HLS stream
+tltv bridge --stream http://example.com/live.m3u8 --name "My Channel"
+
+# Bridge an M3U playlist with XMLTV guide
+tltv bridge --stream http://provider.com/channels.m3u --guide http://provider.com/guide.xml
+
+# Bridge a directory of .m3u8 files (with optional sidecar .json metadata)
+tltv bridge --stream /media/hls
+
+# With on-demand channels and custom settings
+tltv bridge --stream http://mediaserver:8000/api/channels.m3u \
+  --guide http://mediaserver:8000/api/xmltv.xml --on-demand \
+  --listen :8000 --hostname origin.example.com:443
+```
+
+Source formats are auto-detected: M3U playlists (with tvg-id/tvg-name attributes), JSON channel arrays, local directories with sidecar `.json` files, or single HLS streams. Guide data can be XMLTV or JSON.
+
+All flags also work as environment variables for Docker: `STREAM`, `GUIDE`, `NAME`, `ON_DEMAND=1`, `POLL`, `LISTEN`, `KEYS_DIR`, `HOSTNAME`, `PEERS`.
+
+Docker Compose example:
+```yaml
+services:
+  bridge:
+    image: tltv
+    command: bridge
+    ports: ["8000:8000"]
+    volumes: [bridge-keys:/data]
+    environment:
+      STREAM: http://mediaserver:8000/api/channels.m3u
+      GUIDE: http://mediaserver:8000/api/xmltv.xml
+      HOSTNAME: bridge.example.com:443
+volumes:
+  bridge-keys:
+```
+
+Mount `/data` to persist channel keys across restarts. Set `HOSTNAME` explicitly -- Docker's default `HOSTNAME` is the container ID.
+
+Private channels (`access: "token"`) are supported: hidden from node info and peers, token required on all endpoints, token injected into every URI in the HLS playlist graph.
+
+## Relay
+
+The relay is a long-running node that re-serves existing TLTV channels from upstream nodes with full signature verification. It does not have channel private keys and cannot modify signed documents.
+
+```bash
+# Relay specific channels
+tltv relay --channels "tltv://TVabc...@origin.example.com:443"
+
+# Relay all public channels from a node
+tltv relay --node origin.example.com:443
+
+# Relay with a config file
+tltv relay --config relay.json --hostname relay.example.com:443
+```
+
+The relay verifies every metadata and guide document against the channel's Ed25519 public key before caching. Documents are served verbatim (raw bytes preserved, unknown fields intact). Private, on-demand, and retired channels are refused per spec. If a channel transitions to any of these states, the relay stops immediately.
+
+Migration chains are followed automatically (up to 5 hops). Peer exchange participates in gossip with validated entries, 7-day staleness cutoff, and 100-entry limit.
+
+Config file format:
+```json
+{
+  "channels": ["tltv://TVabc...@origin.example.com:443"],
+  "nodes": ["origin.example.com:443"]
+}
+```
+
+Environment variables: `CHANNELS`, `NODE`, `CONFIG`, `LISTEN`, `HOSTNAME`, `PEERS`, `META_POLL`, `GUIDE_POLL`, `PEER_POLL`.
+
+Docker Compose example:
+```yaml
+services:
+  relay:
+    image: tltv
+    command: relay
+    ports: ["8000:8000"]
+    volumes: [relay-data:/data]
+    environment:
+      NODE: origin.example.com:443
+      HOSTNAME: relay.example.com:443
+volumes:
+  relay-data:
+```
+
 ## Project Structure
 
 ```
@@ -228,11 +341,16 @@ network.go          Network commands (node, fetch, guide, peers, stream, crawl)
 vanity.go           Multi-threaded vanity channel ID miner
 output.go           Terminal output formatting and colors
 signal.go           OS signal handling
+bridge*.go          Bridge origin server (source parsing, identity, HLS rewriting, HTTP)
+relay*.go           Relay node (upstream fetch+verify, caching, gossip, HTTP)
 main_test.go        75 tests against all protocol test vectors + edge cases
+bridge_test.go      58 bridge tests (source parsing, manifest rewriting, endpoints)
+relay_test.go       26 relay tests (fetch+verify, access checks, migration, endpoints)
 Makefile            Build, test, install, cross-compile (CGO_ENABLED=0)
+Dockerfile          Multi-stage: golang:1.22-alpine -> scratch (~10 MB)
 ```
 
-Zero external dependencies. Everything uses the Go standard library (`crypto/ed25519`, `encoding/json`, `net/http`, `math/big`).
+Zero external dependencies. Everything uses the Go standard library (`crypto/ed25519`, `encoding/json`, `net/http`, `math/big`). 159 tests.
 
 ## License