python-corekit 0.1.0__py3-none-any.whl

corekit/exceptions/http/exceptions.py

@@ -0,0 +1,37 @@
+from typing import Any
+
+from fastapi import status
+
+from corekit.exceptions.base import CustomHTTPException
+
+
+# 400 Errors
+class UnauthorizedException(CustomHTTPException):
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(status_code=status.HTTP_401_UNAUTHORIZED, **kwargs)
+
+
+class ForbiddenException(CustomHTTPException):
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(status_code=status.HTTP_403_FORBIDDEN, **kwargs)
+
+
+class NotFoundException(CustomHTTPException):
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(status_code=status.HTTP_404_NOT_FOUND, **kwargs)
+
+
+class ConflictErrorException(CustomHTTPException):
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(status_code=status.HTTP_409_CONFLICT, **kwargs)
+
+
+class UnprocessableEntityException(CustomHTTPException):
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, **kwargs)
+
+
+# 500 Errors
+class InternalServerErrorException(CustomHTTPException):
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, **kwargs)

corekit/exceptions/types.py

@@ -0,0 +1,17 @@
+"""
+Type aliases for exception classes.
+
+These name the *class*, for signatures that accept an exception type rather than
+an instance -- ``def handle(exc: CustomExceptionType) -> None``.
+
+``type(X)`` returns X's metaclass, which is ``type`` for an ordinary class and
+carries no information about X. ``type[X]`` is the subscript form these need.
+"""
+
+from corekit.exceptions.base import CustomException, CustomHTTPException
+
+__all__ = ["ArbitraryCustomExceptionType", "CustomExceptionType", "CustomHTTPExceptionType"]
+
+CustomExceptionType = type[CustomException]
+CustomHTTPExceptionType = type[CustomHTTPException]
+ArbitraryCustomExceptionType = CustomExceptionType | CustomHTTPExceptionType

corekit/files/__init__.py

@@ -0,0 +1,25 @@
+"""
+File reading and writing, with format handled by the manager.
+
+    with JsonFileManager("data.json") as file:
+        data = file.read()
+
+``FileManager`` handles opening, closing and mode checking; a subclass supplies
+``_serialize`` and ``_deserialize`` for its format.
+"""
+
+from corekit.files.base import FileContent, FileManager
+from corekit.files.enum import FileError, FileMode
+from corekit.files.json import JsonFileManager
+from corekit.files.pickle import PickleFileManager
+from corekit.files.toml import TomlFileManager
+
+__all__ = [
+    "FileContent",
+    "FileError",
+    "FileManager",
+    "FileMode",
+    "JsonFileManager",
+    "PickleFileManager",
+    "TomlFileManager",
+]

corekit/files/base.py

