waveium 0.2.0__py3-none-any.whl

waveium/_sse.py

@@ -0,0 +1,497 @@
+"""SSE (Server-Sent Events) transport layer for the Waveium SDK.
+
+Implements the W3C SSE specification with auto-reconnection,
+keepalive handling, and configurable backoff. Used internally
+by StreamOperations to provide typed event streams.
+"""
+
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import (
+    AsyncIterator,
+    Dict,
+    Iterator,
+    List,
+    Optional,
+)
+
+import httpx
+
+logger = logging.getLogger("waveium")
+
+from .exceptions import (
+    AuthenticationError,
+    AuthorizationError,
+    NotFoundError,
+    StreamReconnectError,
+    StreamTimeoutError,
+    ValidationError,
+)
+from ._http import _handle_error_response
+
+# SSE-specific timeout: long read (server keepalive every 15s,
+# deadline 330s), normal connect/write/pool.
+SSE_TIMEOUT = httpx.Timeout(
+    connect=10.0,
+    read=360.0,
+    write=10.0,
+    pool=10.0,
+)
+
+# HTTP status codes that should not be retried
+_NON_RETRYABLE_STATUSES = {400, 401, 403, 404}
+
+
+@dataclass
+class RawSSEEvent:
+    """A single parsed SSE event from the wire."""
+
+    event: str = "message"
+    data: str = ""
+    id: Optional[str] = None
+    retry: Optional[int] = None
+
+
+def _parse_sse_lines(lines: Iterator[str]) -> Iterator[RawSSEEvent]:
+    """Parse SSE lines per the W3C EventSource specification.
+
+    Handles event, data, id, retry fields, multi-line data
+    concatenation, and comment (keepalive) filtering.
+
+    Args:
+        lines: Iterator of text lines from the SSE stream.
+
+    Yields:
+        Parsed RawSSEEvent instances.
+    """
+    current_event = "message"
+    current_data: List[str] = []
+    current_id: Optional[str] = None
+    current_retry: Optional[int] = None
+
+    for raw_line in lines:
+        line = raw_line.rstrip("\n").rstrip("\r")
+
+        # Empty line: dispatch event if data is non-empty
+        if not line:
+            if current_data:
+                yield RawSSEEvent(
+                    event=current_event,
+                    data="\n".join(current_data),
+                    id=current_id,
+                    retry=current_retry,
+                )
+            # Reset for next event
+            current_event = "message"
+            current_data = []
+            current_id = None
+            current_retry = None
+            continue
+
+        # Comment line (keepalive or debug)
+        if line.startswith(":"):
+            continue
+
+        # Field parsing
+        if ":" in line:
+            field_name, _, value = line.partition(":")
+            # Strip single leading space from value per spec
+            if value.startswith(" "):
+                value = value[1:]
+        else:
+            field_name = line
+            value = ""
+
+        if field_name == "event":
+            current_event = value
+        elif field_name == "data":
+            current_data.append(value)
+        elif field_name == "id":
+            current_id = value
+        elif field_name == "retry":
+            try:
+                current_retry = int(value)
+            except ValueError:
+                pass
+
+
+async def _async_parse_sse_lines(
+    lines: AsyncIterator[str],
+) -> AsyncIterator[RawSSEEvent]:
+    """Async version of _parse_sse_lines.
+
+    Args:
+        lines: Async iterator of text lines from the SSE stream.
+
+    Yields:
+        Parsed RawSSEEvent instances.
+    """
+    current_event = "message"
+    current_data: List[str] = []
+    current_id: Optional[str] = None
+    current_retry: Optional[int] = None
+
+    async for raw_line in lines:
+        line = raw_line.rstrip("\n").rstrip("\r")
+
+        if not line:
+            if current_data:
+                yield RawSSEEvent(
+                    event=current_event,
+                    data="\n".join(current_data),
+                    id=current_id,
+                    retry=current_retry,
+                )
+            current_event = "message"
+            current_data = []
+            current_id = None
+            current_retry = None
+            continue
+
+        if line.startswith(":"):
+            continue
+
+        if ":" in line:
+            field_name, _, value = line.partition(":")
+            if value.startswith(" "):
+                value = value[1:]
+        else:
+            field_name = line
+            value = ""
+
+        if field_name == "event":
+            current_event = value
+        elif field_name == "data":
+            current_data.append(value)
+        elif field_name == "id":
+            current_id = value
+        elif field_name == "retry":
+            try:
+                current_retry = int(value)
+            except ValueError:
+                pass
+
+
+@dataclass
+class SSEConnection:
+    """Synchronous SSE connection with auto-reconnection.
+
+    Handles the server's 5-minute connection timeout by
+    automatically reconnecting when a timeout event is received.
+    Network errors trigger exponential backoff.
+
+    Usage:
+        conn = SSEConnection(client, url, headers=headers)
+        with conn:
+            for event in conn:
+                process(event)
+    """
+
+    client: httpx.Client
+    url: str
+    headers: Dict[str, str] = field(default_factory=dict)
+    max_reconnects: int = 50
+    max_total_seconds: float = 7200.0
+    initial_retry_ms: int = 1000
+    max_retry_ms: int = 30000
+
+    _last_event_id: Optional[str] = field(default=None, init=False, repr=False)
+    _server_retry_ms: Optional[int] = field(
+        default=None, init=False, repr=False
+    )
+    _closed: bool = field(default=False, init=False, repr=False)
+
+    def __iter__(self) -> Iterator[RawSSEEvent]:
+        start_time = time.monotonic()
+        reconnect_count = 0
+        backoff_ms = self.initial_retry_ms
+        logger.debug("SSE connecting to %s", self.url)
+
+        while not self._closed:
+            # Check total time limit
+            elapsed = time.monotonic() - start_time
+            if elapsed >= self.max_total_seconds:
+                raise StreamTimeoutError(
+                    f"SSE stream exceeded maximum duration "
+                    f"of {self.max_total_seconds}s"
+                )
+
+            # Check reconnect limit
+            if reconnect_count > self.max_reconnects:
+                raise StreamReconnectError(
+                    f"SSE stream exceeded maximum reconnect "
+                    f"count of {self.max_reconnects}"
+                )
+
+            # Build request headers
+            request_headers = {
+                **self.headers,
+                "Accept": "text/event-stream",
+                "Cache-Control": "no-cache",
+            }
+            if self._last_event_id is not None:
+                request_headers["Last-Event-ID"] = self._last_event_id
+
+            try:
+                with self.client.stream(
+                    "GET",
+                    self.url,
+                    headers=request_headers,
+                    timeout=SSE_TIMEOUT,
+                ) as response:
+                    # Handle non-success status codes
+                    if response.status_code >= 400:
+                        if response.status_code in _NON_RETRYABLE_STATUSES:
+                            # Read body for error details
+                            response.read()
+                            raise _handle_error_response(response)
+                        # 5xx: will retry after backoff
+                        logger.warning(
+                            "SSE server error %d, retrying in %dms",
+                            response.status_code,
+                            backoff_ms,
+                        )
+                        reconnect_count += 1
+                        self._backoff_sleep(backoff_ms)
+                        backoff_ms = min(backoff_ms * 2, self.max_retry_ms)
+                        continue
+
+                    # Reset backoff on successful connection
+                    backoff_ms = self.initial_retry_ms
+                    is_timeout_reconnect = False
+                    logger.debug("SSE connected to %s", self.url)
+
+                    for event in _parse_sse_lines(response.iter_lines()):
+                        if self._closed:
+                            return
+
+                        # Track last event ID for reconnection
+                        if event.id is not None:
+                            self._last_event_id = event.id
+
+                        # Track server-suggested retry interval
+                        if event.retry is not None:
+                            self._server_retry_ms = event.retry
+
+                        # Timeout event: reconnect immediately
+                        if event.event == "timeout":
+                            logger.debug("SSE server timeout, reconnecting")
+                            is_timeout_reconnect = True
+                            reconnect_count += 1
+                            break
+
+                        yield event
+
+                    # If we exited the loop normally (stream ended)
+                    # without a timeout event, reconnect with backoff
+                    if not is_timeout_reconnect:
+                        if self._closed:
+                            return
+                        reconnect_count += 1
+                        retry_ms = (
+                            self._server_retry_ms
+                            if self._server_retry_ms is not None
+                            else backoff_ms
+                        )
+                        logger.debug(
+                            "SSE stream ended, reconnecting in %dms",
+                            retry_ms,
+                        )
+                        self._backoff_sleep(retry_ms)
+                        backoff_ms = min(backoff_ms * 2, self.max_retry_ms)
+
+            except (
+                httpx.RequestError,
+                httpx.StreamError,
+            ) as e:
+                if self._closed:
+                    return
+                reconnect_count += 1
+                if reconnect_count > self.max_reconnects:
+                    raise StreamReconnectError(
+                        f"SSE stream exceeded maximum reconnect "
+                        f"count of {self.max_reconnects}"
+                    ) from e
+                retry_ms = (
+                    self._server_retry_ms
+                    if self._server_retry_ms is not None
+                    else backoff_ms
+                )
+                logger.warning(
+                    "SSE connection error: %s, retrying in %dms",
+                    e,
+                    retry_ms,
+                )
+                self._backoff_sleep(retry_ms)
+                backoff_ms = min(backoff_ms * 2, self.max_retry_ms)
+
+            except (
+                AuthenticationError,
+                AuthorizationError,
+                NotFoundError,
+                ValidationError,
+            ):
+                # Non-retryable errors: propagate immediately
+                raise
+
+    def _backoff_sleep(self, ms: int) -> None:
+        """Sleep for backoff duration, respecting close signal."""
+        time.sleep(ms / 1000.0)
+
+    def close(self) -> None:
+        """Signal the connection to stop iterating."""
+        self._closed = True
+
+    def __enter__(self) -> "SSEConnection":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+@dataclass
+class AsyncSSEConnection:
+    """Asynchronous SSE connection with auto-reconnection.
+
+    Async counterpart of SSEConnection. Handles the server's
+    5-minute connection timeout and network errors with
+    automatic reconnection.
+
+    Usage:
+        conn = AsyncSSEConnection(client, url, headers=headers)
+        async with conn:
+            async for event in conn:
+                await process(event)
+    """
+
+    client: httpx.AsyncClient
+    url: str
+    headers: Dict[str, str] = field(default_factory=dict)
+    max_reconnects: int = 50
+    max_total_seconds: float = 7200.0
+    initial_retry_ms: int = 1000
+    max_retry_ms: int = 30000
+
+    _last_event_id: Optional[str] = field(default=None, init=False, repr=False)
+    _server_retry_ms: Optional[int] = field(
+        default=None, init=False, repr=False
+    )
+    _closed: bool = field(default=False, init=False, repr=False)
+
+    async def __aiter__(self) -> AsyncIterator[RawSSEEvent]:
+        import asyncio
+
+        start_time = time.monotonic()
+        reconnect_count = 0
+        backoff_ms = self.initial_retry_ms
+
+        while not self._closed:
+            elapsed = time.monotonic() - start_time
+            if elapsed >= self.max_total_seconds:
+                raise StreamTimeoutError(
+                    f"SSE stream exceeded maximum duration "
+                    f"of {self.max_total_seconds}s"
+                )
+
+            if reconnect_count > self.max_reconnects:
+                raise StreamReconnectError(
+                    f"SSE stream exceeded maximum reconnect "
+                    f"count of {self.max_reconnects}"
+                )
+
+            request_headers = {
+                **self.headers,
+                "Accept": "text/event-stream",
+                "Cache-Control": "no-cache",
+            }
+            if self._last_event_id is not None:
+                request_headers["Last-Event-ID"] = self._last_event_id
+
+            try:
+                async with self.client.stream(
+                    "GET",
+                    self.url,
+                    headers=request_headers,
+                    timeout=SSE_TIMEOUT,
+                ) as response:
+                    if response.status_code >= 400:
+                        if response.status_code in _NON_RETRYABLE_STATUSES:
+                            await response.aread()
+                            raise _handle_error_response(response)
+                        reconnect_count += 1
+                        await asyncio.sleep(backoff_ms / 1000.0)
+                        backoff_ms = min(backoff_ms * 2, self.max_retry_ms)
+                        continue
+
+                    backoff_ms = self.initial_retry_ms
+                    is_timeout_reconnect = False
+
+                    async for event in _async_parse_sse_lines(
+                        response.aiter_lines()
+                    ):
+                        if self._closed:
+                            return
+
+                        if event.id is not None:
+                            self._last_event_id = event.id
+
+                        if event.retry is not None:
+                            self._server_retry_ms = event.retry
+
+                        if event.event == "timeout":
+                            is_timeout_reconnect = True
+                            reconnect_count += 1
+                            break
+
+                        yield event
+
+                    if not is_timeout_reconnect:
+                        if self._closed:
+                            return
+                        reconnect_count += 1
+                        retry_ms = (
+                            self._server_retry_ms
+                            if self._server_retry_ms is not None
+                            else backoff_ms
+                        )
+                        await asyncio.sleep(retry_ms / 1000.0)
+                        backoff_ms = min(backoff_ms * 2, self.max_retry_ms)
+
+            except (
+                httpx.RequestError,
+                httpx.StreamError,
+            ) as e:
+                if self._closed:
+                    return
+                reconnect_count += 1
+                if reconnect_count > self.max_reconnects:
+                    raise StreamReconnectError(
+                        f"SSE stream exceeded maximum reconnect "
+                        f"count of {self.max_reconnects}"
+                    ) from e
+                retry_ms = (
+                    self._server_retry_ms
+                    if self._server_retry_ms is not None
+                    else backoff_ms
+                )
+                await asyncio.sleep(retry_ms / 1000.0)
+                backoff_ms = min(backoff_ms * 2, self.max_retry_ms)
+
+            except (
+                AuthenticationError,
+                AuthorizationError,
+                NotFoundError,
+                ValidationError,
+            ):
+                raise
+
+    async def close(self) -> None:
+        """Signal the connection to stop iterating."""
+        self._closed = True
+
+    async def __aenter__(self) -> "AsyncSSEConnection":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

