Use semver for document template metamodel version

Author: MarekSuchanek

packages/dsw-document-worker/CHANGELOG.md

@@ -7,6 +7,10 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Changed
+
+- Switch to use semver for document template metamodel versioning
+
 
 ## [4.21.0]
 

packages/dsw-document-worker/dsw/document_worker/consts.py

@@ -2,7 +2,8 @@
 CMD_CHANNEL = 'doc_worker'
 CMD_COMPONENT = 'doc_worker'
 COMPONENT_NAME = 'Document Worker'
-CURRENT_METAMODEL = 16
+CURRENT_METAMODEL_MAJOR = 17
+CURRENT_METAMODEL_MINOR = 0
 DEFAULT_ENCODING = 'utf-8'
 EXIT_SUCCESS = 0
 NULL_UUID = '00000000-0000-0000-0000-000000000000'

packages/dsw-document-worker/dsw/document_worker/model/context.py

@@ -6,6 +6,7 @@
 import dateutil.parser as dp
 
 from ..consts import NULL_UUID
+from ..utils import check_metamodel_version
 from .utils import unmarkdown
 
 AnnotationsT = dict[str, str | list[str]]
@@ -2072,14 +2073,11 @@ def load(data: dict, **options):
 
 class DocumentContext:
     """Document Context smart representation"""
-    METAMODEL_VERSION = 16
 
     def __init__(self, *, ctx, **options):
-        self.metamodel_version = int(ctx.get('metamodelVersion', '0'))
-        if self.metamodel_version != self.METAMODEL_VERSION:
-            raise ValueError(f'Unsupported metamodel version: {self.metamodel_version} '
-                             f'(expected: {self.METAMODEL_VERSION})')
-
+        check_metamodel_version(
+            metamodel_version=str(ctx.get('metamodelVersion', '0')),
+        )
         self.config = ContextConfig.load(ctx['config'], **options)
         self.km = KnowledgeModel.load(ctx['knowledgeModel'], **options)
         self.questionnaire = Questionnaire.load(ctx['questionnaire'], **options)

packages/dsw-document-worker/dsw/document_worker/utils.py

@@ -1,3 +1,6 @@
+from .consts import CURRENT_METAMODEL_MAJOR, CURRENT_METAMODEL_MINOR
+
+
 _BYTE_SIZES = ["B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB"]
 
 
@@ -11,3 +14,18 @@ def byte_size_format(num: float):
             return f'{_round_size(num)} {unit}'
         num /= 1000.0
     return f'{_round_size(num)} YB'
+
+
+def check_metamodel_version(metamodel_version: str):
+    version_parts = metamodel_version.split('.')
+    try:
+        major = int(version_parts[0]) if len(version_parts) > 0 else 0
+        minor = int(version_parts[1]) if len(version_parts) > 1 else 0
+    except ValueError as e:
+        raise ValueError(f'Invalid metamodel version format: {metamodel_version}') from e
+    if major != CURRENT_METAMODEL_MAJOR:
+        raise ValueError(f'Unsupported metamodel version: {metamodel_version} '
+                         f'(expected major version {CURRENT_METAMODEL_MAJOR})')
+    if minor < CURRENT_METAMODEL_MINOR:
+        raise ValueError(f'Unsupported metamodel version: {metamodel_version} '
+                         f'(expected at least {CURRENT_METAMODEL_MINOR} minor version)')

packages/dsw-document-worker/dsw/document_worker/worker.py

@@ -16,13 +16,13 @@
 from .build_info import BUILD_INFO
 from .config import DocumentWorkerConfig, TemplateConfig
 from .consts import DocumentState, COMPONENT_NAME, NULL_UUID, \
-    CMD_COMPONENT, CMD_CHANNEL, PROG_NAME, CURRENT_METAMODEL
+    CMD_COMPONENT, CMD_CHANNEL, PROG_NAME
 from .context import Context
 from .documents import DocumentFile, DocumentNameGiver
 from .exceptions import create_job_exception, JobException
 from .limits import LimitsEnforcer
 from .templates import TemplateRegistry, Template, Format
