python-corekit 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

corekit/http/exceptions.py

@@ -0,0 +1,140 @@
+"""
+HTTP-specific exceptions.
+
+These live here, not in ``corekit.exceptions``, so the exception package does
+not have to import this layer. The bases (``CoreHTTPException`` and the
+retryable / non-retryable variants) still come from there.
+"""
+
+from http import HTTPMethod
+from typing import Any
+
+from corekit.exceptions.base import (
+    InternalCoreException,
+    NonRetryableCoreHTTPException,
+    RetryableCoreHTTPException,
+)
+from corekit.exceptions.enum import Retryability
+from corekit.http.status import HTTPStatusCode
+
+__all__ = [
+    "BadGatewayException",
+    "BadRequestException",
+    "ConflictErrorException",
+    "ForbiddenException",
+    "GatewayTimeoutException",
+    "InternalServerErrorException",
+    "NotFoundException",
+    "ServiceUnavailableException",
+    "TooManyRequestsException",
+    "UnauthorizedException",
+    "UnprocessableEntityException",
+    "UnsupportedMediaTypeException",
+    "UnsupportedMethodError",
+    "URLMismatchError",
+    "RETRYABLE_STATUS_CODES",
+]
+
+
+class _CodedHTTPException:
+    """
+    Sets ``status_code`` from the class. The code is the type, so a caller
+    cannot pass a different one and have a ``GatewayTimeoutException`` that is
+    actually a 200.
+    """
+
+    code: HTTPStatusCode
+
+    def __init__(self, **kwargs: Any) -> None:
+        if "status_code" in kwargs:
+            raise TypeError(f"{type(self).__name__} does not accept status_code; it is always {int(self.code)}")
+        super().__init__(status_code=self.code, **kwargs)
+
+
+class BadRequestException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.BAD_REQUEST
+
+
+class UnauthorizedException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.UNAUTHORIZED
+
+
+class ForbiddenException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.FORBIDDEN
+
+
+class NotFoundException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.NOT_FOUND
+
+
+class ConflictErrorException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.CONFLICT
+
+
+class UnsupportedMediaTypeException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.UNSUPPORTED_MEDIA_TYPE
+
+
+class UnprocessableEntityException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.UNPROCESSABLE_ENTITY
+
+
+class TooManyRequestsException(_CodedHTTPException, RetryableCoreHTTPException):
+    code = HTTPStatusCode.TOO_MANY_REQUESTS
+
+
+class InternalServerErrorException(_CodedHTTPException, RetryableCoreHTTPException):
+    code = HTTPStatusCode.INTERNAL_SERVER_ERROR
+
+
+class BadGatewayException(_CodedHTTPException, RetryableCoreHTTPException):
+    code = HTTPStatusCode.BAD_GATEWAY
+
+
+class ServiceUnavailableException(_CodedHTTPException, RetryableCoreHTTPException):
+    code = HTTPStatusCode.SERVICE_UNAVAILABLE
+
+
+class GatewayTimeoutException(_CodedHTTPException, RetryableCoreHTTPException):
+    code = HTTPStatusCode.GATEWAY_TIMEOUT
+
+
+# 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.
+# Derived from the typed exceptions so this set cannot drift from retryability.
+RETRYABLE_STATUS_CODES = frozenset(
+    {
+        TooManyRequestsException.code,
+        InternalServerErrorException.code,
+        BadGatewayException.code,
+        ServiceUnavailableException.code,
+        GatewayTimeoutException.code,
+    }
+)
+
+
+class URLMismatchError(InternalCoreException):
+    """
+    Raised when an absolute URL does not share the client's base URL.
+    """
+
+    def __init__(self, url: str, base_url: str) -> None:
+        super().__init__(
+            message=f"URL {url} does not match base URL {base_url}",
+            retryable=Retryability.NON_RETRYABLE,
+        )
+        self.url = url
+        self.base_url = base_url
+
+
+class UnsupportedMethodError(InternalCoreException):
+    """
+    Raised when a client is asked for an HTTP method it does not implement.
+    """
+
+    def __init__(self, method: HTTPMethod) -> None:
+        super().__init__(
+            message=f"Method {method} is not supported",
+            retryable=Retryability.NON_RETRYABLE,
+        )
+        self.method = method

corekit/http/response.py

@@ -1,12 +1,61 @@
 from pydantic import BaseModel, Field
 
