From 24897dd73d661f29a070d3e17c80dec3876c9f05 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Joakim=20Frosteg=C3=A5rd?= Date: Sun, 12 Jan 2025 23:09:05 +0100 Subject: [PATCH] Improve documentation around IPv4/IPv6 address binding --- crates/http/src/config.rs | 19 +++++++++++++++++++ crates/udp/src/config.rs | 19 +++++++++++++++++++ crates/ws/src/config.rs | 19 +++++++++++++++++++ 3 files changed, 57 insertions(+) diff --git a/crates/http/src/config.rs b/crates/http/src/config.rs index 68c0e3d1..4cee7424 100644 --- a/crates/http/src/config.rs +++ b/crates/http/src/config.rs @@ -71,6 +71,25 @@ impl aquatic_common::cli::Config for Config { #[serde(default, deny_unknown_fields)] pub struct NetworkConfig { /// Bind to this address + /// + /// When providing an IPv4 style address, only IPv4 traffic will be + /// handled. Examples: + /// - "0.0.0.0:3000" binds to port 3000 on all network interfaces + /// - "127.0.0.1:3000" binds to port 3000 on the loopback interface + /// (localhost) + /// + /// When it comes to IPv6-style addresses, behaviour differs between + /// operating systems. On Linux or macOS, by default, both IPv4 and IPv6 + /// traffic is received. For instance: + /// - "[::]:3000" binds on all interfaces on port 3000, with both IPv4 and + /// IPv6 traffic being accepted + /// - "[::1]:3000" binds on the loopback interface (localhost) on port + /// 3000, with both IPv4 and IPv6 traffic being accepted + /// + /// In this case, to only accept traffic over IPv6, use an IPv6-style + /// address, and additionally set "only_ipv6" below. + /// + /// For other operating systems, please refer to their documentation. pub address: SocketAddr, /// Only allow access over IPv6 pub only_ipv6: bool, diff --git a/crates/udp/src/config.rs b/crates/udp/src/config.rs index ae97a4f0..40914ba6 100644 --- a/crates/udp/src/config.rs +++ b/crates/udp/src/config.rs @@ -55,6 +55,25 @@ impl aquatic_common::cli::Config for Config { #[serde(default, deny_unknown_fields)] pub struct NetworkConfig { /// Bind to this address + /// + /// When providing an IPv4 style address, only IPv4 traffic will be + /// handled. Examples: + /// - "0.0.0.0:3000" binds to port 3000 on all network interfaces + /// - "127.0.0.1:3000" binds to port 3000 on the loopback interface + /// (localhost) + /// + /// When it comes to IPv6-style addresses, behaviour differs between + /// operating systems. On Linux or macOS, by default, both IPv4 and IPv6 + /// traffic is received. For instance: + /// - "[::]:3000" binds on all interfaces on port 3000, with both IPv4 and + /// IPv6 traffic being accepted + /// - "[::1]:3000" binds on the loopback interface (localhost) on port + /// 3000, with both IPv4 and IPv6 traffic being accepted + /// + /// In this case, to only accept traffic over IPv6, use an IPv6-style + /// address, and additionally set "only_ipv6" below. + /// + /// For other operating systems, please refer to their documentation. pub address: SocketAddr, /// Only allow access over IPv6 pub only_ipv6: bool, diff --git a/crates/ws/src/config.rs b/crates/ws/src/config.rs index d6f092ec..5abb611e 100644 --- a/crates/ws/src/config.rs +++ b/crates/ws/src/config.rs @@ -75,6 +75,25 @@ impl aquatic_common::cli::Config for Config { #[serde(default, deny_unknown_fields)] pub struct NetworkConfig { /// Bind to this address + /// + /// When providing an IPv4 style address, only IPv4 traffic will be + /// handled. Examples: + /// - "0.0.0.0:3000" binds to port 3000 on all network interfaces + /// - "127.0.0.1:3000" binds to port 3000 on the loopback interface + /// (localhost) + /// + /// When it comes to IPv6-style addresses, behaviour differs between + /// operating systems. On Linux or macOS, by default, both IPv4 and IPv6 + /// traffic is received. For instance: + /// - "[::]:3000" binds on all interfaces on port 3000, with both IPv4 and + /// IPv6 traffic being accepted + /// - "[::1]:3000" binds on the loopback interface (localhost) on port + /// 3000, with both IPv4 and IPv6 traffic being accepted + /// + /// In this case, to only accept traffic over IPv6, use an IPv6-style + /// address, and additionally set "only_ipv6" below. + /// + /// For other operating systems, please refer to their documentation. pub address: SocketAddr, /// Only allow access over IPv6 pub only_ipv6: bool,