{"id":31702166,"url":"https://github.com/abilian/py-capnweb","last_synced_at":"2026-01-20T17:01:00.816Z","repository":{"id":317607288,"uuid":"1067408678","full_name":"abilian/py-capnweb","owner":"abilian","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-24T22:01:01.000Z","size":1325,"stargazers_count":33,"open_issues_count":5,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-28T06:47:31.725Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abilian.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-30T20:19:00.000Z","updated_at":"2025-11-19T13:18:18.000Z","dependencies_parsed_at":"2025-10-23T11:18:04.038Z","dependency_job_id":"e7c37c6c-a441-4d1f-b386-db59d18d5ec5","html_url":"https://github.com/abilian/py-capnweb","commit_stats":null,"previous_names":["abilian/py-capnweb"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/abilian/py-capnweb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fpy-capnweb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fpy-capnweb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fpy-capnweb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fpy-capnweb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abilian","download_url":"https://codeload.github.com/abilian/py-capnweb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fpy-capnweb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28607624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-08T21:12:11.868Z","updated_at":"2026-01-20T17:01:00.802Z","avatar_url":"https://github.com/abilian.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cap'n Web Python\n\nA complete Python implementation of the [Cap'n Web protocol](https://github.com/cloudflare/capnweb) - a capability-based RPC system with promise pipelining, structured errors, and multiple transport support.\n\n## What's in the Box\n\n**Core Features:**\n- **Capability-based security** - Unforgeable object references with explicit disposal\n- **Promise pipelining** - Batch multiple dependent calls into single round-trips\n- **Multiple transports** - HTTP Batch, WebSocket, and WebTransport/HTTP/3\n- **Type-safe** - Full type hints compatible with pyright/mypy\n- **Async/await** - Built on Python's asyncio\n- **Bidirectional RPC** - Peer-to-peer capability passing\n- **100% Interoperable** - Fully compatible with TypeScript reference implementation\n\n**Beta-Testing-Ready\":**\n- 352 tests passing, 76% coverage\n- 0 linting errors, 0 typing errors\n- Hook-based architecture (clean, maintainable)\n- ~99% protocol compliance\n\n## Why Use Cap'n Web?\n\n**Traditional RPC has problems:**\n- No security model (anyone can call anything)\n- No resource management (memory leaks)\n- Poor performance (round-trip per call)\n\n**Cap'n Web solves these:**\n- **Security**: Capabilities are unforgeable - you can only call what you have a reference to\n- **Resource Management**: Explicit disposal with reference counting prevents leaks\n- **Performance**: Promise pipelining batches dependent calls into one round-trip\n- **Flexibility**: Pass capabilities as arguments - the server decides who gets access\n\n## Installation\n\n```bash\npip install capnweb\n# or\nuv add capnweb\n\n# For WebTransport support (optional):\npip install capnweb[webtransport]\n```\n\n## Quick Start\n\n**Server:**\n```python\nfrom capnweb.server import Server, ServerConfig\nfrom capnweb.types import RpcTarget\nfrom capnweb.error import RpcError\n\nclass Calculator(RpcTarget):\n    async def call(self, method: str, args: list) -\u003e any:\n        match method:\n            case \"add\": return args[0] + args[1]\n            case \"multiply\": return args[0] * args[1]\n            case _: raise RpcError.not_found(f\"Unknown method: {method}\")\n\n    async def get_property(self, property: str) -\u003e any:\n        raise RpcError.not_found(\"No properties\")\n\nasync def main():\n    server = Server(ServerConfig(host=\"127.0.0.1\", port=8080))\n    server.register_capability(0, Calculator())\n    await server.start()\n    await asyncio.Event().wait()  # Run forever\n```\n\n**Client:**\n```python\nfrom capnweb.client import Client, ClientConfig\n\nasync with Client(ClientConfig(url=\"http://localhost:8080/rpc/batch\")) as client:\n    result = await client.call(0, \"add\", [5, 3])\n    print(f\"5 + 3 = {result}\")  # Output: 8\n```\n\n**Promise Pipelining** (advanced):\n```python\nasync with Client(config) as client:\n    batch = client.pipeline()\n\n    # These calls are batched into a single HTTP request!\n    user = batch.call(0, \"getUser\", [\"alice\"])\n    profile = batch.call(0, \"getProfile\", [user.id])  # Property access on promise!\n    posts = batch.call(0, \"getPosts\", [user.id])\n\n    u, p, posts_data = await asyncio.gather(user, profile, posts)\n```\n\n## Current Status (v0.4.0)\n\n**Transports:**\n- ✅ HTTP Batch\n- ⚠️ WebSocket (partial support - client→server RPC only, bidirectional RPC in progress)\n- ✅ WebTransport/HTTP/3 (requires aioquic)\n\n**Protocol Features:**\n- ✅ Wire protocol (all message types)\n- ✅ Promise pipelining\n- ✅ Expression evaluation (including `.map()`)\n- ⚠️ Bidirectional RPC (HTTP Batch only, WebSocket support in progress)\n- ✅ Resume tokens\n- ✅ Reference counting\n- ✅ Structured errors\n- ⚠️ IL plan execution (only remap supported, full IL is low priority)\n\n**Code Quality:**\n- ✅ 352 tests passing (100% success rate)\n- ✅ 76% test coverage\n- ✅ 0 linting errors (ruff)\n- ✅ 0 typing errors (pyrefly)\n- ✅ TypeScript interoperability verified\n\n## Documentation\n\n- **[Quickstart Guide](docs/quickstart.md)** - Get started in 5 minutes\n- **[API Reference](docs/api-reference.md)** - Complete API documentation\n- **[Architecture Guide](docs/architecture.md)** - Understand the internals\n- **[Examples](examples/)** - Working code examples\n\n## Examples\n\n**Included examples:**\n- `examples/calculator/` - Simple RPC calculator\n- `examples/batch-pipelining/` - Promise pipelining demonstration\n- `examples/peer_to_peer/` - Bidirectional RPC (Alice \u0026 Bob) - HTTP Batch only\n- `examples/chat/` - ⚠️ Real-time WebSocket chat (requires bidirectional WebSocket - in progress)\n- `examples/microservices/` - Service mesh architecture\n- `examples/actor-system/` - Distributed actor system with supervisor/worker\n- `examples/webtransport/` - WebTransport/HTTP/3 standalone demo\n- `examples/webtransport-integrated/` - WebTransport with full RPC\n\nEach example includes a README with running instructions.\n\n## Transport Limitations\n\n**Current WebSocket Support:**\n- ✅ Client can connect to server via `ws://` or `wss://` URLs\n- ✅ Client can call server methods (request-response RPC)\n- ✅ Server can respond to client requests\n- ❌ Server **cannot** initiate calls to clients (no bidirectional RPC yet)\n- ❌ Chat example currently non-functional due to this limitation\n\n**Workaround for bidirectional RPC:**\nUse HTTP Batch transport instead - it supports full bidirectional RPC including:\n- Passing client capabilities to server\n- Server calling methods on client capabilities\n- See `examples/peer_to_peer/` for working bidirectional RPC example\n\n**WebTransport:**\n- Full bidirectional support\n- Requires `aioquic` library: `pip install capnweb[webtransport]`\n\n## Development\n\n```bash\n# Clone and install\ngit clone https://github.com/abilian/py-capnweb.git\ncd py-capnweb\nuv sync\n\n# Run tests\npytest\n# or\nmake test\n\n# Run linting \u0026 type checking\nruff check\npyrefly check\n# or\nmake check\n\n# Run with coverage\npytest --cov=capnweb --cov-report=term-missing\n```\n\n## Protocol Compliance\n\nThis implementation follows the [Cap'n Web protocol specification](https://github.com/cloudflare/capnweb/blob/main/protocol.md).\n\n**Interoperability Testing:**\nCross-implementation testing with TypeScript reference validates all combinations:\n- Python Server ↔ Python Client ✅\n- Python Server ↔ TypeScript Client ✅\n- TypeScript Server ↔ Python Client ✅\n- TypeScript Server ↔ TypeScript Client ✅\n\nRun interop tests: `cd interop \u0026\u0026 bash run_tests.sh`\n\n## What's New\n\nSee [CHANGES.md](CHANGES.md) for detailed release notes.\n\n**v0.4.0** (latest):\n- WebTransport/HTTP/3 support with certificate management\n- Actor system example with distributed capabilities\n- \"Perfect\" code quality (0 linting errors, 0 typing errors)\n- 352 tests passing\n\n**v0.3.1**:\n- Comprehensive documentation (quickstart, architecture, API reference)\n- 85% test coverage (up from 67%)\n- Legacy code removed (clean hook-based architecture)\n\n**v0.3.0**:\n- Promise pipelining support\n- 100% TypeScript interoperability\n- Array escaping for compatibility\n\n## License\n\nDual-licensed under MIT or Apache-2.0, at your option.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabilian%2Fpy-capnweb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabilian%2Fpy-capnweb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabilian%2Fpy-capnweb/lists"}