Vendoring chattolib

This plugin ships a vendored copy of chattolib and all its dependencies in vendor/. Nothing has to be installed separately — the plugin brings its own dependency tree.

Why Vendoring?

No dependencies to install: hermes plugin install works immediately
No lazy-import complexity: no ensure() or lazy_import mechanisms
Isolated: the vendored copy cannot conflict with a system-installed one
Offline-friendly: works in air-gapped environments

Layout

Two of the vendored packages contain compiled extension modules and are therefore platform-specific: protobuf (its google/_upb runtime) and websockets (its speedups mask helper). Everything else is pure Python. The tree is split accordingly, so the shared part is stored once:

vendor/
├── __init__.py
├── common/                    # pure-Python packages (5.8 MB), all platforms
│   ├── chattolib/
│   ├── httpx/ httpcore/ h11/ anyio/ idna/ certifi/
│   └── typing_extensions.py
└── platform/                  # compiled extensions, 2.3–3.9 MB per platform
    ├── linux-x86_64/          #   google/ websockets/
    ├── linux-aarch64/
    └── macos-arm64/

Total: 14.4 MB on disk (~9.6 MB tracked by git, the .so files compress well).

vendor_path.py derives the platform tag from platform.system() / platform.machine() at import time and puts both directories on sys.path. Both adapter.py and platform_config.py call setup_vendor_path() before importing anything from chattolib.

sys.path order — and why it differs per directory

Directory	Position	Why
`platform/<tag>`	prepended	The compiled extensions must match the vendored chattolib. A host copy of `protobuf` at a different version would break the generated `_pb` code.
`common`	appended	The Hermes agent ships most of this itself — `httpx` (same pin, 0.28.1), `certifi`, `anyio`, `httpcore`, `h11`, `idna`, `typing_extensions`. A plugin must not shadow the host's pinned versions; Hermes pins `certifi` exactly, and prepending would substitute our CA bundle process-wide.

So the host's pure-Python packages win, and our copies act as a fallback — which keeps out-of-process use (the cron sender, hermes_standalone_sender_fn) working in an environment without Hermes.

Note that Hermes' pins drift from ours (anyio 4.12.1 vs 4.15.1, idna 3.18 vs 3.20, certifi 2026.5.20 vs 2026.7.22) — the append order is exactly what keeps those differences harmless.

The packages Hermes does not provide — chattolib and the compiled protobuf/websockets — always come from vendor/.

The rest (httpx, httpcore, h11, anyio, idna, certifi, typing_extensions, ~4.2 MB) Hermes does provide, so it is fair to ask why they are vendored at all. Because of the cron sender: hermes_standalone_sender_fn delivers scheduled messages out of process, in no Hermes venv, and there vendor/common is the only thing on sys.path. The append order means those copies are inert wherever Hermes runs and load-bearing where it does not.

chattolib requires httpx>=0.27, protobuf>=5.28 and (via the [realtime] extra) websockets>=13.0. Two of those floors are worth knowing about: protobuf>=5.28 is wrong in practice — chattolib b13 ships gencode 7.35.1, and protobuf ≥ 5.27 refuses at import time to load gencode newer than its own runtime, so a host protobuf older than 7.35.1 raises VersionError rather than degrading. And if a future Hermes release pins httpx below 0.27, the appended fallback no longer helps — the host copy would be found first and be too old.

If the current platform was not vendored, the import fails with an explicit message naming the available platforms — rather than a cryptic dlopen error about an invalid Mach-O/ELF file.

Updating or rebuilding

# Default platform set: linux-x86_64, linux-aarch64, macos-arm64
./vendor_chattolib.sh

# A single platform
PLATFORMS="linux-x86_64" ./vendor_chattolib.sh

# Add another one (see the table below for valid tags)
PLATFORMS="linux-x86_64 linux-aarch64 macos-arm64 windows-amd64" ./vendor_chattolib.sh

# Pin a specific chattolib version (keep the [realtime] extra — without it
# websockets is not vendored and the event stream cannot start)
CHATTOLIB_SPEC="chattolib[realtime]==0.5.0b13" ./vendor_chattolib.sh

The script passes --only-binary :all: --no-binary chattolib. Everything must come as a prebuilt wheel, because a source distribution of pyqwest, protobuf or websockets could not be built for a foreign platform — uv would build it for the host and silently drop host-architecture binaries into vendor/platform/<other-tag>/. chattolib itself is the documented exception: it is pure Python, so building it from an sdist yields identical, platform-independent files on any host. That exception is load-bearing, not cosmetic — upstream stopped publishing wheels after 0.5.0b4, so without it the resolver falls back to b4 and a refresh silently changes nothing.

The script wipes vendor/, installs the dependency tree once per platform via uv pip install --python-platform …, splits the result with vendor_split.py, and verifies that import chattolib works on the machine you ran it on. Afterwards: git add vendor/.

Supported platform tags

Tag	uv `--python-platform`	vendored by default
`linux-x86_64`	`x86_64-unknown-linux-gnu`	✅
`linux-aarch64`	`aarch64-unknown-linux-gnu`	✅
`macos-arm64`	`aarch64-apple-darwin`	✅
`linux-x86_64-musl`	`x86_64-unknown-linux-musl`	—
`linux-aarch64-musl`	`aarch64-unknown-linux-musl`	—
`macos-x86_64`	`x86_64-apple-darwin`	—
`windows-amd64`	`x86_64-pc-windows-msvc`	—

All seven are available as binary wheels upstream; only the default three are committed, to keep the repository at a reasonable size (14.4 MB for vendor/).

Python versions

The script resolves wheels for Python 3.11 (PYTHON_VERSION), which is the project minimum. What that buys differs per package, and the difference matters:

Package	Tag at 3.11	Consequence
`protobuf`	`abi3` (`_message.abi3.so`)	Stable ABI, forward compatible — one build covers 3.11 through 3.15.
`websockets`	`cp311` (`speedups.cpython-311-…so`)	Version-specific.

So on Python 3.12+ the protobuf runtime still loads, and chattolib imports fine — but websockets.speedups is not importable and websockets silently falls back to its pure-Python apply_mask (it wraps the import in try: … except ImportError:). Verified on 3.12 and 3.14: chattolib and its realtime module import, apply_mask resolves to websockets.utils.

That is a performance fallback, not a breakage — masking is a small part of frame handling. It is the price for keeping one build instead of one per minor version, and the reason PYTHON_VERSION must stay at the project minimum: raising it would pull cp312-…-style wheels and make the whole tree version-specific.

If you raise PYTHON_VERSION, check the resulting .so names. *.abi3.so for protobuf; anything under websockets/ is tied to that exact CPython minor version regardless.

Development without vendoring

pip install chattolib

A system-installed chattolib is only used if vendor/ is absent — the vendored copy is deliberately prepended to sys.path and therefore wins. Keep the installed version in step with vendor/common/chattolib-*.dist-info/, or tests will pass against one chattolib while the plugin ships another.

License

The vendored chattolib is licensed under MPL-2.0 + Apache-2.0 (see vendor/common/chattolib-*.dist-info/). Upstream source: https://github.com/chattocorp/chatto

VENDORING.md 8.0 KB Historie Surový