Harden registry synchronization consistency

Signed-off-by: Aaron Zielstorff <aaron.zielstorff@iese.fraunhofer.de>

Author: aaronzi

basyx.aasrepository/basyx.aasrepository-feature-registry-integration/Readme.md

@@ -1,6 +1,6 @@
 # AssetAdministrationShell Repository - Registry Integration
-This feature automatically integrates the Descriptor with the Registry while creation of the Shell at Repository. <br>
-It also automatically removes the Descriptor from the Registry when the Shell is removed from the Repository. 
+This feature automatically creates and updates the Descriptor in the Registry when a Shell or its Asset Information changes in the Repository. <br>
+It also automatically removes the Descriptor from the Registry when the Shell is removed from the Repository.
 
 To enable this feature, the following two properties should be configured:
 
@@ -31,4 +31,14 @@ basyx.aasrepository.feature.registryintegration.authorization.client-secret = <c
 basyx.aasrepository.feature.registryintegration.authorization.username=test
 basyx.aasrepository.feature.registryintegration.authorization.password=test
 basyx.aasrepository.feature.registryintegration.authorization.scopes=[]
-```
+```
+
+The Registry permissions required by the integration are:
+
+- `CREATE` when a Shell is created
+- `READ` and `UPDATE` when a Shell or its Asset Information is updated
+- `DELETE` when a Shell is deleted
+
+`READ` is required during updates because the Registry API replaces complete descriptors. The integration reads the existing descriptor first so that Registry-managed endpoint metadata and Submodel Descriptors are retained.
+
+The Registry API currently provides neither conditional updates nor a partial update operation for Shell Descriptors. Consequently, descriptor changes made directly in the Registry by another client must not run concurrently with an AAS update if both changes need to be retained.

basyx.aasrepository/basyx.aasrepository-feature-registry-integration/src/main/java/org/eclipse/digitaltwin/basyx/aasrepository/feature/registry/integration/RegistryIntegrationAasRepository.java

@@ -26,7 +26,9 @@
 
 import java.io.File;
 import java.io.InputStream;
+import java.util.Arrays;
 import java.util.List;
+import java.util.Objects;
 
 import org.eclipse.digitaltwin.aas4j.v3.model.AssetAdministrationShell;
 import org.eclipse.digitaltwin.aas4j.v3.model.AssetInformation;
