Skip to content

Install and test ​

Where a source type goes, how the app finds it, and how to see what it says.

The folder ​

A source type is a folder inside source-types/, next to the Orbuzo program. The folder holds one program — source-type.exe on Windows, source-type on macOS and Linux — and anything else it needs.

text
Orbuzo.exe
source-types/
  vidhost/
    source-type.exe
    README.md
  • The folder's name does not matter; your about.id does. Keep it the same forever: saved sources are linked to it.
  • The app starts your program with its folder as the working directory.
  • When the user clicks Add a source…, the app starts each program it has not seen and calls getSourceTypeInfo. It remembers the answer until the program file changes.
  • A folder that cannot be used — no program, no answer in time, a protocol version the app does not speak — is still listed, with the reason.

To test a build without copying it next to the app each time, set ROBOLIB_SOURCE_TYPES_DIR to the folder that holds your source type's folder.

Your log ​

Everything you write to stderr goes to a log file on the user's computer, one per source type, in Orbuzo's cache folder (%LOCALAPPDATA%\Orbuzo\logs\source-types\ on Windows). Lines are rate-limited. Never log passwords, tokens, search queries, sink addresses or file contents, and prefer not to log titles: a log may end up attached to a bug report.

Source traffic ​

Debug builds of Orbuzo record every line between the app and its source types, and show it in View › Source traffic — or a source's Show traffic. You see each request, its answer, how long it took, and your stderr, live. A malformed line shows exactly as it was sent, which is often the bug.

Limits ​

The app enforces these without warning. A source type that goes over them has its request fail, or its process stopped.

WhatLimit
Answering getSourceTypeInfo after start5 s
ping2 s
setOptions, getItems, getItem, search, getCaptions30 s each; a progress notification resets it, up to 5 minutes
downloadno total limit; fails after 60 s with no bytes and no progress
Exiting after shutdown3 s
One message1 MiB

A source type that fails 3 times in 5 minutes — a crash, a kill, or garbage on stdout — is not restarted until the user asks.

Before you publish ​

  1. Write nothing but protocol messages to stdout.
  2. Keep item ids stable across restarts. The app uses them to remember what was imported.
  3. Answer every request, with a result or an error. Fail rather than hang.
  4. Keep getItems and search fast. Download only in download.
  5. Stop quickly on $/cancelRequest, shutdown, or the end of stdin.
  6. Ignore fields and caps you do not recognise, so a newer app does not break you.