waveium/async_client.py

@@ -0,0 +1,92 @@
+"""Asynchronous Waveium API client."""
+
+from typing import Optional
+
+from ._config import Config
+from ._http import AsyncHTTPClient
+from .resources import (
+    AsyncAuthResource,
+    AsyncEnvironmentsResource,
+    AsyncExecutionsResource,
+    AsyncOrganizationsResource,
+    AsyncProjectsResource,
+    AsyncRolesResource,
+    AsyncScenesResource,
+    AsyncTeamsResource,
+    AsyncUsersResource,
+)
+
+
+class AsyncClient:
+    """Asynchronous Waveium API client.
+
+    Example:
+        >>> import waveium
+        >>> async with waveium.AsyncClient(
+        ...     api_key="wvx_..."
+        ... ) as client:
+        ...     resp = await client.environments.create(
+        ...         name="My Environment"
+        ...     )
+        ...     env = resp.environment
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> None:
+        """Initialize async Waveium client.
+
+        Args:
+            api_key: API key for authentication. If not
+                provided, will try to load from
+                WAVEIUM_API_KEY environment variable.
+            base_url: Base URL for the Waveium API.
+                Defaults to production URL.
+            timeout: Request timeout in seconds.
+                Defaults to 60.0.
+            max_retries: Maximum number of retries for
+                failed requests. Defaults to 3.
+
+        Raises:
+            ConfigurationError: If configuration is invalid.
+        """
+        self._config = Config(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._config.validate()
+
+        self._http = AsyncHTTPClient(self._config)
+
+        # Initialize resources
+        self.auth = AsyncAuthResource(self._http)
+        self.environments = AsyncEnvironmentsResource(self._http)
+        self.scenes = AsyncScenesResource(self._http)
+        self.executions = AsyncExecutionsResource(self._http)
+        self.users = AsyncUsersResource(self._http)
+        self.organizations = AsyncOrganizationsResource(self._http)
+        self.roles = AsyncRolesResource(self._http)
+        self.teams = AsyncTeamsResource(self._http)
+        self.projects = AsyncProjectsResource(self._http)
+
+    async def close(self) -> None:
+        """Close the HTTP client and release resources."""
+        await self._http.close()
+
+    async def __aenter__(self) -> "AsyncClient":
+        """Enter async context manager."""
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        """Exit async context manager."""
+        await self.close()
+
+    def __repr__(self) -> str:
+        """Return string representation of client."""
+        return f"<Waveium AsyncClient base_url=" f"{self._config.base_url}>"

waveium/client.py

@@ -0,0 +1,90 @@
+"""Synchronous Waveium API client."""
+
+from typing import Optional
+
+from ._config import Config
+from ._http import HTTPClient
+from .resources import (
+    AuthResource,
+    EnvironmentsResource,
+    ExecutionsResource,
+    OrganizationsResource,
+    ProjectsResource,
+    RolesResource,
+    ScenesResource,
+    TeamsResource,
+    UsersResource,
+)
+
+
+class Client:
+    """Synchronous Waveium API client.
+
+    Example:
+        >>> import waveium
+        >>> client = waveium.Client(api_key="wvx_...")
+        >>> resp = client.environments.create(
+        ...     name="My Environment"
+        ... )
+        >>> env = resp.environment
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> None:
+        """Initialize Waveium client.
+
+        Args:
+            api_key: API key for authentication. If not
+                provided, will try to load from
+                WAVEIUM_API_KEY environment variable.
+            base_url: Base URL for the Waveium API.
+                Defaults to production URL.
+            timeout: Request timeout in seconds.
+                Defaults to 60.0.
+            max_retries: Maximum number of retries for
+                failed requests. Defaults to 3.
+
+        Raises:
+            ConfigurationError: If configuration is invalid.
+        """
+        self._config = Config(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._config.validate()
+
+        self._http = HTTPClient(self._config)
+
+        # Initialize resources
+        self.auth = AuthResource(self._http)
+        self.environments = EnvironmentsResource(self._http)
+        self.scenes = ScenesResource(self._http)
+        self.executions = ExecutionsResource(self._http)
+        self.users = UsersResource(self._http)
+        self.organizations = OrganizationsResource(self._http)
+        self.roles = RolesResource(self._http)
+        self.teams = TeamsResource(self._http)
+        self.projects = ProjectsResource(self._http)
+
+    def close(self) -> None:
+        """Close the HTTP client and release resources."""
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        """Enter context manager."""
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """Exit context manager."""
+        self.close()
+
+    def __repr__(self) -> str:
+        """Return string representation of client."""
+        return f"<Waveium Client base_url=" f"{self._config.base_url}>"