Direct users to our docs when we suspect TLS on a plain socket.

* Expand TLS hint.

Signed-off-by: Sam Barker <[email protected]>
Co-authored-by: Keith Wall <[email protected]>

Author: SamBarker

kroxylicious-runtime/pom.xml

@@ -23,6 +23,7 @@
 
     <properties>
         <libs.dir>libs</libs.dir>
+        <release.version>${project.version}</release.version>
     </properties>
 
     <name>Proxy runtime</name>
@@ -217,6 +218,7 @@
                 <filtering>true</filtering>
                 <includes>
                     <include>META-INF/metadata.properties</include>
+                    <include>META-INF/stablelinks.properties</include>
                 </includes>
             </resource>
         </resources>

kroxylicious-runtime/src/main/java/io/kroxylicious/proxy/internal/ProxyChannelStateMachine.java

@@ -30,6 +30,7 @@
 import io.kroxylicious.proxy.internal.ProxyChannelState.Forwarding;
 import io.kroxylicious.proxy.internal.codec.FrameOversizedException;
 import io.kroxylicious.proxy.internal.util.Metrics;
+import io.kroxylicious.proxy.internal.util.StableKroxyliciousLinkGenerator;
 import io.kroxylicious.proxy.model.VirtualClusterModel;
 import io.kroxylicious.proxy.service.HostPort;
 import io.kroxylicious.proxy.tag.VisibleForTesting;
