fix(server)!: reject a wildcard bind with no advertised address

README.md

@@ -288,7 +288,7 @@ For configuration options and detailed help:
 You can also use environment variables to override any configuration setting:
 
 - Override TCP address
-   `IGGY_TCP_ADDRESS=0.0.0.0:8090 cargo run --bin iggy-server`
+   `IGGY_TCP_ADDRESS=127.0.0.1:8090 cargo run --bin iggy-server`
 
 - Set custom data path
    `IGGY_SYSTEM_PATH=/data/iggy cargo run --bin iggy-server`

bdd/docker-compose.server.yml

@@ -65,6 +65,7 @@ services:
       - IGGY_ROOT_PASSWORD=iggy
       - IGGY_SYSTEM_PATH=local_data
       - IGGY_TCP_ADDRESS=0.0.0.0:8090
+      - IGGY_NODE_ADVERTISED_ADDRESS=iggy-server
       - IGGY_HTTP_ADDRESS=0.0.0.0:3000
       - IGGY_QUIC_ADDRESS=0.0.0.0:8080
       - IGGY_WEBSOCKET_ADDRESS=0.0.0.0:8070

core/configs/src/server_config/defaults.rs

@@ -29,6 +29,7 @@ use super::cluster::{
 };
 use super::message_bus::MessageBusConfig;
 use super::metadata::MetadataConfig;
+use super::node::NodeConfig;
 use super::partition::PartitionConfig;
 use super::quic::{QuicCertificateConfig, QuicConfig};
 use super::server::ServerConfig;
