barebidi 0.1.0__py3-none-any.whl

barebidi/__init__.py

@@ -0,0 +1,33 @@
+from . import protocol
+from .browser import Browser, find_firefox, start
+from .connection import BidiError, BrowserClosedError, Connection
+from .context import Context
+from .dialogs import Dialog
+from .downloads import Download
+from .element import Element, ElementQuery
+from .frame import Frame, JavaScriptError
+from .network import ExpectedResponse, Intercept, InterceptedRequest, Request, Response
+from .tab import Tab
+
+__all__ = [
+    "BidiError",
+    "BrowserClosedError",
+    "Browser",
+    "Connection",
+    "Context",
+    "Dialog",
+    "Download",
+    "Element",
+    "ElementQuery",
+    "ExpectedResponse",
+    "Frame",
+    "Intercept",
+    "InterceptedRequest",
+    "JavaScriptError",
+    "Request",
+    "Response",
+    "Tab",
+    "find_firefox",
+    "protocol",
+    "start",
+]

barebidi/browser.py

@@ -0,0 +1,458 @@
+import asyncio
+import contextlib
+import json
+import logging
+import os
+import re
+import shutil
+import signal
+import subprocess
+import sys
+import tempfile
+from collections.abc import AsyncIterator, Callable, Iterable
+from pathlib import Path
+from typing import Any
+
+from .connection import BidiError, Connection, Handler
+from .context import Context
+from .dialogs import DialogHandler, Dialogs
+from .downloads import Downloads
+from .network import Intercept, InterceptHandler, Network, Phase
+from .proxy import NO_PROXY_PREFS, Proxy, Relay
+from .stealth import CLEAR_AUTOMATION_FLAG, HIDE_WEBDRIVER
+from .stealth import PREFS as STEALTH_PREFS
+from .tab import Tab
+
+log = logging.getLogger(__name__)
+
+_WS_URL = re.compile(rb"WebDriver BiDi listening on (ws://\S+)")
+
+
+class _ExitedDuringStartup(RuntimeError):
+    pass
+
+DEFAULT_HEADLESS_SCREEN = (1920, 1080)
+
+ROUTED_MOUSE = "remote.events.async.mouse.enabled"
+
+DEFAULT_PREFS: dict[str, Any] = {
+    "browser.shell.checkDefaultBrowser": False,
+    "browser.startup.homepage_override.mstone": "ignore",
+    "browser.aboutwelcome.enabled": False,
+    "browser.tabs.warnOnClose": False,
+    "browser.sessionstore.resume_from_crash": False,
+    "datareporting.policy.dataSubmissionEnabled": False,
+    "toolkit.telemetry.reportingpolicy.firstRun": False,
+    "app.update.disabledForTesting": True,
+    # Behind a proxy, WebRTC must not reveal the real IP by reaching STUN servers directly.
+    "media.peerconnection.ice.proxy_only_if_behind_proxy": True,
+    # Mouse and wheel input enters through the browser window and its hit testing, like real input, instead
+    # of being synthesized inside the page's process: it reaches cross-site iframes, with coherent coordinates.
+    ROUTED_MOUSE: True,
+    "remote.events.async.wheel.enabled": True,
+}
+
+
+def find_firefox() -> str:
+    if path := os.environ.get("FIREFOX_PATH"):
+        return path
+    candidates = {
+        "darwin": ["/Applications/Firefox.app/Contents/MacOS/firefox", "/Applications/Firefox Nightly.app/Contents/MacOS/firefox"],
+        "win32": [
+            rf"{os.environ.get('PROGRAMFILES', 'C:/Program Files')}\Mozilla Firefox\firefox.exe",
+            rf"{os.environ.get('PROGRAMFILES(X86)', 'C:/Program Files (x86)')}\Mozilla Firefox\firefox.exe",
+        ],
+    }.get(sys.platform, [])
+    for candidate in candidates:
+        if Path(candidate).exists():
+            return candidate
+    for name in ("firefox", "firefox-esr", "firefox-nightly"):
+        if found := shutil.which(name):
+            return found
+    raise FileNotFoundError("Firefox not found; install it or set FIREFOX_PATH")
+
+
+def _is_snap(executable: str) -> bool:
+    """A snap-packaged Firefox (Ubuntu's default), directly or through the script Ubuntu puts in /usr/bin."""
+    resolved = Path(executable).resolve()
+    if resolved.parts[:2] == ("/", "snap"):
+        return True
+    try:
+        with open(resolved, "rb") as file:
+            head = file.read(4096)
+    except OSError:
+        return False
+    return head.startswith(b"#!") and b"/snap/" in head
+
+
+class Browser:
+    """Firefox driven over WebDriver BiDi.
+
+    `proxy`, `locale` and `timezone` set up the default context (see Context); `profile` keeps its
+    cookies and storage between runs instead of starting from a temporary profile. `screen` is the
+    size of the virtual screen in headless mode; otherwise the real screen is used. With `humanize`,
+    the mouse travels in curves, keys are typed at a human rhythm and scrolling uses the wheel;
+    turn it off (here or later through the attribute) for speed. Downloaded files go to `downloads`,
+    or to a temporary folder that disappears with the browser. `timeout` is how many seconds Firefox
+    gets to answer each command (None waits forever); slow pages can get more through Tab.get.
+    """
+
+    def __init__(
+        self,
+        *,
+        headless: bool = False,
+        screen: tuple[int, int] | None = None,
+        stealth: bool = True,
+        humanize: bool = True,
+        profile: str | Path | None = None,
+        proxy: str | None = None,
+        locale: str | None = None,
+        timezone: str | None = None,
+        executable_path: str | None = None,
+        args: Iterable[str] = (),
+        prefs: dict[str, Any] | None = None,
+        env: dict[str, str] | None = None,
+        downloads: str | Path | None = None,
+        timeout: float | None = 60.0,
+        startup_timeout: float = 30.0,
+    ):
+        if screen and not headless:
+            raise ValueError("the screen size can only be chosen in headless mode; otherwise it is the real one")
+        self.headless = headless
+        self.screen = screen or DEFAULT_HEADLESS_SCREEN
+        self.stealth = stealth
+        self.humanize = humanize
+        self.profile = Path(profile) if profile else None
+        self.downloads = Path(downloads) if downloads else None  # where files go; a temporary folder if None
+        self.proxy = Proxy.parse(proxy) if proxy else None
+        self.locale = locale
+        self.timezone = timezone
+        self.executable_path = executable_path
+        self.args = list(args)
+        self.env = dict(env or {})  # extra environment for the browser process (e.g. a patched build's config)
+        self.prefs = {
+            **DEFAULT_PREFS,
+            **(STEALTH_PREFS if stealth else {}),
+            **(self.proxy.prefs() if self.proxy else NO_PROXY_PREFS),
+            **(prefs or {}),
+        }
+        self.timeout = timeout  # seconds Firefox gets to answer each command; mouse and keyboard add their own duration
+        self.startup_timeout = startup_timeout
+        self.connection: Connection
+        self.session_id: str | None = None
+        self.capabilities: dict = {}
+        self._process: asyncio.subprocess.Process | None = None
+        self._profile: str | None = None
+        self._stderr_task: asyncio.Task | None = None
+        self._parents: dict[str, str] = {}
+        self._user_contexts: dict[str, str] = {}
+        self._pointers: dict[str, tuple[int, int]] = {}
+        self._network = Network(self)
+        self._dialogs = Dialogs(self)
+        self._downloader = Downloads(self)
+        self._downloads_dir: str | None = None
+        self._scratch: Path | None = None
+        self._relays: list[Relay] = []
+        self.context = Context(self, "default")
+
+    async def __aenter__(self) -> "Browser":
+        return await self.start()
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.stop()
+
+    async def start(self) -> "Browser":
+        executable = self.executable_path or find_firefox()
+        # A snap's /tmp is its own: keep our temporary folders where a snap-packaged Firefox can reach them.
+        self._scratch = Path.home() / "snap" / "firefox" / "common" if _is_snap(executable) else None
+        if self._scratch:
+            self._scratch.mkdir(parents=True, exist_ok=True)
+        if self.profile:
+            self.profile.mkdir(parents=True, exist_ok=True)
+            self._profile = str(self.profile)
+        else:
+            self._profile = tempfile.mkdtemp(prefix="barebidi-", dir=self._scratch)
+        if self.proxy and self.proxy.credentials:
+            self.prefs |= (await self._relay(self.proxy)).local.prefs()
+        prefs = "".join(f"user_pref({json.dumps(k)}, {json.dumps(v)});\n" for k, v in self.prefs.items())
+        Path(self._profile, "user.js").write_text(prefs)
+
+        cmd = [executable, "--remote-debugging-port=0", "--profile", self._profile, "--no-remote"]
+        if self.headless:
+            cmd.append("--headless")
+        env = dict(os.environ)
+        if self.stealth:
+            # Access to the browser's own scope; older Firefox takes the flag, newer ones only the variable.
+            cmd.append("--remote-allow-system-access")
+            env["MOZ_REMOTE_ALLOW_SYSTEM_ACCESS"] = "1"
+        cmd += [*self.args, "about:blank"]
+        if self.headless:
+            width, height = self.screen
+            env |= {"MOZ_HEADLESS_WIDTH": str(width), "MOZ_HEADLESS_HEIGHT": str(height)}
+        env |= self.env  # caller's env wins, so it can override our defaults
+        try:
+            url = await self._launch(cmd, env)
+            self._stderr_task = asyncio.create_task(self._drain_stderr())
+            self.connection = await Connection.connect(f"{url}/session", self.timeout)
+            # Dialogs wait for us to answer them (see Dialogs); native file pickers are cancelled at once.
+            prompts = {"default": "ignore", "file": "dismiss"}
+            session = await self.connection.send("session.new", {"capabilities": {"alwaysMatch": {"unhandledPromptBehavior": prompts}}})
+            await self._track_frames()
+            await self._watch_dialogs_and_downloads()
+            await self.context._emulate(self.locale, self.timezone)
+            if self.stealth:
+                await self._clear_automation_flag()
+            tab = await self._replace_initial_tab()
+            if self.headless:
+                await self._fit_window(tab)
+            if self.stealth and not await self._webdriver_hidden(tab):
+                log.info("this Firefox keeps navigator.webdriver on; hiding it with a preload script instead")
+                await self.connection.send("script.addPreloadScript", {"functionDeclaration": HIDE_WEBDRIVER})
+        except BaseException:
+            await self._cleanup(grace=0)
+            raise
+        self.session_id = session["sessionId"]
+        self.capabilities = session["capabilities"]
+        return self
+
+    async def stop(self) -> None:
+        if self._process is None:
+            return
+        if hasattr(self, "connection") and not self.connection.closed:
+            try:
+                await asyncio.wait_for(self.connection.send("browser.close"), 5)
+            except Exception:
+                pass
+            await self.connection.close()
+        await self._cleanup()
+
+    async def tabs(self) -> list[Tab]:
+        tree = await self.connection.send("browsingContext.getTree", {"maxDepth": 0})
+        return [Tab(self, c["context"]) for c in tree["contexts"]]
+
+    async def new_tab(self, url: str | None = None, background: bool = False) -> Tab:
+        return await self.context.new_tab(url, background)
+
+    async def get(self, url: str, new_tab: bool = False) -> Tab:
+        return await self.context.get(url, new_tab)
+
+    async def new_context(self, *, proxy: str | None = None, locale: str | None = None, timezone: str | None = None) -> Context:
+        """A new isolated identity, gone when closed or when the browser stops."""
+        parsed = Proxy.parse(proxy) if proxy else None
+        relay = await self._relay(parsed) if parsed and parsed.credentials else None
+        config = relay.local if relay else parsed
+        result = await self.connection.send("browser.createUserContext", {"proxy": config.bidi()} if config else {})
+        context = Context(self, result["userContext"])
+        context._relay = relay
+        await context._emulate(locale, timezone)
+        return context
+
+    async def cookies(self, domain: str | None = None) -> list[dict]:
+        return await self.context.cookies(domain)
+
+    async def set_cookies(self, cookies: Iterable[dict]) -> None:
+        await self.context.set_cookies(cookies)
+
+    async def clear_cookies(self) -> None:
+        await self.context.clear_cookies()
+
+    async def on_dialog(self, handler: DialogHandler) -> Callable[[], None]:
+        """Like Tab.on_dialog, for the dialogs of every tab."""
+        return self._dialogs.add(handler)
+
+    async def on(self, event: str, handler: Handler, contexts: list[str] | None = None) -> str:
+        """Subscribe to a BiDi event or module ("network.responseCompleted", "log")."""
+        self.connection.on(event, handler)
+        params: dict = {"events": [event]}
+        if contexts:
+            params["contexts"] = contexts
+        result = await self.connection.send("session.subscribe", params)
+        return result.get("subscription", "")
+
+    async def intercept(self, handler: InterceptHandler, url: str | None = None, phase: Phase = "request") -> Intercept:
+        """Pause matching requests in every tab and pass them to `handler`.
+
+        The handler settles each one with continue_(), abort() or fulfill(); if it doesn't,
+        the next matching intercept gets it, and if none does the request continues untouched.
+        """
+        return await self._network.intercept(handler, url, phase)
+
+    async def block(self, *urls: str, resource_types: Iterable[str] = ()) -> Intercept:
+        """Abort requests matching any URL pattern or resource type ("image", "font", "media", ...)."""
+        return await self._network.block(urls, resource_types)
+
+    async def set_extra_headers(self, headers: dict[str, str]) -> None:
+        """Add headers to every request; an empty dict removes them."""
+        await self._network.set_extra_headers(headers)
+
+    def top_level(self, context: str) -> str:
+        """The tab a browsing context (e.g. an iframe) belongs to."""
+        while context in self._parents:
+            context = self._parents[context]
+        return context
+
+    def user_context_of(self, context: str) -> str:
+        return self._user_contexts.get(context, "default")
+
+    async def _relay(self, proxy: Proxy) -> Relay:
+        """Firefox's way to a proxy with credentials, which it then never has to handle (see Relay)."""
+        relay = await Relay(proxy).start()
+        self._relays.append(relay)
+        return relay
+
+    async def _clear_automation_flag(self) -> None:
+        await self._chrome_eval(CLEAR_AUTOMATION_FLAG)
+
+    @contextlib.asynccontextmanager
+    async def _input_inside_frames(self) -> AsyncIterator[None]:
+        """Mouse input sent to a frame goes straight into its document instead of through the window."""
+        switch = f"Services.prefs.setBoolPref({json.dumps(ROUTED_MOUSE)}, %s)"
+        switched = bool(self.prefs.get(ROUTED_MOUSE)) and await self._chrome_eval(switch % "false")
+        if self.prefs.get(ROUTED_MOUSE) and not switched:
+            log.warning("no access to the browser's scope (it needs stealth=True): mouse input can't go straight into the frame")
+        try:
+            yield
+        finally:
+            if switched:
+                await self._chrome_eval(switch % "true")
+
+    async def _chrome_eval(self, expression: str) -> bool:
+        """Run `expression` in the browser's own scope, which needs the system access stealth mode asks for."""
+        try:
+            tree = await self.connection.send("browsingContext.getTree", {"moz:scope": "chrome", "maxDepth": 0})
+            target = {"context": tree["contexts"][0]["context"]}
+            result = await self.connection.send("script.evaluate", {"expression": expression, "target": target, "awaitPromise": False})
+        except (BidiError, IndexError) as error:
+            log.debug("cannot run in the browser's scope: %s", error)
+            return False
+        return result.get("type") != "exception"
+
+    async def _webdriver_hidden(self, tab: Tab) -> bool:
+        for _ in range(10):  # the flag reaches content processes asynchronously
+            if not await tab.evaluate("navigator.webdriver", isolated=True):
+                return True
+            await asyncio.sleep(0.05)
+        return False
+
+    async def _fit_window(self, tab: Tab) -> None:
+        # Headless Firefox spreads its window over the whole screen, menu bar and dock included, which no
+        # real window does. Place it over the available area instead, like a maximized window.
+        x, y, width, height = await tab.evaluate(
+            "[screen.availLeft, screen.availTop, screen.availWidth, screen.availHeight]", isolated=True
+        )
+        window = (await self.connection.send("browser.getClientWindows"))["clientWindows"][0]["clientWindow"]
+        await self.connection.send(
+            "browser.setClientWindowState",
+            {"clientWindow": window, "state": "normal", "x": x, "y": y, "width": width, "height": height},
+        )
+
+    async def _replace_initial_tab(self) -> Tab:
+        # Firefox focuses the address bar of the startup about:blank tab, so documents loaded there never
+        # get focus (document.hasFocus() stays false). Tabs opened over BiDi get content focus.
+        initial = await self.tabs()
+        tab = await self.new_tab()
+        for old in initial:
+            await old.close()
+        return tab
+
+    async def _track_frames(self) -> None:
+        def created(params: dict) -> None:
+            self._user_contexts[params["context"]] = params.get("userContext", "default")
+            if params.get("parent"):
+                self._parents[params["context"]] = params["parent"]
+
+        def destroyed(params: dict) -> None:
+            self._parents.pop(params["context"], None)
+            self._user_contexts.pop(params["context"], None)
+            for child in params.get("children") or ():
+                destroyed(child)
+
+        self.connection.on("browsingContext.contextCreated", created)
+        self.connection.on("browsingContext.contextDestroyed", destroyed)
+        await self.connection.send(
+            "session.subscribe", {"events": ["browsingContext.contextCreated", "browsingContext.contextDestroyed"]}
+        )
+
+    async def _watch_dialogs_and_downloads(self) -> None:
+        self.connection.on("browsingContext.userPromptOpened", self._dialogs.opened)
+        self.connection.on("browsingContext.downloadWillBegin", self._downloader.begun)
+        self.connection.on("browsingContext.downloadEnd", self._downloader.ended)
+        events = ["browsingContext.userPromptOpened", "browsingContext.downloadWillBegin", "browsingContext.downloadEnd"]
+        await self.connection.send("session.subscribe", {"events": events})
+        if self.downloads:
+            self.downloads.mkdir(parents=True, exist_ok=True)
+            self._downloads_dir = str(self.downloads.resolve())
+        else:
+            self._downloads_dir = tempfile.mkdtemp(prefix="barebidi-downloads-", dir=self._scratch)
+        behavior = {"type": "allowed", "destinationFolder": self._downloads_dir}
+        await self.connection.send("browser.setDownloadBehavior", {"downloadBehavior": behavior})
+
+    async def _launch(self, cmd: list[str], env: dict[str, str]) -> str:
+        """Start Firefox and return its WebDriver BiDi URL."""
+        for attempt in range(2):
+            log.debug("launching %s", cmd)
+            self._process = await asyncio.create_subprocess_exec(
+                *cmd, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, env=env
+            )
+            try:
+                return await asyncio.wait_for(self._read_ws_url(), self.startup_timeout)
+            except _ExitedDuringStartup:
+                # Right after an update Firefox may restart itself to finish it: the copy that carries on
+                # isn't one we can talk to, so close it and start again.
+                await self._kill_strays()
+                if attempt:
+                    raise
+        raise AssertionError("unreachable")
+
+    async def _read_ws_url(self) -> str:
+        assert self._process and self._process.stderr
+        output = []
+        while line := await self._process.stderr.readline():
+            output.append(line)
+            if match := _WS_URL.search(line):
+                return match.group(1).decode()
+        raise _ExitedDuringStartup("Firefox exited during startup:\n" + b"".join(output).decode(errors="replace"))
+
+    async def _kill_strays(self) -> None:
+        """Close every Firefox still running on our profile, such as one that restarted itself."""
+        if not self._profile or sys.platform == "win32":
+            return
+        ours = f"--remote-debugging-port=0 --profile {self._profile}"  # only processes we launched
+        for attempt in range(50):
+            ps = await asyncio.create_subprocess_exec("ps", "-A", "-ww", "-o", "pid=,command=", stdout=subprocess.PIPE)
+            listing = (await ps.communicate())[0].decode(errors="replace")
+            pids = [int(line.split(None, 1)[0]) for line in listing.splitlines() if ours in line]
+            if not pids:
+                return
+            for pid in pids:
+                with contextlib.suppress(ProcessLookupError):
+                    os.kill(pid, signal.SIGKILL if attempt >= 30 else signal.SIGTERM)
+            await asyncio.sleep(0.1)
+
+    async def _drain_stderr(self) -> None:
+        assert self._process and self._process.stderr
+        while line := await self._process.stderr.readline():
+            log.debug("firefox: %s", line.decode(errors="replace").rstrip())
+
+    async def _cleanup(self, grace: float = 10) -> None:
+        if self._process and self._process.returncode is None:
+            try:
+                await asyncio.wait_for(self._process.wait(), grace)
+            except TimeoutError:
+                self._process.kill()
+                await self._process.wait()
+        if self._stderr_task:
+            self._stderr_task.cancel()
+        await self._kill_strays()
+        for relay in self._relays:
+            relay.close()
+        self._relays.clear()
+        if self._profile and self.profile is None:
+            shutil.rmtree(self._profile, ignore_errors=True)
+        if self._downloads_dir and self.downloads is None:
+            shutil.rmtree(self._downloads_dir, ignore_errors=True)
+        self._process = None
+
+
+async def start(**kwargs: Any) -> Browser:
+    return await Browser(**kwargs).start()

