soulfire.download_connect.DownloadServiceClient

class soulfire.download_connect.DownloadServiceClient(address: str, *, codec: connectrpc.codec.Codec | None = _PROTO_BINARY_CODEC, protocol: connectrpc.protocol.ProtocolType = ProtocolType.CONNECT, accept_compression: collections.abc.Iterable[connectrpc.compression.Compression] | None = None, send_compression: connectrpc.compression.Compression | None = _GZIP_COMPRESSION, timeout_ms: int | None = None, read_max_bytes: int | None = None, interceptors: collections.abc.Iterable[connectrpc.interceptor.Interceptor] = (), http_client: pyqwest.Client | None = None)[source]

Bases: connectrpc.client.ConnectClient

Service for downloading content from remote URLs through the SoulFire server. This service acts as a proxy, allowing clients to fetch remote resources using the server’s network connection and optionally through a configured proxy.

Use cases include: - Downloading resources that may be blocked from the client’s network - Fetching content through a specific proxy for anonymity or geo-unlocking - Centralizing external API calls through the server

The service uses a Reactor Netty HTTP client with: - 5-second response timeout - Automatic compression support - Default Accept, Accept-Language, and User-Agent headers

Authorization: - Requires a valid JWT token - Caller must have DOWNLOAD_URL permission for the specified instance

Error handling: - Returns gRPC INTERNAL status on network errors, timeouts, or server failures - The error description contains details about the failure

async download(request: soulfire.download_pb2.DownloadRequest, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) → soulfire.download_pb2.DownloadResponse[source]

Downloads content from the specified URI and returns the response.

Makes an HTTP GET request to the URI specified in the request, optionally routing through a proxy. Custom headers can be provided to customize the request.

Parameters:
  • URI (request - Contains the target) – and optional proxy configuration

  • permissions (instance ID for) – and optional proxy configuration

  • headers (optional) – and optional proxy configuration

:param : and optional proxy configuration

Returns:

The downloaded content as bytes, along with response headers and HTTP status code

Errors:

PERMISSION_DENIED - Caller lacks DOWNLOAD_URL permission for the instance INTERNAL - Network error, connection timeout, invalid URI, or other server error