meshcall 0.1.0__tar.gz

meshcall-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.DS_Store
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+*.py[cod]
+build/
+dist/
+node_modules/
+.yarn/
+generated/
+meshcall-router/bin/
+.conformance-*.log
+dist-npm/

meshcall-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 t4wefan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

meshcall-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.5
+Name: meshcall
+Version: 0.1.0
+Summary: Async typed RPC for Python services: WebSocket direct or through the MeshCall Router
+Project-URL: Homepage, https://github.com/t4wefan/meshcall
+Project-URL: Changelog, https://github.com/t4wefan/meshcall/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/t4wefan/meshcall/issues
+Author: t4wefan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,pydantic,router,rpc,streaming,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic>=2.11
+Requires-Dist: websockets>=16.1
+Description-Content-Type: text/markdown
+
+# meshcall-py
+
+The Python runtime and code-generation package for the MeshCall monorepo.
+Its import name is `meshcall`.
+
+```bash
+go -C ../meshcall-router build -o bin/meshcall-router ./cmd/meshcall-router
+uv sync
+uv run pytest -q
+uv build
+```
+
+The monorepo-level runnable examples are in `../demo`. See the repository root
+README for the complete Python/TypeScript workflow.
+
+`WebSocketRouter` launches the standalone Go executable. It supports
+`binary_path`, `auth_file`, readiness timeouts, `pid`, `is_running`,
+`wait_closed()`, and async context management. A prebuilt binary can also be
+selected with `MESHCALL_ROUTER_BINARY`; running it requires no Go compiler.
+
+Pass `RouterCredentials(username=..., password=...)` or
+`RouterCredentials(token=...)` as `auth` to a WebSocket client or Router server
+driver. `RouterAuthClient` provides `whoami()`, `issue_token(scopes=..., ...)`,
+and `revoke_token(...)`. Use `RouterScope(service=..., methods=[...])` to limit
+a token, or `register_service=True` for temporary service instances.
+See [Router authentication and management](../docs/router.md).

meshcall-0.1.0/README.md

@@ -0,0 +1,26 @@
+# meshcall-py
+
+The Python runtime and code-generation package for the MeshCall monorepo.
+Its import name is `meshcall`.
+
+```bash
+go -C ../meshcall-router build -o bin/meshcall-router ./cmd/meshcall-router
+uv sync
+uv run pytest -q
+uv build
+```
+
+The monorepo-level runnable examples are in `../demo`. See the repository root
+README for the complete Python/TypeScript workflow.
+
+`WebSocketRouter` launches the standalone Go executable. It supports
+`binary_path`, `auth_file`, readiness timeouts, `pid`, `is_running`,
+`wait_closed()`, and async context management. A prebuilt binary can also be
+selected with `MESHCALL_ROUTER_BINARY`; running it requires no Go compiler.
+
+Pass `RouterCredentials(username=..., password=...)` or
+`RouterCredentials(token=...)` as `auth` to a WebSocket client or Router server
+driver. `RouterAuthClient` provides `whoami()`, `issue_token(scopes=..., ...)`,
+and `revoke_token(...)`. Use `RouterScope(service=..., methods=[...])` to limit
+a token, or `register_service=True` for temporary service instances.
+See [Router authentication and management](../docs/router.md).

meshcall-0.1.0/conformance/fixture.py