@@ -0,0 +1,117 @@
+from typing import Any, BinaryIO, Iterator, TextIO, Union
+
+from corekit.files.enum import FileError, FileMode
+
+FileContent: type[str | bytes] = Union[str, bytes]
+
+
+class FileManager:
+    def __init__(
+        self,
+        file_path: str,
+        mode: FileMode | None = None,
+        binary: bool = False,
+    ) -> None:
+        self.file_path = file_path
+        self._mode = mode or FileMode.get_default(binary=binary)
+        self._fp: BinaryIO | TextIO | None = None
+
+    @property
+    def mode(self) -> FileMode:
+        return self._mode
+
+    @property
+    def is_open(self) -> bool:
+        """
+        Helper method to determine if the file is open
+        """
+        return self._fp is not None
+
+    @property
+    def can_write(self) -> bool:
+        """
+        Helper method to determine if the file can be written to
+        """
+        return self.is_open and self._mode.can_write()
+
+    def _verify_file_status(self, should_be_open: bool) -> None:
+        if self.is_open != should_be_open:
+            raise ValueError(FileError.NOT_OPEN if should_be_open else FileError.OPEN)  # FIXME: raise custom exception
+
+    # ===== File Opening/Closing Methods =====
+    def _open(self) -> None:
+        """
+        Opens the file
+        """
+        self._verify_file_status(should_be_open=False)
+        self._fp = open(self.file_path, self.mode.value)
+
+    def _close(self) -> None:
+        self._verify_file_status(should_be_open=True)
+        self._fp.close()
+
+    # ===== Formatting Methods =====
+    def _serialize(self, content: Any) -> FileContent:
+        """
+        Helper method to serialize the content into the required format.
+        By default, does nothing and returns the input as is.
+        """
+        return content
+
+    def _deserialize(self, content: FileContent) -> Any:
+        """
+        Helper method to deserialize the content from the required format
+        into the working format. By default, does nothing and returns the
+        input as is.
+        """
+        return content
+
+    # ===== Context Manager Methods =====
+    def __enter__(self) -> "FileManager":
+        self._open()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self._close()
+
+    # ===== File Reading Methods =====
+    def read(self, size: int = -1) -> str | bytes:
+        """
+        Reads content from the file
+        """
+        self._verify_file_status(should_be_open=True)
+        return self._deserialize(self._fp.read(size))
+
+    def readline(self) -> str | bytes:
+        """
+        Reads a single line from the file
+        """
+        self._verify_file_status(should_be_open=True)
+        return self._deserialize(self._fp.readline())
+
+    def stream(self) -> Iterator[str | bytes]:
+        """
+        Streams the file line by line
+        """
+        self._verify_file_status(should_be_open=True)
+        for line in self._fp:
+            yield self._deserialize(line)
+
+    # ===== File Writing Methods =====
+    def write(self, content: FileContent, newline: bool = False, skip_verification: bool = False) -> None:
+        """
+        Writes content to the file
+        """
+        if not skip_verification:
+            self._verify_file_status(should_be_open=True)
+        if newline:
+            content += "\n"
+        self._fp.write(self._serialize(content))
+
+    def writelines(self, lines: list[FileContent], newline: bool = True) -> None:
+        """
+        Writes multiple lines to the file
+        """
+        self._verify_file_status(should_be_open=True)
+        for line in lines:
+            self.write(line, newline=newline, skip_verification=True)

corekit/files/enum.py

@@ -0,0 +1,30 @@
+from corekit.schemas.enum import StringEnum
+
+
+class FileMode(StringEnum):
+    APPEND = "a"
+    APPEND_BINARY = "ab"
+    APPEND_WRITE = "a+"
+    APPEND_WRITE_BINARY = "a+b"
+    READ = "r"
+    READ_BINARY = "rb"
+    READ_WRITE = "r+"
+    READ_WRITE_BINARY = "r+b"
+    WRITE = "w"
+    WRITE_BINARY = "wb"
+
+    @classmethod
+    def get_default(cls, binary: bool = False) -> "FileMode":
+        if binary:
+            return cls.READ_BINARY
+        return cls.READ
+
+    def can_write(self) -> bool:
+        if self in {FileMode.READ, FileMode.READ_BINARY}:
+            return False
+        return True
+
+
+class FileError(StringEnum):
+    NOT_OPEN = "File is not open"
+    OPEN = "File is open"

corekit/files/json.py

@@ -0,0 +1,12 @@
+import json as _json
+from typing import Any
+
+from corekit.files.base import FileContent, FileManager
+
+
+class JsonFileManager(FileManager):
+    def _serialize(self, content: Any) -> FileContent:
+        return _json.dumps(content)
+
+    def _deserialize(self, content: FileContent) -> Any:
+        return _json.loads(content)

corekit/files/pickle.py

@@ -0,0 +1,12 @@
+import pickle
+from typing import Any
+
+from corekit.files.base import FileContent, FileManager
+
+
+class PickleFileManager(FileManager):
+    def _serialize(self, content: Any) -> FileContent:
+        return pickle.dumps(content)
+
+    def _deserialize(self, content: FileContent) -> Any:
+        return pickle.loads(content)

