spoke-connect (Python)

PyPI package spoke-connect: SPOKE Connect session-core bindings (generated uniffi Python + native spoke_connect / libspoke_connect).

Packaging contract: connect-binding-channels.md §3.3.

Install

At spoke lockstep tag vX.Y.Z:

pip install spoke-connect==X.Y.Z

Platform wheels (py3-none-<platform>) ship for manylinux_2_35_x86_64, macosx_11_0_arm64, and win_amd64. Each wheel bundles that platform's shared library beside the spoke_connect module (uniffi ctypes loader contract). Version locksteps with the spoke monorepo SemVer / git tag vX.Y.Z.

Release publishes via Trusted Publishing on the top-level release.yml workflow (publish-pypi job, OIDC). The PyPI Pending publisher for spoke-connect binds repository 42ch-dev/spoke to that workflow filename; the first successful stable-tag publish activates the project on PyPI.

Usage

import spoke_connect

peer_id = spoke_connect.derive_peer_id_from_ed25519_pubkey(pubkey)
protocol = spoke_connect.protocol_version()  # 1

Transport / WebSocket stays in the host product.

Build features

ffi-smoke-host is non-default and is not implied by remote-adapter or ffi. Full loopback smoke procedure: Smoke/README.md.

RemoteAdapter FFI surface

With remote-adapter enabled, the binding ships the additive remote-adapter surface: RemoteAdapterFFI (single peer), MultiPeerRouterFFI (multi-peer routing), the callback Transport interface, the in-memory loopback helpers, and the tool faces — invoke_tool on the adapter, router, and responder, register_tool_handler on the adapter and responder, the ToolHandler callback, and connect_responder_ffi / ConnectResponderFFI for the accept side. The optional-port dialer ops (project / compute / list_fork_timeline_events on RemoteAdapterFFI) and the responder ports face (PortsHandler + the optional ports: constructor parameter) ride the same session invoke path.

Transport contract

The callback Transport is a message-oriented interface: one envelope per call, blocking receive, idempotent close.

The surface bounds messages at one envelope per call; byte-stream carriers apply length-prefix (or equivalent) delimiting before handing envelopes to the adapter.

MultiPeerRouterFFI

new_multi_peer_router_ffi() returns the router as a synchronous object over the same runtime: a peer registry (register_peer(adapter) accepts an established RemoteAdapterFFI and returns its peer_id; unregister_peer(peer_id); list_peers()), the BaselinePorts six families routed per call to exactly one capable peer, and the two HostManifestPort aggregation views — the composed get_host_capability_manifest() and the per-peer list_peer_host_capability_manifests(). Selection matches each registered peer's cached HostCapabilityManifest: required capability, exact namespace, soft role preference, and a deterministic lowest-peer_id tie-break.

Tool faces

• invoke_tool(capability_id, arguments_json) — invoke a tool on the peer (dialer → responder, responder → dialer, or router → capable peer); returns the tool's result as a JSON string. A non-tools. id or malformed arguments rejects INVALID_INPUT with zero wire traffic; a dispatch deny rejects CAPABILITY_PORT_MISSING with the peer's preserved wire_code.
• register_tool_handler(capability_id, handler) — serve reverse invokes through a foreign ToolHandler; last-wins per id, never mutates the manifest. The callback's handle(arguments_json) returns the result JSON; a raised FfiError.Rejected passes through verbatim as an application reject, any other outcome is contained to INTERNAL_ERROR and the session survives.
• connect_responder_ffi(...) / ConnectResponderFFI — the accept side: wrap a connected (host-accepted) callback Transport. The constructor returns immediately in Handshaking — poll state() (bounded) to Established before invoking; a handshake failure surfaces as state() → "Closed" (never a thrown constructor error), config-validation failures return Dial { kind: "config" }.
• Handlers run on the FFI blocking pool — do not synchronously call back into the FFI faces from handle; hand off asynchronously in the host instead.

Responder ports serving face (PortsHandler)

The optional ports: constructor parameter (between peer_keys and invoke_timeout_ms) serves every declared port.* family through a foreign PortsHandler callback: the nine baseline serve ops (get_knowledge_entry / put_knowledge_entry / get_relation / put_relation / list_knowledge_entries / list_timeline_events / put_findings / list_rules / list_peer_host_capability_manifests) plus the three optional ops (project / compute / list_fork_timeline_events) — every method returns the op's result as a JSON string. Passing nothing keeps the documented absent-ports behavior: the constructor is still valid and every port.* op answers the default deny branch (CAPABILITY_PORT_MISSING with the peer's preserved op_unsupported wire code). Optional ops are capability-gated like the baseline rows: a session whose negotiated capabilities lack l2-computable / l5-fork denies at the responder's dispatch gate with the same deny row.

Callback outcomes map strictly: FfiError.Rejected passes through verbatim as an application reject (kind re-hung onto details); a foreign exception, Dial, or panic is contained to INTERNAL_ERROR with details: None and the session survives. The ports callbacks behave like tool handlers — demand-driven, one blocking-pool thread per in-flight callback — so the same rules apply: never call back into the FFI surface from inside a ports callback (hand off asynchronously in the host instead), and size the host accordingly (one blocking-pool thread per transport end; ~256 full-duplex sessions at the tokio default cap). The dialer optional ops (project / compute / list_fork_timeline_events on RemoteAdapterFFI) reject malformed JSON locally with INVALID_INPUT and zero wire traffic.

Layout

Maintainer: regenerate → stage native → wheel → smoke

Commands from the repository root (local nightly convention for cargo: cargo +nightly …).

Production regenerate uses ffi,remote-adapter only (no ffi-smoke-host). Full loopback smoke recipe: Smoke/README.md.

# 1. Build the production ffi cdylib (must run before generate — default build replaces the stub)
cargo +nightly build -p spoke-connect --features ffi,remote-adapter --release

# 2. Generate bindings (first-party uniffi 0.32)
cargo +nightly run -p spoke-connect --features ffi,bindgen-cli,remote-adapter --bin uniffi-bindgen -- \
  generate --library target/release/libspoke_connect.dylib \
  --language python --out-dir crates/spoke-connect/bindings/python/spoke_connect
mv crates/spoke-connect/bindings/python/spoke_connect/spoke_connect.py \
   crates/spoke-connect/bindings/python/spoke_connect/__init__.py

# 3. Stage host native beside the module (darwin arm64 example)
cp target/release/libspoke_connect.dylib \
  crates/spoke-connect/bindings/python/spoke_connect/
install_name_tool -id @rpath/libspoke_connect.dylib \
  crates/spoke-connect/bindings/python/spoke_connect/libspoke_connect.dylib

# 4. Golden-parity smoke (no wheel required)
PYTHONPATH=crates/spoke-connect/bindings/python \
  python3 -m unittest discover -s crates/spoke-connect/bindings/python/Smoke -v

# 5. Build platform wheel (host RID or CI artifact — recipe: tooling/connect/build-python-wheel.sh)
./tooling/connect/build-python-wheel.sh

# Release: all three wheels from build-connect-ffi artifacts
./tooling/connect/build-python-wheels-from-ffi.sh ffi-assembled

v1 publishes platform wheels only (no sdist): a source install cannot produce the native library without a Rust toolchain.

Committed natives (in-tree smoke)

Reference

• Wheel recipe: tooling/connect/build-python-wheel.sh
• Release wheels (all RIDs): tooling/connect/build-python-wheels-from-ffi.sh
• Pre-publish inventory gate: tooling/connect/verify-python-wheels.sh
• FFI surface: ../../src/ffi.rs
• Publish strategy: connect-publish-strategy.md