@@ -0,0 +1,166 @@
+"""Reference Python fixture for the conformance suite (see conformance/FIXTURE.md)."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+from collections.abc import AsyncIterator
+from typing import cast
+
+from pydantic import BaseModel
+
+from meshcall import RpcContext, RpcInputStream, RpcServer, method, service
+from meshcall.drivers import WebSocketRouterServerDriver
+from meshcall.errors import MeshCallError
+
+
+class Echo(BaseModel):
+    value: int
+    text: str
+
+
+class Tag(BaseModel):
+    tag: str
+
+
+class Tags(BaseModel):
+    tags: list[str]
+
+
+class Index(BaseModel):
+    index: int
+
+
+class Value(BaseModel):
+    value: int
+
+
+class Total(BaseModel):
+    total: int
+
+
+class Metadata(BaseModel):
+    metadata: dict[str, str]
+
+
+class Ok(BaseModel):
+    ok: bool = True
+
+
+class Instance(BaseModel):
+    instance: str
+
+
+@service("conformance.v1.Targeted", targeted=True)
+class Targeted:
+    """A targeted service: every call must name the instance it is for."""
+
+    @method(read_only=True)
+    async def whoami(self, ctx: RpcContext) -> Instance:
+        """Return the id of the instance that served the call."""
+        return Instance(instance=ctx.instance_id)
+
+
+@service("conformance.v1.Fixture")
+class Fixture:
+    """Deterministic behaviours the conformance suite drives through the Router."""
+
+    def __init__(self) -> None:
+        self.cancelled: list[str] = []
+        self.invoked: list[str] = []
+        self.server: RpcServer | None = None
+
+    @method(read_only=True)
+    async def echo(self, value: int, text: str) -> Echo:
+        """Return the input unchanged."""
+        return Echo(value=value, text=text)
+
+    @method(idempotent=True)
+    async def fail(self, code: str, message: str, retryable: bool = False) -> Ok:
+        """Raise an application error with the given code."""
+        raise MeshCallError(code, message, retryable=retryable, details={"from": "fixture"})
+
+    @method(read_only=True)
+    async def bad_response(self) -> Ok:
+        """Return a response that breaks this method's own contract."""
+        return cast(Ok, {"ok": "not-a-bool"})
+
+    @method(idempotent=True)
+    async def slow(self, ms: int, tag: str = "") -> Tag:
+        """Sleep ``ms`` milliseconds; record ``tag`` if cancelled meanwhile."""
+        self.invoked.append(tag)
+        try:
+            await asyncio.sleep(ms / 1000)
+        except asyncio.CancelledError:
+            self.cancelled.append(tag)
+            raise
+        return Tag(tag=tag)
+
+    @method(read_only=True)
+    async def cancelled_tags(self) -> Tags:
+        """Tags of slow calls that observed cancellation."""
+        return Tags(tags=list(self.cancelled))
+
+    @method(read_only=True)
+    async def invoked_tags(self) -> Tags:
+        """Tags of every slow call that started, in order."""
+        return Tags(tags=list(self.invoked))
+
+    @method.server_stream(read_only=True)
+    async def count(self, n: int, gap_ms: int = 0) -> AsyncIterator[Index]:
+        """Yield 0..n-1 with ``gap_ms`` between items."""
+        for index in range(n):
+            if gap_ms:
+                await asyncio.sleep(gap_ms / 1000)
+            yield Index(index=index)
+
+    @method.client_stream(idempotent=True)
+    async def sum(self, items: RpcInputStream[Value], offset: int = 0) -> Total:
+        """Add every streamed value to ``offset``."""
+        total = offset
+        async for item in items:
+            total += item.value
+        return Total(total=total)
+
+    @method(read_only=True)
+    async def metadata_echo(self, ctx: RpcContext) -> Metadata:
+        """Return the call metadata and set trailers describing it."""
+        ctx.set_trailer("echoed", "yes")
+        ctx.set_trailer("count", str(len(ctx.metadata)))
+        return Metadata(metadata=dict(ctx.metadata))
+
+    @method(destructive=True)
+    async def drain_self(self, delay_ms: int = 0) -> Ok:
+        """Drain and stop this instance after ``delay_ms``."""
+
+        async def later() -> None:
+            await asyncio.sleep(delay_ms / 1000)
+            assert self.server is not None
+            await self.server.stop(drain=True, drain_timeout=30)
+
+        asyncio.get_running_loop().create_task(later())
+        return Ok()
+
+
+async def main() -> None:
+    fixture = Fixture()
+    ping = float(os.environ.get("MESHCALL_PING_INTERVAL_MS", "15000")) / 1000
+    server = RpcServer(
+        services=[fixture, Targeted],
+        driver=WebSocketRouterServerDriver(
+            os.environ["MESHCALL_ROUTER_URL"],
+            instance_id=os.environ.get("MESHCALL_CONFORMANCE_INSTANCE", "fixture-1"),
+            ping_interval=ping,
+            ping_timeout=max(1.0, ping * 2),
+        ),
+        access_log=False,
+    )
+    fixture.server = server
+    await server.start()
+    print("fixture registered", file=sys.stderr, flush=True)
+    await server.wait_closed()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

meshcall-0.1.0/hatch_build.py