corekit/files/toml.py

@@ -0,0 +1,43 @@
+"""
+Reading TOML files.
+
+    with TomlFileManager("corekit.toml") as file:
+        settings = file.read()
+
+Read-only: ``tomllib`` is the standard library's parser and it does not write.
+Attempting to write raises rather than silently doing nothing.
+"""
+
+import tomllib
+from typing import Any
+
+from corekit.files.base import FileContent, FileManager
+
+__all__ = ["TomlFileManager"]
+
+
+class TomlFileManager(FileManager):
+    """
+    A FileManager that parses TOML on read.
+
+    TOML must be read as bytes: ``tomllib.load`` decodes the file itself, so
+    that it can honour the encoding the format mandates.
+    """
+
+    def __init__(self, file_path: str, **kwargs: Any) -> None:
+        kwargs.setdefault("binary", True)
+        super().__init__(file_path, **kwargs)
+
+    def _deserialize(self, content: FileContent) -> Any:
+        """
+        Parse TOML text or bytes into a mapping.
+        """
+        if isinstance(content, str):
+            content = content.encode("utf-8")
+        return tomllib.loads(content.decode("utf-8"))
+
+    def _serialize(self, content: Any) -> FileContent:
+        """
+        Not supported: the standard library has no TOML writer.
+        """
+        raise NotImplementedError("TomlFileManager is read-only; tomllib does not write TOML.")

corekit/http/client.py

