chore: core structure of base DataUpgrade lib and handlers for pre upgrade-charm

[marcoppenheimer]

Changes Made

feat: add dependency conflict validators

• build_complete_sem_ver() converts string versions into full major.minor.patch semantic versions, padding with 0s where not specified
  • etc 1.3 --> [1, 3, 0]
• All verification functions called in verify_inequality_requirements wrapper, returning boolean if passed arg version meets passed arg requirement
• Involved functions support version definition specification used by poetry, supporting:
  • Caret
  • Tilde
  • Wildcard
  • Inequality
    • NOTE - Choosing to support only > and >= for the time being, as an 'upgrade' implies increasing in version

      feat: strict typing of input dependencies with DependencyModel

• Charm authors can define a dict of arbitrarily named keys in their charm with value of the dependencies for the current version of the charm, passing it in to the constructor of DataUpgrade
• The Pydantic model evaluates these specified dependencies for compliance to the above-mentioned specification, and whether specified version is compatible with specified upgrade_supported
• REVIEW NOTE - Idea is to load back the persisted dependencies dict from relation data into the same type as the defined model, and use something like:

  if not old_deps >> new_deps:
      raise

  • Use of the bitshift operator is fairly weird, but I thought it was actually quite a nice override, very much welcome opinions here

    feat: custom Exceptions for various failure cases

• UpgradeError base-class
• ClusterNotReadyError to be raised during pre_upgrade_check() by charm authors
• UpgradeFailedError to be raised during upgrade_granted_event() handlers by charm authors

  feat: DataUpgrade object for handling and emitting of upgrade events

• Persists charm-author passed dependencies to relation data during upgrade-relation-created handler
• Exposes properties for use by charm authors for state, stored_dependencies, upgrade_stack
• Abstractmethods for pre_upgrade_check and build_upgrade_stack, to be overridden by charm authors
• pre_upgrade_check handler does the following:
  • Fails if not leader
  • Fails if ANY unit is already in the process of upgrading (by checking state)
  • Runs charm-author defined pre_upgrade_check
  • Runs charm-author defined build_upgrade_stack, writing it to relation data
  • Sets all units to state=waiting

    style: add ruff

• Basic ruff pyproject.toml specification, in preparation for a future PR to this repo to replace flake8 for all libraries