Skip to content

RpcClient: the host connection

from nativehtmlkit import RpcClient
rpc = app.rpc

RpcClient is the authenticated, length-prefixed JSON-RPC connection to the Core host (Unix socket on Linux, named pipe on Windows). Application, Window and Document are built on it. Use it directly for Core v1 methods that have no convenience wrapper, such as desktop.paths, window.list or document.get. Parameters and results are those of the public Core wire protocol v1 (method list and JSON schemas ship with the Core release under protocol/v1/).

Attributes

Attribute Meaning
hello The host.hello result: protocol_version, host_version, app_id, capabilities (set by from_environment)
closed (property) True once the connection ended
closed_locally (property) True when close() ended it (not the host or a transport error)
shutdown_requested threading.Event, set when the host announced app.shutdown
dropped_notifications Notifications the SDK dropped because its callback queue (128) was full

Requests

call

rpc.call(method: str, params: dict | None = None, *, timeout=<default>) -> Any

Send a request and wait for the result. The default timeout is 15 s, and none for dialog.* methods (a person is answering). An explicit timeout=None waits forever. On timeout the SDK asks the host to cancel and raises RpcTimeoutError; the remote outcome is unknown. If the reply won the race against the deadline, its result is returned.

Raises RpcError (host error, code is the numeric wire code), ClientBusyError (an RpcError with local=True: more than 128 requests pending or the 8 MiB outgoing buffer is full; nothing was sent), LocalRequestError (ValueError: the request is not JSON-encodable, has non-string keys or exceeds the 2 MiB frame; nothing was sent), DisconnectedError, RpcTimeoutError.

paths = app.rpc.call("desktop.paths")        # {"config", "data", "cache", "state", "runtime"}
for w in app.rpc.call("window.list"):
    print(w["window_id"], w["title"])

desktop.paths returns per-application directories named after the app id (XDG directories on Linux, the AppData folders on Windows). The directories are not created for you.

call_async

rpc.call_async(method: str, params: dict | None = None) -> concurrent.futures.Future

Send a request and return a Future. Done-callbacks run on a short-lived nativehtmlkit-completion thread per result, so they may call synchronous SDK methods. future.cancel() asks the host to cancel (advisory).

future = app.rpc.call_async("window.get", {"window_id": window.id})
future.add_done_callback(lambda f: print(f.result()["title"]))

notify

rpc.notify(method: str, params: dict | None = None) -> None: send a notification (no reply), for example request.cancel.

Host-to-client messages

Method Meaning
on_request(method, callback) Answer host requests (window.before_close, app.before_quit): callback(params) returns the result ({"allow": bool}). One handler per method. Prefer Window.on_before_close / Application.on_before_quit, which Application routes through these.
on_notification(method, callback) Handle host notifications: callback(params). One handler per method; Application already uses document.event, document.error, window.event and app.shutdown. Registering one of those replaces the SDK's own handler and breaks the object model; use it for others such as app.activated (a second launch of a single-instance app: {"args", "cwd", "activation_token"}).

Lifetime

Method Meaning
wait(timeout=None) -> bool Wait until the connection closed
flush(timeout=2.0) Wait until queued outgoing messages were written; TimeoutError otherwise
wait_for_notifications(timeout) -> bool Wait until already received ordered notifications were handled
close() Close the connection; pending requests fail with DisconnectedError

Construction: RpcClient(stream, *, workers=4, ordered_notifications=False) and RpcClient.from_environment(*, workers=4, ordered_notifications=False) are used by Application.from_environment(); applications rarely construct a client themselves.

Threads

The client runs a reader and a writer thread that never execute application code, four worker threads for host requests (and app.shutdown), and, for an Application, one ordered "application events" thread for notifications. A full callback queue drops further notifications (counted in dropped_notifications) and answers further host requests with error -32005, which the host treats as a denial. See architecture.


Source: nativehtmlkit-python/docs/reference/rpc.md ยท edit the page there.