quay/data/registry_model/interface.py

from abc import ABCMeta, abstractmethod
from six import add_metaclass

@add_metaclass(ABCMeta)
class RegistryDataInterface(object):
  """ Interface for code to work with the registry data model. The registry data model consists
      of all tables that store registry-specific information, such as Manifests, Blobs, Images,
      and Labels.
  """

  @abstractmethod
  def find_matching_tag(self, repository_ref, tag_names):
    """ Finds an alive tag in the repository matching one of the given tag names and returns it
        or None if none.
    """

  @abstractmethod
  def get_most_recent_tag(self, repository_ref):
    """ Returns the most recently pushed alive tag in the repository, if any. If none, returns
        None.
    """

  @abstractmethod
  def lookup_repository(self, namespace_name, repo_name, kind_filter=None):
    """ Looks up and returns a reference to the repository with the given namespace and name,
        or None if none. """

  @abstractmethod
  def get_manifest_for_tag(self, tag):
    """ Returns the manifest associated with the given tag. """

  @abstractmethod
  def lookup_manifest_by_digest(self, repository_ref, manifest_digest, allow_dead=False):
    """ Looks up the manifest with the given digest under the given repository and returns it
        or None if none. """

  @abstractmethod
  def get_legacy_images(self, repository_ref):
    """
    Returns an iterator of all the LegacyImage's defined in the matching repository.
    """

  @abstractmethod
  def get_legacy_image(self, repository_ref, docker_image_id, include_parents=False):
    """
    Returns the matching LegacyImages under the matching repository, if any. If none,
    returns None.
    """

  @abstractmethod
  def create_manifest_label(self, manifest, key, value, source_type_name, media_type_name=None):
    """ Creates a label on the manifest with the given key and value.

        Can raise InvalidLabelKeyException or InvalidMediaTypeException depending
        on the validation errors.
    """

  @abstractmethod
  def list_manifest_labels(self, manifest, key_prefix=None):
    """ Returns all labels found on the manifest. If specified, the key_prefix will filter the
        labels returned to those keys that start with the given prefix.
    """

  @abstractmethod
  def get_manifest_label(self, manifest, label_uuid):
    """ Returns the label with the specified UUID on the manifest or None if none. """

  @abstractmethod
  def delete_manifest_label(self, manifest, label_uuid):
    """ Delete the label with the specified UUID on the manifest. Returns the label deleted
        or None if none.
    """

  @abstractmethod
  def list_repository_tags(self, repository_ref, include_legacy_images=False):
    """
    Returns a list of all the active tags in the repository. Note that this can be a *heavy*
    operation on repositories with a lot of tags, and should be avoided for more targetted
    operations wherever possible.
    """

  @abstractmethod
  def list_repository_tag_history(self, repository_ref, page=1, size=100, specific_tag_name=None):
    """
    Returns the history of all tags in the repository (unless filtered). This includes tags that
    have been made in-active due to newer versions of those tags coming into service.
    """

  @abstractmethod
  def get_repo_tag(self, repository_ref, tag_name, include_legacy_image=False):
    """
    Returns the latest, *active* tag found in the repository, with the matching name
    or None if none.
    """

  @abstractmethod
  def retarget_tag(self, repository_ref, tag_name, manifest_or_legacy_image,
                   is_reversion=False):
    """
    Creates, updates or moves a tag to a new entry in history, pointing to the manifest or
    legacy image specified. If is_reversion is set to True, this operation is considered a
    reversion over a previous tag move operation. Returns the updated Tag or None on error.
    """

  @abstractmethod
  def delete_tag(self, repository_ref, tag_name):
    """
    Deletes the latest, *active* tag with the given name in the repository.
    """

  @abstractmethod
  def change_repository_tag_expiration(self, tag, expiration_date):
    """ Sets the expiration date of the tag under the matching repository to that given. If the
        expiration date is None, then the tag will not expire. Returns a tuple of the previous
        expiration timestamp in seconds (if any), and whether the operation succeeded.
    """

  @abstractmethod
  def get_legacy_images_owned_by_tag(self, tag):
    """ Returns all legacy images *solely owned and used* by the given tag. """

  @abstractmethod
  def get_security_status(self, manifest_or_legacy_image):
    """ Returns the security status for the given manifest or legacy image or None if none. """

  @abstractmethod
  def backfill_manifest_for_tag(self, tag):
    """ Backfills a manifest for the V1 tag specified.
        If a manifest already exists for the tag, returns that manifest.

        NOTE: This method will only be necessary until we've completed the backfill, at which point
        it should be removed.
    """