mirror of
https://github.com/bitechdev/ResolveSpec.git
synced 2026-10-03 20:11:57 +00:00
refactor: move JS and Python clients under clients/
This commit is contained in:
@@ -0,0 +1,43 @@
|
||||
"""ResolveSpec Python client: REST (ResolveSpec), HeaderSpec and WebSocketSpec."""
|
||||
from typing import Mapping, Optional
|
||||
|
||||
from .headerspec import (
|
||||
AsyncHeaderSpecClient,
|
||||
HeaderSpecClient,
|
||||
build_headers,
|
||||
decode_header_value,
|
||||
encode_header_value,
|
||||
)
|
||||
from .funcspec import AsyncFuncSpecClient, FuncSpecClient
|
||||
from .http import ResolveSpecError, merge_headers
|
||||
from .resolvespec import AsyncResolveSpecClient, ResolveSpecClient
|
||||
from .types import * # noqa: F401,F403
|
||||
from .websocket import Subscription, WebSocketClient
|
||||
|
||||
|
||||
def _cache_key(base_url: str, token: Optional[str], headers: Optional[Mapping[str, str]]):
|
||||
return (
|
||||
base_url,
|
||||
token,
|
||||
tuple(sorted((k.lower(), v) for k, v in (headers or {}).items())),
|
||||
)
|
||||
|
||||
|
||||
_resolvespec: dict = {}
|
||||
_headerspec: dict = {}
|
||||
|
||||
|
||||
def get_resolvespec_client(base_url: str, token: Optional[str] = None, headers: Optional[Mapping[str, str]] = None) -> ResolveSpecClient:
|
||||
"""Cached sync client, keyed by base_url + token + headers (case-insensitive names)."""
|
||||
key = _cache_key(base_url, token, headers)
|
||||
if key not in _resolvespec:
|
||||
_resolvespec[key] = ResolveSpecClient(base_url, token, headers)
|
||||
return _resolvespec[key]
|
||||
|
||||
|
||||
def get_headerspec_client(base_url: str, token: Optional[str] = None, headers: Optional[Mapping[str, str]] = None) -> HeaderSpecClient:
|
||||
"""Cached sync client, keyed by base_url + token + headers (case-insensitive names)."""
|
||||
key = _cache_key(base_url, token, headers)
|
||||
if key not in _headerspec:
|
||||
_headerspec[key] = HeaderSpecClient(base_url, token, headers)
|
||||
return _headerspec[key]
|
||||
@@ -0,0 +1,197 @@
|
||||
"""FunctionSpec client: calls user-defined SQL endpoints (Go pkg/funcspec).
|
||||
|
||||
Routes are defined by the server application, so calls take a `path`.
|
||||
Parameters are sent as query string values and/or `X-*` headers; the server never
|
||||
reads a request body. Query-string values override headers of the same name.
|
||||
|
||||
Server behaviour worth knowing (pkg/funcspec):
|
||||
- `sort` is inserted raw into ORDER BY, so it must be SQL (`col DESC`), not `-col`.
|
||||
- Field selection (`X-Select-Fields`) is a no-op server-side, so it is not exposed.
|
||||
- Only one search operator per column is kept.
|
||||
- Values starting with `ZIP_` or `__` are base64-decoded by the server (even after our
|
||||
own encoding), so such plaintext values cannot be sent faithfully.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from typing import Any, Dict, List, Mapping, Optional
|
||||
|
||||
import httpx
|
||||
|
||||
from .headerspec import _OPERATOR_MAP, _bool, _filter_value, encode_header_value
|
||||
from .http import client_headers, error_from, merge_headers, parse_json
|
||||
from .types import APIResponse, FuncSpecOptions
|
||||
|
||||
Params = Mapping[str, Any]
|
||||
|
||||
_CONTENT_RANGE = re.compile(r"(\d+)-(\d+)/(\d+)")
|
||||
|
||||
|
||||
def _safe(value: str) -> str:
|
||||
"""Encode values that are unsafe as raw header/query text (non-ASCII, control chars, edge spaces)."""
|
||||
if not value.isascii() or not value.isprintable() or value != value.strip():
|
||||
return encode_header_value(value)
|
||||
return value
|
||||
|
||||
|
||||
def build_headers(options: Mapping[str, Any]) -> Dict[str, str]:
|
||||
"""Build the X-* headers understood by funcspec.ParseParameters."""
|
||||
h: Dict[str, str] = {}
|
||||
o = options
|
||||
|
||||
for f in o.get("filters") or []:
|
||||
operator = f["operator"]
|
||||
logic = f.get("logic_operator") or "AND"
|
||||
value = _safe(_filter_value(f))
|
||||
if operator == "eq" and logic == "AND":
|
||||
h[f"X-FieldFilter-{f['column']}"] = value
|
||||
else:
|
||||
kind = "X-SearchOr" if logic == "OR" else "X-SearchOp"
|
||||
h[f"{kind}-{_OPERATOR_MAP.get(operator, operator)}-{f['column']}"] = value
|
||||
|
||||
for col, text in (o.get("search_filters") or {}).items():
|
||||
h[f"X-SearchFilter-{col}"] = _safe(str(text)) # CAST(col AS TEXT) ILIKE %text%
|
||||
|
||||
if o.get("custom_sql_where"):
|
||||
h["X-Custom-SQL-W"] = _safe(o["custom_sql_where"])
|
||||
if o.get("custom_sql_or"):
|
||||
h["X-Custom-SQL-Or"] = _safe(o["custom_sql_or"])
|
||||
|
||||
if o.get("sort"):
|
||||
h["X-Sort"] = _safe(",".join(_sort_term(s) for s in o["sort"]))
|
||||
if o.get("limit") is not None:
|
||||
h["X-Limit"] = str(o["limit"])
|
||||
if o.get("offset") is not None:
|
||||
h["X-Offset"] = str(o["offset"])
|
||||
|
||||
for name, key in (("X-Distinct", "distinct"), ("X-SkipCount", "skip_count"), ("X-SkipCache", "skip_cache")):
|
||||
if o.get(key) is not None:
|
||||
h[name] = _bool(o[key])
|
||||
|
||||
fmt = o.get("response_format")
|
||||
if fmt:
|
||||
h[{"simple": "X-SimpleApi", "detail": "X-DetailApi", "syncfusion": "X-Syncfusion"}[fmt]] = "true"
|
||||
return h
|
||||
|
||||
|
||||
def _sort_term(s: Mapping[str, str]) -> str:
|
||||
# funcspec puts this verbatim into ORDER BY
|
||||
return f"{s['column']} {'DESC' if s.get('direction', 'asc').upper() == 'DESC' else 'ASC'}"
|
||||
|
||||
|
||||
def build_query(params: Optional[Params]) -> Dict[str, Any]:
|
||||
"""Query-string values: bools -> true/false, lists -> repeated keys (server: IN filter)."""
|
||||
out: Dict[str, Any] = {}
|
||||
for k, v in (params or {}).items():
|
||||
if v is None:
|
||||
continue
|
||||
if isinstance(v, (list, tuple)):
|
||||
out[k] = [_safe(_q(x)) for x in v]
|
||||
else:
|
||||
out[k] = _safe(_q(v))
|
||||
return out
|
||||
|
||||
|
||||
def _q(v: Any) -> str:
|
||||
return _bool(v) if isinstance(v, bool) else str(v)
|
||||
|
||||
|
||||
def _metadata(response: httpx.Response, options: Optional[Mapping[str, Any]]) -> Dict[str, int]:
|
||||
"""Content-Range is `items {offset}-{offset+len}/{total}`."""
|
||||
m = _CONTENT_RANGE.search(response.headers.get("content-range", ""))
|
||||
start, end, total = (int(x) for x in m.groups()) if m else (0, 0, 0)
|
||||
return {
|
||||
"total": total,
|
||||
"count": end - start,
|
||||
"filtered": total,
|
||||
"offset": start,
|
||||
"limit": int((options or {}).get("limit") or 0),
|
||||
}
|
||||
|
||||
|
||||
def _wrap(response: httpx.Response, options: Optional[Mapping[str, Any]], with_metadata: bool) -> APIResponse:
|
||||
data = parse_json(response)
|
||||
if not response.is_success: # 206 Partial Content is success
|
||||
raise error_from(response, data)
|
||||
result: APIResponse = {"success": True, "data": data}
|
||||
if with_metadata:
|
||||
result["metadata"] = _metadata(response, options)
|
||||
return result
|
||||
|
||||
|
||||
class _Base:
|
||||
def __init__(
|
||||
self,
|
||||
base_url: str,
|
||||
token: Optional[str] = None,
|
||||
headers: Optional[Mapping[str, str]] = None,
|
||||
timeout: Optional[float] = 30.0,
|
||||
):
|
||||
self.base_url = base_url
|
||||
self.token = token
|
||||
self.headers = dict(headers or {}) # snapshot
|
||||
self.timeout = timeout
|
||||
|
||||
def _req(self, method: str, path: str, params: Optional[Params], options: Optional[Mapping[str, Any]]):
|
||||
url = f"{self.base_url.rstrip('/')}/{path.lstrip('/')}"
|
||||
headers = merge_headers(
|
||||
client_headers(self.token, self.headers),
|
||||
build_headers(options) if options else {},
|
||||
)
|
||||
return method.upper(), url, headers, build_query(params)
|
||||
|
||||
|
||||
class FuncSpecClient(_Base):
|
||||
"""Synchronous client. Use as a context manager or call close()."""
|
||||
|
||||
def __init__(self, *args: Any, transport: Optional[httpx.BaseTransport] = None, **kwargs: Any):
|
||||
super().__init__(*args, **kwargs)
|
||||
self._http = httpx.Client(timeout=self.timeout, transport=transport)
|
||||
|
||||
def close(self) -> None:
|
||||
self._http.close()
|
||||
|
||||
def __enter__(self) -> "FuncSpecClient":
|
||||
return self
|
||||
|
||||
def __exit__(self, *exc: Any) -> None:
|
||||
self.close()
|
||||
|
||||
def _send(self, req, options, with_metadata) -> APIResponse:
|
||||
method, url, headers, query = req
|
||||
return _wrap(self._http.request(method, url, headers=headers, params=query), options, with_metadata)
|
||||
|
||||
def query(self, path: str, params: Optional[Params] = None, options: Optional[FuncSpecOptions] = None, *, method: str = "GET") -> APIResponse:
|
||||
"""Single-record endpoint (Handler.SqlQuery). `data` is the row object."""
|
||||
return self._send(self._req(method, path, params, options), options, False)
|
||||
|
||||
def query_list(self, path: str, params: Optional[Params] = None, options: Optional[FuncSpecOptions] = None, *, method: str = "GET") -> APIResponse:
|
||||
"""List endpoint (Handler.SqlQueryList). Adds `metadata` from Content-Range."""
|
||||
return self._send(self._req(method, path, params, options), options, True)
|
||||
|
||||
|
||||
class AsyncFuncSpecClient(_Base):
|
||||
"""Asyncio client. Use as an async context manager or await aclose()."""
|
||||
|
||||
def __init__(self, *args: Any, transport: Optional[httpx.AsyncBaseTransport] = None, **kwargs: Any):
|
||||
super().__init__(*args, **kwargs)
|
||||
self._http = httpx.AsyncClient(timeout=self.timeout, transport=transport)
|
||||
|
||||
async def aclose(self) -> None:
|
||||
await self._http.aclose()
|
||||
|
||||
async def __aenter__(self) -> "AsyncFuncSpecClient":
|
||||
return self
|
||||
|
||||
async def __aexit__(self, *exc: Any) -> None:
|
||||
await self.aclose()
|
||||
|
||||
async def _send(self, req, options, with_metadata) -> APIResponse:
|
||||
method, url, headers, query = req
|
||||
return _wrap(await self._http.request(method, url, headers=headers, params=query), options, with_metadata)
|
||||
|
||||
async def query(self, path: str, params: Optional[Params] = None, options: Optional[FuncSpecOptions] = None, *, method: str = "GET") -> APIResponse:
|
||||
return await self._send(self._req(method, path, params, options), options, False)
|
||||
|
||||
async def query_list(self, path: str, params: Optional[Params] = None, options: Optional[FuncSpecOptions] = None, *, method: str = "GET") -> APIResponse:
|
||||
return await self._send(self._req(method, path, params, options), options, True)
|
||||
@@ -0,0 +1,336 @@
|
||||
"""HeaderSpec client: query options sent as HTTP headers (Go restheadspec).
|
||||
|
||||
Methods: GET=read, POST=create, PUT=update, DELETE=delete.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import base64
|
||||
import json
|
||||
import re
|
||||
from typing import Any, Dict, Mapping, Optional
|
||||
|
||||
import httpx
|
||||
|
||||
from .http import build_url, client_headers, error_from, merge_headers, parse_json
|
||||
from .types import APIResponse, FilterOption, HeaderSpecOptions
|
||||
|
||||
_PREFIXES = ("ZIP_", "__")
|
||||
|
||||
_OPERATOR_MAP = {
|
||||
"eq": "equals",
|
||||
"neq": "notequals",
|
||||
"gt": "greaterthan",
|
||||
"gte": "greaterthanorequal",
|
||||
"lt": "lessthan",
|
||||
"lte": "lessthanorequal",
|
||||
"like": "contains",
|
||||
"ilike": "contains",
|
||||
"contains": "contains",
|
||||
"startswith": "beginswith",
|
||||
"endswith": "endswith",
|
||||
"in": "in",
|
||||
"between": "between",
|
||||
"between_inclusive": "betweeninclusive",
|
||||
"is_null": "empty",
|
||||
"is_not_null": "notempty",
|
||||
}
|
||||
|
||||
|
||||
def encode_header_value(value: str) -> str:
|
||||
"""Base64 (UTF-8) with ZIP_ prefix, for complex header values."""
|
||||
return "ZIP_" + base64.b64encode(value.encode("utf-8")).decode("ascii")
|
||||
|
||||
|
||||
def decode_header_value(value: str) -> str:
|
||||
"""Decode a value that may carry a ZIP_ or __ base64 prefix (nested allowed)."""
|
||||
code = value
|
||||
for prefix in _PREFIXES:
|
||||
if code.startswith(prefix):
|
||||
b64 = re.sub(r"[\n\r ]", "", code[len(prefix):])
|
||||
b64 += "=" * (-len(b64) % 4)
|
||||
code = base64.b64decode(b64).decode("utf-8")
|
||||
break
|
||||
if code.startswith(_PREFIXES):
|
||||
code = decode_header_value(code)
|
||||
return code
|
||||
|
||||
|
||||
def _geo_header(operator: str) -> Optional[str]:
|
||||
op = operator.lower()
|
||||
if op.endswith("_within"):
|
||||
return "X-VectorFilter-"
|
||||
if op.startswith("st_") or op in ("bbox", "&&"):
|
||||
return "X-SpatialFilter-"
|
||||
return None
|
||||
|
||||
|
||||
def _filter_value(f: FilterOption) -> str:
|
||||
v = f.get("value")
|
||||
if v is None:
|
||||
return ""
|
||||
if isinstance(v, (list, tuple)):
|
||||
return ",".join(_scalar(x) for x in v)
|
||||
return _scalar(v)
|
||||
|
||||
|
||||
def _scalar(v: Any) -> str:
|
||||
if isinstance(v, bool): # match JS String(true)
|
||||
return "true" if v else "false"
|
||||
return str(v)
|
||||
|
||||
|
||||
def _bool(v: bool) -> str:
|
||||
return "true" if v else "false"
|
||||
|
||||
|
||||
def _preload_spec(p: Mapping[str, Any]) -> str:
|
||||
cols = p.get("columns")
|
||||
return f"{p['relation']}:{','.join(cols)}" if cols else p["relation"]
|
||||
|
||||
|
||||
def build_headers(options: HeaderSpecOptions) -> Dict[str, str]:
|
||||
"""Build restheadspec HTTP headers from options. See README for the mapping."""
|
||||
h: Dict[str, str] = {}
|
||||
o = options
|
||||
|
||||
if o.get("columns"):
|
||||
h["X-Select-Fields"] = ",".join(o["columns"])
|
||||
if o.get("omit_columns"):
|
||||
h["X-Not-Select-Fields"] = ",".join(o["omit_columns"])
|
||||
|
||||
for f in o.get("filters") or []:
|
||||
logic = f.get("logic_operator") or "AND"
|
||||
operator = f["operator"]
|
||||
op = _OPERATOR_MAP.get(operator, operator)
|
||||
value = _filter_value(f)
|
||||
geo = _geo_header(operator)
|
||||
if geo:
|
||||
payload: Dict[str, Any] = {"op": operator, "value": f.get("value")}
|
||||
if logic == "OR":
|
||||
payload["logic"] = "or"
|
||||
h[f"{geo}{f['column']}"] = json.dumps(payload, separators=(",", ":"))
|
||||
elif operator == "eq" and logic == "AND":
|
||||
h[f"X-FieldFilter-{f['column']}"] = value
|
||||
elif logic == "OR":
|
||||
h[f"X-SearchOr-{op}-{f['column']}"] = value
|
||||
else:
|
||||
h[f"X-SearchOp-{op}-{f['column']}"] = value
|
||||
|
||||
if o.get("sort"):
|
||||
h["X-Sort"] = ",".join(
|
||||
("-" if s["direction"].upper() == "DESC" else "+") + s["column"] for s in o["sort"]
|
||||
)
|
||||
|
||||
if o.get("limit") is not None:
|
||||
h["X-Limit"] = str(o["limit"])
|
||||
if o.get("offset") is not None:
|
||||
h["X-Offset"] = str(o["offset"])
|
||||
if o.get("cursor_forward"):
|
||||
h["X-Cursor-Forward"] = o["cursor_forward"]
|
||||
if o.get("cursor_backward"):
|
||||
h["X-Cursor-Backward"] = o["cursor_backward"]
|
||||
|
||||
if o.get("preload"):
|
||||
# Go applies X-Preload-Where to every preload in the matching X-Preload header,
|
||||
# so preloads are grouped by where clause.
|
||||
groups: Dict[str, list] = {}
|
||||
for p in o["preload"]:
|
||||
groups.setdefault(p.get("where") or "", []).append(_preload_spec(p))
|
||||
n = 0
|
||||
for where, specs in groups.items():
|
||||
if not where:
|
||||
h["X-Preload"] = "|".join(specs)
|
||||
elif "" not in groups and n == 0:
|
||||
# X-Preload-Where would also apply to a where-less X-Preload, so only use it alone
|
||||
h["X-Preload"] = "|".join(specs)
|
||||
h["X-Preload-Where"] = where
|
||||
n += 1
|
||||
else:
|
||||
n += 1
|
||||
h[f"X-Preload-{n}"] = "|".join(specs)
|
||||
h[f"X-Preload-{n}-Where"] = where
|
||||
|
||||
if o.get("expand"):
|
||||
h["X-Expand"] = "|".join(_preload_spec(e) for e in o["expand"])
|
||||
if o.get("custom_sql_joins"):
|
||||
h["X-Custom-SQL-Join"] = "|".join(o["custom_sql_joins"])
|
||||
if o.get("custom_sql_or"):
|
||||
h["X-Custom-SQL-Or"] = " OR ".join(o["custom_sql_or"])
|
||||
if o.get("search_columns"):
|
||||
h["X-SearchCols"] = ",".join(o["search_columns"])
|
||||
for col, sql in (o.get("advanced_sql") or {}).items():
|
||||
h[f"X-AdvSQL-{col}"] = sql
|
||||
|
||||
vs = o.get("vector_search")
|
||||
if vs:
|
||||
h[f"X-Vector-Search-{vs['column']}"] = vs.get("metric") or "l2"
|
||||
h["X-Vector-Search-Vector"] = json.dumps(vs["vector"], separators=(",", ":"))
|
||||
if vs.get("as"):
|
||||
h["X-Vector-Search-As"] = vs["as"]
|
||||
if vs.get("direction"):
|
||||
h["X-Vector-Search-Dir"] = vs["direction"]
|
||||
|
||||
for name, key in (
|
||||
("X-Clean-JSON", "clean_json"),
|
||||
("X-Distinct", "distinct"),
|
||||
("X-SkipCount", "skip_count"),
|
||||
("X-SkipCache", "skip_cache"),
|
||||
("X-Transaction-Atomic", "atomic_transaction"),
|
||||
("X-Single-Record-As-Object", "single_record_as_object"),
|
||||
):
|
||||
if o.get(key) is not None:
|
||||
h[name] = _bool(o[key])
|
||||
|
||||
if o.get("pk_row"):
|
||||
h["X-PKRow"] = o["pk_row"]
|
||||
|
||||
fmt = o.get("response_format")
|
||||
if fmt:
|
||||
h[{"simple": "X-SimpleApi", "detail": "X-DetailApi", "syncfusion": "X-Syncfusion"}[fmt]] = "true"
|
||||
|
||||
if o.get("xfiles"):
|
||||
h["X-Files"] = encode_header_value(json.dumps(o["xfiles"], separators=(",", ":")))
|
||||
|
||||
if o.get("fetch_row_number"):
|
||||
h["X-Fetch-RowNumber"] = o["fetch_row_number"]
|
||||
|
||||
for cc in o.get("computedColumns") or []:
|
||||
h[f"X-CQL-SEL-{cc['name']}"] = cc["expression"]
|
||||
|
||||
if o.get("customOperators"):
|
||||
h["X-Custom-SQL-W"] = " AND ".join(co["sql"] for co in o["customOperators"])
|
||||
|
||||
return h
|
||||
|
||||
|
||||
def _int(s: Optional[str]) -> int:
|
||||
try:
|
||||
return int(s) # type: ignore[arg-type]
|
||||
except (TypeError, ValueError):
|
||||
return 0
|
||||
|
||||
|
||||
def _wrap(response: httpx.Response) -> APIResponse:
|
||||
"""Wrap a raw restheadspec body, deriving metadata from Content-Range / X-Limit."""
|
||||
data = parse_json(response)
|
||||
if not response.is_success:
|
||||
raise error_from(response, data)
|
||||
cr = response.headers.get("content-range")
|
||||
total = _int(cr.split("/")[-1]) if cr else 0
|
||||
offset = _int(cr.split("/")[0].split("-")[0].split(" ")[-1]) if cr else 0
|
||||
return {
|
||||
"data": data,
|
||||
"success": True,
|
||||
"error": data.get("error") if isinstance(data, dict) else None,
|
||||
"metadata": {
|
||||
"count": total,
|
||||
"total": total,
|
||||
"filtered": total,
|
||||
"offset": offset,
|
||||
"limit": _int(response.headers.get("x-limit")),
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
class _Base:
|
||||
def __init__(
|
||||
self,
|
||||
base_url: str,
|
||||
token: Optional[str] = None,
|
||||
headers: Optional[Mapping[str, str]] = None,
|
||||
timeout: Optional[float] = 30.0,
|
||||
):
|
||||
self.base_url = base_url
|
||||
self.token = token
|
||||
self.headers = dict(headers or {}) # snapshot
|
||||
self.timeout = timeout
|
||||
|
||||
def _base_headers(self) -> Dict[str, str]:
|
||||
return client_headers(self.token, self.headers)
|
||||
|
||||
def _req(self, method, schema, entity, id, options=None, body=None):
|
||||
opt = build_headers(options) if options else {}
|
||||
return (
|
||||
method,
|
||||
build_url(self.base_url, schema, entity, id),
|
||||
merge_headers(self._base_headers(), opt),
|
||||
body,
|
||||
)
|
||||
|
||||
def _read_req(self, schema, entity, id, options):
|
||||
return self._req("GET", schema, entity, id, options)
|
||||
|
||||
def _create_req(self, schema, entity, data, options):
|
||||
return self._req("POST", schema, entity, None, options, data)
|
||||
|
||||
def _update_req(self, schema, entity, id, data, options):
|
||||
return self._req("PUT", schema, entity, id, options, data)
|
||||
|
||||
def _delete_req(self, schema, entity, id):
|
||||
return self._req("DELETE", schema, entity, id)
|
||||
|
||||
|
||||
class HeaderSpecClient(_Base):
|
||||
"""Synchronous client. Use as a context manager or call close()."""
|
||||
|
||||
def __init__(self, *args: Any, transport: Optional[httpx.BaseTransport] = None, **kwargs: Any):
|
||||
super().__init__(*args, **kwargs)
|
||||
self._http = httpx.Client(timeout=self.timeout, transport=transport)
|
||||
|
||||
def close(self) -> None:
|
||||
self._http.close()
|
||||
|
||||
def __enter__(self) -> "HeaderSpecClient":
|
||||
return self
|
||||
|
||||
def __exit__(self, *exc: Any) -> None:
|
||||
self.close()
|
||||
|
||||
def _send(self, req) -> APIResponse:
|
||||
method, url, headers, body = req
|
||||
return _wrap(self._http.request(method, url, headers=headers, json=body))
|
||||
|
||||
def read(self, schema: str, entity: str, id: Optional[str] = None, options: Optional[HeaderSpecOptions] = None) -> APIResponse:
|
||||
return self._send(self._read_req(schema, entity, id, options))
|
||||
|
||||
def create(self, schema: str, entity: str, data: Any, options: Optional[HeaderSpecOptions] = None) -> APIResponse:
|
||||
return self._send(self._create_req(schema, entity, data, options))
|
||||
|
||||
def update(self, schema: str, entity: str, id: str, data: Any, options: Optional[HeaderSpecOptions] = None) -> APIResponse:
|
||||
return self._send(self._update_req(schema, entity, id, data, options))
|
||||
|
||||
def delete(self, schema: str, entity: str, id: str) -> APIResponse:
|
||||
return self._send(self._delete_req(schema, entity, id))
|
||||
|
||||
|
||||
class AsyncHeaderSpecClient(_Base):
|
||||
"""Asyncio client. Use as an async context manager or await aclose()."""
|
||||
|
||||
def __init__(self, *args: Any, transport: Optional[httpx.AsyncBaseTransport] = None, **kwargs: Any):
|
||||
super().__init__(*args, **kwargs)
|
||||
self._http = httpx.AsyncClient(timeout=self.timeout, transport=transport)
|
||||
|
||||
async def aclose(self) -> None:
|
||||
await self._http.aclose()
|
||||
|
||||
async def __aenter__(self) -> "AsyncHeaderSpecClient":
|
||||
return self
|
||||
|
||||
async def __aexit__(self, *exc: Any) -> None:
|
||||
await self.aclose()
|
||||
|
||||
async def _send(self, req) -> APIResponse:
|
||||
method, url, headers, body = req
|
||||
return _wrap(await self._http.request(method, url, headers=headers, json=body))
|
||||
|
||||
async def read(self, schema: str, entity: str, id: Optional[str] = None, options: Optional[HeaderSpecOptions] = None) -> APIResponse:
|
||||
return await self._send(self._read_req(schema, entity, id, options))
|
||||
|
||||
async def create(self, schema: str, entity: str, data: Any, options: Optional[HeaderSpecOptions] = None) -> APIResponse:
|
||||
return await self._send(self._create_req(schema, entity, data, options))
|
||||
|
||||
async def update(self, schema: str, entity: str, id: str, data: Any, options: Optional[HeaderSpecOptions] = None) -> APIResponse:
|
||||
return await self._send(self._update_req(schema, entity, id, data, options))
|
||||
|
||||
async def delete(self, schema: str, entity: str, id: str) -> APIResponse:
|
||||
return await self._send(self._delete_req(schema, entity, id))
|
||||
@@ -0,0 +1,76 @@
|
||||
"""Shared HTTP helpers for the REST clients."""
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any, Dict, Mapping, Optional
|
||||
from urllib.parse import quote
|
||||
|
||||
|
||||
class ResolveSpecError(Exception):
|
||||
"""Raised on a non-2xx response or an unsuccessful API result."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
message: str,
|
||||
status_code: Optional[int] = None,
|
||||
code: Optional[str] = None,
|
||||
details: Any = None,
|
||||
detail: Optional[str] = None,
|
||||
):
|
||||
super().__init__(message)
|
||||
self.message = message
|
||||
self.status_code = status_code
|
||||
self.code = code
|
||||
self.details = details
|
||||
self.detail = detail # server-side reason (funcspec / restheadspec errors)
|
||||
|
||||
|
||||
def merge_headers(*sources: Mapping[str, str]) -> Dict[str, str]:
|
||||
"""Merge HTTP headers case-insensitively; the last source wins and keeps its spelling."""
|
||||
result: Dict[str, str] = {}
|
||||
for source in sources:
|
||||
for name, value in source.items():
|
||||
for existing in [k for k in result if k.lower() == name.lower()]:
|
||||
del result[existing]
|
||||
result[name] = value
|
||||
return result
|
||||
|
||||
|
||||
def client_headers(token: Optional[str], headers: Optional[Mapping[str, str]]) -> Dict[str, str]:
|
||||
"""Content-Type < custom headers < bearer token."""
|
||||
return merge_headers(
|
||||
{"Content-Type": "application/json"},
|
||||
headers or {},
|
||||
{"Authorization": f"Bearer {token}"} if token else {},
|
||||
)
|
||||
|
||||
|
||||
def build_url(base_url: str, schema: str, entity: str, id: Optional[Any] = None) -> str:
|
||||
url = f"{base_url.rstrip('/')}/{quote(schema, safe='')}/{quote(entity, safe='')}"
|
||||
if id is not None and id != "":
|
||||
url += f"/{quote(str(id), safe='')}"
|
||||
return url
|
||||
|
||||
|
||||
def drop_none(d: Mapping[str, Any]) -> Dict[str, Any]:
|
||||
return {k: v for k, v in d.items() if v is not None}
|
||||
|
||||
|
||||
def parse_json(response: Any) -> Any:
|
||||
try:
|
||||
return response.json()
|
||||
except ValueError:
|
||||
return None
|
||||
|
||||
|
||||
def error_from(response: Any, data: Any) -> ResolveSpecError:
|
||||
err = data.get("error") if isinstance(data, dict) else None
|
||||
err = err if isinstance(err, dict) else {}
|
||||
text = (response.text or "").strip() if data is None else ""
|
||||
fallback = text[:200] or f"{response.reason_phrase} ({response.status_code})"
|
||||
return ResolveSpecError(
|
||||
err.get("message") or fallback,
|
||||
status_code=response.status_code,
|
||||
code=err.get("code"),
|
||||
details=err.get("details"),
|
||||
detail=err.get("detail"),
|
||||
)
|
||||
@@ -0,0 +1,137 @@
|
||||
"""ResolveSpec client: JSON body protocol (POST {operation, data, options})."""
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any, Dict, List, Mapping, Optional, Tuple
|
||||
|
||||
import httpx
|
||||
|
||||
from .http import build_url, client_headers, drop_none, error_from, parse_json
|
||||
from .types import APIResponse, Options, RecordId
|
||||
|
||||
|
||||
def _url_id(id: Optional[RecordId]) -> Optional[str]:
|
||||
return str(id) if isinstance(id, (int, str)) else None
|
||||
|
||||
|
||||
def _body_id(id: Optional[RecordId]) -> Optional[List[str]]:
|
||||
return id if isinstance(id, list) else None
|
||||
|
||||
|
||||
class _Base:
|
||||
def __init__(
|
||||
self,
|
||||
base_url: str,
|
||||
token: Optional[str] = None,
|
||||
headers: Optional[Mapping[str, str]] = None,
|
||||
timeout: Optional[float] = 30.0,
|
||||
):
|
||||
self.base_url = base_url
|
||||
self.token = token
|
||||
self.headers = dict(headers or {}) # snapshot
|
||||
self.timeout = timeout
|
||||
|
||||
def _headers(self) -> Dict[str, str]:
|
||||
return client_headers(self.token, self.headers)
|
||||
|
||||
def _request(
|
||||
self, method: str, schema: str, entity: str, id: Optional[str], body: Optional[Dict[str, Any]]
|
||||
) -> Tuple[str, str, Dict[str, str], Optional[Dict[str, Any]]]:
|
||||
return method, build_url(self.base_url, schema, entity, id), self._headers(), body
|
||||
|
||||
@staticmethod
|
||||
def _result(response: httpx.Response) -> APIResponse:
|
||||
data = parse_json(response)
|
||||
if not response.is_success:
|
||||
raise error_from(response, data)
|
||||
return data
|
||||
|
||||
# request builders (shared by sync and async)
|
||||
def _metadata_req(self, schema, entity):
|
||||
return self._request("GET", schema, entity, None, None)
|
||||
|
||||
def _read_req(self, schema, entity, id, options):
|
||||
body = drop_none({"operation": "read", "id": _body_id(id), "options": options})
|
||||
return self._request("POST", schema, entity, _url_id(id), body)
|
||||
|
||||
def _create_req(self, schema, entity, data, options):
|
||||
body = drop_none({"operation": "create", "data": data, "options": options})
|
||||
return self._request("POST", schema, entity, None, body)
|
||||
|
||||
def _update_req(self, schema, entity, data, id, options):
|
||||
body = drop_none({"operation": "update", "id": _body_id(id), "data": data, "options": options})
|
||||
return self._request("POST", schema, entity, _url_id(id), body)
|
||||
|
||||
def _delete_req(self, schema, entity, id):
|
||||
return self._request("POST", schema, entity, str(id), {"operation": "delete"})
|
||||
|
||||
|
||||
class ResolveSpecClient(_Base):
|
||||
"""Synchronous client. Use as a context manager or call close()."""
|
||||
|
||||
def __init__(self, *args: Any, transport: Optional[httpx.BaseTransport] = None, **kwargs: Any):
|
||||
super().__init__(*args, **kwargs)
|
||||
self._http = httpx.Client(timeout=self.timeout, transport=transport)
|
||||
|
||||
def close(self) -> None:
|
||||
self._http.close()
|
||||
|
||||
def __enter__(self) -> "ResolveSpecClient":
|
||||
return self
|
||||
|
||||
def __exit__(self, *exc: Any) -> None:
|
||||
self.close()
|
||||
|
||||
def _send(self, req) -> APIResponse:
|
||||
method, url, headers, body = req
|
||||
return self._result(self._http.request(method, url, headers=headers, json=body))
|
||||
|
||||
def get_metadata(self, schema: str, entity: str) -> APIResponse:
|
||||
return self._send(self._metadata_req(schema, entity))
|
||||
|
||||
def read(self, schema: str, entity: str, id: Optional[RecordId] = None, options: Optional[Options] = None) -> APIResponse:
|
||||
return self._send(self._read_req(schema, entity, id, options))
|
||||
|
||||
def create(self, schema: str, entity: str, data: Any, options: Optional[Options] = None) -> APIResponse:
|
||||
return self._send(self._create_req(schema, entity, data, options))
|
||||
|
||||
def update(self, schema: str, entity: str, data: Any, id: Optional[RecordId] = None, options: Optional[Options] = None) -> APIResponse:
|
||||
return self._send(self._update_req(schema, entity, data, id, options))
|
||||
|
||||
def delete(self, schema: str, entity: str, id: Any) -> APIResponse:
|
||||
return self._send(self._delete_req(schema, entity, id))
|
||||
|
||||
|
||||
class AsyncResolveSpecClient(_Base):
|
||||
"""Asyncio client. Use as an async context manager or await aclose()."""
|
||||
|
||||
def __init__(self, *args: Any, transport: Optional[httpx.AsyncBaseTransport] = None, **kwargs: Any):
|
||||
super().__init__(*args, **kwargs)
|
||||
self._http = httpx.AsyncClient(timeout=self.timeout, transport=transport)
|
||||
|
||||
async def aclose(self) -> None:
|
||||
await self._http.aclose()
|
||||
|
||||
async def __aenter__(self) -> "AsyncResolveSpecClient":
|
||||
return self
|
||||
|
||||
async def __aexit__(self, *exc: Any) -> None:
|
||||
await self.aclose()
|
||||
|
||||
async def _send(self, req) -> APIResponse:
|
||||
method, url, headers, body = req
|
||||
return self._result(await self._http.request(method, url, headers=headers, json=body))
|
||||
|
||||
async def get_metadata(self, schema: str, entity: str) -> APIResponse:
|
||||
return await self._send(self._metadata_req(schema, entity))
|
||||
|
||||
async def read(self, schema: str, entity: str, id: Optional[RecordId] = None, options: Optional[Options] = None) -> APIResponse:
|
||||
return await self._send(self._read_req(schema, entity, id, options))
|
||||
|
||||
async def create(self, schema: str, entity: str, data: Any, options: Optional[Options] = None) -> APIResponse:
|
||||
return await self._send(self._create_req(schema, entity, data, options))
|
||||
|
||||
async def update(self, schema: str, entity: str, data: Any, id: Optional[RecordId] = None, options: Optional[Options] = None) -> APIResponse:
|
||||
return await self._send(self._update_req(schema, entity, data, id, options))
|
||||
|
||||
async def delete(self, schema: str, entity: str, id: Any) -> APIResponse:
|
||||
return await self._send(self._delete_req(schema, entity, id))
|
||||
@@ -0,0 +1,166 @@
|
||||
"""Types aligned with Go pkg/common/types.go. Dict keys are the wire names."""
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any, Dict, List, NotRequired, TypedDict, Union
|
||||
|
||||
Operator = str # eq neq gt gte lt lte like ilike in contains startswith endswith
|
||||
# between between_inclusive is_null is_not_null
|
||||
# st_dwithin bbox (spatial) | l2_within cosine_within ip_within (vector)
|
||||
Operation = str # read | create | update | delete
|
||||
SortDirection = str # asc | desc | ASC | DESC
|
||||
VectorMetric = str # l2 | cosine | ip
|
||||
ResponseFormat = str # simple | detail | syncfusion
|
||||
|
||||
RecordId = Union[int, str, List[str]]
|
||||
|
||||
|
||||
class Parameter(TypedDict):
|
||||
name: str
|
||||
value: str
|
||||
sequence: NotRequired[int]
|
||||
|
||||
|
||||
class FilterOption(TypedDict):
|
||||
column: str
|
||||
operator: str
|
||||
value: Any
|
||||
logic_operator: NotRequired[str] # "AND" | "OR"
|
||||
|
||||
|
||||
class SortOption(TypedDict):
|
||||
column: str
|
||||
direction: str
|
||||
|
||||
|
||||
class CustomOperator(TypedDict):
|
||||
name: str
|
||||
sql: str
|
||||
|
||||
|
||||
class ComputedColumn(TypedDict):
|
||||
name: str
|
||||
expression: str
|
||||
|
||||
|
||||
class PreloadOption(TypedDict, total=False):
|
||||
relation: str
|
||||
table_name: str
|
||||
columns: List[str]
|
||||
omit_columns: List[str]
|
||||
sort: List[SortOption]
|
||||
filters: List[FilterOption]
|
||||
where: str
|
||||
limit: int
|
||||
offset: int
|
||||
updateable: bool
|
||||
computed_ql: Dict[str, str]
|
||||
recursive: bool
|
||||
primary_key: str
|
||||
related_key: str
|
||||
foreign_key: str
|
||||
recursive_child_key: str
|
||||
sql_joins: List[str]
|
||||
join_aliases: List[str]
|
||||
|
||||
|
||||
# `as` is a keyword, so the functional syntax is required.
|
||||
VectorSearchOption = TypedDict(
|
||||
"VectorSearchOption",
|
||||
{
|
||||
"column": str,
|
||||
"vector": List[float],
|
||||
"metric": str, # l2 (default) | cosine | ip
|
||||
"as": str, # distance column alias, default _distance
|
||||
"direction": str, # asc (default) | desc
|
||||
},
|
||||
total=False,
|
||||
)
|
||||
|
||||
|
||||
class ExpandOption(TypedDict, total=False):
|
||||
relation: str
|
||||
columns: List[str]
|
||||
|
||||
|
||||
class XFiles(TypedDict, total=False):
|
||||
tablename: str
|
||||
schema: str
|
||||
primarykey: str
|
||||
foreignkey: str
|
||||
relatedkey: str
|
||||
sort: List[str]
|
||||
prefix: str
|
||||
editable: bool
|
||||
recursive: bool
|
||||
expand: bool
|
||||
rownumber: bool
|
||||
skipcount: bool
|
||||
offset: int
|
||||
limit: int
|
||||
columns: List[str]
|
||||
omit_columns: List[str]
|
||||
cql_columns: List[str]
|
||||
sql_joins: List[str]
|
||||
sql_or: List[str]
|
||||
sql_and: List[str]
|
||||
parenttables: List["XFiles"]
|
||||
childtables: List["XFiles"]
|
||||
filter_fields: List[Dict[str, str]]
|
||||
cursor_forward: str
|
||||
cursor_backward: str
|
||||
|
||||
|
||||
class Options(TypedDict, total=False):
|
||||
preload: List[PreloadOption]
|
||||
columns: List[str]
|
||||
omit_columns: List[str]
|
||||
filters: List[FilterOption]
|
||||
sort: List[SortOption]
|
||||
limit: int
|
||||
offset: int
|
||||
customOperators: List[CustomOperator]
|
||||
computedColumns: List[ComputedColumn]
|
||||
parameters: List[Parameter]
|
||||
cursor_forward: str
|
||||
cursor_backward: str
|
||||
fetch_row_number: str
|
||||
vector_search: VectorSearchOption
|
||||
|
||||
|
||||
class HeaderSpecOptions(Options, total=False):
|
||||
"""Options only available to the header-based (restheadspec) protocol."""
|
||||
|
||||
expand: List[ExpandOption] # X-Expand
|
||||
custom_sql_joins: List[str] # X-Custom-SQL-Join
|
||||
custom_sql_or: List[str] # X-Custom-SQL-Or
|
||||
search_columns: List[str] # X-SearchCols
|
||||
advanced_sql: Dict[str, str] # X-AdvSQL-{col}
|
||||
clean_json: bool # X-Clean-JSON
|
||||
distinct: bool # X-Distinct
|
||||
skip_count: bool # X-SkipCount
|
||||
skip_cache: bool # X-SkipCache
|
||||
pk_row: str # X-PKRow
|
||||
response_format: str # X-SimpleApi / X-DetailApi / X-Syncfusion
|
||||
single_record_as_object: bool # X-Single-Record-As-Object
|
||||
atomic_transaction: bool # X-Transaction-Atomic
|
||||
xfiles: XFiles # X-Files
|
||||
|
||||
|
||||
class FuncSpecOptions(TypedDict, total=False):
|
||||
"""Options understood by funcspec endpoints (sent as X-* headers)."""
|
||||
|
||||
filters: List[FilterOption] # eq+AND -> X-FieldFilter; others X-SearchOp / X-SearchOr (one per column)
|
||||
search_filters: Dict[str, str] # X-SearchFilter-{col}: text ILIKE
|
||||
custom_sql_where: str # X-Custom-SQL-W
|
||||
custom_sql_or: str # X-Custom-SQL-Or
|
||||
sort: List[SortOption] # sent as SQL ORDER BY terms ("col DESC")
|
||||
limit: int
|
||||
offset: int
|
||||
distinct: bool
|
||||
skip_count: bool
|
||||
skip_cache: bool
|
||||
response_format: str # simple | detail | syncfusion
|
||||
|
||||
|
||||
# Responses are plain dicts: {"success", "data", "metadata"?, "error"?}
|
||||
APIResponse = Dict[str, Any]
|
||||
@@ -0,0 +1,335 @@
|
||||
"""WebSocketSpec client (asyncio). Mirrors the Go websocketspec message protocol."""
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import json
|
||||
import logging
|
||||
import uuid
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any, Awaitable, Callable, Dict, List, Optional, Union
|
||||
|
||||
from websockets.asyncio.client import ClientConnection, connect
|
||||
|
||||
from .http import ResolveSpecError
|
||||
from .types import FilterOption, PreloadOption, SortOption
|
||||
|
||||
log = logging.getLogger("resolvespec.websocket")
|
||||
|
||||
# Connection states
|
||||
DISCONNECTED = "disconnected"
|
||||
CONNECTING = "connecting"
|
||||
CONNECTED = "connected"
|
||||
DISCONNECTING = "disconnecting"
|
||||
RECONNECTING = "reconnecting"
|
||||
|
||||
Notification = Dict[str, Any]
|
||||
Callback = Callable[[Any], Union[None, Awaitable[None]]]
|
||||
EVENTS = ("connect", "disconnect", "error", "message", "state_change")
|
||||
|
||||
|
||||
@dataclass
|
||||
class Subscription:
|
||||
id: str
|
||||
entity: str
|
||||
schema: Optional[str] = None
|
||||
options: Optional[Dict[str, Any]] = None
|
||||
callback: Optional[Callback] = field(default=None, repr=False)
|
||||
|
||||
|
||||
def _drop_none(d: Dict[str, Any]) -> Dict[str, Any]:
|
||||
return {k: v for k, v in d.items() if v is not None}
|
||||
|
||||
|
||||
class WebSocketClient:
|
||||
"""
|
||||
Usage:
|
||||
async with WebSocketClient("ws://localhost:8080/ws") as ws:
|
||||
rows = await ws.read("users", schema="public", limit=10)
|
||||
|
||||
Events (`on(event, callback)`): connect, disconnect, error, message, state_change.
|
||||
Callbacks may be sync or async.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
url: str,
|
||||
*,
|
||||
reconnect: bool = True,
|
||||
reconnect_interval: float = 3.0,
|
||||
max_reconnect_attempts: int = 10,
|
||||
heartbeat_interval: float = 30.0,
|
||||
request_timeout: float = 30.0,
|
||||
subscribe_timeout: float = 10.0,
|
||||
headers: Optional[Dict[str, str]] = None,
|
||||
):
|
||||
self.url = url
|
||||
self.reconnect = reconnect
|
||||
self.reconnect_interval = reconnect_interval
|
||||
self.max_reconnect_attempts = max_reconnect_attempts
|
||||
self.heartbeat_interval = heartbeat_interval
|
||||
self.request_timeout = request_timeout
|
||||
self.subscribe_timeout = subscribe_timeout
|
||||
self.headers = dict(headers or {})
|
||||
|
||||
self._ws: Optional[ClientConnection] = None
|
||||
self._state = DISCONNECTED
|
||||
self._pending: Dict[str, "asyncio.Future[Dict[str, Any]]"] = {}
|
||||
self._subscriptions: Dict[str, Subscription] = {}
|
||||
self._listeners: Dict[str, Callback] = {}
|
||||
self._tasks: List["asyncio.Task[Any]"] = []
|
||||
self._reader: Optional["asyncio.Task[Any]"] = None
|
||||
self._manual_close = False
|
||||
|
||||
# ---- lifecycle -------------------------------------------------------
|
||||
|
||||
async def __aenter__(self) -> "WebSocketClient":
|
||||
await self.connect()
|
||||
return self
|
||||
|
||||
async def __aexit__(self, *exc: Any) -> None:
|
||||
await self.close()
|
||||
|
||||
async def connect(self) -> None:
|
||||
if self.is_connected():
|
||||
return
|
||||
self._manual_close = False
|
||||
self._set_state(CONNECTING)
|
||||
try:
|
||||
self._ws = await connect(self.url, additional_headers=self.headers or None)
|
||||
except Exception as e:
|
||||
self._set_state(DISCONNECTED)
|
||||
await self._emit("error", e)
|
||||
raise
|
||||
self._set_state(CONNECTED)
|
||||
self._reader = asyncio.create_task(self._read_loop(self._ws))
|
||||
self._heartbeat = asyncio.create_task(self._heartbeat_loop())
|
||||
await self._emit("connect")
|
||||
|
||||
async def close(self) -> None:
|
||||
self._manual_close = True
|
||||
self._set_state(DISCONNECTING)
|
||||
for t in (self._reader, getattr(self, "_heartbeat", None), getattr(self, "_reconnect_task", None)):
|
||||
if t and t is not asyncio.current_task():
|
||||
t.cancel()
|
||||
if self._ws:
|
||||
await self._ws.close()
|
||||
self._ws = None
|
||||
self._fail_pending(ResolveSpecError("WebSocket closed"))
|
||||
self._set_state(DISCONNECTED)
|
||||
|
||||
def is_connected(self) -> bool:
|
||||
return self._ws is not None and self._state == CONNECTED
|
||||
|
||||
@property
|
||||
def state(self) -> str:
|
||||
return self._state
|
||||
|
||||
def on(self, event: str, callback: Callback) -> None:
|
||||
if event not in EVENTS:
|
||||
raise ValueError(f"unknown event {event!r}; expected one of {EVENTS}")
|
||||
self._listeners[event] = callback
|
||||
|
||||
def off(self, event: str) -> None:
|
||||
self._listeners.pop(event, None)
|
||||
|
||||
def get_subscriptions(self) -> List[Subscription]:
|
||||
return list(self._subscriptions.values())
|
||||
|
||||
# ---- operations ------------------------------------------------------
|
||||
|
||||
async def request(
|
||||
self,
|
||||
operation: str,
|
||||
entity: str,
|
||||
*,
|
||||
schema: Optional[str] = None,
|
||||
record_id: Optional[str] = None,
|
||||
data: Any = None,
|
||||
options: Optional[Dict[str, Any]] = None,
|
||||
) -> Any:
|
||||
message = _drop_none({
|
||||
"type": "request",
|
||||
"operation": operation,
|
||||
"entity": entity,
|
||||
"schema": schema,
|
||||
"record_id": record_id,
|
||||
"data": data,
|
||||
"options": options,
|
||||
})
|
||||
response = await self._call(message, self.request_timeout, "Request")
|
||||
return response.get("data")
|
||||
|
||||
async def read(
|
||||
self,
|
||||
entity: str,
|
||||
*,
|
||||
schema: Optional[str] = None,
|
||||
record_id: Optional[str] = None,
|
||||
filters: Optional[List[FilterOption]] = None,
|
||||
columns: Optional[List[str]] = None,
|
||||
sort: Optional[List[SortOption]] = None,
|
||||
preload: Optional[List[PreloadOption]] = None,
|
||||
limit: Optional[int] = None,
|
||||
offset: Optional[int] = None,
|
||||
) -> Any:
|
||||
options = _drop_none({
|
||||
"filters": filters, "columns": columns, "sort": sort,
|
||||
"preload": preload, "limit": limit, "offset": offset,
|
||||
})
|
||||
return await self.request("read", entity, schema=schema, record_id=record_id, options=options)
|
||||
|
||||
async def create(self, entity: str, data: Any, *, schema: Optional[str] = None) -> Any:
|
||||
return await self.request("create", entity, schema=schema, data=data)
|
||||
|
||||
async def update(self, entity: str, id: str, data: Any, *, schema: Optional[str] = None) -> Any:
|
||||
return await self.request("update", entity, schema=schema, record_id=id, data=data)
|
||||
|
||||
async def delete(self, entity: str, id: str, *, schema: Optional[str] = None) -> None:
|
||||
await self.request("delete", entity, schema=schema, record_id=id)
|
||||
|
||||
async def meta(self, entity: str, *, schema: Optional[str] = None) -> Any:
|
||||
return await self.request("meta", entity, schema=schema)
|
||||
|
||||
async def subscribe(
|
||||
self,
|
||||
entity: str,
|
||||
callback: Callback,
|
||||
*,
|
||||
schema: Optional[str] = None,
|
||||
filters: Optional[List[FilterOption]] = None,
|
||||
) -> str:
|
||||
message = _drop_none({
|
||||
"type": "subscription",
|
||||
"operation": "subscribe",
|
||||
"entity": entity,
|
||||
"schema": schema,
|
||||
"options": _drop_none({"filters": filters}),
|
||||
})
|
||||
response = await self._call(message, self.subscribe_timeout, "Subscription")
|
||||
sub_id = (response.get("data") or {}).get("subscription_id")
|
||||
if not sub_id:
|
||||
raise ResolveSpecError("Subscription failed")
|
||||
self._subscriptions[sub_id] = Subscription(
|
||||
sub_id, entity, schema, _drop_none({"filters": filters}) or None, callback
|
||||
)
|
||||
return sub_id
|
||||
|
||||
async def unsubscribe(self, subscription_id: str) -> None:
|
||||
message = {"type": "subscription", "operation": "unsubscribe", "subscription_id": subscription_id}
|
||||
await self._call(message, self.subscribe_timeout, "Unsubscribe")
|
||||
self._subscriptions.pop(subscription_id, None)
|
||||
|
||||
# ---- internals -------------------------------------------------------
|
||||
|
||||
async def _call(self, message: Dict[str, Any], timeout: float, what: str) -> Dict[str, Any]:
|
||||
self._ensure_connected()
|
||||
mid = str(uuid.uuid4())
|
||||
message["id"] = mid
|
||||
fut: "asyncio.Future[Dict[str, Any]]" = asyncio.get_running_loop().create_future()
|
||||
self._pending[mid] = fut
|
||||
try:
|
||||
await self._ws.send(json.dumps(message)) # type: ignore[union-attr]
|
||||
response = await asyncio.wait_for(fut, timeout)
|
||||
except asyncio.TimeoutError:
|
||||
raise ResolveSpecError(f"{what} timeout") from None
|
||||
finally:
|
||||
self._pending.pop(mid, None)
|
||||
if not response.get("success"):
|
||||
err = response.get("error") or {}
|
||||
raise ResolveSpecError(
|
||||
err.get("message") or f"{what} failed", code=err.get("code"), details=err.get("details")
|
||||
)
|
||||
return response
|
||||
|
||||
def _ensure_connected(self) -> None:
|
||||
if not self.is_connected():
|
||||
raise ResolveSpecError("WebSocket is not connected. Call connect() first.")
|
||||
|
||||
def _fail_pending(self, exc: Exception) -> None:
|
||||
for fut in self._pending.values():
|
||||
if not fut.done():
|
||||
fut.set_exception(exc)
|
||||
self._pending.clear()
|
||||
|
||||
async def _read_loop(self, ws: ClientConnection) -> None:
|
||||
try:
|
||||
async for raw in ws:
|
||||
await self._handle_message(raw)
|
||||
except asyncio.CancelledError:
|
||||
raise
|
||||
except Exception as e: # connection error
|
||||
await self._emit("error", e)
|
||||
# connection ended
|
||||
if ws is not self._ws:
|
||||
return
|
||||
self._ws = None
|
||||
if hb := getattr(self, "_heartbeat", None):
|
||||
hb.cancel()
|
||||
self._fail_pending(ResolveSpecError("WebSocket disconnected"))
|
||||
self._set_state(DISCONNECTED)
|
||||
await self._emit("disconnect", ws.close_code, ws.close_reason)
|
||||
if self.reconnect and not self._manual_close:
|
||||
self._reconnect_task = asyncio.create_task(self._reconnect())
|
||||
|
||||
async def _reconnect(self) -> None:
|
||||
for attempt in range(1, self.max_reconnect_attempts + 1):
|
||||
if self._manual_close:
|
||||
return
|
||||
log.debug("Reconnection attempt %d/%d", attempt, self.max_reconnect_attempts)
|
||||
self._set_state(RECONNECTING)
|
||||
await asyncio.sleep(self.reconnect_interval)
|
||||
try:
|
||||
await self.connect()
|
||||
return
|
||||
except Exception as e:
|
||||
log.debug("Reconnection failed: %s", e)
|
||||
self._set_state(DISCONNECTED)
|
||||
|
||||
async def _handle_message(self, raw: Union[str, bytes]) -> None:
|
||||
try:
|
||||
message = json.loads(raw)
|
||||
except ValueError as e:
|
||||
log.debug("Error parsing message: %s", e)
|
||||
return
|
||||
await self._emit("message", message)
|
||||
kind = message.get("type")
|
||||
if kind == "response":
|
||||
fut = self._pending.get(message.get("id"))
|
||||
if fut and not fut.done():
|
||||
fut.set_result(message)
|
||||
elif kind == "notification":
|
||||
sub = self._subscriptions.get(message.get("subscription_id"))
|
||||
if sub and sub.callback:
|
||||
await _maybe_await(sub.callback(message))
|
||||
elif kind != "pong":
|
||||
log.debug("Unknown message type: %s", kind)
|
||||
|
||||
async def _heartbeat_loop(self) -> None:
|
||||
try:
|
||||
while True:
|
||||
await asyncio.sleep(self.heartbeat_interval)
|
||||
if self.is_connected():
|
||||
await self._ws.send(json.dumps({"id": str(uuid.uuid4()), "type": "ping"})) # type: ignore[union-attr]
|
||||
except asyncio.CancelledError:
|
||||
raise
|
||||
except Exception as e:
|
||||
log.debug("Heartbeat failed: %s", e)
|
||||
|
||||
def _set_state(self, state: str) -> None:
|
||||
if self._state != state:
|
||||
self._state = state
|
||||
cb = self._listeners.get("state_change")
|
||||
if cb:
|
||||
res = cb(state)
|
||||
if asyncio.iscoroutine(res):
|
||||
asyncio.ensure_future(res)
|
||||
|
||||
async def _emit(self, event: str, *args: Any) -> None:
|
||||
cb = self._listeners.get(event)
|
||||
if cb:
|
||||
await _maybe_await(cb(*args))
|
||||
|
||||
|
||||
async def _maybe_await(result: Any) -> None:
|
||||
if asyncio.iscoroutine(result) or isinstance(result, asyncio.Future):
|
||||
await result
|
||||
Reference in New Issue
Block a user