refactor: Add http error 500 to resources

caoccao · caoccao · commit a41d7ed9f86f · 2025-08-13T16:02:37.000+02:00
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
@@ -13,6 +13,7 @@ digitalpetri-modbus-tcp = "2.1.0"
 dropwizard-metrics = "4.2.33"
 equalsverifier = "3.17.5"
 errorprone = "2.38.0"
+freemarker = "2.3.34"
 future-converter = "1.2.0"
 guava = "33.4.8-jre"
 hikari = "6.2.1"
@@ -89,6 +90,7 @@ dropwizard-metrics-jvm = { module = "io.dropwizard.metrics:metrics-jvm", version
 dropwizard-metrics-logback = { module = "io.dropwizard.metrics:metrics-logback", version.ref = "dropwizard-metrics" }
 equalsverifier = { module = "nl.jqno.equalsverifier:equalsverifier", version.ref = "equalsverifier" }
 errorprone = { module = "com.google.errorprone:error_prone_core", version.ref = "errorprone" }
+freemarker = { module = "org.freemarker:freemarker", version.ref = "freemarker" }
 json-schema-inferrer = { module = "com.github.saasquatch:json-schema-inferrer", version.ref = "json-schema-inferrer" }
 jersey-container-jdk-http = { module = "org.glassfish.jersey.containers:jersey-container-jdk-http", version.ref = "jersey" }
 jersey-hk2 = { module = "org.glassfish.jersey.inject:jersey-hk2", version.ref = "jersey" }
diff --git a/hivemq-edge/build.gradle.kts b/hivemq-edge/build.gradle.kts
@@ -194,6 +194,9 @@ dependencies {
     implementation(libs.victools.jsonschema.jackson)
     implementation(libs.json.schema.inferrer)
 
+    // i18n
+    implementation(libs.freemarker)
+
     // Edge modules
     compileOnly("com.hivemq:hivemq-edge-module-etherip")
     compileOnly("com.hivemq:hivemq-edge-module-plc4x")
diff --git a/hivemq-edge/src/main/java/com/hivemq/api/errors/HttpErrorFactory.java b/hivemq-edge/src/main/java/com/hivemq/api/errors/HttpErrorFactory.java
@@ -16,18 +16,19 @@
 
 package com.hivemq.api.errors;
 
+import com.hivemq.common.i18n.OpenAPIHttpError;
+import com.hivemq.edge.api.model.*;
 import com.hivemq.edge.api.model.InsufficientStorageError;
 import com.hivemq.edge.api.model.InternalServerError;
 import com.hivemq.edge.api.model.InvalidQueryParameterError;
-import com.hivemq.edge.api.model.PreconditionFailedError;
-import com.hivemq.edge.api.model.RequestBodyMissingError;
-import com.hivemq.edge.api.model.RequestBodyParameterMissingError;
 import com.hivemq.edge.api.model.TemporaryNotAvailableError;
 import com.hivemq.edge.api.model.UrlParameterMissingError;
 import com.hivemq.http.HttpStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+import java.util.Map;
+
 public final class HttpErrorFactory extends ErrorFactory {
     private HttpErrorFactory() {
         super();
@@ -53,10 +54,10 @@ private HttpErrorFactory() {
     public static @NotNull InternalServerError internalServerError(final @Nullable String reason) {
         return InternalServerError.builder()
                 .type(type(InternalServerError.class))
-                .title("Internal Server Error")
+                .title(OpenAPIHttpError.HTTP_ERROR_500_TITLE.get())
                 .detail(reason == null ?
-                        "An unexpected error occurred, check the logs." :
-                        "An unexpected error occurred: " + reason)
+                        OpenAPIHttpError.HTTP_ERROR_500_DETAIL_DEFAULT.get() :
+                        OpenAPIHttpError.HTTP_ERROR_500_DETAIL_WITH_REASON.get(Map.of("reason", reason)))
                 .status(HttpStatus.INTERNAL_SERVER_ERROR_500)
                 .build();
     }
diff --git a/hivemq-edge/src/main/java/com/hivemq/common/i18n/I18nTemplate.java b/hivemq-edge/src/main/java/com/hivemq/common/i18n/I18nTemplate.java
@@ -0,0 +1,27 @@
+/*
+ *  Copyright 2019-present HiveMQ GmbH
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package com.hivemq.common.i18n;
+
+import org.jetbrains.annotations.NotNull;
+
+public interface I18nTemplate {
+    @NotNull String getKey();
+
+    @NotNull String getName();
+
+    @NotNull String getResourceName();
+}
diff --git a/hivemq-edge/src/main/java/com/hivemq/common/i18n/LocaleContext.java b/hivemq-edge/src/main/java/com/hivemq/common/i18n/LocaleContext.java
@@ -0,0 +1,36 @@
+/*
+ *  Copyright 2019-present HiveMQ GmbH
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package com.hivemq.common.i18n;
+
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.Locale;
+
+public final class LocaleContext {
+    public static @NotNull Locale DEFAULT_LOCALE = Locale.US;
+
+    private static final ThreadLocal<Locale> THREAD_LOCAL_LOCALE = ThreadLocal.withInitial(() -> DEFAULT_LOCALE);
+
+    public static @NotNull Locale getCurrentLocale() {
+        return THREAD_LOCAL_LOCALE.get();
+    }
+
+    public static void setCurrentLocale(final @Nullable Locale locale) {
+        THREAD_LOCAL_LOCALE.set(locale == null ? DEFAULT_LOCALE : locale);
+    }
+}
diff --git a/hivemq-edge/src/main/java/com/hivemq/common/i18n/OpenAPIErrorTemplate.java b/hivemq-edge/src/main/java/com/hivemq/common/i18n/OpenAPIErrorTemplate.java
@@ -0,0 +1,111 @@
+/*
+ *  Copyright 2019-present HiveMQ GmbH
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package com.hivemq.common.i18n;
+
+import freemarker.cache.StringTemplateLoader;
+import freemarker.template.Configuration;
+import freemarker.template.Template;
+import freemarker.template.TemplateException;
+import org.apache.commons.io.IOUtils;
+import org.jetbrains.annotations.NotNull;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.IOException;
+import java.io.StringReader;
+import java.io.StringWriter;
+import java.nio.charset.StandardCharsets;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Properties;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Singleton class to manage OpenAPI error templates using FreeMarker.
+ * It provides methods to retrieve error messages based on the current locale and template keys.
+ * <p>
+ * This class is thread-safe and uses a cache to store configurations for different locales.
+ */
+public final class OpenAPIErrorTemplate {
+
+    private static final OpenAPIErrorTemplate INSTANCE = new OpenAPIErrorTemplate();
+
+    private final @NotNull Map<String, Configuration> configurationMap;
+    private final @NotNull Logger logger;
+
+    private OpenAPIErrorTemplate() {
+        configurationMap = new ConcurrentHashMap<>();
+        logger = LoggerFactory.getLogger(getClass());
+    }
+
+    public static @NotNull OpenAPIErrorTemplate getInstance() {
+        return INSTANCE;
+    }
+
+    private Configuration createConfiguration(final @NotNull Locale locale) {
+        final Configuration configuration = new Configuration(Configuration.VERSION_2_3_34);
+        configuration.setDefaultEncoding(StandardCharsets.UTF_8.name());
+        final StringTemplateLoader stringTemplateLoader = new StringTemplateLoader();
+        configuration.setTemplateLoader(stringTemplateLoader);
+        configuration.setLocale(locale);
+        return configuration;
+    }
+
+    public @NotNull String get(final @NotNull I18nTemplate i18nTemplate) {
+        return get(i18nTemplate, Map.of());
+    }
+
+    public @NotNull String get(final @NotNull I18nTemplate i18nTemplate, final @NotNull Map<String, Object> map) {
+        final Locale locale = LocaleContext.getCurrentLocale();
+        Configuration configuration = configurationMap.get(locale.toString());
+        if (configuration == null) {
+            configuration = createConfiguration(locale);
+            configurationMap.put(locale.toString(), configuration);
+        }
+        try {
+            final StringTemplateLoader stringTemplateLoader = (StringTemplateLoader) configuration.getTemplateLoader();
+            if (stringTemplateLoader.findTemplateSource(i18nTemplate.getKey()) == null) {
+                final Properties properties = new Properties();
+                try (final StringReader stringReader = new StringReader(IOUtils.resourceToString(i18nTemplate.getResourceName(),
+                        StandardCharsets.UTF_8))) {
+                    properties.load(stringReader);
+                }
+                synchronized (configuration) {
+                    for (final Map.Entry<Object, Object> entry : properties.entrySet()) {
+                        stringTemplateLoader.putTemplate(String.valueOf(entry.getKey()),
+                                String.valueOf(entry.getValue()));
+                    }
+                }
+            }
+            final Template template = configuration.getTemplate(i18nTemplate.getKey());
+            try (final StringWriter stringWriter = new StringWriter()) {
+                template.process(map, stringWriter);
+                return stringWriter.toString();
+            }
+        } catch (final TemplateException e) {
+            final String errorMessage =
+                    "Error: Template " + i18nTemplate.getKey() + " for " + locale + " could not be processed.";
+            logger.error(errorMessage);
+            return errorMessage;
+        } catch (final IOException e) {
+            final String errorMessage =
+                    "Error: Template " + i18nTemplate.getKey() + " for " + locale + " could not be loaded.";
+            logger.error(errorMessage);
+            return errorMessage;
+        }
+    }
+}
diff --git a/hivemq-edge/src/main/java/com/hivemq/common/i18n/OpenAPIHttpError.java b/hivemq-edge/src/main/java/com/hivemq/common/i18n/OpenAPIHttpError.java
@@ -0,0 +1,59 @@
+/*
+ *  Copyright 2019-present HiveMQ GmbH
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package com.hivemq.common.i18n;
+
+import org.jetbrains.annotations.NotNull;
+
+import java.util.Map;
+
+public enum OpenAPIHttpError implements I18nTemplate {
+    HTTP_ERROR_500_TITLE("http.error.500.title"),
+    HTTP_ERROR_500_DETAIL_DEFAULT("http.error.500.detail.default"),
+    HTTP_ERROR_500_DETAIL_WITH_REASON("http.error.500.detail.with.reason"),
+    ;
+
+    private static final String RESOURCE_NAME_PREFIX = "/templates/openapi-errors-";
+    private static final String RESOURCE_NAME_SUFFIX = ".properties";
+    private final @NotNull String key;
+
+    OpenAPIHttpError(final @NotNull String key) {
+        this.key = key;
+    }
+
+    public @NotNull String get() {
+        return get(Map.of());
+    }
+
+    public @NotNull String get(final @NotNull Map<String, Object> map) {
+        return OpenAPIErrorTemplate.getInstance().get(this, map);
+    }
+
+    @Override
+    public @NotNull String getKey() {
+        return key;
+    }
+
+    @Override
+    public @NotNull String getName() {
+        return name();
+    }
+
+    @Override
+    public @NotNull String getResourceName() {
+        return RESOURCE_NAME_PREFIX + LocaleContext.getCurrentLocale() + RESOURCE_NAME_SUFFIX;
+    }
+}
diff --git a/hivemq-edge/src/main/resources/templates/openapi-errors-en_US.properties b/hivemq-edge/src/main/resources/templates/openapi-errors-en_US.properties
@@ -0,0 +1,3 @@
+http.error.500.title=Internal Server Error
+http.error.500.detail.default=An unexpected error occurred, check the logs.
+http.error.500.detail.with.reason=An unexpected error occurred: ${reason}
diff --git a/hivemq-edge/src/test/java/com/hivemq/common/i18n/OpenAPIErrorTemplateTest.java b/hivemq-edge/src/test/java/com/hivemq/common/i18n/OpenAPIErrorTemplateTest.java
@@ -0,0 +1,29 @@
+/*
+ *  Copyright 2019-present HiveMQ GmbH
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package com.hivemq.common.i18n;
+
+import org.junit.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+public class OpenAPIErrorTemplateTest {
+    @Test
+    public void whenLocaleIsNull_thenUseDefaultLocale() {
+        LocaleContext.setCurrentLocale(null);
+        assertThat(LocaleContext.getCurrentLocale()).isEqualTo(LocaleContext.DEFAULT_LOCALE);
+    }
+}
diff --git a/hivemq-edge/src/test/java/com/hivemq/common/i18n/OpenAPIHttpErrorTest.java b/hivemq-edge/src/test/java/com/hivemq/common/i18n/OpenAPIHttpErrorTest.java
@@ -0,0 +1,47 @@
+/*
+ *  Copyright 2019-present HiveMQ GmbH
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package com.hivemq.common.i18n;
+
+import org.junit.Test;
+
+import java.util.Locale;
+import java.util.Map;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+public class OpenAPIHttpErrorTest {
+    @Test
+    public void whenLocaleIsEnUS_thenHttpError500ShouldWork() {
+        LocaleContext.setCurrentLocale(Locale.US);
+        assertThat(OpenAPIHttpError.HTTP_ERROR_500_TITLE.get()).isEqualTo("Internal Server Error");
+        assertThat(OpenAPIHttpError.HTTP_ERROR_500_DETAIL_DEFAULT.get()).isEqualTo(
+                "An unexpected error occurred, check the logs.");
+        assertThat(OpenAPIHttpError.HTTP_ERROR_500_DETAIL_WITH_REASON.get(Map.of("reason", "test."))).isEqualTo(
+                "An unexpected error occurred: test.");
+    }
+
+    @Test
+    public void whenLocaleIsEnGB_thenHttpError500ShouldFail() {
+        LocaleContext.setCurrentLocale(Locale.UK);
+        assertThat(OpenAPIHttpError.HTTP_ERROR_500_TITLE.get()).isEqualTo(
+                "Error: Template http.error.500.title for en_GB could not be loaded.");
+        assertThat(OpenAPIHttpError.HTTP_ERROR_500_DETAIL_DEFAULT.get()).isEqualTo(
+                "Error: Template http.error.500.detail.default for en_GB could not be loaded.");
+        assertThat(OpenAPIHttpError.HTTP_ERROR_500_DETAIL_WITH_REASON.get(Map.of("reason", "test."))).isEqualTo(
+                "Error: Template http.error.500.detail.with.reason for en_GB could not be loaded.");
+    }
+}

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+http.error.500.title=Internal Server Error`
	`2`	`+http.error.500.detail.default=An unexpected error occurred, check the logs.`
	`3`	`+http.error.500.detail.with.reason=An unexpected error occurred: ${reason}`