synpath 0.1.0__py3-none-any.whl

synpath/remote.py

@@ -0,0 +1,195 @@
+"""Order entry through your own `synpath serve`, with the `Client` method names.
+
+`synpath.Client(server="http://127.0.0.1:8000")` sends every trading call to
+that server's `/trading` routes instead of to the venues, which is what
+makes the engine's order types reachable from Python: a stop, an iceberg,
+an order on a bucket. Market data stays direct. The server holds the venue
+credentials; this side holds only the server's access token, found in the local
+registry for a loopback address (`synpath.server.local`) or given.
+"""
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any
+
+import httpx
+
+from .errors import AuthenticationError, BadRequest, ExchangeError, NetworkError, NotSupported
+from .server.local import resolve_key
+from .trading.errors import InsufficientFunds, OrderNotFound, RiskRejected
+from .bucket import BUCKET_PREFIX, Bucket, BucketMember, BucketOrderReport, BucketPosition
+from .trading.types import Balance, EditRequest, FeeEstimate, Fill, Order, OrderRequest, Position, Settlement, Side
+from .types import Page
+
+TRADING_PATH = "/trading"
+
+
+class RemoteTrading:
+    """The trading half of `Client`, over HTTP to a self-hosted server."""
+
+    def __init__(self, server: str, key: str | None = None, *, http_client: Any = None,
+                 home_dir: str | None = None, timeout: float = 30.0):
+        base = server.rstrip("/")
+        self.base = base if base.endswith(TRADING_PATH) else base + TRADING_PATH
+        self.server = server
+        self.key = resolve_key(server, key, home_dir=home_dir)
+        self._http = http_client
+        self._owned = http_client is None
+        self.timeout = timeout
+
+    # -- transport ------------------------------------------------------------
+
+    def _headers(self) -> dict[str, str]:
+        if not self.key:
+            raise AuthenticationError(
+                f"no access token for {self.server}: pass access_token=, set SYNPATH_ACCESS_TOKEN, or, for a server on this "
+                "machine, start it with `synpath serve` so its token is in ~/.synpath/servers.json"
+            )
+        return {"Authorization": f"Bearer {self.key}"}
+
+    async def _call(self, method: str, path: str, *, params: dict[str, Any] | None = None,
+                    json: Any = None) -> Any:
+        if self._http is None:
+            self._http = httpx.AsyncClient(timeout=self.timeout)
+        clean = {k: v for k, v in (params or {}).items() if v is not None}
+        try:
+            response = await self._http.request(method, self.base + path, params=clean, json=json, headers=self._headers())
+        except httpx.HTTPError as exc:
+            raise NetworkError(f"{method} {path}: {exc}") from exc
+        if response.status_code >= 400:
+            raise self._error(response, method, path)
+        return response.json() if response.content else None
+
+    @staticmethod
+    def _error(response: httpx.Response, method: str, path: str) -> Exception:
+        """The server's `{"error": {"code", "message", "details"}}` as the
+        exception an in-process caller would have caught."""
+        try:
+            error = (response.json() or {}).get("error") or {}
+        except ValueError:
+            error = {}
+        code = str(error.get("code") or "")
+        message = str(error.get("message") or response.text or response.reason_phrase)
+        details = error.get("details") or {}
+        status = response.status_code
+        if status in (401, 403):
+            return AuthenticationError(message)
+        if status == 404:
+            return OrderNotFound(message)
+        if code == "risk_rejected" or status == 409:
+            return RiskRejected(message, rule=str(details.get("rule") or code or "rejected"))
+        if code == "insufficient_funds":
+            return InsufficientFunds(message)
+        if status in (400, 422):
+            return BadRequest(message)
+        if details.get("retryable"):
+            return NetworkError(f"{method} {path} -> {status}: {message}")
+        return ExchangeError(f"{method} {path} -> {status}: {message}")
+
+    # -- orders ---------------------------------------------------------------
+
+    async def create_order(self, request: OrderRequest) -> Order:
+        return Order.model_validate(await self._call("POST", "/orders", json=request.model_dump(mode="json")))
+
+    async def create_bucket(self, *, book: str, name: str, members: list[BucketMember]) -> Bucket:
+        body = {"book": book, "name": name, "members": [m.model_dump(mode="json") for m in members]}
+        return Bucket.model_validate(await self._call("POST", "/buckets", json=body))
+
+    async def fetch_buckets(self, *, book: str | None = None, status: str = "active") -> list[Bucket]:
+        page = await self._call("GET", "/buckets", params={"book": book, "status": status})
+        return [Bucket.model_validate(row) for row in page.get("data", [])]
+
+    async def fetch_bucket(self, bucket_id: str) -> Bucket:
+        return Bucket.model_validate(await self._call("GET", f"/buckets/{_bare(bucket_id)}"))
+
+    async def archive_bucket(self, bucket_id: str) -> Bucket:
+        return Bucket.model_validate(await self._call("DELETE", f"/buckets/{_bare(bucket_id)}"))
+
+    async def fetch_bucket_position(self, bucket_id: str, *, book: str | None = None) -> BucketPosition:
+        return BucketPosition.model_validate(
+            await self._call("GET", f"/buckets/{_bare(bucket_id)}/position", params={"book": book}))
+
+    async def fetch_bucket_orders(self, bucket_id: str) -> list[BucketOrderReport]:
+        page = await self._call("GET", f"/buckets/{_bare(bucket_id)}/orders")
+        return [BucketOrderReport.model_validate(row) for row in page.get("data", [])]
+
+    async def fetch_bucket_order(self, bucket_id: str, order_id: str) -> BucketOrderReport:
+        return BucketOrderReport.model_validate(
+            await self._call("GET", f"/buckets/{_bare(bucket_id)}/orders/{order_id}"))
+
+    async def create_orders(self, requests: list[OrderRequest]) -> list[Order | Exception]:
+        out: list[Order | Exception] = []
+        for request in requests:
+            try:
+                out.append(await self.create_order(request))
+            except Exception as exc:   # one refusal does not stop the rest, as the venue adapters behave
+                out.append(exc)
+        return out
+
+    async def cancel_order(self, order_id: str, *, market_id: str | None = None, venue: str | None = None) -> Order:
+        return Order.model_validate(await self._call("DELETE", f"/orders/{order_id}"))
+
+    async def cancel_all_orders(self, *, market_id: str | None = None, venue: str | None = None) -> int | None:
+        count = 0
+        for order in await self.fetch_open_orders(market_id=market_id, venue=venue):
+            await self.cancel_order(order.id)
+            count += 1
+        return count
+
+    async def edit_order(self, request: EditRequest, *, venue: str | None = None, current: Order | None = None) -> Order:
+        body = request.model_dump(mode="json", exclude_none=True)
+        return Order.model_validate(await self._call("PATCH", f"/orders/{request.order_id}", json=body))
+
+    async def fetch_order(self, order_id: str, *, market_id: str | None = None, venue: str | None = None) -> Order:
+        return Order.model_validate(await self._call("GET", f"/orders/{order_id}"))
+
+    async def fetch_open_orders(self, *, market_id: str | None = None, venue: str | None = None) -> list[Order]:
+        page = await self._call("GET", "/orders", params={"venue": venue})
+        orders = [Order.model_validate(row) for row in page.get("data", [])]
+        return [o for o in orders if market_id is None or o.market_id == market_id]
+
+    # -- portfolio ------------------------------------------------------------
+
+    async def fetch_my_trades(self, *, market_id: str | None = None, venue: str | None = None,
+                              since: int | None = None, limit: int | None = None, cursor: str | None = None) -> Page[Fill]:
+        page = await self._call("GET", "/fills", params={"since": since, "venue": venue})
+        fills = [Fill.model_validate(row) for row in page.get("data", [])]
+        if market_id is not None:
+            fills = [f for f in fills if f.market_id == market_id]
+        if limit is not None:
+            fills = fills[:limit]
+        return Page(fills, next_cursor=None)
+
+    async def fetch_positions(self, *, market_id: str | None = None, venue: str | None = None) -> list[Position]:
+        page = await self._call("GET", "/positions")
+        positions = [Position.model_validate(row) for row in page.get("data", [])]
+        return [p for p in positions
+                if (market_id is None or p.market_id == market_id) and (venue is None or p.venue == venue)]
+
+    async def fetch_balance(self, venue: str) -> Balance:
+        page = await self._call("GET", "/balances")
+        for row in page.get("data", []):
+            balance = Balance.model_validate(row)
+            if balance.venue == venue:
+                return balance
+        raise NotSupported(f"{self.server} reports no balance for {venue}: is that venue configured there?")
+
+    async def fetch_settlements(self, **_: Any) -> Page[Settlement]:
+        raise NotSupported("settlements are read from the venue, not through a synpath server; "
+                           "use synpath.Client(load_credentials()) for them")
+
+    async def fetch_fee_estimate(self, market_id: str, side: Side, price: Decimal, amount: Decimal) -> FeeEstimate:
+        raise NotSupported("fee estimates are read from the venue, not through a synpath server; "
+                           "use synpath.Client(load_credentials()) or fetch_fee_schedule() for them")
+
+    # -- housekeeping ---------------------------------------------------------
+
+    async def close(self) -> None:
+        if self._http is not None and self._owned:
+            await self._http.aclose()
+            self._http = None
+
+
+def _bare(bucket_id: str) -> str:
+    """A bucket's id, whether given as `<id>` or as its market id `bucket:<id>`."""
+    return bucket_id[len(BUCKET_PREFIX):] if bucket_id.startswith(BUCKET_PREFIX) else bucket_id

