How source types work
A source type is a small program that lets Orbuzo's desktop app browse a site or service and download from it. You can write one in any language that reads and writes lines.
Words
- A source type is the program: "VidHost", "Podcast archive".
- A source is one the user set up from it, with their own settings: "My channel", "Conference talks". A user can make many sources from one source type.
- The host is the Orbuzo desktop app, which starts your program and talks to it.
Local Files is not a source type. Files on the user's own disks are part of the app itself.
What a source type does
It lists what is in a place, says what each file is, and downloads a file when the user asks. That is all. It does not transcribe, summarise or talk to Orbuzo's servers — the app does those.
your source type ──JSON-RPC over stdin/stdout──► Orbuzo desktop app ──HTTPS──► Orbuzo
│ ▲
└──────── one HTTP PUT per download ───────────┘ (to 127.0.0.1)How it talks to the app
- JSON-RPC 2.0 over stdio. One JSON message per line on stdin and stdout. The app sends requests; you answer them, and send a few notifications of your own.
- stdout is for messages only. Anything else you print there breaks the stream. Log to stderr: the app keeps it in a log file on the user's computer and never sends it anywhere.
- One process per source. Three sources made from your source type are three copies of your program, each started with its own settings. A process never sees another source's settings.
- Settings arrive once. The app saves the user's settings and passes them in every time it starts you, with
setOptions. When the user edits a source, the app starts a fresh process. Store nothing.
The network, and nothing else
A source type gets nothing from the computer but the network:
- no files — you never read or write the user's disk;
- no paths, in either direction;
- no file bytes in JSON-RPC messages.
To hand over a file, the app gives you a one-time address on 127.0.0.1, and you PUT the bytes there. The app decides where the file is saved. See Downloads and the sink.
This keeps source types ready for a sandbox. A later version of the app can start them with access to the network and their own folder, and nothing else, without breaking a source type that follows these rules.
The calls
| The app calls | You answer with |
|---|---|
getSourceTypeInfo | who you are, and the settings a source needs |
setOptions | whether those settings work |
getItems | a page of what is in a folder |
getItem | one item, in full |
search | items matching a query, if you offer search |
getCaptions | a file's subtitle tracks |
download | a file or a track, sent to the sink |
ping, shutdown | your status; stopping |
Every message, field and error is in the protocol reference.
Next
Your first source type builds a working one in about 250 lines of Go.