Feature/22339 UI schema (#453)

* add test and wiring for adapters to expose their uiSchema

ui schema > intial impl for simulation adapter

* fix uiSchema for the simulation adapter

* fix uiSchema for the modbus adapter

* fix uiSchema for the modbus adapter

* ui schema > added ui schemas for PLC4X adapters

* ui schema > improve nullability handling in ProtocolAdapterApiUtils, cleanup

* Update hivemq-edge/src/main/java/com/hivemq/api/model/adapters/ProtocolAdapter.java

Co-authored-by: Stefan Frehse <[email protected]>

---------

Co-authored-by: Nicolas Van Labeke <[email protected]>
Co-authored-by: Stefan Frehse <[email protected]>

Author: 3 people

hivemq-edge/src/main/java/com/hivemq/api/model/adapters/ProtocolAdapter.java

@@ -103,6 +103,10 @@ public enum Capability {
     @Schema(description = "JSONSchema in the \'https://json-schema.org/draft/2020-12/schema\' format, which describes the configuration requirements for the adapter.")
     private final @NotNull JsonNode configSchema;
 
+    @JsonProperty("uiSchema")
+    @Schema(description = "UISchema (see https://rjsf-team.github.io/react-jsonschema-form/docs/api-reference/uiSchema/), which describes the UI rendering of the configuration for the adapter.")
+    private final @NotNull JsonNode uiSchema;
+
     public ProtocolAdapter(
             @JsonProperty("id") final @NotNull String id,
             @JsonProperty("protocol") final @NotNull String protocol,
@@ -117,7 +121,8 @@ public ProtocolAdapter(
             @JsonProperty("capabilities") final @NotNull Set<Capability> capabilities,
             @JsonProperty("category") final @Nullable ProtocolAdapterCategory category,
             @JsonProperty("tags") final @Nullable List<String> tags,
-            @JsonProperty("configSchema") final @NotNull JsonNode configSchema) {
+            @JsonProperty("configSchema") final @NotNull JsonNode configSchema,
+            @JsonProperty("uiSchema") final @NotNull JsonNode uiSchema) {
         this.id = id;
         this.protocol = protocol;
         this.name = name;
@@ -132,6 +137,7 @@ public ProtocolAdapter(
         this.category = category;
         this.tags = tags;
         this.configSchema = configSchema;
+        this.uiSchema = uiSchema;
     }
 
     public @NotNull String getId() {
@@ -190,6 +196,10 @@ public ProtocolAdapter(
         return category;
     }
 
+    public @Nullable JsonNode getUiSchema() {
+        return uiSchema;
+    }
+
     @Override
     public boolean equals(final Object o) {
         if (this == o) {

hivemq-edge/src/main/java/com/hivemq/api/model/components/Module.java

@@ -102,52 +102,52 @@ public Module(
         this.provisioningLink = provisioningLink;
     }
 
-    public String getId() {
+    public @NotNull String getId() {
         return id;
     }
 
-    public String getVersion() {
+    public @NotNull String getVersion() {
         return version;
     }
 
-    public String getName() {
+    public @NotNull String getName() {
         return name;
     }
 
-    public String getAuthor() {
+    public @NotNull String getAuthor() {
         return author;
     }
 
-    public Integer getPriority() {
+    public @NotNull Integer getPriority() {
         return priority;
     }
 
-    public String getDescription() {
+    public @Nullable String getDescription() {
         return description;
     }
 
-    public Boolean getInstalled() {
+    public @Nullable Boolean getInstalled() {
         return installed;
     }
 
-    public Link getDocumentationLink() {
+    public @Nullable Link getDocumentationLink() {
         return documentationLink;
     }
 
-    public Link getProvisioningLink() {
+    public @Nullable Link getProvisioningLink() {
         return provisioningLink;
     }
 
-    public Link getLogoUrl() {
+    public @Nullable Link getLogoUrl() {
         return logoUrl;
     }
 
-    public String getModuleType() {
+    public @Nullable String getModuleType() {
         return moduleType;
     }
 
     @Override
-    public boolean equals(final Object o) {
+    public boolean equals(final @Nullable Object o) {
         if (this == o) return true;
         if (o == null || getClass() != o.getClass()) return false;
         Module extension = (Module) o;
@@ -160,7 +160,7 @@ public int hashCode() {
     }
 
     @Override
-    public String toString() {
+    public @NotNull String toString() {
         final StringBuilder sb = new StringBuilder("Module{");
         sb.append("id='").append(id).append('\'');
         sb.append(", version='").append(version).append('\'');

hivemq-edge/src/main/java/com/hivemq/api/resources/impl/ProtocolAdapterApiUtils.java

@@ -15,7 +15,10 @@
  */
 package com.hivemq.api.resources.impl;
 
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.Preconditions;
 import com.hivemq.adapter.sdk.api.ProtocolAdapterCapability;
 import com.hivemq.adapter.sdk.api.ProtocolAdapterInformation;
@@ -28,11 +31,15 @@
 import com.hivemq.edge.HiveMQEdgeConstants;
 import com.hivemq.edge.VersionProvider;
 import com.hivemq.extension.sdk.api.annotations.NotNull;
+import com.hivemq.extension.sdk.api.annotations.Nullable;
 import com.hivemq.http.HttpConstants;
 import com.hivemq.protocols.ProtocolAdapterManager;
 import com.hivemq.protocols.ProtocolAdapterSchemaManager;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 import java.util.HashSet;
+import java.util.Objects;
 import java.util.Set;
 import java.util.stream.Collectors;
 
@@ -44,6 +51,117 @@
  */
 public class ProtocolAdapterApiUtils {
 
+    private static final Logger LOG = LoggerFactory.getLogger(ProtocolAdapterApiUtils.class);
+    private static final String DEFAULT_SCHEMA = "{\n" +
+            "  \"ui:tabs\": [\n" +
+            "    {\n" +
+            "      \"id\": \"coreFields\",\n" +
+            "      \"title\": \"Core Fields\",\n" +
+            "      \"properties\": [\"id\", \"port\", \"host\", \"uri\", \"url\", \"timeout\"]\n" +
+            "    },\n" +
+            "    {\n" +
+            "      \"id\": \"subFields\",\n" +
+            "      \"title\": \"Subscription\",\n" +
+            "      \"properties\": [\"subscriptions\"]\n" +
+            "    },\n" +
+            "    {\n" +
+            "      \"id\": \"security\",\n" +
+            "      \"title\": \"protocolAdapter.uiSchema.groups.security\",\n" +
+            "      \"properties\": [\"security\", \"tls\"]\n" +
+            "    },\n" +
+            "    {\n" +
+            "      \"id\": \"publishing\",\n" +
+            "      \"title\": \"protocolAdapter.uiSchema.groups.publishing\",\n" +
+            "      \"properties\": [\n" +
+            "        \"maxPollingErrorsBeforeRemoval\",\n" +
+            "        \"publishChangedDataOnly\",\n" +
+            "        \"publishingInterval\",\n" +
+            "        \"pollingIntervalMillis\",\n" +
+            "        \"destination\",\n" +
+            "        \"qos\",\n" +
+            "        \"minValue\",\n" +
+            "        \"maxValue\"\n" +
+            "      ]\n" +
+            "    },\n" +
+            "    {\n" +
+            "      \"id\": \"authentication\",\n" +
+            "      \"title\": \"protocolAdapter.uiSchema.groups.authentication\",\n" +
+            "      \"properties\": [\"auth\"]\n" +
+            "    },\n" +
+            "    {\n" +
+            "      \"id\": \"http\",\n" +
+            "      \"title\": \"protocolAdapter.uiSchema.groups.http\",\n" +
+            "      \"properties\": [\n" +
+            "        \"httpRequestMethod\",\n" +
+            "        \"httpRequestBodyContentType\",\n" +
+            "        \"httpRequestBody\",\n" +
+            "        \"httpHeaders\",\n" +
+            "        \"httpConnectTimeout\",\n" +
+            "        \"httpRequestBodyContentType\",\n" +
+            "        \"assertResponseIsJson\",\n" +
+            "        \"httpPublishSuccessStatusCodeOnly\",\n" +
+            "        \"allowUntrustedCertificates\"\n" +
+            "      ]\n" +
+            "    },\n" +
+            "    {\n" +
+            "      \"id\": \"ads\",\n" +
+            "      \"title\": \"protocolAdapter.uiSchema.groups.ads\",\n" +
+            "      \"properties\": [\"sourceAmsPort\", \"targetAmsPort\", \"sourceAmsNetId\", \"targetAmsNetId\"]\n" +
+            "    },\n" +
+            "    {\n" +
+            "      \"id\": \"eip\",\n" +
+            "      \"title\": \"protocolAdapter.uiSchema.groups.eip\",\n" +
+            "      \"properties\": [\"slot\", \"backplane\"]\n" +
+            "    },\n" +
+            "    {\n" +
+            "      \"id\": \"s7advanced\",\n" +
+            "      \"title\": \"protocolAdapter.uiSchema.groups.s7advanced\",\n" +
+            "      \"properties\": [\n" +
+            "        \"controllerType\",\n" +
+            "        \"remoteRack\",\n" +
+            "        \"remoteSlot\",\n" +
+            "        \"ping\",\n" +
+            "        \"pingTime\",\n" +
+            "        \"maxAmqCaller\",\n" +
+            "        \"maxAmqCallee\",\n" +
+            "        \"remoteTsap\",\n" +
+            "        \"remoteRack2\",\n" +
+            "        \"remoteSlot2\",\n" +
+            "        \"pduSize\",\n" +
+            "        \"retryTime\",\n" +
+            "        \"retryTimeout\",\n" +
+            "        \"readTimeout\"\n" +
+            "      ]\n" +
+            "    }\n" +
+            "  ],\n" +
+            "  \"ui:submitButtonOptions\": {\n" +
+            "    \"norender\": true\n" +
+            "  },\n" +
+            "  \"id\": {\n" +
+            "    \"ui:disabled\": true\n" +
+            "  },\n" +
+            "  \"port\": {\n" +
+            "    \"ui:widget\": \"updown\"\n" +
+            "  },\n" +
+            "  \"httpRequestBody\": {\n" +
+            "    \"ui:widget\": \"textarea\"\n" +
+            "  },\n" +
+            "  \"subscriptions\": {\n" +
+            "    \"ui:batchMode\": true,\n" +
+            "    \"items\": {\n" +
+            "      \"ui:order\": [\"node\", \"holding-registers\", \"mqtt-topic\", \"destination\", \"qos\", \"*\"],\n" +
+            "      \"ui:collapsable\": {\n" +
+            "        \"titleKey\": \"destination\"\n" +
+            "      }\n" +
+            "    }\n" +
+            "  },\n" +
+            "  \"auth\": {\n" +
+            "    \"basic\": {\n" +
+            "      \"ui:order\": [\"username\", \"password\", \"*\"]\n" +
+            "    }\n" +
+            "  }\n" +
+            "}";
+
     /**
      * Convert between the internal system representation of a ProtocolAdapter type and its API based sibling.
      * This decoupling allows for flexibility when internal model changes would otherwise impact API support
@@ -61,21 +179,31 @@ public static ProtocolAdapter convertInstalledAdapterType(
         Preconditions.checkNotNull(info);
         Preconditions.checkNotNull(configurationService);
         String logoUrl = info.getLogoUrl();
+        //noinspection ConstantValue
         if (logoUrl != null) {
             logoUrl = logoUrl.startsWith("/") ? "/module" + logoUrl : "/module/" + logoUrl;
             logoUrl = applyAbsoluteServerAddressInDeveloperMode(logoUrl, configurationService);
+        } else {
+            // although it is marked as not null it is input from outside (possible customer adapter),
+            // so we should trust but validate and at least log.
+            LOG.warn("Logo url for adapter '{}' was null. ", info.getDisplayName());
         }
-
-
         final ProtocolAdapterFactory<?> protocolAdapterFactory =
                 adapterManager.getProtocolAdapterFactory(info.getProtocolId());
+        if (protocolAdapterFactory == null) {
+            // this can only happen if the adapter somehow got removed from the manager concurrently, which is not possible right now
+            LOG.warn("Factory for adapter '{}' was not found while conversion of adapter to information for REST API.",
+                    info.getDisplayName());
+            return null;
+        }
+
         final ProtocolAdapterSchemaManager protocolAdapterSchemaManager =
                 new ProtocolAdapterSchemaManager(objectMapper, protocolAdapterFactory.getConfigClass());
 
 
         final String rawVersion = info.getVersion();
         final String version = rawVersion.replace("${edge-version}", versionProvider.getVersion());
-
+        final JsonNode uiSchema = getUiSchemaForAdapter(objectMapper, info);
         return new ProtocolAdapter(info.getProtocolId(),
                 info.getProtocolName(),
                 info.getDisplayName(),
@@ -87,11 +215,36 @@ public static ProtocolAdapter convertInstalledAdapterType(
                 info.getAuthor(),
                 true,
                 getCapabilities(info),
-                info == null ? null : convertApiCategory(info.getCategory()),
+                convertApiCategory(info.getCategory()),
                 info.getTags() == null ?
                         null :
                         info.getTags().stream().map(Enum::toString).collect(Collectors.toList()),
-                protocolAdapterSchemaManager.generateSchemaNode());
+                protocolAdapterSchemaManager.generateSchemaNode(),
+                uiSchema);
+    }
+
+    @VisibleForTesting
+    protected static @NotNull JsonNode getUiSchemaForAdapter(
+            @NotNull ObjectMapper objectMapper, @NotNull ProtocolAdapterInformation info) {
+        final String uiSchemaAsString = info.getUiSchema();
+        if (uiSchemaAsString != null) {
+            try {
+                return objectMapper.readTree(uiSchemaAsString);
+            } catch (JsonProcessingException e) {
+                LOG.warn("Ui schema for adapter '{}' is not parsable, the default zu schema will be applied. ",
+                        info.getDisplayName(),
+                        e);
+                // fall through to parsing the DEFAULT SCHEMA
+            }
+        }
+
+        try {
+            return objectMapper.readTree(Objects.requireNonNullElse(uiSchemaAsString, DEFAULT_SCHEMA));
+        } catch (JsonProcessingException e) {
+            LOG.error("Exception during parsing of default zu schema: ", e);
+            // this should never happen as we control the input (default schema)
+            throw new RuntimeException(e);
+        }
     }
 
     private static @NotNull Set<ProtocolAdapter.Capability> getCapabilities(final @NotNull ProtocolAdapterInformation info) {
@@ -132,18 +285,19 @@ public static ProtocolAdapter convertModuleAdapterType(
                 Set.of(),
                 null,
                 null,
+                null,
                 null);
     }
 
-    public static String applyAbsoluteServerAddressInDeveloperMode(
-            @NotNull String logoUrl, final @NotNull ConfigurationService configurationService) {
+    public static @NotNull String applyAbsoluteServerAddressInDeveloperMode(
+            final @NotNull String logoUrl, final @NotNull ConfigurationService configurationService) {
         Preconditions.checkNotNull(logoUrl);
         Preconditions.checkNotNull(configurationService);
-        if (logoUrl != null && Boolean.getBoolean(HiveMQEdgeConstants.DEVELOPMENT_MODE)) {
+        if (Boolean.getBoolean(HiveMQEdgeConstants.DEVELOPMENT_MODE)) {
             //-- when we're in developer mode, ensure we make the logo urls fully qualified
             //-- as the FE maybe being run from a different development server.
             if (!logoUrl.startsWith(HttpConstants.HTTP)) {
-                logoUrl = ApiUtils.getWebContextRoot(configurationService.apiConfiguration(),
+                return ApiUtils.getWebContextRoot(configurationService.apiConfiguration(),
                         !logoUrl.startsWith(HttpConstants.SLASH)) + logoUrl;
             }
         }
@@ -155,7 +309,10 @@ public static String applyAbsoluteServerAddressInDeveloperMode(
      *
      * @param category the category enum to convert
      */
-    public static ProtocolAdapterCategory convertApiCategory(com.hivemq.adapter.sdk.api.ProtocolAdapterCategory category) {
+    public static @Nullable ProtocolAdapterCategory convertApiCategory(final @Nullable com.hivemq.adapter.sdk.api.ProtocolAdapterCategory category) {
+        if (category == null) {
+            return null;
+        }
         return new ProtocolAdapterCategory(category.name(),
                 category.getDisplayName(),
                 category.getDescription(),