Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,22 @@ This project adheres to the [PEP 8](https://www.python.org/dev/peps/pep-0008/) c

Before submitting a pull request, please make sure your changes pass all tests. New features should include additional unit tests validating the changes.

### HTTP Requests

Use `Route` templates for paths and the shared clients in `runpod.api` for HTTP requests. Route parameters are escaped, and service bases are configured in `runpod.api.routes`. Keep a client context open across related requests to reuse its connection pool.

```python
from runpod.api.rest import AsyncRESTClient
from runpod.api.routes import Route

async with AsyncRESTClient() as client:
pod = await client.request(Route("GET", "/v2/pods/{pod_id}", pod_id=pod_id))
```

`RESTClient` provides the synchronous equivalent. Both clients apply account authentication and bounded rate-limit waits. `HTTPClient` and `SyncHTTPClient` in `runpod.api.http` handle raw transport for GraphQL, streams, worker requests, and uploads. These raw clients require explicit authentication headers. Their `stream()` contexts expose responses for protocol-specific handling and release them on exit. A supplied session remains owned by its caller.

Account login and credential storage belong in `runpod.auth`. CLI commands belong in `runpod.cli`.

## Getting Help

If you have any questions or need help with contributing, feel free to reach out on the [issue tracker](https://github.com/runpod/runpod-python/issues) or open a new issue. We're here to help!
Expand Down
4 changes: 2 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -60,8 +60,8 @@ local_scheme = "no-local-version"


[project.scripts]
runpod = "runpod.rp_cli.main:run"
rp = "runpod.rp_cli.main:run"
runpod = "runpod.cli.main:run"
rp = "runpod.cli.main:run"


[dependency-groups]
Expand Down
24 changes: 6 additions & 18 deletions runpod/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -37,9 +37,9 @@
"update_endpoint_template": "runpod.api.ctl_commands",
"update_user_settings": "runpod.api.ctl_commands",
# config helpers
"check_credentials": "runpod.cli.groups.config.functions",
"get_credentials": "runpod.cli.groups.config.functions",
"set_credentials": "runpod.cli.groups.config.functions",
"check_credentials": "runpod.auth.credentials",
"get_credentials": "runpod.auth.credentials",
"set_credentials": "runpod.auth.credentials",
# endpoint clients
"AsyncioEndpoint": "runpod.endpoint",
"AsyncioJob": "runpod.endpoint",
Expand Down Expand Up @@ -100,22 +100,10 @@ def _selected_profile() -> str:


def _load_api_key():
"""resolve the api key from the environment, then stored credentials.
"""resolve the api key from the environment or selected profile."""
from .auth import load_api_key

the credential lookup is deferred (and tolerant of a missing cli
dependency closure) so a bare `import runpod` never drags in the
config/cli modules; the deployed worker gets its key from the env.
"""
key = os.environ.get("RUNPOD_API_KEY")
if key:
return key
try:
creds = importlib.import_module(
"runpod.cli.groups.config.functions"
).get_credentials(profile)
except Exception: # noqa: BLE001 - no stored key is a valid state
return None
return creds.get("api_key") if creds else None
return load_api_key(profile)


def __getattr__(name):
Expand Down
29 changes: 25 additions & 4 deletions runpod/_hosts.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@
RUNPOD_CONSOLE_URL web console base URL (default https://console.runpod.io)
RUNPOD_PROXY_DOMAIN pod HTTP proxy domain (default proxy.runpod.net)
RUNPOD_ENDPOINT_BASE_URL serverless base URL (default https://api.runpod.ai/v2)
RUNPOD_API_BASE_URL control-plane base URL (default https://api.runpod.io)
RUNPOD_HAPI_URL host API base URL (default https://hapi.runpod.net)
The endpoint domain is the host of ``RUNPOD_ENDPOINT_BASE_URL``. When that is
unset or blank, a non-blank ``runpod.endpoint_url_base`` set programmatically
Expand All @@ -23,6 +25,8 @@
DEFAULT_CONSOLE_URL = "https://console.runpod.io"
DEFAULT_PROXY_DOMAIN = "proxy.runpod.net"
DEFAULT_ENDPOINT_BASE_URL = "https://api.runpod.ai/v2"
DEFAULT_API_BASE_URL = "https://api.runpod.io"
DEFAULT_HOST_API_URL = "https://hapi.runpod.net"


def _env(name: str, default: str) -> str:
Expand All @@ -35,6 +39,26 @@ def console_url() -> str:
return _env("RUNPOD_CONSOLE_URL", DEFAULT_CONSOLE_URL).rstrip("/")


def api_base_url() -> str:
"""control-plane API base URL."""
return _env("RUNPOD_API_BASE_URL", DEFAULT_API_BASE_URL).rstrip("/")


def host_api_base_url() -> str:
"""host API base URL for pod log snapshots."""
return _env("RUNPOD_HAPI_URL", DEFAULT_HOST_API_URL).rstrip("/")


def endpoint_base_url() -> str:
"""serverless API base URL with environment and module overrides."""
import runpod

module_base = (runpod.endpoint_url_base or "").strip()
return _env(

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

endpoint_base_url() gives RUNPOD_ENDPOINT_BASE_URL priority over a value assigned in code to runpod.endpoint_url_base. Before this PR, RunPodClient and the asyncio runner read runpod.endpoint_url_base directly. A user who sets runpod.endpoint_url_base = "https://custom" in a shell that also has the env var set now silently hits the env var's URL. Is that precedence intended? If so, a note in the docs/release notes would help; otherwise an explicit assignment in code should probably win.

"RUNPOD_ENDPOINT_BASE_URL", module_base or DEFAULT_ENDPOINT_BASE_URL
).rstrip("/")


def proxy_url(pod_id: str, port: Union[int, str]) -> str:
"""Public HTTP proxy URL for ``port`` on ``pod_id``."""
domain = _env("RUNPOD_PROXY_DOMAIN", DEFAULT_PROXY_DOMAIN).strip("/")
Expand All @@ -46,9 +70,6 @@ def endpoint_domain() -> str:
Load-balanced endpoints are served on ``<endpoint_id>.<endpoint_domain>``.
"""
import runpod

module_base = (runpod.endpoint_url_base or "").strip()
base = _env("RUNPOD_ENDPOINT_BASE_URL", module_base or DEFAULT_ENDPOINT_BASE_URL)
base = endpoint_base_url()
host = base.split("://", 1)[-1]
return host.split("/", 1)[0]
64 changes: 23 additions & 41 deletions runpod/api/graphql.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,29 +3,16 @@
"""

import json
import os
from typing import Any, Dict, Optional

import requests

from runpod import error
from runpod.auth import resolve_api_key as _resolve_api_key
from runpod.user_agent import USER_AGENT

HTTP_STATUS_UNAUTHORIZED = 401


def _graphql_url() -> str:
api_url_base = os.environ.get("RUNPOD_API_BASE_URL", "https://api.runpod.io")
return f"{api_url_base}/graphql"

from .http import HTTPClient, SyncHTTPClient
from .routes import Route

def _resolve_api_key(api_key: Optional[str]) -> str:
from runpod import api_key as global_api_key # pylint: disable=import-outside-toplevel, cyclic-import

effective_api_key = api_key or global_api_key
if not effective_api_key:
raise error.AuthenticationError("No API key provided")
return effective_api_key
HTTP_STATUS_UNAUTHORIZED = 401


def _build_headers(api_key: Optional[str]) -> Dict[str, str]:
Expand Down Expand Up @@ -66,19 +53,17 @@ def run_graphql_query(
"""
effective_api_key = _resolve_api_key(api_key)

response = requests.post(
_graphql_url(),
with SyncHTTPClient().stream(
Route("POST", "/graphql"),
headers=_build_headers(effective_api_key),
data=json.dumps(_build_payload(query, variables)),
timeout=30,
)

if response.status_code == HTTP_STATUS_UNAUTHORIZED:
raise error.AuthenticationError(
"Unauthorized request, please check your API key."
)

return _check_response(response.json(), query)
) as response:
if response.status_code == HTTP_STATUS_UNAUTHORIZED:
raise error.AuthenticationError(
"Unauthorized request, please check your API key."
)
return _check_response(response.json(), query)


async def run_graphql_query_async(
Expand All @@ -102,21 +87,18 @@ async def run_graphql_query_async(
is available. Login creates its auth request this way so a
stale stored key cannot fail the request.
"""
import aiohttp # pylint: disable=import-outside-toplevel

effective_api_key = None if anonymous else _resolve_api_key(api_key)

client_timeout = aiohttp.ClientTimeout(total=timeout)
async with aiohttp.ClientSession(timeout=client_timeout) as session:
async with session.post(
_graphql_url(),
headers={**_build_headers(effective_api_key), **(headers or {})},
json=_build_payload(query, variables),
) as response:
if response.status == HTTP_STATUS_UNAUTHORIZED:
raise error.AuthenticationError(
"Unauthorized request, please check your API key."
)
response_json = await response.json()
async with HTTPClient().stream(
Route("POST", "/graphql"),
headers={**_build_headers(effective_api_key), **(headers or {})},
json=_build_payload(query, variables),
timeout=timeout,
) as response:
if response.status == HTTP_STATUS_UNAUTHORIZED:
raise error.AuthenticationError(
"Unauthorized request, please check your API key."
)
response_json = await response.json()

return _check_response(response_json, query)
138 changes: 138 additions & 0 deletions runpod/api/http.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
"""shared HTTP sessions, request lifetimes, and response decoding."""

from contextlib import asynccontextmanager, contextmanager
from typing import Mapping

import aiohttp
import requests
from yarl import URL

from runpod.user_agent import USER_AGENT

from .routes import Route, api_base_url


class HTTPClient:
"""an async transport with an explicitly scoped connection pool."""

def __init__(
self,
base_url: str | None = None,
*,
headers: Mapping[str, str] | None = None,
session: aiohttp.ClientSession | None = None,
):
self.base_url = api_base_url() if base_url is None else base_url
self.headers = {"User-Agent": USER_AGENT} if session is None else {}
self.headers.update(headers or {})
self.session = session
self._owns_session = session is None

async def __aenter__(self):
if self.session is None:
self.session = aiohttp.ClientSession(cookie_jar=aiohttp.DummyCookieJar())
elif self.session.closed:
raise RuntimeError("the supplied HTTP session is closed")
self.session._retry_connection = False
return self

async def __aexit__(self, *args):
await self.close()

async def close(self):
if self._owns_session and self.session is not None:
session, self.session = self.session, None
await session.close()

@asynccontextmanager
async def stream(self, route: Route, *, timeout=30, headers=None, **kwargs):
if self.session is None:
async with HTTPClient(self.base_url, headers=self.headers) as client:
async with client.stream(
route, timeout=timeout, headers=headers, **kwargs
) as response:
yield response
return
self.session._retry_connection = False

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This runs on every stream() call, and __aenter__ does the same at line 36, including when the caller passed their own aiohttp session (the asyncio runner wraps the caller's session at asyncio_runner.py 50, 131, 183, 204, 219). That permanently changes private state on a session we don't own. As I read the aiohttp source, the flag turns off the automatic retry of idempotent requests on a stale keep-alive connection, so a long-lived status()/output() poll could now fail with ServerDisconnectedError where it used to be retried. I have not reproduced this against a live server. Is disabling retry intentional for non-idempotent POSTs only? If so, could it be set only on sessions the client owns and only for non-idempotent methods?

if not isinstance(timeout, aiohttp.ClientTimeout):
timeout = aiohttp.ClientTimeout(total=timeout)
kwargs.setdefault("allow_redirects", False)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

stream() sets allow_redirects=False, but the 3xx check lives only in HTTPClient.request(). RESTClient.request and AsyncRESTClient.request override request() without that check, and stream() callers (artifact upload via Route("PUT", "") + raise_for_status, targets._request_json, get_json, tasks.poll_result) never see it. A 302 with an empty body makes run_rest_request return None (callers then fail with TypeError), the upload is treated as success because raise_for_status only fires at 400+, and the JSON paths raise a decode error instead of AppHTTPError. The old requests.post GraphQL path followed redirects, so this is also a behavior change. Could the 3xx check move into stream() or a shared response-check helper, with tests for a 3xx on REST and on the upload?

async with self.session.request(
route.method,
URL(route.url(self.base_url), encoded=True),
headers={**self.headers, **(headers or {})},
timeout=timeout,
**kwargs,
) as response:
yield response

async def request(self, route: Route, *, response_type="json", **kwargs):
if response_type not in {"json", "text"}:
raise ValueError("response_type must be json or text")
async with self.stream(route, **kwargs) as response:
response.raise_for_status()
if 300 <= response.status < 400:
raise aiohttp.ClientResponseError(
response.request_info,
response.history,
status=response.status,
message="unexpected redirect",
headers=response.headers,
)
if response_type == "text":
return await response.text()
if response.status == 204 or not await response.read():
return None
return await response.json(content_type=None)


class SyncHTTPClient:
"""a synchronous transport with the same routes and ownership rules."""

def __init__(
self,
base_url: str | None = None,
*,
headers: Mapping[str, str] | None = None,
session: requests.Session | None = None,
):
self.base_url = api_base_url() if base_url is None else base_url
self.headers = {"User-Agent": USER_AGENT} if session is None else {}
self.headers.update(headers or {})
self.session = session
self._owns_session = session is None

def __enter__(self):
if self.session is None:
self.session = requests.Session()
return self

def __exit__(self, *args):
self.close()

def close(self):
if self._owns_session and self.session is not None:
session, self.session = self.session, None
session.close()

@contextmanager
def stream(self, route: Route, *, timeout=30, headers=None, **kwargs):
if self.session is None:
with SyncHTTPClient(self.base_url, headers=self.headers) as client:
with client.stream(
route, timeout=timeout, headers=headers, **kwargs
) as response:
yield response
return
kwargs.setdefault("allow_redirects", False)
response = self.session.request(
route.method,
route.url(self.base_url),
headers={**self.headers, **(headers or {})},
timeout=timeout,
**kwargs,
)
try:
yield response
finally:
response.close()
10 changes: 0 additions & 10 deletions runpod/api/mutations/apps.py
Original file line number Diff line number Diff line change
Expand Up @@ -66,16 +66,6 @@
}
"""

MUTATION_CREATE_FLASH_AUTH_REQUEST = """
mutation createFlashAuthRequest {
createFlashAuthRequest {
id
status
expiresAt
}
}
"""

MUTATION_PREPARE_ARTIFACT_UPLOAD = """
mutation PrepareArtifactUpload($input: PrepareFlashArtifactUploadInput!) {
prepareFlashArtifactUpload(input: $input) {
Expand Down
10 changes: 0 additions & 10 deletions runpod/api/queries/apps.py
Original file line number Diff line number Diff line change
Expand Up @@ -65,13 +65,3 @@
}
}
"""

# no apiKey: the console shows the key only to the approver.
QUERY_FLASH_AUTH_REQUEST_STATUS = """
query flashAuthRequestStatus($flashAuthRequestId: String!) {
flashAuthRequestStatus(flashAuthRequestId: $flashAuthRequestId) {
id
status
}
}
"""
Loading
Loading