Component Versioning

The ComponentVersioningService manages the full lifecycle of platform component versions. It provides semantic version parsing, version registration, status transitions, deprecation workflows, compatibility checking, and version comparison. All version data is cached and evicted automatically when changes occur.

Register a Version

Endpoint: POST /api/v1/registry/components/:componentId/versions

curl -X POST http://localhost:8084/api/v1/registry/components/550e8400-e29b-41d4-a716-446655440000/versions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "version": "3.2.0",
    "description": "New query optimization engine",
    "releaseNotes": "Added cost-based optimizer for complex joins",
    "status": "STABLE",
    "releaseDate": "2026-02-01",
    "dockerImage": "matih/trino:3.2.0",
    "helmChartVersion": "0.15.0",
    "minPlatformVersion": "2.0.0",
    "maxPlatformVersion": "3.0.0",
    "lts": false,
    "recommended": true
  }'

When a version is registered, the service parses the version string using the semver4j library to populate the semanticVersion field. If the version is marked as recommended, all other versions for the same component have their recommended flag cleared.

ComponentVersion Structure

Version Status Lifecycle

Endpoint: PUT /api/v1/registry/versions/:versionId/status?status=DEPRECATED

When a version is transitioned to END_OF_LIFE and no endOfLifeDate is set, the current date is automatically assigned.

Deprecation

Endpoint: POST /api/v1/registry/versions/:versionId/deprecate?endOfSupportDate=2026-12-31

When a version is deprecated:

1. The status is set to DEPRECATED
2. The endOfSupportDate is recorded
3. If the deprecated version was the recommended version, the recommended flag is cleared and the latest stable version is automatically promoted to recommended
4. A VERSION_DEPRECATED event is published to Kafka

Set Recommended Version

Endpoint: POST /api/v1/registry/components/:componentId/versions/:versionId/set-recommended

Only one version per component can be recommended at a time. Setting a new recommended version automatically clears the flag on the previous recommended version.

Version Comparison

Endpoint: GET /api/v1/registry/versions/:versionId1/compare/:versionId2

Compares two versions of the same component using semantic versioning rules.

VersionComparison Structure

Compatibility Check

Endpoint: POST /api/v1/registry/versions/:versionId/check-compatibility

Validates whether a version is compatible with the currently installed component versions.

curl -X POST http://localhost:8084/api/v1/registry/versions/550e8400/check-compatibility \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "trino": "3.1.0",
    "kafka": "3.6.0",
    "postgresql": "16.1"
  }'

CompatibilityResult Structure

The check evaluates each VersionDependency against the installed versions, comparing minimum and maximum version constraints using semantic versioning.

Version Dependencies

Each version can declare dependencies on other platform components through the VersionDependency entity.

Dependency Types

Automated Lifecycle Processing

A scheduled task runs daily at 6:00 AM to process version lifecycle transitions:

1. Versions that have reached their endOfLifeDate are automatically transitioned to END_OF_LIFE status
2. Versions reaching their endOfSupportDate trigger VERSION_END_OF_SUPPORT events for downstream notification