soulfire.download_connect.DownloadService

class soulfire.download_connect.DownloadService[source]

Bases: Protocol

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, ctx: connectrpc.request.RequestContext[soulfire.download_pb2.DownloadRequest, soulfire.download_pb2.DownloadResponse], /) → 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