synpath/server/__init__.py

@@ -0,0 +1,98 @@
+"""HTTP layer over the library. `create_app`, `create_trading_app`,
+`VenueRegistry`, `ControlStore` and `Principal` are also exported from the
+top-level package: `from synpath import create_app`.
+
+```bash
+pip install synpath
+python -m synpath.server          # http://127.0.0.1:8000/docs
+```
+
+Two ways to use it:
+
+**Standalone**, as above, or with any ASGI server:
+
+```bash
+uvicorn synpath.server:app --port 8000
+```
+
+**Mounted**, when something else owns authentication, quotas and metering:
+
+```python
+from fastapi import Depends, FastAPI
+from synpath.server import create_app
+
+outer = FastAPI()
+outer.include_router(create_app(docs=False).router, dependencies=[Depends(my_auth)])
+```
+
+The read app has no auth of its own and never will — a service that ships
+authentication inside the open-source core forces every host to work around
+it. Everything cross-venue (matching the same question across exchanges,
+routing an order) belongs outside too.
+
+**Trading is a second app**, because placing an order does need to know who
+is asking:
+
+```python
+from synpath.server import create_trading_app, ControlStore
+
+store = await ControlStore("control.db").open()
+user, key = await store.bootstrap("owner")      # once; the key is shown once
+app = create_trading_app(engine, store)
+```
+
+It carries per-key grants scoped to a subaccount (`view`, `trade`,
+`manage_credentials`, `manage_members`), an append-only audit log the
+database itself enforces, and `/ws/events`, which replays the engine's event
+stream from a cursor before following it live. See
+[docs/server.md](../docs/server.md).
+
+`GET /openapi.json` is the contract. Generate a typed client from it rather
+than hand-writing one:
+
+```bash
+npx @hey-api/openapi-ts -i http://127.0.0.1:8000/openapi.json -o ./src/synpath
+```
+"""
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+__all__ = ["create_app", "VenueRegistry", "app", "main", "create_trading_app", "ControlStore", "Principal"]
+
+_app = None
+
+
+def __getattr__(name: str) -> Any:
+    """Import FastAPI lazily.
+
+    `synpath` itself must not require it: someone using the library in a
+    notebook should not be made to install a web framework. Resolving the
+    import here also means a missing dependency fails with a sentence saying
+    what to install, rather than a bare ImportError three frames down.
+    """
+    if name not in __all__:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    try:
+        # importlib rather than `from . import api`, which would look the name
+        # up on this package and re-enter this function forever.
+        api = importlib.import_module(f"{__name__}.api")
+    except ImportError as exc:  # pragma: no cover - depends on env
+        raise ImportError(
+            "synpath.server needs FastAPI, which the base install carries. Reinstall with:\n"
+            "    pip install synpath"
+        ) from exc
+    if name == "app":
+        # One module-level instance, so `uvicorn synpath.server:app` works.
+        global _app
+        if _app is None:
+            _app = api.create_app()
+        return _app
+    if name == "main":
+        return importlib.import_module(f"{__name__}.__main__").main
+    if name == "create_trading_app":
+        return importlib.import_module(f"{__name__}.trading").create_trading_app
+    if name in ("ControlStore", "Principal"):
+        return getattr(importlib.import_module(f"{__name__}.store"), name)
+    return getattr(api, name)