@@ -0,0 +1,44 @@
+"""Bundle the Go binaries into platform wheels.
+
+Release builds set MESHCALL_BUNDLE_DIR to a directory holding `meshcall-router`
+and `meshcall` (`.exe` on Windows) for one platform and MESHCALL_WHEEL_TAG to
+that platform's wheel tag (e.g. `manylinux_2_17_x86_64.manylinux2014_x86_64`,
+`macosx_11_0_arm64`, `win_amd64`). The binaries land in `meshcall/bin/`, which
+is the first place `meshcall.router_install` looks. Without the variables the
+build is the ordinary pure wheel, and the runtime falls back to downloading
+the release on first use.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class BundleBinaries(BuildHookInterface):
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        if self.target_name != "wheel":
+            return
+        bundle = os.environ.get("MESHCALL_BUNDLE_DIR")
+        tag = os.environ.get("MESHCALL_WHEEL_TAG")
+        if not bundle and not tag:
+            return
+        if not (bundle and tag):
+            raise RuntimeError("set both MESHCALL_BUNDLE_DIR and MESHCALL_WHEEL_TAG")
+        source = Path(bundle)
+        found = 0
+        for name in ("meshcall-router", "meshcall", "meshcall-router.exe", "meshcall.exe"):
+            binary = source / name
+            if binary.is_file():
+                build_data["force_include"][str(binary)] = f"meshcall/bin/{name}"
+                found += 1
+        if found < 2:
+            raise RuntimeError(f"{source} must contain meshcall-router and meshcall")
+        build_data["pure_python"] = False
+        build_data["infer_tag"] = False
+        build_data["tag"] = f"py3-none-{tag}"

meshcall-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "meshcall"
+version = "0.1.0"
+description = "Async typed RPC for Python services: WebSocket direct or through the MeshCall Router"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "t4wefan" }]
+requires-python = ">=3.11"
+keywords = ["rpc", "websocket", "asyncio", "pydantic", "streaming", "router"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Framework :: Pydantic :: 2",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Networking",
+    "Typing :: Typed",
+]
+dependencies = [
+    "loguru>=0.7.3",
+    "pydantic>=2.11",
+    "websockets>=16.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/t4wefan/meshcall"
+Changelog = "https://github.com/t4wefan/meshcall/blob/main/CHANGELOG.md"
+Issues = "https://github.com/t4wefan/meshcall/issues"
+
+[project.scripts]
+meshcall = "meshcall.launcher:main"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.411",
+    "pytest>=8.3",
+    "pytest-asyncio>=0.26",
+    "ruff>=0.16.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel.hooks.custom]
+# Platform wheels carry the Go binaries; see hatch_build.py.
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.sdist]
+exclude = ["src/meshcall/bin"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+# Test fixtures are deliberately terse; test_diagnostics asserts the warnings.
+filterwarnings = ["ignore::meshcall.diagnostics.MeshCallWarning"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.pyright]
+extraPaths = [
+    "..",
+    "../demo/quickstart/src",
+    "../demo/py2ts/src",
+    "../demo/showcase/src",
+    "../demo/router/src",
+    "../demo/ts2py/src",
+    "../demo/ts2py/py-client/src",
+]

meshcall-0.1.0/src/meshcall/__init__.py

@@ -0,0 +1,112 @@
+from meshcall.client import ClientBase
+from meshcall.context import (
+    CallOptions,
+    ClientCallInfo,
+    ClientCallNext,
+    ClientInterceptor,
+    ReconnectPolicy,
+    RetryPolicy,
+    RpcContext,
+    ServerCallNext,
+    ServerInterceptor,
+)
+from meshcall.contract import (
+    Balance,
+    get_service_contract,
+    get_service_method_binding,
+    get_service_warnings,
+    method,
+    service,
+)
+from meshcall.contract_io import load_contract, render_contract, write_contract
+from meshcall.diagnostics import ContractWarning, MeshCallWarning, lint_contract
+from meshcall.errors import (
+    CallCancelledError,
+    ContractError,
+    DeadlineExceededError,
+    ErrorCode,
+    InternalError,
+    InvalidArgumentError,
+    MeshCallError,
+    MethodNotFoundError,
+    PermissionDeniedError,
+    ProtocolError,
+    ResourceExhaustedError,
+    UnauthenticatedError,
+    UnavailableError,
+    Violation,
+)
+from meshcall.ir import (
+    BalanceKind,
+    BalancePolicy,
+    BindingKind,
+    MethodAnnotations,
+    StreamKind,
+)
+from meshcall.logging import RpcLogger
+from meshcall.router import WebSocketRouter
+from meshcall.router_auth import (
+    IssuedToken,
+    RouterAuthClient,
+    RouterCredentials,
+    RouterIdentity,
+    RouterScope,
+)
+from meshcall.server import RpcServer
+from meshcall.streams import RpcDuplex, RpcDuplexClient, RpcInputStream, RpcServerStream
+
+__all__ = [
+    "Balance",
+    "BalanceKind",
+    "BalancePolicy",
+    "BindingKind",
+    "CallCancelledError",
+    "CallOptions",
+    "ClientBase",
+    "ClientCallInfo",
+    "ClientCallNext",
+    "ClientInterceptor",
+    "ContractError",
+    "ContractWarning",
+    "DeadlineExceededError",
+    "ErrorCode",
+    "InternalError",
+    "InvalidArgumentError",
+    "IssuedToken",
+    "MeshCallError",
+    "MeshCallWarning",
+    "MethodAnnotations",
+    "MethodNotFoundError",
+    "PermissionDeniedError",
+    "ProtocolError",
+    "ReconnectPolicy",
+    "ResourceExhaustedError",
+    "RetryPolicy",
+    "RouterAuthClient",
+    "RouterCredentials",
+    "RouterIdentity",
+    "RouterScope",
+    "RpcContext",
+    "RpcDuplex",
+    "RpcDuplexClient",
+    "RpcInputStream",
+    "RpcLogger",
+    "RpcServer",
+    "RpcServerStream",
+    "ServerCallNext",
+    "ServerInterceptor",
+    "StreamKind",
+    "UnauthenticatedError",
+    "UnavailableError",
+    "Violation",
+    "WebSocketRouter",
+    "get_service_contract",
+    "get_service_method_binding",
+    "get_service_warnings",
+    "lint_contract",
+    "load_contract",
+    "method",
+    "render_contract",
+    "service",
+    "write_contract",
+]