barebidi/connection.py

@@ -0,0 +1,123 @@
+import asyncio
+import itertools
+import json
+import logging
+from collections import defaultdict
+from collections.abc import Callable
+from typing import Any
+
+from websockets.asyncio.client import ClientConnection, connect
+from websockets.exceptions import ConnectionClosed
+
+log = logging.getLogger(__name__)
+
+Handler = Callable[[dict], Any]
+
+_GONE = "Firefox closed the connection: it was stopped, exited or crashed"
+
+
+class BidiError(Exception):
+    def __init__(self, error: str, message: str, stacktrace: str | None = None):
+        super().__init__(f"{error}: {message}")
+        self.error = error
+        self.message = message
+        self.stacktrace = stacktrace
+
+
+class BrowserClosedError(ConnectionError):
+    """Firefox is gone: it was stopped, exited or crashed."""
+
+
+class Connection:
+    def __init__(self, ws: ClientConnection, timeout: float | None = None):
+        self._ws = ws
+        self.timeout = timeout  # default seconds to wait for each answer; None waits forever
+        self._ids = itertools.count(1)
+        self._pending: dict[int, asyncio.Future] = {}
+        self._handlers: dict[str, list[Handler]] = defaultdict(list)
+        self._tasks: set[asyncio.Task] = set()
+        self._reader = asyncio.create_task(self._read_loop())
+
+    @classmethod
+    async def connect(cls, url: str, timeout: float | None = None) -> "Connection":
+        return cls(await connect(url, max_size=None), timeout)
+
+    @property
+    def closed(self) -> bool:
+        return self._reader.done()
+
+    async def send(self, method: str, params: dict | None = None, timeout: float | None = None) -> dict:
+        """Send a command and wait for its result, at most `timeout` seconds (by default, the connection's)."""
+        if self.closed:
+            raise BrowserClosedError(_GONE)
+        msg_id = next(self._ids)
+        future = asyncio.get_running_loop().create_future()
+        self._pending[msg_id] = future
+        payload = json.dumps({"id": msg_id, "method": method, "params": params or {}})
+        log.debug("-> %s", payload)
+        timeout = self.timeout if timeout is None else timeout
+        try:
+            try:
+                await self._ws.send(payload)
+            except ConnectionClosed as error:
+                raise BrowserClosedError(_GONE) from error
+            try:
+                return await asyncio.wait_for(future, timeout)
+            except TimeoutError:
+                raise TimeoutError(f"Firefox didn't answer {method} within {timeout}s") from None
+        finally:
+            self._pending.pop(msg_id, None)
+
+    def on(self, event: str, handler: Handler) -> None:
+        """Register a local handler. `event` may be a full name or a module ("network")."""
+        self._handlers[event].append(handler)
+
+    def off(self, event: str, handler: Handler) -> None:
+        if handler in self._handlers.get(event, []):
+            self._handlers[event].remove(handler)
+
+    async def close(self) -> None:
+        await self._ws.close()
+        await asyncio.gather(self._reader, return_exceptions=True)
+
+    async def _read_loop(self) -> None:
+        try:
+            async for raw in self._ws:
+                log.debug("<- %s", raw)
+                msg = json.loads(raw)
+                if msg.get("type") == "event":
+                    self._dispatch(msg["method"], msg.get("params", {}))
+                else:
+                    self._resolve(msg)
+        except ConnectionClosed:
+            pass
+        finally:
+            for future in self._pending.values():
+                if not future.done():
+                    future.set_exception(BrowserClosedError(_GONE))
+
+    def _resolve(self, msg: dict) -> None:
+        future = self._pending.get(msg.get("id"))
+        if future is None:
+            if msg.get("type") == "error":
+                log.warning("unmatched error: %s", msg)
+            return
+        if future.done():
+            return
+        if msg.get("type") == "error":
+            future.set_exception(BidiError(msg["error"], msg.get("message", ""), msg.get("stacktrace")))
+        else:
+            future.set_result(msg.get("result", {}))
+
+    def _dispatch(self, method: str, params: dict) -> None:
+        module = method.split(".", 1)[0]
+        for handler in [*self._handlers.get(method, ()), *self._handlers.get(module, ())]:
+            try:
+                result = handler(params)
+            except Exception:
+                log.exception("event handler for %s failed", method)
+                continue
+            if asyncio.iscoroutine(result):
+                task = asyncio.create_task(result)
+                self._tasks.add(task)
+                task.add_done_callback(self._tasks.discard)