quay/data/logs_model/interface.py

from abc import ABCMeta, abstractmethod
from six import add_metaclass


class LogsIterationTimeout(Exception):
    """
    Exception raised if logs iteration times out.
    """


@add_metaclass(ABCMeta)
class ActionLogsDataInterface(object):
    """
    Interface for code to work with the logs data model.

    The logs data model consists of all access for reading and writing action logs.
    """

    @abstractmethod
    def lookup_logs(
        self,
        start_datetime,
        end_datetime,
        performer_name=None,
        repository_name=None,
        namespace_name=None,
        filter_kinds=None,
        page_token=None,
        max_page_count=None,
    ):
        """
        Looks up all logs between the start_datetime and end_datetime, filtered by performer (a
        user), repository or namespace.

        Note that one (and only one) of the three can be specified. Returns a LogEntriesPage.
        `filter_kinds`, if specified, is a set/list of the kinds of logs to filter out.
        """

    @abstractmethod
    def lookup_latest_logs(
        self,
        performer_name=None,
        repository_name=None,
        namespace_name=None,
        filter_kinds=None,
        size=20,
    ):
        """
        Looks up latest logs of a specific kind, filtered by performer (a user), repository or
        namespace.

        Note that one (and only one) of the three can be specified. Returns a list of `Log`.
        """

    @abstractmethod
    def get_aggregated_log_counts(
        self,
        start_datetime,
        end_datetime,
        performer_name=None,
        repository_name=None,
        namespace_name=None,
        filter_kinds=None,
    ):
        """
        Returns the aggregated count of logs, by kind, between the start_datetime and end_datetime,
        filtered by performer (a user), repository or namespace.

        Note that one (and only one) of the three can be specified. Returns a list of
        AggregatedLogCount.
        """

    @abstractmethod
    def count_repository_actions(self, repository, day):
        """
        Returns the total number of repository actions over the given day, in the given repository
        or None on error.
        """

    @abstractmethod
    def queue_logs_export(
        self,
        start_datetime,
        end_datetime,
        export_action_logs_queue,
        namespace_name=None,
        repository_name=None,
        callback_url=None,
        callback_email=None,
        filter_kinds=None,
    ):
        """
        Queues logs between the start_datetime and end_time, filtered by a repository or namespace,
        for export to the specified URL and/or email address.

        Returns the ID of the export job queued or None if error.
        """

    @abstractmethod
    def log_action(
        self,
        kind_name,
        namespace_name=None,
        performer=None,
        ip=None,
        metadata=None,
        repository=None,
        repository_name=None,
        timestamp=None,
        is_free_namespace=False,
    ):
        """
        Logs a single action as having taken place.
        """

    @abstractmethod
    def yield_logs_for_export(
        self,
        start_datetime,
        end_datetime,
        repository_id=None,
        namespace_id=None,
        max_query_time=None,
    ):
        """
        Returns an iterator that yields bundles of all logs found between the start_datetime and
        end_datetime, optionally filtered by the repository or namespace. This function should be
        used for any bulk lookup operations, and should be implemented by implementors to put
        minimal strain on the backing storage for large operations. If there was an error in setting
        up, returns None.

        If max_query_time is specified, each iteration that yields a log bundle will have its
        queries run with a maximum timeout of that specified, and, if any exceed that threshold,
        LogsIterationTimeout will be raised instead of returning the logs bundle.
        """

    @abstractmethod
    def yield_log_rotation_context(self, cutoff_date, min_logs_per_rotation):
        """
        A generator that yields contexts implementing the LogRotationContextInterface. Each context
        represents a set of logs to be archived and deleted once the context completes without
        exceptions.

        For database logs, the LogRotationContext abstracts over a set of rows. When the context
        finishes, its associated rows get deleted.

        For Elasticsearch logs, the LogRotationContext abstracts over indices. When the context
        finishes, its associated index gets deleted.
        """


@add_metaclass(ABCMeta)
class LogRotationContextInterface(object):
    """
    Interface for iterating over a set of logs to be archived.
    """

    @abstractmethod
    def yield_logs_batch(self):
        """
        Generator yielding batch of logs and a filename for that batch.

        A batch is a subset of the logs part of the context.
        """