-from .utils import byte_size_format
+from .utils import byte_size_format, check_metamodel_version
 
 
 LOG = logging.getLogger(__name__)
@@ -161,12 +161,9 @@ def _enrich_context(self):
 
     def check_compliance(self):
         SentryReporter.set_tags(phase='check')
-        metamodel_version = int(self.doc_context.get('metamodelVersion', '0'))
-        if metamodel_version != CURRENT_METAMODEL:
-            LOG.error('Command with metamodel version %d  is not supported '
-                      'by this worker (version %d)', metamodel_version, CURRENT_METAMODEL)
-            raise RuntimeError(f'Unsupported metamodel version: {metamodel_version} '
-                               f'(expected {CURRENT_METAMODEL})')
+        check_metamodel_version(
+            metamodel_version=str(self.doc_context.get('metamodelVersion', '0')),
+        )
 
     @handle_job_step('Failed to build final document')
     def build_document(self):

packages/dsw-tdk/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Switch to use semver for document template metamodel versioning
+
 
 ## [4.21.0]
 

packages/dsw-tdk/dsw/tdk/consts.py

@@ -5,7 +5,9 @@
 
 APP = 'dsw-tdk'
 VERSION = '4.21.0'
-METAMODEL_VERSION = 16
+METAMODEL_VERSION_MAJOR = 17
+METAMODEL_VERSION_MINOR = 0
+METAMODEL_VERSION = f'{METAMODEL_VERSION_MAJOR}.{METAMODEL_VERSION_MINOR}'
 
 REGEX_SEMVER = re.compile(r'^[0-9]+\.[0-9]+\.[0-9]+$')
 REGEX_WIZARD_ID = re.compile(r'^[a-zA-Z0-9-_.]+$')

packages/dsw-tdk/dsw/tdk/core.py

@@ -33,30 +33,38 @@ def __init__(self, message: str, hint: str):
 
 
 METAMODEL_VERSION_SUPPORT = {
-    1: (2, 5, 0),
-    2: (2, 6, 0),
-    3: (2, 12, 0),
-    4: (3, 2, 0),
-    5: (3, 5, 0),
-    6: (3, 6, 0),
-    7: (3, 7, 0),
-    8: (3, 8, 0),
-    9: (3, 10, 0),
-    10: (3, 12, 0),
-    11: (3, 20, 0),
-    12: (4, 1, 0),
-    13: (4, 3, 0),
-    14: (4, 10, 0),
-    15: (4, 12, 0),
-    16: (4, 13, 0),
+    '1.0': (2, 5, 0),
+    '2.0': (2, 6, 0),
+    '3.0': (2, 12, 0),
+    '4.0': (3, 2, 0),
+    '5.0': (3, 5, 0),
+    '6.0': (3, 6, 0),
+    '7.0': (3, 7, 0),
+    '8.0': (3, 8, 0),
+    '9.0': (3, 10, 0),
+    '10.0': (3, 12, 0),
+    '11.0': (3, 20, 0),
+    '12.0': (4, 1, 0),
+    '13.0': (4, 3, 0),
+    '14.0': (4, 10, 0),
+    '15.0': (4, 12, 0),
+    '16.0': (4, 13, 0),
+    '17.0': (4, 22, 0),
 }
 
 
 # pylint: disable=too-many-public-methods
 class TDKCore:
 
     def _check_metamodel_version(self):
-        mm_ver = self.safe_template.metamodel_version
+        hint = 'Fix your metamodelVersion in template.json and/or visit docs'
+        mm_ver = str(self.safe_template.metamodel_version)
+        try:
+            if '.' not in mm_ver:
+                mm_ver = f'{mm_ver}.0'
+            mm_major, mm_minor = map(int, mm_ver.split('.'))
+        except ValueError as e:
+            raise TDKProcessingError(f'Invalid metamodel version format: {mm_ver}', hint) from e
         api_version = self.remote_version.split('~', maxsplit=1)[0]
         if '-' in api_version:
             api_version = api_version.split('-', maxsplit=1)[0]
