Skip to main content

The Bridge

The Bridge is an optional, always-on companion to an AudioSilo server. It writes to the library folders and runs the heavy jobs, so the server itself can stay read-only and safe to expose to the internet. It is a separate program in its own repository, audiosilo-bridge, and runs beside the server, usually as a second container.

:::info Private repository, Phase 0 The audiosilo-bridge repository (and its image, ghcr.io/kodestar/audiosilo-bridge) is private for now, and the Bridge is being built in phases. Phase 0, which these pages describe, lays the foundations: pairing, the heartbeat and the capability, the job queue with leases, the library mapping checks and one proof job, bridge.verify. The jobs that make the Bridge useful (generated character sheets and recaps first, then podcasts, read-along, Audible backups and file moves) arrive in later phases. :::

What it is for​

The server never writes into a library: it reads the folders, indexes them and streams them. Anything that has to change files, or that is too heavy to run in the server (speech recognition, an AI agent), belongs to the Bridge. Today that is the desktop manager's job and the contributor tool's (audiosilo-sidecars); the Bridge is where those jobs move, run from the server's admin console rather than from a desktop app.

The engine came from audiosilo-sidecars: its packages (speech recognition, the agent pipeline, QA, spelling, contribution, the scheduler and supervisor) were imported with their history, so git log --follow and git blame still reach the reliability fixes made there. Phase 0 imports and tests the engine but doesn't run it; the shell around it (the server link, the job runner, the mapping checks, the Bridge's own page) is new and smaller.

The pull-only rule​

The Bridge calls the server; the server never calls the Bridge. There is no route on the Bridge that the server calls and no Bridge address the server dials:

  • The server stores intents and status: the jobs admins ask for (bridge_jobs) and the Bridge's last heartbeat (bridge_status). It never opens a connection to the Bridge.
  • The Bridge pulls: it sends a heartbeat every 30 seconds, long-polls for jobs, and reports progress, which renews each job's lease.
  • The console links to the Bridge's own page (the heartbeat's ui_url) for the admin's browser to open, nothing more.
  • Removing the Bridge breaks nothing. Its capability turns off two minutes after its last heartbeat, and anything that needs it disappears from the UI.

This keeps the server's surface unchanged: it needs no route to the Bridge, no credentials for it, and nothing about the Bridge's network.

How it relates to the server​

The Bridge is a third client of the server's wire format, after the player and the desktop manager, and the rule is the same: the server defines the contract and the Bridge mirrors it by hand (its internal/link; there is no codegen). A change to the server's internal/bridge or handlers_bridge.go is a change in audiosilo-bridge too, with a test on each side. The seam is section 23 of the workspace CROSS-REPO.md; this site's digest is the cross-repo contract.

Server (audiosilo-server)Bridge (audiosilo-bridge)
Pairingthe console mints a code; POST /bridge/pair trades it for a token of kind bridgeexchanges the code once, keeps the token sealed
Statusstores the last heartbeat; capabilities.bridge while it is under 2 minutes oldPUT /bridge/status every 30 s
Jobsbridge_jobs: the intent and the leaseserver_jobs: the execution truth
Librarieslists them (id, name, root) and each indexed book's files with their sizeschecks where it sees each one, and whether it can write there
UISettings > Bridge in the admin consoleits own page on port 8091

A few rules hold across the seam:

  • Bridge actions are admin-only. Only an admin pairs a Bridge, queues its jobs or cancels them, and the Bridge's token works only while the admin who paired it is still an enabled admin.
  • One Bridge per server. Pairing another revokes the first.
  • Library mappings are checked, never assumed. The Bridge proves it sees the server's copy of a library (a known book's files, with the server's sizes) before anything may write there. See Library mappings.
  • Path is the identity, as everywhere: a job is about (library_id, rel_path), follows its book when it moves, and goes with its library.
  • Hidden folders stay hidden. The server never indexes or lists a path through a dot-folder by name, so the folder the Bridge will keep its own files in, inside a book (.audiosilo/, from Phase 1a), can never become a phantom book.

Compatibility​

Everything is additive. An older server has no Bridge routes and no bridge flag: the Bridge's pairing gets a 404 (or 405) and says the server is too old. Shipped players never see either, and nothing in the player uses the Bridge yet.

In these pages​

  • Pairing and jobs - the token, the heartbeat and the capability, the job model (states, leases, attempts, cancel, resume after a restart) and bridge.verify.
  • Library mappings - how the Bridge finds each library and proves it has the right one.
  • Configuration - the Bridge's settings and environment, the images and the compose example.
  • Development - the gate, the layout and the Bridge's own page.
  • The server's routes are in the API reference.