+from corekit.exceptions import CoreHTTPException
+from corekit.http.exceptions import (
+    BadGatewayException,
+    ConflictErrorException,
+    ForbiddenException,
+    GatewayTimeoutException,
+    InternalServerErrorException,
+    NotFoundException,
+    ServiceUnavailableException,
+    TooManyRequestsException,
+    UnauthorizedException,
+    UnprocessableEntityException,
+)
+from corekit.http.status import HTTPStatusCode
 from corekit.schemas.pydantic.fields import DefaultDictField
 from corekit.schemas.types import AnyDict
 
 
 class BaseApiResponse(BaseModel):
-    status_code: int = Field(..., description="HTTP status code")
+    status_code: HTTPStatusCode | int = Field(..., description="HTTP status code")
     text: str = Field(..., description="Response text")
     data: AnyDict = DefaultDictField()
     headers: AnyDict = DefaultDictField()
     cookies: AnyDict = DefaultDictField()
+
+    @property
+    def ok(self) -> bool:
+        """
+        Whether the status is below 400. A failure is still a response.
+        """
+        return int(self.status_code) < 400
+
+    def raise_for_status(self) -> "BaseApiResponse":
+        """
+        Raise a typed HTTP exception for a failure status.
+
+        Opt-in. ``request`` still returns the failure so existing callers that
+        read ``status_code`` keep working.
+        """
+        if self.ok:
+            return self
+
+        typed = {
+            int(UnauthorizedException.code): UnauthorizedException,
+            int(ForbiddenException.code): ForbiddenException,
+            int(NotFoundException.code): NotFoundException,
+            int(ConflictErrorException.code): ConflictErrorException,
+            int(UnprocessableEntityException.code): UnprocessableEntityException,
+            int(TooManyRequestsException.code): TooManyRequestsException,
+            int(InternalServerErrorException.code): InternalServerErrorException,
+            int(BadGatewayException.code): BadGatewayException,
+            int(ServiceUnavailableException.code): ServiceUnavailableException,
+            int(GatewayTimeoutException.code): GatewayTimeoutException,
+        }
+        detail = self.text or f"HTTP {int(self.status_code)}"
+        exception_type = typed.get(int(self.status_code))
+        if exception_type is None:
+            raise CoreHTTPException(status_code=int(self.status_code), detail=detail)
+        raise exception_type(detail=detail)

corekit/http/status.py

@@ -0,0 +1,89 @@
+"""
+HTTP codes
+See HTTP Status Code Registry:
+https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
+
+And RFC 2324 - https://tools.ietf.org/html/rfc2324
+"""
+
+from corekit.schemas import IntegerEnum
+
+__all__ = ["HTTPStatusCode"]
+
+
+class HTTPStatusCode(IntegerEnum):
+    CONTINUE = 100
+    SWITCHING_PROTOCOLS = 101
+    PROCESSING = 102
+    EARLY_HINTS = 103
+    OK = 200
+    CREATED = 201
+    ACCEPTED = 202
+    NON_AUTHORITATIVE_INFORMATION = 203
+    NO_CONTENT = 204
+    RESET_CONTENT = 205
+    PARTIAL_CONTENT = 206
+    MULTI_STATUS = 207
+    ALREADY_REPORTED = 208
+    IM_USED = 226
+    MULTIPLE_CHOICES = 300
+    MOVED_PERMANENTLY = 301
+    FOUND = 302
+    SEE_OTHER = 303
+    NOT_MODIFIED = 304
+    USE_PROXY = 305
+    RESERVED = 306
+    TEMPORARY_REDIRECT = 307
+    PERMANENT_REDIRECT = 308
+    BAD_REQUEST = 400
+    UNAUTHORIZED = 401
+    PAYMENT_REQUIRED = 402
+    FORBIDDEN = 403
+    NOT_FOUND = 404
+    METHOD_NOT_ALLOWED = 405
+    NOT_ACCEPTABLE = 406
+    PROXY_AUTHENTICATION_REQUIRED = 407
+    REQUEST_TIMEOUT = 408
+    CONFLICT = 409
+    GONE = 410
+    LENGTH_REQUIRED = 411
+    PRECONDITION_FAILED = 412
+    REQUEST_ENTITY_TOO_LARGE = 413
+    REQUEST_URI_TOO_LONG = 414
+    UNSUPPORTED_MEDIA_TYPE = 415
+    REQUESTED_RANGE_NOT_SATISFIABLE = 416
+    EXPECTATION_FAILED = 417
+    IM_A_TEAPOT = 418
+    MISDIRECTED_REQUEST = 421
+    UNPROCESSABLE_ENTITY = 422
+    LOCKED = 423
+    FAILED_DEPENDENCY = 424
+    TOO_EARLY = 425
+    UPGRADE_REQUIRED = 426
+    PRECONDITION_REQUIRED = 428
+    TOO_MANY_REQUESTS = 429
+    REQUEST_HEADER_FIELDS_TOO_LARGE = 431
+    UNAVAILABLE_FOR_LEGAL_REASONS = 451
+    INTERNAL_SERVER_ERROR = 500
+    NOT_IMPLEMENTED = 501
+    BAD_GATEWAY = 502
+    SERVICE_UNAVAILABLE = 503
+    GATEWAY_TIMEOUT = 504
+    HTTP_VERSION_NOT_SUPPORTED = 505
+    VARIANT_ALSO_NEGOTIATES = 506
+    INSUFFICIENT_STORAGE = 507
+    LOOP_DETECTED = 508
+    NOT_EXTENDED = 510
+    NETWORK_AUTHENTICATION_REQUIRED = 511
+
+    @classmethod
+    def coerce(cls, code: int) -> "HTTPStatusCode | int":
+        """
+        Return the enum member for a known status, or the raw code otherwise.
+
+        Proxies and CDNs emit statuses this registry does not name. Callers
+        should still get the numeric code rather than a failed response parse.
+        """
+        if cls.is_member(code):
+            return cls.from_int(code)
+        return code