@@ -52,6 +53,7 @@ impl Default for ServerConfig {
             consumer_group: ConsumerGroupConfig::default(),
             data_maintenance: DataMaintenanceConfig::default(),
             heartbeat: HeartbeatConfig::default(),
+            node: NodeConfig::default(),
             personal_access_token: PersonalAccessTokenConfig::default(),
             system: Arc::new(ServerSystemConfig::default()),
             quic: QuicConfig::default(),

core/configs/src/server_config/mod.rs

@@ -26,6 +26,7 @@ pub mod defaults;
 pub mod displays;
 pub mod message_bus;
 pub mod metadata;
+pub mod node;
 pub mod partition;
 pub mod quic;
 pub mod server;

core/configs/src/server_config/node.rs

@@ -0,0 +1,98 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you 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.
+
+// This node's own client-facing identity, for the cluster-disabled server.
+
+use super::COMPONENT;
+use super::cluster::AdvertisedAddress;
+use crate::ConfigurationError;
+use configs::ConfigEnv;
+use iggy_common::Validatable;
+use serde::{Deserialize, Serialize};
+
+/// Named to match its roster counterpart: `advertised_address` here and
+/// `cluster.nodes[*].advertised_address` there are the same setting for the
+/// same question, and an operator moving between the two modes should not have
+/// to learn a second spelling.
+#[derive(Debug, Default, Deserialize, Serialize, Clone, ConfigEnv)]
+#[serde(deny_unknown_fields)]
+pub struct NodeConfig {
+    /// Client-facing address: a literal IP or a DNS hostname. `None` leaves
+    /// the server deriving one from its bind address.
+    #[serde(default)]
+    pub advertised_address: Option<String>,
+}
+
+impl Validatable<ConfigurationError> for NodeConfig {
+    fn validate(&self) -> Result<(), ConfigurationError> {
+        let Some(address) = self.advertised_address.as_deref() else {
+            return Ok(());
+        };
+
+        let parsed = address.parse::<AdvertisedAddress>().map_err(|error| {
+            eprintln!("{COMPONENT} - node.advertised_address '{address}': {error}");
+            ConfigurationError::InvalidConfigurationValue
+        })?;
+
+        if parsed.is_unspecified() {
+            eprintln!(
+                "{COMPONENT} - node.advertised_address '{address}' is the unspecified address, \
+                 which tells a client which interfaces this node accepts on rather than where to \
+                 reach it; declare a routable address or leave it unset"
+            );
+            return Err(ConfigurationError::InvalidConfigurationValue);
+        }
+
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn advertised(address: &str) -> NodeConfig {
+        NodeConfig {
+            advertised_address: Some(address.to_owned()),
+        }
+    }
+
+    #[test]
+    fn validate_accepts_an_unset_address() {
+        assert!(NodeConfig::default().validate().is_ok());
+    }
+
+    #[test]
+    fn validate_accepts_a_routable_address() {
+        assert!(advertised("203.0.113.10").validate().is_ok());
+        assert!(advertised("broker-1.example.com").validate().is_ok());
+        assert!(advertised("2001:db8::1").validate().is_ok());
+    }
+
+    #[test]
+    fn validate_rejects_an_unspecified_address() {
+        assert!(advertised("0.0.0.0").validate().is_err());
+        assert!(advertised("::").validate().is_err());
+    }
+
+    #[test]
+    fn validate_rejects_an_unparsable_address() {
+        assert!(advertised("broker-1.example.com:8090").validate().is_err());
+        assert!(advertised("10.0.0.256").validate().is_err());
+        assert!(advertised("").validate().is_err());
+    }
+}

core/configs/src/server_config/server.rs

@@ -19,6 +19,7 @@ use super::COMPONENT;
 use super::cluster::ClusterConfig;
 use super::message_bus::MessageBusConfig;
 use super::metadata::MetadataConfig;
+use super::node::NodeConfig;
 use super::partition::PartitionConfig;
 use super::quic::QuicConfig;
 use super::tcp::TcpConfig;
@@ -111,6 +112,8 @@ pub struct ServerConfig {
     pub consumer_group: ConsumerGroupConfig,
     pub data_maintenance: DataMaintenanceConfig,
     #[serde(default)]
+    pub node: NodeConfig,
+    #[serde(default)]
     pub personal_access_token: PersonalAccessTokenConfig,
     pub heartbeat: HeartbeatConfig,
     pub system: Arc<ServerSystemConfig>,

core/configs/src/server_config/validators.rs

@@ -31,6 +31,7 @@ use crate::common::http::HMAC_JWT_ALGORITHMS;
 use crate::common::validators::SEGMENT_MAX_SIZE_BYTES;
 use err_trail::ErrContext;
 use iggy_common::{IggyExpiry, MAX_MESSAGE_SIZE_UPPER_BYTES, Validatable};
+use std::net::SocketAddr;
 
 /// compio-ws (tungstenite 0.29) `write_buffer_size` default. Used to
 /// evaluate the `max_write_buffer_size > write_buffer_size` invariant
@@ -76,6 +77,10 @@ impl Validatable<ConfigurationError> for ServerConfig {
         self.cluster.validate().error(|e: &ConfigurationError| {
             format!("{COMPONENT} (error: {e}) - failed to validate cluster config")
         })?;
+        self.node.validate().error(|e: &ConfigurationError| {
+            format!("{COMPONENT} (error: {e}) - failed to validate node config")
+        })?;
+        self.validate_client_facing_address()?;
         self.metadata.validate().error(|e: &ConfigurationError| {
             format!("{COMPONENT} (error: {e}) - failed to validate metadata config")
         })?;
@@ -424,6 +429,38 @@ fn reject_unsupported(config: &ServerConfig) -> Result<(), ConfigurationError> {
     Ok(())
 }
 
+impl ServerConfig {
+    /// `tcp.address` must name a bind address, and a wildcard one must be
+    /// paired with a declared client-facing address.
+    fn validate_client_facing_address(&self) -> Result<(), ConfigurationError> {
+        let bind = self.tcp.address.parse::<SocketAddr>().map_err(|error| {
+            eprintln!(
+                "{COMPONENT} - tcp.address '{}' is not an address and port: {error}. The host \
+                     is required and must be a literal IP, so ':PORT' and 'hostname:PORT' are \
+                     both rejected; use 127.0.0.1:PORT for loopback or 0.0.0.0:PORT to accept on \
+                     every interface.",
+                self.tcp.address
+            );
+            ConfigurationError::InvalidConfigurationValue
+        })?;
+
+        if self.cluster.enabled || self.node.advertised_address.is_some() {
+            return Ok(());
+        }
+        if !bind.ip().to_canonical().is_unspecified() {
+            return Ok(());
+        }
+
+        eprintln!(
+            "{COMPONENT} - tcp.address binds the wildcard {bind}, which says which interfaces this \
+             node accepts on rather than where a client reaches it, so cluster metadata would carry \
+             no address for this node. Set node.advertised_address to the address clients dial, or \
+             bind a concrete address."
+        );
+        Err(ConfigurationError::InvalidConfigurationValue)
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::super::cluster::{ClusterNodeConfig, TransportPorts};
@@ -470,6 +507,56 @@ mod tests {
         );
     }
 
+    #[test]
+    fn given_wildcard_bind_without_advertised_address_when_validating_should_reject() {
+        for wildcard in ["0.0.0.0:8090", "[::]:8090", "[::ffff:0.0.0.0]:8090"] {
+            let config = config_with_override(&format!(
+                "[tcp]\naddress = \"{wildcard}\"\n[cluster]\nenabled = false\n"
+            ));
+            assert!(
+                config.validate().is_err(),
+                "{wildcard} names no address a client can dial"
+            );
+        }
+    }
+
+    #[test]
+    fn given_a_hostless_or_named_bind_address_when_validating_should_reject() {
+        for address in [":8090", "localhost:8090", "0.0.0.0", "not-an-address"] {
+            let config = config_with_override(&format!("[tcp]\naddress = \"{address}\"\n"));
+            assert!(
+                config.validate().is_err(),
+                "{address} does not name a bind address"
+            );
+        }
+    }
+
+    #[test]
+    fn given_wildcard_bind_with_advertised_address_when_validating_should_pass() {
+        let config = config_with_override(
+            "[tcp]\naddress = \"0.0.0.0:8090\"\n[cluster]\nenabled = false\n\
+             [node]\nadvertised_address = \"broker-1.example.com\"\n",
+        );
+        assert!(config.validate().is_ok());
+    }
+
+    #[test]
+    fn given_concrete_bind_without_advertised_address_when_validating_should_pass() {
+        let config = config_with_override(
+            "[tcp]\naddress = \"192.0.2.10:8090\"\n[cluster]\nenabled = false\n",
+        );
+        assert!(config.validate().is_ok());
+    }
+
+    #[test]
+    fn given_clustered_wildcard_bind_without_advertised_address_when_validating_should_pass() {
+        // The roster answers the client-facing address per node, so the bind
+        // address is free to be a wildcard with nothing declared here.
+        let config =
+            config_with_override("[tcp]\naddress = \"0.0.0.0:8090\"\n[cluster]\nenabled = true\n");
+        assert!(config.validate().is_ok());
+    }
+
     #[test]
     fn given_shipped_default_config_when_validating_should_pass() {
         let config: ServerConfig = Figment::new()

core/integration/tests/server/cluster_metadata_advertised.rs

@@ -0,0 +1,81 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you 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.
+
+//! `node.advertised_address` on a cluster-disabled server: what a client is
+//! told about the one node in the roster.
+//!
+//! Without a roster the server has only its own bind address to reason from,
+//! and a bind address answers which interfaces it accepts on - never where a
+//! client reaches it. Behind any NAT (published container ports, a Service, a
+//! load balancer) the two are different addresses, and this setting is the
+//! only way to state the second one. The bind-derived fallback and the empty
+//! answer for a wildcard bind are pinned at unit level (`cluster_meta.rs`)
+//! and across the SDKs in `bdd/`; what needs a real server is that a declared
+//! address survives config load and reaches the wire.
+
+use iggy::prelude::*;
+use integration::iggy_harness;
+
+const ADVERTISED_ADDRESS: &str = "broker-1.example.com";
+
+// The harness runs a VSR cluster by default, where the roster answers the
+// client-facing address per node and this setting is deliberately ignored. One
+// node with clustering off is the shape that reaches the self-synthesized
+// path: `--replica-id 0` stays valid without a cluster, any higher id does not.
+#[iggy_harness(
+    cluster_nodes = 1,
+    server(cluster.enabled = false, node.advertised_address = "broker-1.example.com")
+)]
+async fn given_a_declared_advertised_address_when_getting_cluster_metadata_should_publish_it(
+    harness: &TestHarness,
+) {
+    let client = harness
+        .node(0)
+        .tcp_client()
+        .expect("tcp client")
+        .with_root_login()
+        .connect()
+        .await
+        .expect("connect");
+
+    let metadata = client
+        .get_cluster_metadata()
+        .await
+        .expect("get cluster metadata");
+
+    assert_eq!(
+        metadata.nodes.len(),
+        1,
+        "a cluster-disabled server reports itself alone, got {metadata}"
+    );
+    assert!(
+        !metadata.name.is_empty(),
+        "the single-node label still names the cluster"
+    );
+    let node = &metadata.nodes[0];
+    // The harness binds a concrete loopback address, so this also pins the
+    // precedence: a declaration outranks an address the bind could vouch for,
+    // because only the declaration is a claim about reachability.
+    assert_eq!(
+        node.ip, ADVERTISED_ADDRESS,
+        "the declared address must reach the wire verbatim"
+    );
+    assert_ne!(
+        node.endpoints.tcp, 0,
+        "the self node reports its real tcp port alongside the declared address"
+    );
+}

core/integration/tests/server/mod.rs

@@ -50,6 +50,9 @@ mod http_rbac;
 mod http_tls;
 // Binary GetClusterMetadata must serve the real roster from a VSR cluster.
 mod cluster_metadata_vsr;
+// A declared node.advertised_address outranks the bind address a
+// cluster-disabled server would otherwise publish.
+mod cluster_metadata_advertised;
 // A metadata view change must persist the advanced view and recover it from disk
 // across a replica restart.
 mod cluster_view_durability_vsr;

core/server/README.md

@@ -12,6 +12,15 @@ cargo run --bin iggy-server --release
 
 The Docker image `apache/iggy:latest` ships the server together with the CLI; the `edge` tag tracks the latest development build.
 
+The image binds every listener to `0.0.0.0` so the container is reachable from outside it. A wildcard bind says which interfaces accept connections, not where a client reaches the server, so the address to publish in cluster metadata has to be supplied and the server refuses to start without it. On a single host with published ports that address is `localhost`:
+
+```sh
+docker run -p 3000:3000 -p 8090:8090 \
+  -e IGGY_NODE_ADVERTISED_ADDRESS=localhost apache/iggy:latest
+```
+
+Use the hostname or load balancer address clients actually dial when they are not on the same host. The Helm chart derives it from the Service DNS name.
+
 To run one node of a cluster, pass its replica ID from the `cluster.nodes` roster:
 
 ```sh
@@ -27,7 +36,7 @@ Settings are read from [config.toml](config.toml), resolved relative to the work
 Any single value can be overridden with an `IGGY_`-prefixed environment variable that mirrors the TOML path:
 
 ```sh
-IGGY_TCP_ADDRESS=0.0.0.0:8090 IGGY_HTTP_ENABLED=false cargo run --bin iggy-server
+IGGY_TCP_ADDRESS=127.0.0.1:8090 IGGY_HTTP_ENABLED=false cargo run --bin iggy-server
 ```
 
 Cluster membership, quorum and replica addressing live under `[cluster]`.