Background service API

The window is only a view. The work is done by Pythonator’s background service (the daemon), which keeps running when the window closes. The window talks to it over a local socket, and so can your own scripts, a status-bar widget, a deploy script or a test harness. Anything the window can do, a script can do.

The socket isn’t on the network: no other computer and no other user of this computer can open it.

Connecting

The background service writes a fresh random token to daemon.token in the data folder (readable only by you) each time it starts. Send it first:

{"op": "hello", "req": 1, "token": "<the contents of daemon.token>"}

A wrong token, or any other message first, and the connection is closed. After a correct hello you receive a reply, then a snapshot of every service and its state, the list of plugins, and their panels.

If the background service isn’t running, start it with pythonator --daemon (the window does this for you).

Messages

Both directions send one JSON object per line, UTF-8, at most 1 MB per line.

Requests have an op and a req number of your choice. Every request gets exactly one reply with the same req:

{"ev": "reply", "req": 7, "ok": true, "data": ...}
{"ev": "reply", "req": 8, "ok": false, "error": "Invalid id: String should match pattern ..."}

A request with a field it doesn’t know, a missing field or a bad value is refused with an error, never guessed at.

Events arrive whenever something happens, to every connected client. They have an ev and no req.

Requests

Events

A client that reads too slowly first gets only the newest output (with a notice saying so), and is disconnected if it falls 64 MB behind. The services don’t wait for anyone.

The service object

The same object is stored in services.json. Only name and folder are required.

{
  "id": "3f9a1c2b7d10",
  "name": "web api",
  "folder": "/home/me/code/api",
  "runtime": "python",
  "entry": "main.py",
  "command": [],
  "args": ["--workers", "2"],
  "env": {"LOG_LEVEL": "info"},
  "env_file": ".env",
  "mode": "sandbox",
  "network": {"enabled": true, "ports": [8000], "expose": "local"},
  "sandbox": {"write_project": true, "folders": [{"path": "/home/me/datasets", "write": false}]},
  "container": {"engine": "auto", "image": "", "network": "", "read_only_root": true},
  "restart": "on-failure",
  "max_restarts": 5,
  "stop_timeout": 10.0,
  "autostart": false,
  "memory_mb": 0,
  "git": {"url": "https://github.com/me/api.git", "branch": "", "pull_on_start": false},
  "schedule": ""
}

Every field is checked the same way as in the window: see Services.

Example: a command-line client

pyctl.py is a complete client in under 90 lines of standard-library Python, for Windows, macOS and Linux:

python docs/examples/pyctl.py list
python docs/examples/pyctl.py start "web api"
python docs/examples/pyctl.py tail "web api"

The core of it:

sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
sock.connect(socket_path())  # daemon.sock in the data folder, see Connecting
file = sock.makefile("rwb")
token = (home / "daemon.token").read_text().strip()
file.write(json.dumps({"op": "hello", "req": 1, "token": token}).encode() + b"\n")
file.flush()
for line in file:
    message = json.loads(line)
    ...

Versioning

hello returns the protocol number, 1 in this version. It changes only when a change would break existing clients; new requests, events and fields don’t change it.