@@ -0,0 +1,176 @@
+"""
+A small HTTP client with retries.
+
+Subclass and give it a base URL::
+
+    class GithubClient(BaseApiClient):
+        '''
+        Talks to the GitHub API.
+        '''
+
+        @property
+        def base_url(self) -> str:
+            return "https://api.github.com"
+
+        @property
+        def headers(self) -> dict[str, str]:
+            return {"Authorization": f"Bearer {self.token}"}
+
+    client = GithubClient()
+    response = client.get("/user")          # or await client.async_get("/user")
+    response.data["login"]
+
+Every response comes back as a ``BaseApiResponse``, so callers see one shape
+regardless of what the endpoint returned. Requests that fail with a retryable
+status are retried with exponential backoff.
+"""
+
+from http import HTTPMethod
+from typing import Any
+from urllib.parse import urljoin
+
+import httpx
+
+from corekit.http.exponential_backoff import ExponentialBackoff
+from corekit.http.response import BaseApiResponse
+from corekit.observability.benchmarkable import Benchmarkable
+
+__all__ = ["BaseApiClient", "URLMismatchError"]
+
+# Statuses worth retrying: the server is busy or briefly unavailable, so the
+# same request may well succeed shortly. A 4xx other than 429 will not.
+RETRYABLE_STATUS_CODES = frozenset({429, 500, 502, 503, 504})
+
+
+class URLMismatchError(Exception):
+    """
+    Raised when an absolute URL is passed that does not share the base URL.
+    """
+
+
+class BaseApiClient(Benchmarkable):
+    """
+    Base for API clients. Override ``base_url`` and, usually, ``headers``.
+    """
+
+    def __init__(self, retries: int = 3, timeout: float = 30.0) -> None:
+        super().__init__()
+        self.retries = retries
+        self.timeout = timeout
+
+    @property
+    def headers(self) -> dict[str, str]:
+        """
+        Headers sent with every request.
+        """
+        return {}
+
+    @property
+    def base_url(self) -> str:
+        """
+        The root every relative path is resolved against.
+        """
+        return ""
+
+    def _build_url(self, url: str) -> str:
+        """
+        Resolve a path against the base URL, accepting an absolute URL that
+        already matches it.
+        """
+        if url.startswith(self.base_url):
+            return url
+        if url.startswith("http"):
+            raise URLMismatchError(f"URL {url} does not match base URL {self.base_url}")
+        return urljoin(self.base_url, url)
+
+    @staticmethod
+    def _to_response(raw: Any) -> BaseApiResponse:
+        """
+        Normalize an httpx response into a BaseApiResponse.
+
+        The body is decoded as JSON when it parses, and left as text otherwise,
+        so a caller never has to guard against a non-JSON error page.
+        """
+        try:
+            data = raw.json()
+        except ValueError:
+            data = {}
+        if not isinstance(data, dict):
+            data = {"data": data}
+
+        return BaseApiResponse(
+            status_code=raw.status_code,
+            text=raw.text,
+            data=data,
+            headers=dict(raw.headers),
+            cookies=dict(raw.cookies),
+        )
+
+    def _new_backoff(self) -> ExponentialBackoff:
+        return ExponentialBackoff(retries=self.retries)
+
+    def request(self, method: HTTPMethod, url: str, **kwargs: Any) -> BaseApiResponse:
+        """
+        Send a request, retrying retryable statuses.
+        """
+
+        target = self._build_url(url)
+        backoff = self._new_backoff()
+
+        while True:
+            with httpx.Client(timeout=self.timeout) as client:
+                raw = client.request(str(method), target, headers=self.headers, **kwargs)
+
+            if raw.status_code not in RETRYABLE_STATUS_CODES or backoff.did_timeout():
+                return self._to_response(raw)
+
+            self.warning(f"{method} {target} returned {raw.status_code}; retrying")
+            backoff.wait()
+
+    async def async_request(self, method: HTTPMethod, url: str, **kwargs: Any) -> BaseApiResponse:
+        """
+        Send a request asynchronously, retrying retryable statuses.
+        """
+
+        target = self._build_url(url)
+        backoff = self._new_backoff()
+
+        while True:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                raw = await client.request(str(method), target, headers=self.headers, **kwargs)
+
+            if raw.status_code not in RETRYABLE_STATUS_CODES or backoff.did_timeout():
+                return self._to_response(raw)
+
+            self.warning(f"{method} {target} returned {raw.status_code}; retrying")
+            await backoff.async_wait()
+
+    def get(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return self.request(HTTPMethod.GET, url, **kwargs)
+
+    def post(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return self.request(HTTPMethod.POST, url, **kwargs)
+
+    def put(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return self.request(HTTPMethod.PUT, url, **kwargs)
+
+    def patch(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return self.request(HTTPMethod.PATCH, url, **kwargs)
+
+    def delete(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return self.request(HTTPMethod.DELETE, url, **kwargs)
+
+    async def async_get(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.async_request(HTTPMethod.GET, url, **kwargs)
+
+    async def async_post(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.async_request(HTTPMethod.POST, url, **kwargs)
+
+    async def async_put(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.async_request(HTTPMethod.PUT, url, **kwargs)
+
+    async def async_patch(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.async_request(HTTPMethod.PATCH, url, **kwargs)
+
+    async def async_delete(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.async_request(HTTPMethod.DELETE, url, **kwargs)

corekit/http/exponential_backoff.py

@@ -0,0 +1,100 @@
+"""
+Exponential backoff with jitter.
+
+    backoff = ExponentialBackoff(retries=5)
+    while True:
+        try:
+            return do_something()
+        except TransientError:
+            backoff.wait()          # or `await backoff.async_wait()`
+
+Delays double each attempt up to ``max_delay``, with jitter so that several
+clients retrying together do not synchronize.
+"""
+
+import asyncio
+import random
+import time
+
+from corekit.exceptions.base import ExponentialBackoffTimeoutException
+from corekit.observability.loggable import Loggable
+
+__all__ = ["ExponentialBackoff"]
+
+
+class ExponentialBackoff(Loggable):
+    """
+    Tracks retry attempts and sleeps for an increasing delay between them.
+    """
+
+    def __init__(
+        self,
+        retries: int = 5,
+        base_delay: float = 1,
+        max_delay: float = 32,
+        jitter: bool = True,
+        exc_to_raise: BaseException | None = None,
+    ) -> None:
+        """
+        :param retries: attempts allowed before giving up.
+        :param base_delay: delay before the first retry, in seconds.
+        :param max_delay: ceiling for any single delay, in seconds.
+        :param jitter: randomize each delay, so concurrent clients desynchronize.
+        :param exc_to_raise: raised on exhaustion instead of the default. Use it
+            to surface the original failure rather than masking it with a
+            timeout that says nothing about what actually went wrong.
+        """
+        super().__init__()
+        self.retries = retries
+        self.base_delay = base_delay
+        self.max_delay = max_delay
+        self.jitter = jitter
+        self.exc_to_raise = exc_to_raise
+        self.attempt_num = 0
+
+    def did_timeout(self) -> bool:
+        """
+        Whether the allowed attempts are used up.
+        """
+        return self.attempt_num >= self.retries
+
+    def _get_delay(self) -> float:
+        """
+        The delay for the current attempt, raising once attempts are exhausted.
+        """
+        if self.did_timeout():
+            if self.exc_to_raise is not None:
+                raise self.exc_to_raise
+            raise ExponentialBackoffTimeoutException(attempts=self.attempt_num)
+
+        delay = min(self.base_delay * (2**self.attempt_num), self.max_delay)
+        if self.jitter:
+            delay *= random.uniform(0.5, 1.5)
+        return delay
+
+    def wait(self) -> None:
+        """
+        Block for the current delay, then advance the attempt counter.
+        """
+        delay = self._get_delay()
+        self.info(f"Attempt {self.attempt_num}, waiting {delay:.2f} seconds...")
+        time.sleep(delay)
+        self.attempt_num += 1
+
+    async def async_wait(self) -> None:
+        """
+        Await the current delay, then advance the attempt counter.
+
+        Use this in async code: ``wait`` blocks the event loop, stalling every
+        other task in the process.
+        """
+        delay = self._get_delay()
+        self.info(f"Attempt {self.attempt_num}, waiting {delay:.2f} seconds...")
+        await asyncio.sleep(delay)
+        self.attempt_num += 1
+
+    def restart(self) -> None:
+        """
+        Reset the attempt counter.
+        """
+        self.attempt_num = 0

corekit/http/response.py

@@ -0,0 +1,12 @@
+from pydantic import BaseModel, Field
+
+from corekit.schemas.pydantic.fields import DefaultDictField
+from corekit.schemas.types import AnyDict
+
+
+class BaseApiResponse(BaseModel):
+    status_code: int = Field(..., description="HTTP status code")
+    text: str = Field(..., description="Response text")
+    data: AnyDict = DefaultDictField()
+    headers: AnyDict = DefaultDictField()
+    cookies: AnyDict = DefaultDictField()

corekit/log_monitor/__init__.py

@@ -0,0 +1,23 @@
+"""
+Log-driven container automation.
+"""
+
+from corekit.log_monitor.models import (
+    Action,
+    ActionType,
+    ContainerConfig,
+    LogMonitorConfig,
+    Rule,
+    Severity,
+)
+from corekit.log_monitor.service import LogMonitor
+
+__all__ = [
+    "Action",
+    "ActionType",
+    "ContainerConfig",
+    "LogMonitor",
+    "LogMonitorConfig",
+    "Rule",
+    "Severity",
+]

corekit/log_monitor/constants.py

@@ -0,0 +1,8 @@
+DEFAULT_CONFIG_PATH = "config.yaml"
+
+# Bounded histories used for rate limiting, so memory does not grow with uptime.
+ACTION_COUNTS_MAX_LEN = 100
+RESTART_COUNTS_MAX_LEN = 10
+
+DEFAULT_MAX_WORKERS = 20
+SHUTDOWN_TIMEOUT_SECONDS = 30