secondshift 0.1.0b12__py3-none-any.whl

secondshift/connections/http_api/client.py

@@ -0,0 +1,161 @@
+"""Call one approved operation. The model supplies values, never the request shape."""
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote, urlencode
+
+import anyio
+from django.conf import settings
+
+from secondshift.connections.http_api.spec import (
+    BODY,
+    APIArgumentError,
+    APIError,
+    APIRequestError,
+)
+from secondshift.connections.models import Connection
+from secondshift.connections.outbound import RESPONSE_MAX_BYTES, outbound_client
+
+BEARER = "bearer"
+HEADER = "header"
+AUTH_TYPES = (BEARER, HEADER)
+HEADER_NAME_PATTERN = r"[A-Za-z0-9-]{1,64}"
+# Headers an owner may not use for the credential: they change how the request
+# is routed or framed.
+RESERVED_HEADERS = {
+    "host",
+    "content-length",
+    "content-type",
+    "transfer-encoding",
+    "connection",
+    "cookie",
+    "accept",
+    "accept-encoding",
+}
+SCALAR_TYPES = (str, int, float, bool)
+TEXT_MAX_CHARS = 64 * 1024
+
+
+@dataclass(frozen=True)
+class APIRequest:
+    method: str
+    url: str
+    body: Any = None
+
+
+def auth_header(settings_: dict[str, str], token: str) -> dict[str, str]:
+    if settings_.get("auth") == HEADER:
+        name = settings_.get("header", "")
+        if (
+            not re.fullmatch(HEADER_NAME_PATTERN, name)
+            or name.lower() in RESERVED_HEADERS
+        ):
+            raise APIError("The credential header name is not allowed.")
+        return {name: token}
+    return {"Authorization": f"Bearer {token}"}
+
+
+def path_value(value: Any) -> str:
+    """One path segment. Slashes, dots-only segments, and URLs are refused."""
+    if isinstance(value, bool) or not isinstance(value, SCALAR_TYPES):
+        raise APIArgumentError("Path values must be text or numbers.")
+    text = str(value)
+    if not text or text in {".", ".."} or "/" in text or "\\" in text or "://" in text:
+        raise APIArgumentError("A path value is not allowed.")
+    return quote(text, safe="")
+
+
+def query_values(value: Any) -> list[str]:
+    values = value if isinstance(value, list) else [value]
+    if any(item is None or not isinstance(item, SCALAR_TYPES) for item in values):
+        raise APIArgumentError("Query values must be text, numbers, or lists of them.")
+    return [
+        str(item).lower() if isinstance(item, bool) else str(item) for item in values
+    ]
+
+
+def build_request(
+    base_url: str, operation: dict[str, Any], arguments: dict[str, Any]
+) -> APIRequest:
+    declared = {item["name"]: item for item in operation["parameters"]}
+    unknown = set(arguments) - set(declared) - ({BODY} if operation["body"] else set())
+    if unknown:
+        raise APIArgumentError("The call has arguments the operation does not declare.")
+    path = operation["path"]
+    for name, item in declared.items():
+        if item["in"] != "path":
+            continue
+        if name not in arguments:
+            raise APIArgumentError("A required path value is missing.")
+        path = path.replace("{" + name + "}", path_value(arguments[name]))
+    query: list[tuple[str, str]] = []
+    for name, item in declared.items():
+        if item["in"] == "query" and arguments.get(name) is not None:
+            query += [(name, value) for value in query_values(arguments[name])]
+    url = base_url.rstrip("/") + path
+    if query:
+        url += "?" + urlencode(query)
+    return APIRequest(
+        method=operation["method"].upper(),
+        url=url,
+        body=arguments.get(BODY) if operation["body"] else None,
+    )
+
+
+def validate_api_connection(connection: Connection) -> None:
+    if (
+        connection.kind != Connection.Kind.API
+        or connection.provider != Connection.Provider.API
+        or connection.status != Connection.Status.CONNECTED
+        or not connection.access_token
+        or not connection.endpoint_url
+        or connection.token_expired
+    ):
+        raise APIError("This API connection is unavailable.")
+
+
+async def send(connection: Connection, request: APIRequest) -> dict[str, Any]:
+    """Status and body. No token, exception text, or redirect target leaks."""
+    headers = {
+        **auth_header(connection.settings, connection.access_token),
+        "Accept": "application/json, text/plain;q=0.5",
+    }
+    try:
+        with anyio.fail_after(settings.OUTBOUND_TIMEOUT_SECONDS):
+            async with outbound_client(headers) as client:
+                response = await client.request(
+                    request.method,
+                    request.url,
+                    json=request.body if request.body is not None else None,
+                )
+                raw = await response.aread()
+    except Exception:
+        raise APIRequestError(
+            "The API request failed. Check the service and token."
+        ) from None
+    if 300 <= response.status_code < 400:
+        return {
+            "status": response.status_code,
+            "ok": False,
+            "body": "The API redirected. SecondShift does not follow redirects.",
+        }
+    content_type = response.headers.get("content-type", "").split(";")[0].strip()
+    text = raw.decode("utf-8", errors="replace").replace(
+        connection.access_token, "[redacted]"
+    )
+    body: Any
+    if content_type == "application/json" or content_type.endswith("+json"):
+        try:
+            body = json.loads(text)
+        except ValueError:
+            body = text[:TEXT_MAX_CHARS]
+    elif content_type.startswith("text/") or not content_type:
+        body = text[:TEXT_MAX_CHARS]
+    else:
+        body = f"Unsupported content type: {content_type[:80]}"
+    result = {"status": response.status_code, "ok": response.is_success, "body": body}
+    if len(json.dumps(result).encode()) > RESPONSE_MAX_BYTES:
+        raise APIError("The API response exceeded the size limit.")
+    return result