@@ -453,10 +454,15 @@ void onClientException(Throwable cause, boolean tlsEnabled) {
         ApiException errorCodeEx;
         if (cause instanceof DecoderException de
                 && de.getCause() instanceof FrameOversizedException e) {
-            var tlsHint = tlsEnabled ? "" : " or an unexpected TLS handshake";
+            String tlsHint;
+            tlsHint = tlsEnabled
+                    ? ""
+                    : " Possible unexpected TLS handshake? When connecting via TLS from your client, make sure to enable TLS for the Kroxylicious gateway ("
+                            + StableKroxyliciousLinkGenerator.INSTANCE.errorLink(StableKroxyliciousLinkGenerator.CLIENT_TLS)
+                            + ").";
             LOGGER.warn(
                     "Received over-sized frame from the client, max frame size bytes {}, received frame size bytes {} "
-                            + "(hint: are we decoding a Kafka frame, or something unexpected like an HTTP request{}?)",
+                            + "(hint: {} Other possible causes are: an oversized Kafka frame, or something unexpected like an HTTP request.)",
                     e.getMaxFrameSizeBytes(), e.getReceivedFrameSizeBytes(), tlsHint);
             errorCodeEx = Errors.INVALID_REQUEST.exception();
         }

kroxylicious-runtime/src/main/java/io/kroxylicious/proxy/internal/util/StableKroxyliciousLinkGenerator.java

@@ -0,0 +1,72 @@
+/*
+ * Copyright Kroxylicious Authors.
+ *
+ * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+package io.kroxylicious.proxy.internal.util;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.UncheckedIOException;
+import java.util.Map;
+import java.util.Properties;
+import java.util.function.Supplier;
+import java.util.stream.Collectors;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class StableKroxyliciousLinkGenerator {
+    private static final Logger LOGGER = LoggerFactory.getLogger(StableKroxyliciousLinkGenerator.class);
+
+    public static final StableKroxyliciousLinkGenerator INSTANCE = new StableKroxyliciousLinkGenerator();
+
+    public static final String CLIENT_TLS = "clientTls";
+    private final LinkInfo links;
+
+    StableKroxyliciousLinkGenerator() {
+        this(() -> {
+            LOGGER.info("loading links from: classpath:META-INF/stablelinks.properties");
+            return StableKroxyliciousLinkGenerator.class.getClassLoader().getResourceAsStream("META-INF/stablelinks.properties");
+        });
+    }
+
+    StableKroxyliciousLinkGenerator(Supplier<InputStream> propLoader) {
+        links = loadLinks(propLoader);
+    }
+
+    public String errorLink(String slug) {
+        return links.generateLink("errors", slug);
+    }
+
+    private LinkInfo loadLinks(Supplier<InputStream> propLoader) {
+        try (var resource = propLoader.get()) {
+            if (resource != null) {
+                Properties properties = new Properties();
+                properties.load(resource);
+                return new LinkInfo(properties);
+            }
+        }
+        catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+        return new LinkInfo(Map.of());
+    }
+
+    private record LinkInfo(Map<String, String> properties) {
+        LinkInfo(Properties properties) {
+            this(properties.entrySet().stream().collect(Collectors.toMap(e -> e.getKey().toString(), e -> e.getValue().toString())));
+        }
+
+        public String generateLink(String namespace, String slug) {
+            String lookupKey = "%s.%s".formatted(namespace, slug);
+            if (properties.containsKey(lookupKey)) {
+                return properties.get(lookupKey);
+            }
+            else {
+                throw new IllegalArgumentException("No link found for " + lookupKey);
+            }
+        }
+    }
+}

kroxylicious-runtime/src/main/java/io/kroxylicious/proxy/model/VirtualClusterModel.java

@@ -39,6 +39,7 @@
 import io.kroxylicious.proxy.config.tls.TrustOptions;
 import io.kroxylicious.proxy.config.tls.TrustProvider;
 import io.kroxylicious.proxy.internal.net.EndpointGateway;
+import io.kroxylicious.proxy.internal.util.StableKroxyliciousLinkGenerator;
 import io.kroxylicious.proxy.service.HostPort;
 import io.kroxylicious.proxy.service.NodeIdentificationStrategy;
 import io.kroxylicious.proxy.tag.VisibleForTesting;
@@ -376,8 +377,10 @@ public Optional<Tls> getTls() {
         private Optional<SslContext> buildDownstreamSslContext() {
             return tls.map(tlsConfiguration -> {
                 if (tlsConfiguration.key() == null) {
-                    throw new IllegalConfigurationException(("Virtual cluster '%s', gateway '%s': 'tls' object is missing the mandatory attribute 'key'.")
-                            .formatted(virtualCluster.getClusterName(), name()));
+                    throw new IllegalConfigurationException(
+                            "Virtual cluster '%s', gateway '%s': 'tls' object is missing the mandatory attribute 'key'. See %s for details"
+                                    .formatted(virtualCluster.getClusterName(), name(),
+                                            StableKroxyliciousLinkGenerator.INSTANCE.errorLink(StableKroxyliciousLinkGenerator.CLIENT_TLS)));
                 }
                 try {
                     var sslContextBuilder = Optional.of(tlsConfiguration.key()).map(NettyKeyProvider::new).map(NettyKeyProvider::forServer)

kroxylicious-runtime/src/main/resources/META-INF/stablelinks.properties

@@ -0,0 +1,7 @@
+#
+# Copyright Kroxylicious Authors.
+#
+# Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+#
+
+errors.clientTls=https://kroxylicious.io/redirect/errors/${release.version}/clientTls

kroxylicious-runtime/src/test/java/io/kroxylicious/proxy/config/ConfigParserTest.java

@@ -410,7 +410,8 @@ void shouldRequireKeyIfDownstreamTlsObjectPresent() {
         assertThatThrownBy(() -> {
             configuration.virtualClusterModel(registry);
         }).isInstanceOf(IllegalConfigurationException.class)
-                .hasMessage("Virtual cluster 'mycluster1', gateway 'default': 'tls' object is missing the mandatory attribute 'key'.");
+                .hasMessageStartingWith("Virtual cluster 'mycluster1', gateway 'default': 'tls' object is missing the mandatory attribute 'key'.");
+        // We can't assert the full message as the link will change with every release
     }
 
     @Test

kroxylicious-runtime/src/test/java/io/kroxylicious/proxy/internal/util/StableKroxyliciousLinkGeneratorTest.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright Kroxylicious Authors.
+ *
+ * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+package io.kroxylicious.proxy.internal.util;
+
+import java.io.ByteArrayInputStream;
+import java.nio.charset.StandardCharsets;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+class StableKroxyliciousLinkGeneratorTest {
+
+    private StableKroxyliciousLinkGenerator stableKroxyliciousLinkGenerator;
+
+    @BeforeEach
+    void setUp() {
+        stableKroxyliciousLinkGenerator = new StableKroxyliciousLinkGenerator(() -> new ByteArrayInputStream("""
+                errors.clientTls=https://example.com/redirect/errors/
+                alternative.clientTls=https://example.com/alternative
+                """.getBytes(StandardCharsets.UTF_8)));
+    }
+
+    @Test
+    void shouldThrowExceptionIfSlugIsNotInGivenNamespace() {
+        // Given
+
+        // When
+        // Then
+        assertThatThrownBy(() -> stableKroxyliciousLinkGenerator.errorLink("unknown"))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("No link found for errors.unknown");
+    }
+
+    @Test
+    void shouldLoadLinkFromErrorNamespace() {
+        // Given
+
+        // When
+        String errorLink = stableKroxyliciousLinkGenerator.errorLink("clientTls");
+
+        // Then
+        assertThat(errorLink).isEqualTo("https://example.com/redirect/errors/");
+    }
+}