synpath/server/__main__.py

@@ -0,0 +1,118 @@
+"""`python -m synpath.server` — run the API locally, or write its schema out.
+
+```bash
+python -m synpath.server                      # the read API on 127.0.0.1:8000
+python -m synpath.server schema --out openapi.json          # the read contract
+python -m synpath.server schema --trading --out openapi.json   # the trading one
+python -m synpath.server bootstrap --control control.db     # the first API key
+```
+
+`schema` exists so a typed client can be generated in CI without starting a
+server or holding credentials:
+
+```bash
+python -m synpath.server schema --trading --out openapi.json
+npx @hey-api/openapi-ts -i openapi.json -o ./src/synpath
+```
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+
+
+def schema(args: argparse.Namespace) -> None:
+    """Write the OpenAPI document without running anything."""
+    if args.trading:
+        from ..engine.engine import Engine, EngineConfig
+        from .store import ControlStore
+        from .trading import create_trading_app
+
+        # The document depends on the routes, not on the engine's state, so an
+        # engine that was never started describes the same contract.
+        engine = Engine({}, EngineConfig(journal_path=":memory:", require_lease=False))
+        app = create_trading_app(engine, ControlStore(":memory:"))
+    else:
+        from .api import create_app
+
+        app = create_app()
+    document = json.dumps(app.openapi(), indent=2, sort_keys=True)
+    if args.out:
+        with open(args.out, "w") as handle:
+            handle.write(document + "\n")
+        print(f"wrote {args.out}")
+    else:
+        print(document)
+
+
+def bootstrap(args: argparse.Namespace) -> None:
+    """Create the first user and key for a control database."""
+    from .store import ControlStore
+
+    async def run() -> None:
+        store = await ControlStore(args.control).open()
+        try:
+            user, key = await store.bootstrap(args.name)
+            print(f"user {user.id} ({user.name})")
+            print(f"key  {key.secret}")
+            print("This key is shown once. It has every permission on every account.")
+        finally:
+            await store.close()
+
+    asyncio.run(run())
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="python -m synpath.server",
+        description="Serve the synpath API. The read app has no authentication: bind to localhost, "
+                    "or mount it behind your own middleware for anything public.",
+    )
+    parser.add_argument("--host", default="127.0.0.1", help="default: 127.0.0.1")
+    parser.add_argument("--port", type=int, default=8000, help="default: 8000")
+    parser.add_argument("--reload", action="store_true", help="reload on code changes")
+    parser.add_argument("--log-level", default="info")
+    sub = parser.add_subparsers(dest="command")
+
+    schema_parser = sub.add_parser("schema", help="write the OpenAPI document and exit")
+    schema_parser.add_argument("--trading", action="store_true", help="the trading contract instead of the read one")
+    schema_parser.add_argument("--out", default=None, help="a file to write, or stdout")
+
+    boot = sub.add_parser("bootstrap", help="create the first user and API key")
+    boot.add_argument("--control", default="synpath-control.db", help="the control database")
+    boot.add_argument("--name", default="owner")
+
+    args = parser.parse_args(argv)
+    if args.command == "schema":
+        return schema(args)
+    if args.command == "bootstrap":
+        return bootstrap(args)
+
+    try:
+        import uvicorn
+    except ImportError:  # pragma: no cover - depends on env
+        raise SystemExit(
+            'synpath.server needs an ASGI server, which the base install carries. Reinstall with:\n'
+            '    pip install synpath'
+        ) from None
+
+    if args.host not in ("127.0.0.1", "localhost", "::1"):
+        print(
+            f"warning: binding to {args.host} exposes an API with no "
+            "authentication. Mount create_app() behind your own middleware "
+            "instead of serving this directly."
+        )
+
+    uvicorn.run(
+        "synpath.server:app",
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+        log_level=args.log_level,
+        factory=False,
+    )
+
+
+if __name__ == "__main__":
+    main()