secondshift/connections/http_api/connections.py

@@ -0,0 +1,187 @@
+"""Create, edit, and re-check HTTP API connections."""
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from django.db import IntegrityError, transaction
+
+from secondshift.connections.dao import binding_taken
+from secondshift.connections.http_api.client import (
+    AUTH_TYPES,
+    BEARER,
+    HEADER,
+    HEADER_NAME_PATTERN,
+    RESERVED_HEADERS,
+)
+from secondshift.connections.http_api.spec import APIError, Spec, load_spec
+from secondshift.connections.models import Connection
+from secondshift.connections.outbound import (
+    OutboundUrlError,
+    host_label,
+    validate_outbound_url,
+)
+from secondshift.connections.services import ConnectionConflict
+from secondshift.connections.tools import UnknownTools, store_tools
+from secondshift.workspaces.models import Workspace
+
+TOKEN_PATTERN = r"\S{1,2000}"
+# Connection.endpoint_url is a URLField with Django's default limit.
+BASE_URL_MAX_LENGTH = 200
+
+
+@dataclass(frozen=True)
+class SpecSummary:
+    title: str
+    servers: tuple[str, ...]
+    operations: int
+    read_only: int
+
+
+def summarize(spec_url: str, spec_text: str) -> SpecSummary:
+    spec = load_spec(spec_url, spec_text)
+    return SpecSummary(
+        title=spec.title,
+        servers=spec.servers,
+        operations=len(spec.operations),
+        read_only=sum(1 for item in spec.operations.values() if item.read_only),
+    )
+
+
+def clean_base_url(value: str) -> str:
+    """Where requests and the credential go. Checked with DNS, like webhooks."""
+    value = value.strip().rstrip("/")
+    if not value or len(value) > BASE_URL_MAX_LENGTH:
+        raise APIError("Enter the API base URL.")
+    try:
+        value = validate_outbound_url(value, "base URL")
+    except OutboundUrlError as error:
+        raise APIError(str(error)) from None
+    if "?" in value or "#" in value:
+        raise APIError("The base URL cannot have a query or fragment.")
+    return value
+
+
+def clean_auth(auth: str, header: str) -> dict[str, str]:
+    if auth not in AUTH_TYPES:
+        raise APIError("Choose how to send the credential.")
+    if auth == BEARER:
+        return {"auth": BEARER}
+    if (
+        not re.fullmatch(HEADER_NAME_PATTERN, header)
+        or header.lower() in RESERVED_HEADERS
+    ):
+        raise APIError("Enter a header name such as X-API-Key.")
+    return {"auth": HEADER, "header": header}
+
+
+def offered(spec: Spec) -> dict[str, Any]:
+    return {name: operation.definition() for name, operation in spec.operations.items()}
+
+
+def select_operations(
+    connection: Connection, operations: dict[str, Any], selected: list[str] | None
+) -> None:
+    """GET operations start selected. Anything else waits for the owner."""
+    try:
+        store_tools(connection, operations, selected)
+    except UnknownTools as error:
+        raise APIError("Choose operations from the spec.") from error
+
+
+def create_api_connection(
+    workspace: Workspace,
+    binding_key: str,
+    display_name: str,
+    spec_url: str,
+    spec_text: str,
+    base_url: str,
+    auth: str,
+    header: str,
+    token: str,
+) -> Connection:
+    if not re.fullmatch(TOKEN_PATTERN, token):
+        raise APIError("Enter the credential without spaces.")
+    if binding_taken(workspace.pk, binding_key):
+        raise ConnectionConflict("This binding already has a connection.")
+    # Cheap checks first, before downloading the spec.
+    auth_settings = clean_auth(auth, header)
+    base_url = clean_base_url(base_url)
+    spec = load_spec(spec_url, spec_text)
+    connection = Connection(
+        workspace=workspace,
+        provider=Connection.Provider.API,
+        kind=Connection.Kind.API,
+        binding_key=binding_key,
+        display_name=display_name.strip() or spec.title or host_label(base_url),
+        endpoint_url=base_url,
+        auth_strategy=Connection.AuthStrategy.API_KEY,
+        access_token=token,
+        metadata={
+            "target": host_label(base_url),
+            "spec_url": spec_url,
+            "settings": auth_settings,
+        },
+    )
+    select_operations(connection, offered(spec), None)
+    connection.full_clean()
+    try:
+        with transaction.atomic():
+            connection.save()
+    except IntegrityError:
+        raise ConnectionConflict("This binding already has a connection.") from None
+    return connection
+
+
+def update_api_connection(
+    connection: Connection,
+    display_name: str | None,
+    token: str | None,
+    base_url: str | None,
+    operations: list[str] | None,
+) -> Connection:
+    """A blank token keeps the current one. A new base URL is an explicit choice."""
+    if connection.kind != Connection.Kind.API:
+        raise ConnectionConflict("Only API connections can be edited here.")
+    if token:
+        if not re.fullmatch(TOKEN_PATTERN, token):
+            raise APIError("Enter the credential without spaces.")
+        connection.access_token = token
+    elif (
+        connection.status != Connection.Status.CONNECTED or not connection.access_token
+    ):
+        raise APIError("Enter a new credential to reconnect.")
+    if display_name is not None:
+        connection.display_name = display_name.strip() or connection.binding_key
+    if base_url is not None:
+        cleaned = clean_base_url(base_url)
+        connection.endpoint_url = cleaned
+        connection.metadata = {
+            **connection.metadata,
+            "target": host_label(cleaned),
+        }
+    if operations is not None:
+        select_operations(connection, connection.offered_tools, operations)
+    connection.status = Connection.Status.CONNECTED
+    connection.full_clean()
+    connection.save()
+    return connection
+
+
+def recheck_api_connection(connection: Connection) -> str:
+    """Load the spec again. The saved base URL never changes here."""
+    spec_url = connection.metadata.get("spec_url", "")
+    if not spec_url:
+        return (
+            "This connection uses a pasted spec, so there is nothing to download again."
+        )
+    spec = load_spec(spec_url, "")
+    operations = offered(spec)
+    kept = [name for name in connection.available_tools if name in operations]
+    select_operations(connection, operations, kept)
+    connection.save(update_fields=["available_tools", "metadata", "updated_at"])
+    message = f"Found {len(operations)} operations. {len(kept)} enabled."
+    base_url = connection.endpoint_url
+    if spec.servers and base_url not in spec.servers:
+        message += f" The spec now lists a different server. Requests still go to {host_label(base_url)}."
+    return message