@@ -54,17 +56,20 @@
  *
  */
 public class RegistryIntegrationAasRepository implements AasRepository {
+	private static final int SHELL_LOCK_COUNT = 64;
 	private static Logger logger = LoggerFactory.getLogger(RegistryIntegrationAasRepository.class);
 
 	private AasRepository decorated;
 
 	private AasRepositoryRegistryLink aasRepositoryRegistryLink;
 	private AttributeMapper attributeMapper;
+	private final Object[] shellMutationLocks = new Object[SHELL_LOCK_COUNT];
 
 	public RegistryIntegrationAasRepository(AasRepository decorated, AasRepositoryRegistryLink aasRepositoryRegistryLink, AttributeMapper attributeMapper) {
 		this.decorated = decorated;
 		this.aasRepositoryRegistryLink = aasRepositoryRegistryLink;
 		this.attributeMapper = attributeMapper;
+		Arrays.setAll(shellMutationLocks, index -> new Object());
 	}
 
 	@Override
@@ -79,40 +84,45 @@ public AssetAdministrationShell getAas(String shellId) throws ElementDoesNotExis
 
 	@Override
 	public void createAas(AssetAdministrationShell shell) throws CollidingIdentifierException {
-		AssetAdministrationShellDescriptor descriptor = createDescriptor(shell);
+		synchronized (getShellMutationLock(shell.getId())) {
+			AssetAdministrationShellDescriptor descriptor = createDescriptor(shell);
 
-		decorated.createAas(shell);
+			decorated.createAas(shell);
 
-		boolean registrationSuccessful = false;
+			boolean registrationSuccessful = false;
 
-		try {
-			registerAas(descriptor);
-			registrationSuccessful = true;
-		} finally {
-			if (!registrationSuccessful)
-				decorated.deleteAas(shell.getId());
+			try {
+				registerAas(descriptor);
+				registrationSuccessful = true;
+			} finally {
+				if (!registrationSuccessful)
+					decorated.deleteAas(shell.getId());
+			}
 		}
 	}
 
 	@Override
 	public void updateAas(String shellId, AssetAdministrationShell shell) {
-		AssetAdministrationShell previousShell = decorated.getAas(shellId);
+		synchronized (getShellMutationLock(shellId)) {
+			AssetAdministrationShell previousShell = decorated.getAas(shellId);
 
-		decorated.updateAas(shellId, shell);
+			decorated.updateAas(shellId, shell);
 
-		try {
-			updateDescriptor(shellId, shell);
-		} catch (RuntimeException e) {
-			rollbackAasUpdate(shellId, previousShell, e);
-			throw e;
+			try {
+				updateDescriptor(shellId, shell);
+			} catch (RuntimeException e) {
+				rollbackAasUpdate(shellId, previousShell, e);
+				throw e;
+			}
 		}
 	}
 
 	@Override
 	public void deleteAas(String shellId) {
-		deleteFromRegistry(shellId);
-		
-		decorated.deleteAas(shellId);
+		synchronized (getShellMutationLock(shellId)) {
+			deleteFromRegistry(shellId);
+			decorated.deleteAas(shellId);
+		}
 	}
 
 	@Override
@@ -127,25 +137,31 @@ public CursorResult<List<Reference>> getSubmodelReferences(String shellId, Pagin
 
 	@Override
 	public void addSubmodelReference(String shellId, Reference submodelReference) {
-		decorated.addSubmodelReference(shellId, submodelReference);
+		synchronized (getShellMutationLock(shellId)) {
+			decorated.addSubmodelReference(shellId, submodelReference);
+		}
 	}
 
 	@Override
 	public void removeSubmodelReference(String shellId, String submodelId) {
-		decorated.removeSubmodelReference(shellId, submodelId);
+		synchronized (getShellMutationLock(shellId)) {
+			decorated.removeSubmodelReference(shellId, submodelId);
+		}
 	}
 
 	@Override
 	public void setAssetInformation(String shellId, AssetInformation shellInfo) throws ElementDoesNotExistException {
-		AssetInformation previousAssetInformation = decorated.getAssetInformation(shellId);
+		synchronized (getShellMutationLock(shellId)) {
+			AssetInformation previousAssetInformation = decorated.getAssetInformation(shellId);
 
-		decorated.setAssetInformation(shellId, shellInfo);
+			decorated.setAssetInformation(shellId, shellInfo);
 
-		try {
-			updateDescriptor(shellId, decorated.getAas(shellId));
-		} catch (RuntimeException e) {
-			rollbackAssetInformationUpdate(shellId, previousAssetInformation, e);
-			throw e;
+			try {
+				updateDescriptor(shellId, decorated.getAas(shellId));
+			} catch (RuntimeException e) {
+				rollbackAssetInformationUpdate(shellId, previousAssetInformation, e);
+				throw e;
+			}
 		}
 	}
 
@@ -168,25 +184,75 @@ private void registerAas(AssetAdministrationShellDescriptor descriptor) {
 
 	private void updateDescriptor(String shellId, AssetAdministrationShell shell) {
 		RegistryAndDiscoveryInterfaceApi registryApi = aasRepositoryRegistryLink.getRegistryApi();
+		AssetAdministrationShellDescriptor existingDescriptor;
 
 		try {
-			AssetAdministrationShellDescriptor existingDescriptor = registryApi.getAssetAdministrationShellDescriptorById(shellId);
-			AssetAdministrationShellDescriptor updatedDescriptor = createDescriptor(shell);
-			updatedDescriptor.setSubmodelDescriptors(existingDescriptor.getSubmodelDescriptors());
+			existingDescriptor = registryApi.getAssetAdministrationShellDescriptorById(shellId);
+		} catch (ApiException e) {
+			throw createRegistryLinkException(shellId, "update", e);
+		}
 
+		AssetAdministrationShellDescriptor updatedDescriptor = createDescriptor(shell);
+		preserveRegistryManagedAttributes(existingDescriptor, updatedDescriptor);
+
+		try {
 			registryApi.putAssetAdministrationShellDescriptorById(shellId, updatedDescriptor);
 
 			logger.info("Shell descriptor '{}' has been automatically updated in the Registry", shellId);
 		} catch (ApiException e) {
+			if (descriptorMatchesAasDerivedState(shellId, updatedDescriptor, registryApi, e)) {
+				logger.warn("Registry update for shell descriptor '{}' returned an error, but a read-back confirmed the requested AAS-derived state.", shellId);
+				return;
+			}
+
 			throw createRegistryLinkException(shellId, "update", e);
 		}
 	}
 
+	private void preserveRegistryManagedAttributes(AssetAdministrationShellDescriptor existingDescriptor, AssetAdministrationShellDescriptor updatedDescriptor) {
+		if (existingDescriptor.getEndpoints() != null)
+			updatedDescriptor.setEndpoints(existingDescriptor.getEndpoints());
+
+		updatedDescriptor.setSubmodelDescriptors(existingDescriptor.getSubmodelDescriptors());
+	}
+
+	private boolean descriptorMatchesAasDerivedState(String shellId, AssetAdministrationShellDescriptor expectedDescriptor, RegistryAndDiscoveryInterfaceApi registryApi, ApiException updateException) {
+		try {
+			AssetAdministrationShellDescriptor actualDescriptor = registryApi.getAssetAdministrationShellDescriptorById(shellId);
+			return aasDerivedAttributesEqual(expectedDescriptor, actualDescriptor);
+		} catch (ApiException verificationException) {
+			updateException.addSuppressed(verificationException);
+			return false;
+		}
+	}
+
+	private boolean aasDerivedAttributesEqual(AssetAdministrationShellDescriptor expected, AssetAdministrationShellDescriptor actual) {
+		return actual != null
+				&& Objects.equals(expected.getAdministration(), actual.getAdministration())
+				&& Objects.equals(expected.getAssetKind(), actual.getAssetKind())
+				&& Objects.equals(expected.getAssetType(), actual.getAssetType())
+				&& Objects.equals(expected.getDescription(), actual.getDescription())
+				&& Objects.equals(expected.getDisplayName(), actual.getDisplayName())
+				&& Objects.equals(expected.getExtensions(), actual.getExtensions())
+				&& Objects.equals(expected.getGlobalAssetId(), actual.getGlobalAssetId())
+				&& Objects.equals(expected.getId(), actual.getId())
+				&& Objects.equals(expected.getIdShort(), actual.getIdShort())
+				&& Objects.equals(expected.getSpecificAssetIds(), actual.getSpecificAssetIds());
+	}
+
 	private AssetAdministrationShellDescriptor createDescriptor(AssetAdministrationShell shell) {
 		return new AasDescriptorFactory(aasRepositoryRegistryLink.getAasRepositoryBaseURLs(), attributeMapper).create(shell);
 	}
 
 	private RepositoryRegistryLinkException createRegistryLinkException(String shellId, String operation, ApiException cause) {
+		return new RepositoryRegistryLinkException(shellId, createRegistryFailureDetails(operation, cause), cause);
+	}
+
+	private RepositoryRegistryUnlinkException createRegistryUnlinkException(String shellId, ApiException cause) {
+		return new RepositoryRegistryUnlinkException(shellId, createRegistryFailureDetails("deletion", cause), cause);
+	}
+
+	private String createRegistryFailureDetails(String operation, ApiException cause) {
 		StringBuilder details = new StringBuilder("Registry descriptor ").append(operation).append(" failed");
 
 		if (cause.getCode() > 0)
@@ -199,7 +265,7 @@ private RepositoryRegistryLinkException createRegistryLinkException(String shell
 		if (responseDetails != null && !responseDetails.isBlank())
 			details.append(": ").append(responseDetails);
 
-		return new RepositoryRegistryLinkException(shellId, details.toString(), cause);
+		return details.toString();
 	}
 
 	private void rollbackAasUpdate(String shellId, AssetAdministrationShell previousShell, RuntimeException updateException) {
@@ -222,30 +288,23 @@ private void rollbackAssetInformationUpdate(String shellId, AssetInformation pre
 
 	private void deleteFromRegistry(String shellId) {
 		RegistryAndDiscoveryInterfaceApi registryApi = aasRepositoryRegistryLink.getRegistryApi();
-		
-		if (!shellExistsOnRegistry(shellId, registryApi)) {
-			logger.error("Unable to un-link the AAS descriptor '{}' from the Registry because it does not exist on the Registry.", shellId);
-			
-			return;
-		}
 
 		try {
 			registryApi.deleteAssetAdministrationShellDescriptorById(shellId);
 
 			logger.info("Shell '{}' has been automatically un-linked from the Registry.", shellId);
 		} catch (ApiException e) {
-			throw new RepositoryRegistryUnlinkException(shellId, e);
+			if (e.getCode() == 404) {
+				logger.info("Shell descriptor '{}' was already absent from the Registry.", shellId);
+				return;
+			}
+
+			throw createRegistryUnlinkException(shellId, e);
 		}
 	}
-	
-	private boolean shellExistsOnRegistry(String shellId, RegistryAndDiscoveryInterfaceApi registryApi) {
-		try {
-			registryApi.getAssetAdministrationShellDescriptorById(shellId);
-			
-			return true;
-		} catch (ApiException e) {
-			return false;
-		}
+
+	private Object getShellMutationLock(String shellId) {
+		return shellMutationLocks[Math.floorMod(Objects.hashCode(shellId), shellMutationLocks.length)];
 	}
 
 	@Override