corekit/jobs/__init__.py

@@ -0,0 +1,26 @@
+"""
+Background tasks, independent of any queue.
+
+Define a task by subclassing ``Task`` or ``ScheduledTask``; it registers itself
+by name when the class is defined. A worker calls ``run_task(name, payload)``,
+which builds the task from its own registry and runs it.
+
+Nothing here imports a queue library. Bind these to RQ, Celery or anything else
+with a small adapter, and keep the tasks themselves portable.
+
+Arguments cross the queue as JSON, never as a serialized object: pickle and dill
+execute code while loading, so a queue holding objects turns write access into
+code execution in a worker.
+"""
+
+from corekit.jobs.registry import TaskNotRegisteredError, task_registry
+from corekit.jobs.runner import run_task
+from corekit.jobs.task import ScheduledTask, Task
+
+__all__ = [
+    "ScheduledTask",
+    "Task",
+    "TaskNotRegisteredError",
+    "run_task",
+    "task_registry",
+]

corekit/jobs/registry.py

@@ -0,0 +1,87 @@
+"""
+The task registry.
+
+A worker rebuilds a task from a name, so the name has to resolve to a class in
+the worker's *own* code. That is the whole security property: the queue chooses
+which registered task runs, never what code exists.
+
+``SmartRegistry`` normalizes keys, so ``"NightlyBackup"``, ``"nightly_backup"``
+and ``"nightly backup"`` all address the same task.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from corekit.registry import SmartRegistry
+
+if TYPE_CHECKING:
+    from corekit.jobs.task import Task
+
+__all__ = ["TaskNotRegisteredError", "task_registry"]
+
+
+class TaskNotRegisteredError(LookupError):
+    """
+    Raised when a queued name matches no registered task.
+    """
+
+
+class _TaskRegistry:
+    """
+    Every concrete ``Task`` subclass, keyed by name.
+
+    Registration happens when a subclass is defined, so importing the module
+    that declares a task is what makes it runnable. A worker must therefore
+    import its tasks before it starts consuming the queue.
+    """
+
+    def __init__(self) -> None:
+        self._registry = SmartRegistry()
+
+    def register(self, task_class: type["Task"]) -> None:
+        """
+        Register a task class under its name.
+        """
+        self._registry[task_class.task_name or task_class.__name__] = task_class
+
+    def get(self, name: str) -> type["Task"]:
+        """
+        Look up a task class by name.
+
+        Raises:
+            TaskNotRegisteredError: If nothing is registered under that name.
+                Usually means the module declaring the task was never imported
+                by this worker.
+        """
+        task_class = self._registry.get(name)
+        if task_class is None:
+            known = ", ".join(sorted(self._registry.keys())) or "none"
+            raise TaskNotRegisteredError(
+                f"No task registered as '{name}'. Import the module that defines it before "
+                f"running the worker. Registered: {known}."
+            )
+        return task_class
+
+    def build(self, name: str) -> "Task":
+        """
+        Construct the task registered under ``name``.
+        """
+        return self.get(name)()
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._registry
+
+    def __len__(self) -> int:
+        return len(self._registry)
+
+    def __iter__(self) -> Any:
+        return iter(self._registry)
+
+    @property
+    def names(self) -> list[str]:
+        """
+        The registered task names, normalized and sorted.
+        """
+        return sorted(self._registry.keys())
+
+
+task_registry = _TaskRegistry()

corekit/jobs/runner.py

@@ -0,0 +1,80 @@
+"""
+The worker entrypoint.
+
+``run_task`` is what a queue calls. It takes a name and a JSON payload, builds
+the task from the worker's own registry and runs it -- so a queue entry selects
+among the tasks this worker already has, and cannot introduce code.
+
+Point the queue at this function rather than at a bound method::
+
+    queue.enqueue(run_task, "NightlyBackup", task.payload("db"))
+
+Enqueueing a bound method makes the queue serialize the instance, which is the
+thing worth avoiding.
+"""
+
+import asyncio
+import inspect
+import logging
+from typing import Any
+
+from corekit.jobs.registry import task_registry
+from corekit.utils.payload import decode_payload
+
+__all__ = ["run_task"]
+
+logger = logging.getLogger(__name__)
+
+
+def run_task(task_name: str, payload: str | bytes | None = None) -> Any:
+    """
+    Build the named task and run it.
+
+    ``success`` runs after ``task_function`` returns; ``failure`` runs if it
+    raises, and the original exception is re-raised so the queue records the
+    job as failed. A hook that raises does not mask the original error.
+    ``last_result`` and ``last_error`` are set on the task before the hook
+    runs. A coroutine ``task_function`` is awaited. ``timeout`` is not applied
+    here; the scheduling adapter owns that.
+
+    Args:
+        task_name: The registered name of the task to run.
+        payload: JSON arguments from ``Task.payload``. Empty means no arguments.
+
+    Returns:
+        Whatever ``task_function`` returns.
+
+    Raises:
+        TaskNotRegisteredError: If no task is registered under that name.
+        ValueError: If the payload is not the expected JSON object.
+    """
+    args, kwargs = decode_payload(payload)
+    task = task_registry.build(task_name)
+
+    try:
+        result = task.task_function(*args, **kwargs)
+        if inspect.iscoroutine(result):
+            result = asyncio.run(result)
+    except Exception as exc:
+        task.last_result = None
+        task.last_error = exc
+        _run_hook(task, "failure", args, kwargs)
+        raise
+
+    task.last_result = result
+    task.last_error = None
+    _run_hook(task, "success", args, kwargs)
+    return result
+
+
+def _run_hook(task: Any, hook_name: str, args: list[Any], kwargs: dict[str, Any]) -> None:
+    """
+    Run a success or failure hook without letting it replace the real outcome.
+
+    A raising ``failure`` hook would otherwise mask the exception that caused
+    it, leaving the job recorded under the wrong error.
+    """
+    try:
+        getattr(task, hook_name)(*args, **kwargs)
+    except Exception:
+        logger.exception(f"Task {task.name} '{hook_name}' hook raised; the task's own outcome stands")

corekit/jobs/task.py

@@ -0,0 +1,173 @@
+"""
+Background tasks, independent of any queue.
+
+``Task`` describes work and how to name it; nothing here imports a queue
+library, so the same task runs under RQ, Celery, a cron entry or a test with no
+queue at all. An adapter binds it to whichever backend an application uses --
+see ``corekit.jobs.runner``.
+
+A task is identified by name and constructed by the worker from its own code::
+
+    class NightlyBackup(ScheduledTask):
+        interval = 86400
+
+        def task_function(self, target: str) -> None:
+            ...
+
+The queue carries ``("NightlyBackup", '{"args": ["db"], "kwargs": {}}')`` and
+never a serialized object, so writing to the queue cannot run arbitrary code in
+a worker.
+"""
+
+import abc
+import logging
+from datetime import datetime, timedelta
+from typing import Any
+
+from corekit.jobs.registry import task_registry
+from corekit.utils.payload import encode_payload
+
+__all__ = ["ScheduledTask", "Task"]
+
+DEFAULT_TASK_TIMEOUT = 180
+
+
+def _declared_abstract_methods(cls: type) -> tuple[str, ...]:
+    """
+    Names marked abstract anywhere in the class's ancestry.
+
+    Needed because ABCMeta has not yet populated ``__abstractmethods__`` when
+    ``__init_subclass__`` runs on the class being defined.
+    """
+    names = set()
+    for klass in cls.__mro__:
+        for name, value in vars(klass).items():
+            if getattr(value, "__isabstractmethod__", False):
+                names.add(name)
+    return tuple(names)
+
+
+class Task(abc.ABC):
+    """
+    A unit of background work.
+
+    Subclasses implement ``task_function`` and are registered by class name when
+    the class is defined, so a worker can rebuild one from a queued name.
+    """
+
+    #: Overrides the class name as the registered identity.
+    task_name: str | None = None
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """
+        Register every concrete subclass under its name.
+
+        Abstract subclasses are skipped -- an intermediate base with methods
+        still unimplemented is a shared parent, not a task a worker can run.
+        ``__abstractmethods__`` is set by ABCMeta *after* this hook runs, so the
+        class's own namespace is inspected instead.
+        """
+        super().__init_subclass__(**kwargs)
+        if not cls._is_abstract():
+            task_registry.register(cls)
+
+    @classmethod
+    def _is_abstract(cls) -> bool:
+        """
+        Whether this class still leaves an abstract method unimplemented.
+        """
+        for name in getattr(cls, "__abstractmethods__", ()) or _declared_abstract_methods(cls):
+            attribute = getattr(cls, name, None)
+            if getattr(attribute, "__isabstractmethod__", False):
+                return True
+        return False
+
+    def __init__(self, name: str | None = None) -> None:
+        """
+        Build the task. ``name`` overrides the registered identity for logging.
+        """
+        self.name = name or self.task_name or type(self).__name__
+        self.logger = logging.getLogger(type(self).__module__)
+        self.last_result: Any = None
+        self.last_error: BaseException | None = None
+
+    @abc.abstractmethod
+    def task_function(self, *args: Any, **kwargs: Any) -> None:
+        """
+        The work to perform. Arguments arrive as JSON-decoded data.
+        """
+        raise NotImplementedError
+
+    def success(self, *args: Any, **kwargs: Any) -> None:
+        """
+        Called after ``task_function`` returns. Override to add behaviour.
+
+        ``last_result`` is set before this runs. The call signature stays
+        ``(*args, **kwargs)`` so an existing override is not broken.
+        """
+        self.logger.info(f"Task {self.name} completed successfully")
+
+    def failure(self, *args: Any, **kwargs: Any) -> None:
+        """
+        Called when ``task_function`` raises. Override to add behaviour.
+
+        ``last_error`` is set before this runs. The call signature stays
+        ``(*args, **kwargs)`` so an existing override is not broken.
+        """
+        self.logger.error(f"Task {self.name} failed")
+
+    def payload(self, *args: Any, **kwargs: Any) -> str:
+        """
+        Encode arguments for the queue, raising now if they cannot cross it.
+        """
+        return encode_payload(args, kwargs)
+
+
+class ScheduledTask(Task):
+    """
+    A task that runs on a schedule.
+
+    ``interval``, ``repeat``, ``timeout``, and ``schedule_delay`` are for the
+    adapter that talks to a scheduler. ``run_task`` does not apply ``timeout``
+    and does not sleep for ``interval`` — wrapping a still-running queue job
+    would change production workers. Copy ``schedule_delay`` per instance so
+    one task cannot mutate the shared class dict.
+    """
+
+    interval: int | None = None
+    repeat: int | None = None
+    timeout: int = DEFAULT_TASK_TIMEOUT
+    schedule_delay: dict[str, int] = {"hours": 1}
+    start_time: datetime | None = None
+
+    #: Default arguments, encoded into the payload when the task is scheduled.
+    args: list[Any] | None = None
+    kwargs: dict[str, Any] | None = None
+
+    def __init__(self, name: str | None = None) -> None:
+        super().__init__(name)
+        # Class attributes are shared. Replace them on the instance so a later
+        # in-place edit cannot change every other scheduled task.
+        self.schedule_delay = dict(self.schedule_delay)
+        if self.args is not None:
+            self.args = list(self.args)
+        if self.kwargs is not None:
+            self.kwargs = dict(self.kwargs)
+
+    def get_start_time(self) -> datetime:
+        """
+        When the first run should happen.
+
+        ``start_time`` if set, otherwise ``schedule_delay`` from now. Timezone
+        handling is the scheduler's business, so this returns local time to
+        match what schedulers expect.
+        """
+        if self.start_time is not None:
+            return self.start_time
+        return datetime.now() + timedelta(**self.schedule_delay)
+
+    def scheduled_payload(self) -> str:
+        """
+        The encoded arguments this task is scheduled with.
+        """
+        return encode_payload(self.args or [], self.kwargs or {})

corekit/log_monitor/models.py

@@ -75,10 +75,16 @@ class PauseContainerAction(BaseAction):
 
 
 class ExecuteCommandAction(BaseAction):
-    """Execute a shell command"""
+    """
+    Run a command as an argument list.
+
+    ``command`` is split like a shell command line, then ``{container}`` is
+    filled in. It is not passed to a shell, so pipes and redirects are not
+    available.
+    """
 
     type: Literal[ActionType.EXECUTE_COMMAND] = ActionType.EXECUTE_COMMAND
-    command: str = Field(..., description="Command template with {container} placeholder")
+    command: str = Field(..., description="Argument list template with a {container} placeholder")
 
 
 # Union type for all actions