@@ -68,16 +76,17 @@ def _check_metamodel_version(self):
         parts = api_version.split('.')
         ver = (int(parts[0]), int(parts[1]), int(parts[2]))
         vtag = f'v{ver[0]}.{ver[1]}.{ver[2]}'
-        hint = 'Fix your metamodelVersion in template.json and/or visit docs'
         if mm_ver not in METAMODEL_VERSION_SUPPORT:
             raise TDKProcessingError(f'Unknown metamodel version: {mm_ver}', hint)
-        min_version = METAMODEL_VERSION_SUPPORT[mm_ver]
-        if min_version > ver:
-            raise TDKProcessingError(f'Unsupported metamodel version for API {vtag}', hint)
-        if mm_ver + 1 in METAMODEL_VERSION_SUPPORT:
-            max_version = METAMODEL_VERSION_SUPPORT[mm_ver + 1]
-            if ver >= max_version:
-                raise TDKProcessingError(f'Unsupported metamodel version for API {vtag}', hint)
+        map_reverse = {f'v{v[0]}.{v[1]}.{v[2]}': k for k, v in METAMODEL_VERSION_SUPPORT.items()}
+        if vtag not in map_reverse:
+            raise TDKProcessingError(f'Unsupported API version: {vtag}', hint)
+        api_mm_major, api_mm_minor = map_reverse[vtag].split('.')
+        if mm_major != api_mm_major or mm_minor < api_mm_minor:
+            raise TDKProcessingError(
+                f'Unsupported metamodel version {mm_ver} for API version {api_version}',
+                hint,
+            )
 
     def __init__(self, template: Template | None = None, project: TemplateProject | None = None,
                  client: DSWAPIClient | None = None, logger: logging.Logger | None = None):

packages/dsw-tdk/dsw/tdk/model.py

@@ -180,7 +180,7 @@ def __init__(self, *, template_id=None, organization_id=None, version=None, name
         self.description = description  # type: str
         self.readme = readme  # type: str
         self.license = template_license  # type: str
-        self.metamodel_version: int = metamodel_version or METAMODEL_VERSION
+        self.metamodel_version: str = metamodel_version or METAMODEL_VERSION
         self.allowed_packages: list[PackageFilter] = []
         self.formats: list[Format] = []
         self.files: dict[str, TemplateFile] = {}

packages/dsw-tdk/dsw/tdk/validation.py

@@ -98,6 +98,37 @@ def _validate_natural(field_name: str, value) -> List[ValidationError]:
     return []
 
 
+def _validate_metamodel_version(field_name: str, value) -> List[ValidationError]:
+    if isinstance(value, int) and value > 0:
+        return []
+    if isinstance(value, str) and '.' in value:
+        parts = value.split('.')
+        if len(parts) != 2:
+            return [ValidationError(
+                field_name=field_name,
+                message='It must be in format <MAJOR>.<MINOR>',
+            )]
+        try:
+            major = int(parts[0])
+            minor = int(parts[1])
+            if major < 1 or minor < 0:
+                return [ValidationError(
+                    field_name=field_name,
+                    message='It must be in format <MAJOR>.<MINOR> '
+                            'with MAJOR >= 1 and MINOR >= 0',
+                )]
+        except ValueError:
+            return [ValidationError(
+                field_name=field_name,
+                message='It must be in format <MAJOR>.<MINOR> '
+                        'with MAJOR >= 1 and MINOR >= 0',
+            )]
+    return [ValidationError(
+        field_name=field_name,
+        message='It must be a positive integer or in format <MAJOR>.<MINOR>',
+    )]
+
+
 def _validate_package_id(field_name: str, value: str) -> List[ValidationError]:
     res = []
     if value is None:
@@ -255,7 +286,7 @@ def _validate_formats(field_name: str, value: List[Format]) -> List[ValidationEr
     'description': [_validate_required, _validate_non_empty],
     'readme': [_validate_required, _validate_non_empty],
     'license': [_validate_required, _validate_non_empty],
-    'metamodel_version': [_validate_natural],
+    'metamodel_version': [_validate_metamodel_version, _validate_required],
     'allowed_packages': [_validate_package_filters],
     'formats': [_validate_required, _validate_formats],
 })