Skip to content

rpc

Class info

Classes

Name Children Inherits
RpcSocket
pyt3client.native.rpc
Requests and streams over one Effect RPC WebSocket; many may run at once.
    T3RpcError
    pyt3client.errors
    A native RPC failed: the server ended the request with a failure, or the socket closed.
      _CauseDie
      pyt3client.native.rpc
        _CauseFail
        pyt3client.native.rpc
          _CauseInterrupt
          pyt3client.native.rpc
            _Chunk
            pyt3client.native.rpc
              _Closed
              pyt3client.native.rpc
              The socket ended; every open request fails with `error`.
                _Defect
                pyt3client.native.rpc
                  _Exit
                  pyt3client.native.rpc
                    _ExitFailure
                    pyt3client.native.rpc
                      _ExitSuccess
                      pyt3client.native.rpc
                        _Frame
                        pyt3client.native.rpc
                        _Ping
                        pyt3client.native.rpc
                          _Pong
                          pyt3client.native.rpc
                            _ProtocolError
                            pyt3client.native.rpc

                              🛈 DocStrings

                              Effect RPC over a WebSocket, the protocol of T3 Code's native clients.

                              Frames are JSON objects tagged by _tag (upstream, vendored Effect: .repos/effect/packages/effect/src/rpc/RpcMessage.ts):

                              • client -> server: Request {id, tag, payload, headers}; Ack {requestId} after each chunk of a stream (the server sends the next chunk once acked); Interrupt {requestId, interruptors} to end a request early; Ping.
                              • server -> client: Chunk {requestId, values} (items of a stream); Exit {requestId, exit}, where exit is {_tag: "Success", value} or {_tag: "Failure", cause: [...]}; Defect {defect} and ClientProtocolError, which end every request; Pong.

                              Methods (tag) and their payloads are in upstream packages/contracts/src/rpc.ts and orchestrationV2.ts (ORCHESTRATION_V2_WS_METHODS).

                              KEEPALIVE_SECONDS module-attribute

                              KEEPALIVE_SECONDS = 15.0
                              

                              Interval of RPC Pings, which keep idle subscriptions open through proxies.

                              RpcSocket

                              Requests and streams over one Effect RPC WebSocket; many may run at once.

                              Use RpcSocket.connect(url). Each request gets its own id; a reader task routes the server's frames to the request they answer.

                              Source code in src/pyt3client/native/rpc.py
                              136
                              137
                              138
                              139
                              140
                              141
                              142
                              143
                              144
                              145
                              146
                              147
                              148
                              149
                              150
                              151
                              152
                              153
                              154
                              155
                              156
                              157
                              158
                              159
                              160
                              161
                              162
                              163
                              164
                              165
                              166
                              167
                              168
                              169
                              170
                              171
                              172
                              173
                              174
                              175
                              176
                              177
                              178
                              179
                              180
                              181
                              182
                              183
                              184
                              185
                              186
                              187
                              188
                              189
                              190
                              191
                              192
                              193
                              194
                              195
                              196
                              197
                              198
                              199
                              200
                              201
                              202
                              203
                              204
                              205
                              206
                              207
                              208
                              209
                              210
                              211
                              212
                              213
                              214
                              215
                              216
                              217
                              218
                              219
                              220
                              221
                              222
                              223
                              224
                              225
                              226
                              227
                              228
                              229
                              230
                              231
                              232
                              233
                              234
                              235
                              236
                              237
                              238
                              239
                              240
                              241
                              242
                              243
                              244
                              245
                              246
                              247
                              248
                              249
                              250
                              251
                              252
                              253
                              254
                              255
                              256
                              257
                              258
                              259
                              260
                              261
                              262
                              263
                              264
                              265
                              266
                              267
                              268
                              269
                              270
                              271
                              272
                              273
                              274
                              275
                              276
                              277
                              278
                              279
                              280
                              281
                              282
                              283
                              284
                              285
                              286
                              class RpcSocket:
                                  """Requests and streams over one Effect RPC WebSocket; many may run at once.
                              
                                  Use `RpcSocket.connect(url)`. Each request gets its own id; a reader task routes
                                  the server's frames to the request they answer.
                                  """
                              
                                  def __init__(self, connection: ClientConnection) -> None:
                                      self._connection = connection
                                      self._next_id = 0
                                      self._pending: dict[str, asyncio.Queue[_Delivery]] = {}
                                      self._closed: T3RpcError | None = None
                                      self._tasks: list[asyncio.Task[None]] = []
                              
                                  @classmethod
                                  @asynccontextmanager
                                  async def connect(cls, url: str) -> AsyncGenerator[RpcSocket]:
                                      """Open the socket at `url` (with its `wsTicket`) and close it on exit."""
                                      from websockets.asyncio.client import connect
                              
                                      async with connect(url, max_size=None) as connection:
                                          socket = cls(connection)
                                          socket._tasks = [
                                              asyncio.create_task(socket._read(), name="t3-rpc-read"),
                                              asyncio.create_task(socket._keepalive(), name="t3-rpc-keepalive"),
                                          ]
                                          try:
                                              yield socket
                                          finally:
                                              for task in socket._tasks:
                                                  task.cancel()
                                              for task in socket._tasks:
                                                  with suppress(asyncio.CancelledError):
                                                      await task
                              
                                  async def call(self, tag: str, payload: Mapping[str, JsonValue]) -> JsonValue:
                                      """Send a request and return its result.
                              
                                      Raises:
                                          T3RpcError: The request failed, or the socket closed before it ended.
                                      """
                                      request_id, queue = self._open()
                                      try:
                                          await self._request(request_id, tag, payload)
                                          while True:
                                              match await queue.get():
                                                  case _Exit(exit=_ExitSuccess(value=value)):
                                                      return value
                                                  case _Exit(exit=_ExitFailure() as failure):
                                                      raise T3RpcError(tag, _failure_message(failure), cause=_dump(failure))
                                                  case _Closed(error=error):
                                                      raise error
                                                  case _Chunk():
                                                      continue  # Not expected for a plain request
                                      finally:
                                          self._pending.pop(request_id, None)
                              
                                  async def stream(self, tag: str, payload: Mapping[str, JsonValue]) -> AsyncIterator[JsonValue]:
                                      """Send a streaming request and yield its items until the server ends it.
                              
                                      Leaving the loop early interrupts the request on the server.
                              
                                      Raises:
                                          T3RpcError: The request failed, or the socket closed before it ended.
                                      """
                                      request_id, queue = self._open()
                                      ended = False
                                      try:
                                          await self._request(request_id, tag, payload)
                                          while True:
                                              match await queue.get():
                                                  case _Chunk(values=values):
                                                      await self._send({"_tag": "Ack", "requestId": request_id})
                                                      for value in values:
                                                          yield value
                                                  case _Exit(exit=_ExitSuccess()):
                                                      ended = True
                                                      return
                                                  case _Exit(exit=_ExitFailure() as failure):
                                                      ended = True
                                                      raise T3RpcError(tag, _failure_message(failure), cause=_dump(failure))
                                                  case _Closed(error=error):
                                                      ended = True
                                                      raise error
                                      finally:
                                          self._pending.pop(request_id, None)
                                          if not ended and self._closed is None:
                                              interrupt = {"_tag": "Interrupt", "requestId": request_id, "interruptors": []}
                                              with suppress(Exception):
                                                  await self._send(interrupt)
                              
                                  def _open(self) -> tuple[str, asyncio.Queue[_Delivery]]:
                                      if self._closed is not None:
                                          raise self._closed
                                      self._next_id += 1
                                      request_id = str(self._next_id)
                                      queue: asyncio.Queue[_Delivery] = asyncio.Queue()
                                      self._pending[request_id] = queue
                                      return request_id, queue
                              
                                  async def _request(self, request_id: str, tag: str, payload: Mapping[str, JsonValue]) -> None:
                                      frame: dict[str, JsonValue] = {
                                          "_tag": "Request",
                                          "id": request_id,
                                          "tag": tag,
                                          "payload": dict(payload),
                                          "headers": [],
                                      }
                                      await self._send(frame)
                              
                                  async def _send(self, frame: Mapping[str, JsonValue]) -> None:
                                      await self._connection.send(json.dumps(frame))
                              
                                  async def _read(self) -> None:
                                      from websockets.exceptions import ConnectionClosed
                              
                                      error = T3RpcError("socket", "the connection closed")
                                      try:
                                          async for raw in self._connection:
                                              try:
                                                  frame = _SERVER_FRAME.validate_json(raw)
                                              except ValidationError:
                                                  logger.debug("Ignoring an unknown RPC frame: %s", str(raw)[:200])
                                                  continue
                                              match frame:
                                                  case _Chunk(request_id=request_id) | _Exit(request_id=request_id):
                                                      if queue := self._pending.get(str(request_id)):
                                                          queue.put_nowait(frame)
                                                  case _Ping():
                                                      await self._send({"_tag": "Pong"})
                                                  case _Pong():
                                                      pass
                                                  case _Defect(defect=defect):
                                                      error = T3RpcError("socket", f"server defect: {json.dumps(defect)[:500]}")
                                                      break
                                                  case _ProtocolError(error=protocol_error):
                                                      message = f"protocol error: {json.dumps(protocol_error)[:500]}"
                                                      error = T3RpcError("socket", message)
                                                      break
                                      except ConnectionClosed as closed:
                                          error = T3RpcError("socket", f"the connection closed: {closed}")
                                      finally:
                                          self._closed = error
                                          for queue in self._pending.values():
                                              queue.put_nowait(_Closed(error))
                              
                                  async def _keepalive(self) -> None:
                                      while self._closed is None:
                                          await asyncio.sleep(KEEPALIVE_SECONDS)
                                          with suppress(Exception):
                                              await self._send({"_tag": "Ping"})
                              

                              call async

                              call(tag: str, payload: Mapping[str, JsonValue]) -> JsonValue
                              

                              Send a request and return its result.

                              Raises:

                              Type Description
                              T3RpcError

                              The request failed, or the socket closed before it ended.

                              Source code in src/pyt3client/native/rpc.py
                              171
                              172
                              173
                              174
                              175
                              176
                              177
                              178
                              179
                              180
                              181
                              182
                              183
                              184
                              185
                              186
                              187
                              188
                              189
                              190
                              191
                              async def call(self, tag: str, payload: Mapping[str, JsonValue]) -> JsonValue:
                                  """Send a request and return its result.
                              
                                  Raises:
                                      T3RpcError: The request failed, or the socket closed before it ended.
                                  """
                                  request_id, queue = self._open()
                                  try:
                                      await self._request(request_id, tag, payload)
                                      while True:
                                          match await queue.get():
                                              case _Exit(exit=_ExitSuccess(value=value)):
                                                  return value
                                              case _Exit(exit=_ExitFailure() as failure):
                                                  raise T3RpcError(tag, _failure_message(failure), cause=_dump(failure))
                                              case _Closed(error=error):
                                                  raise error
                                              case _Chunk():
                                                  continue  # Not expected for a plain request
                                  finally:
                                      self._pending.pop(request_id, None)
                              

                              connect async classmethod

                              connect(url: str) -> AsyncGenerator[RpcSocket]
                              

                              Open the socket at url (with its wsTicket) and close it on exit.

                              Source code in src/pyt3client/native/rpc.py
                              150
                              151
                              152
                              153
                              154
                              155
                              156
                              157
                              158
                              159
                              160
                              161
                              162
                              163
                              164
                              165
                              166
                              167
                              168
                              169
                              @classmethod
                              @asynccontextmanager
                              async def connect(cls, url: str) -> AsyncGenerator[RpcSocket]:
                                  """Open the socket at `url` (with its `wsTicket`) and close it on exit."""
                                  from websockets.asyncio.client import connect
                              
                                  async with connect(url, max_size=None) as connection:
                                      socket = cls(connection)
                                      socket._tasks = [
                                          asyncio.create_task(socket._read(), name="t3-rpc-read"),
                                          asyncio.create_task(socket._keepalive(), name="t3-rpc-keepalive"),
                                      ]
                                      try:
                                          yield socket
                                      finally:
                                          for task in socket._tasks:
                                              task.cancel()
                                          for task in socket._tasks:
                                              with suppress(asyncio.CancelledError):
                                                  await task
                              

                              stream async

                              stream(tag: str, payload: Mapping[str, JsonValue]) -> AsyncIterator[JsonValue]
                              

                              Send a streaming request and yield its items until the server ends it.

                              Leaving the loop early interrupts the request on the server.

                              Raises:

                              Type Description
                              T3RpcError

                              The request failed, or the socket closed before it ended.

                              Source code in src/pyt3client/native/rpc.py
                              193
                              194
                              195
                              196
                              197
                              198
                              199
                              200
                              201
                              202
                              203
                              204
                              205
                              206
                              207
                              208
                              209
                              210
                              211
                              212
                              213
                              214
                              215
                              216
                              217
                              218
                              219
                              220
                              221
                              222
                              223
                              224
                              225
                              async def stream(self, tag: str, payload: Mapping[str, JsonValue]) -> AsyncIterator[JsonValue]:
                                  """Send a streaming request and yield its items until the server ends it.
                              
                                  Leaving the loop early interrupts the request on the server.
                              
                                  Raises:
                                      T3RpcError: The request failed, or the socket closed before it ended.
                                  """
                                  request_id, queue = self._open()
                                  ended = False
                                  try:
                                      await self._request(request_id, tag, payload)
                                      while True:
                                          match await queue.get():
                                              case _Chunk(values=values):
                                                  await self._send({"_tag": "Ack", "requestId": request_id})
                                                  for value in values:
                                                      yield value
                                              case _Exit(exit=_ExitSuccess()):
                                                  ended = True
                                                  return
                                              case _Exit(exit=_ExitFailure() as failure):
                                                  ended = True
                                                  raise T3RpcError(tag, _failure_message(failure), cause=_dump(failure))
                                              case _Closed(error=error):
                                                  ended = True
                                                  raise error
                                  finally:
                                      self._pending.pop(request_id, None)
                                      if not ended and self._closed is None:
                                          interrupt = {"_tag": "Interrupt", "requestId": request_id, "interruptors": []}
                                          with suppress(Exception):
                                              await self._send(interrupt)