Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

feat(core): relay container callbacks to a loopback Floci on a Linux host (#5774)

Hector Venturaa2d02ef96704
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
index cf92247d34..9c0a782408 100644
--- a/docs/getting-started/quick-start.md
+++ b/docs/getting-started/quick-start.md
@@ -201,6 +201,12 @@ sudo ufw allow in on docker0 to any port 12000:12499 proto tcp comment 'floci la
sudo ufw allow in on docker0 to any port 4566 proto tcp comment 'floci ecr data plane'
```
+Floci itself keeps listening on `127.0.0.1`. Containers reach it through the bridge gateway
+(`172.17.0.1` by default): at startup Floci opens a relay on that address, which belongs to the host
+but is not reachable from the network, and logs `Containers reach Floci through 172.17.0.1:4566`.
+There is no need to listen on `0.0.0.0` for SDK calls made from inside a Lambda function, ECS task or
+CodeBuild build.
+
**Docker Desktop** (macOS / Windows / Linux) does not need this — it routes container → host through the Docker VM, which Floci's `DockerHostResolver` detects automatically.
**Floci-in-Docker** (running the published Floci image inside a container) does not need this either — Lambda containers and Floci share the same docker network and reach each other via container IPs.
diff --git a/src/main/java/io/github/hectorvent/floci/config/NetworkExposureGuard.java b/src/main/java/io/github/hectorvent/floci/config/NetworkExposureGuard.java
index 43562892a2..1d69640b33 100644
--- a/src/main/java/io/github/hectorvent/floci/config/NetworkExposureGuard.java
+++ b/src/main/java/io/github/hectorvent/floci/config/NetworkExposureGuard.java
@@ -53,7 +53,7 @@ public class NetworkExposureGuard {
* mode. {@link TlsConfigSource} pins {@code quarkus.http.host} to loopback for the internal
* backends, so when the effective value is that pin the configured host is the next source's.
*/
- static String publicHost(Config config) {
+ public static String publicHost(Config config) {
ConfigValue effective = config.getConfigValue(HTTP_HOST);
if (effective.getValue() != null && !TlsConfigSource.NAME.equals(effective.getSourceName())) {
return effective.getValue();
@@ -82,7 +82,7 @@ public class NetworkExposureGuard {
}
/** True for 127.0.0.0/8, ::1 and localhost. Only IP literals are parsed; no name is resolved. */
- static boolean isLoopback(String host) {
+ public static boolean isLoopback(String host) {
String literal = host.strip();
if (literal.startsWith("[") && literal.endsWith("]")) {
literal = literal.substring(1, literal.length() - 1);
diff --git a/src/main/java/io/github/hectorvent/floci/core/common/docker/BridgeGatewayRelay.java b/src/main/java/io/github/hectorvent/floci/core/common/docker/BridgeGatewayRelay.java
new file mode 100644
index 0000000000..c90ae7963f
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/core/common/docker/BridgeGatewayRelay.java
@@ -0,0 +1,304 @@
+package io.github.hectorvent.floci.core.common.docker;
+
+import com.github.dockerjava.api.model.Network;
+import io.github.hectorvent.floci.config.EmulatorConfig;
+import io.github.hectorvent.floci.config.NetworkExposureGuard;
+import io.quarkus.runtime.ShutdownEvent;
+import io.quarkus.runtime.StartupEvent;
+import io.vertx.core.Vertx;
+import io.vertx.core.net.NetClient;
+import io.vertx.core.net.NetServer;
+import io.vertx.core.net.NetSocket;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.event.Observes;
+import jakarta.inject.Inject;
+import org.eclipse.microprofile.config.Config;
+import org.jboss.logging.Logger;
+
+import java.net.InetAddress;
+import java.net.UnknownHostException;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+import java.util.Locale;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Lets containers reach a Floci that runs directly on a Linux host and listens only on loopback.
+ *
+ * <p>Containers Floci starts (Lambda, ECS, CodeBuild, ...) call back through
+ * {@code host.docker.internal}, which on Linux maps to the Docker bridge gateway
+ * ({@code host-gateway}, normally {@code 172.17.0.1}). Docker Desktop forwards that address to the
+ * host's loopback; native Linux Docker does not, so a Floci bound to {@code 127.0.0.1} refuses
+ * those connections. This relay listens on the bridge gateway address, which belongs to the host
+ * but is not routed from the LAN, and pipes each connection to the same port on the loopback address
+ * Floci listens on. It carries raw TCP, so plain HTTP and the TLS proxy both pass through.
+ *
+ * <p>It starts only on a Linux host (not inside a container, where containers reach Floci by its
+ * own address), only while the public listener is on loopback (a wider bind already covers the
+ * gateway), and only when Docker answers.
+ *
+ * <p>Linux accepts packets for any of its own addresses on any interface, so a LAN neighbour that
+ * routes the gateway address through this host could reach the listener. Each connection is
+ * therefore relayed only when its source lies in one of Docker's network subnets; anything else
+ * is closed, as the loopback bind would have refused it.
+ */
+@ApplicationScoped
+public class BridgeGatewayRelay {
+
+ private static final Logger LOG = Logger.getLogger(BridgeGatewayRelay.class);
+
+ static final String DEFAULT_BRIDGE = "bridge";
+ private static final long SUBNET_REFRESH_INTERVAL_NANOS = TimeUnit.SECONDS.toNanos(5);
+
+ private final Vertx vertx;
+ private final EmulatorConfig config;
+ private final Config mpConfig;
+ private final ContainerDetector containerDetector;
+ private final ContainerLifecycleManager lifecycleManager;
+
+ private final List<NetServer> servers = new CopyOnWriteArrayList<>();
+ private volatile NetClient client;
+ private volatile boolean stopped;
+ private final Set<String> dockerSubnets = ConcurrentHashMap.newKeySet();
+ private volatile long subnetsRefreshedAt;
+
+ @Inject
+ public BridgeGatewayRelay(Vertx vertx, EmulatorConfig config, Config mpConfig,
+ ContainerDetector containerDetector, ContainerLifecycleManager lifecycleManager) {
+ this.vertx = vertx;
+ this.config = config;
+ this.mpConfig = mpConfig;
+ this.containerDetector = containerDetector;
+ this.lifecycleManager = lifecycleManager;
+ }
+
+ void onStart(@Observes StartupEvent ignored) {
+ if (!shouldRun(System.getProperty("os.name", ""), containerDetector.isRunningInContainer(),
+ NetworkExposureGuard.publicHost(mpConfig))) {
+ return;
+ }
+ // Inspecting the network is a Docker call; keep it off the startup path.
+ Thread.ofVirtual().name("floci-bridge-gateway-relay").start(this::start);
+ }
+
+ static boolean shouldRun(String osName, boolean inContainer, String publicHost) {
+ return osName.toLowerCase(Locale.ROOT).contains("linux")
+ && !inContainer
+ && NetworkExposureGuard.isLoopback(publicHost);
+ }
+
+ /**
+ * The ports containers call Floci on, the same ones {@code ContainerReachableEndpoint}
+ * advertises: with TLS, the proxy's public port plus its AWS-HTTPS port; without it, the HTTP
+ * server's port, which can differ from {@code floci.port}.
+ */
+ static List<Integer> relayPorts(boolean tlsEnabled, int flociPort, int httpPort, int awsHttpsPort) {
+ if (!tlsEnabled) {
+ return List.of(httpPort);
+ }
+ if (awsHttpsPort > 0 && awsHttpsPort != flociPort) {
+ return List.of(flociPort, awsHttpsPort);
+ }
+ return List.of(flociPort);
+ }
+
+ void start() {
+ String gateway;
+ try {
+ Network bridge = lifecycleManager.getDockerClient().inspectNetworkCmd()
+ .withNetworkId(DEFAULT_BRIDGE).exec();
+ gateway = gatewayOf(bridge);
+ refreshSubnets();
+ } catch (RuntimeException e) {
+ LOG.debugv("Bridge gateway relay not started: Docker is not reachable ({0})", e.getMessage());
+ return;
+ }
+ if (gateway == null) {
+ LOG.warn("Bridge gateway relay not started: the default bridge network has no IPv4 gateway;"
+ + " containers may not reach Floci on loopback");
+ return;
+ }
+ String target = NetworkExposureGuard.publicHost(mpConfig);
+ List<Integer> ports = relayPorts(config.tls().enabled(), config.port(),
+ mpConfig.getValue("quarkus.http.port", Integer.class), config.tls().awsHttpsPort());
+ NetClient netClient = vertx.createNetClient();
+ client = netClient;
+ if (stopped) {
+ onStop(null);
+ return;
+ }
+ for (int port : ports) {
+ listen(gateway, port, target, netClient, port == ports.getFirst());
+ }
+ }
+
+ private void listen(String gateway, int port, String target, NetClient netClient, boolean primary) {
+ NetServer netServer = vertx.createNetServer();
+ netServer.connectHandler(front -> admit(front, netClient, target, port));
+ servers.add(netServer);
+ netServer.listen(port, gateway).onComplete(ar -> {
+ if (stopped) {
+ netServer.close();
+ } else if (ar.succeeded()) {
+ LOG.infov("Containers reach Floci through {0}:{1}, relayed to {2}:{1}", gateway,
+ String.valueOf(port), target);
+ } else if (primary) {
+ LOG.warnv("Could not listen on the Docker bridge gateway {0}:{1} ({2}); containers will not"
+ + " reach Floci on loopback. Set QUARKUS_HTTP_HOST to an address they can reach"
+ + " (with FLOCI_SECURITY_ALLOW_UNSAFE_NETWORK_EXPOSURE=true) instead.",
+ gateway, String.valueOf(port), ar.cause().getMessage());
+ } else {
+ // The AWS-HTTPS port (443 by default) is privileged, like the TLS proxy's own bind.
+ LOG.debugv("Bridge gateway relay: could not listen on {0}:{1} ({2})", gateway,
+ String.valueOf(port), ar.cause().getMessage());
+ }
+ });
+ }
+
+ /**
+ * Relays a connection from a Docker network and closes any other. A source outside the known
+ * subnets triggers one refresh, at most every few seconds, since a network created after
+ * startup (a compose project, a Floci-managed network) is not known yet.
+ */
+ private void admit(NetSocket front, NetClient netClient, String target, int port) {
+ String source = front.remoteAddress().hostAddress();
+ if (inAnySubnet(source, dockerSubnets)) {
+ relay(front, netClient, target, port);
+ return;
+ }
+ front.pause();
+ vertx.<Boolean>executeBlocking(() -> {
+ if (System.nanoTime() - subnetsRefreshedAt > SUBNET_REFRESH_INTERVAL_NANOS) {
+ refreshSubnets();
+ }
+ return inAnySubnet(source, dockerSubnets);
+ }, false).onComplete(ar -> {
+ if (ar.succeeded() && ar.result()) {
+ relay(front, netClient, target, port);
+ } else {
+ LOG.debugv("Bridge gateway relay: refused {0}, which is not on a Docker network", source);
+ front.close();
+ }
+ });
+ }
+
+ private void refreshSubnets() {
+ subnetsRefreshedAt = System.nanoTime();
+ try {
+ dockerSubnets.addAll(subnetsOf(lifecycleManager.getDockerClient().listNetworksCmd().exec()));
+ } catch (RuntimeException e) {
+ LOG.debugv("Bridge gateway relay: could not list Docker networks ({0})", e.getMessage());
+ }
+ }
+
+ /** Every IPv4 and IPv6 subnet of the given networks, in CIDR form. */
+ static List<String> subnetsOf(List<Network> networks) {
+ List<String> subnets = new ArrayList<>();
+ for (Network network : networks) {
+ if (network == null || network.getIpam() == null || network.getIpam().getConfig() == null) {
+ continue;
+ }
+ for (Network.Ipam.Config ipam : network.getIpam().getConfig()) {
+ String subnet = ipam.getSubnet();
+ if (subnet != null && subnet.contains("/")) {
+ subnets.add(subnet);
+ }
+ }
+ }
+ return subnets;
+ }
+
+ static boolean inAnySubnet(String address, Collection<String> subnets) {
+ for (String subnet : subnets) {
+ if (inSubnet(address, subnet)) {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ /** Whether {@code address}, an IP literal, lies in {@code cidr}; an IPv4-mapped IPv6 source counts as IPv4. */
+ static boolean inSubnet(String address, String cidr) {
+ int slash = cidr.indexOf('/');
+ try {
+ byte[] host = literal(address);
+ byte[] network = literal(cidr.substring(0, slash));
+ int prefix = Integer.parseInt(cidr.substring(slash + 1));
+ if (host == null || network == null || host.length != network.length
+ || prefix < 0 || prefix > host.length * 8) {
+ return false;
+ }
+ for (int bit = 0; bit < prefix; bit++) {
+ int mask = 0x80 >>> (bit % 8);
+ if ((host[bit / 8] & mask) != (network[bit / 8] & mask)) {
+ return false;
+ }
+ }
+ return true;
+ } catch (NumberFormatException e) {
+ LOG.debugv("Bridge gateway relay: ignoring malformed subnet {0}", cidr);
+ return false;
+ }
+ }
+
+ private static byte[] literal(String ip) {
+ // Only IP literals reach here (a socket's peer, a subnet Docker reports), so no lookup runs.
+ if (ip == null || ip.isBlank() || !(ip.contains(":") || Character.isDigit(ip.charAt(0)))) {
+ return null;
+ }
+ try {
+ return InetAddress.getByName(ip).getAddress();
+ } catch (UnknownHostException e) {
+ LOG.debugv("Bridge gateway relay: not an IP literal: {0}", ip);
+ return null;
+ }
+ }
+
+ private static void relay(NetSocket front, NetClient netClient, String target, int port) {
+ front.pause();
+ netClient.connect(port, target).onComplete(ar -> {
+ if (ar.failed()) {
+ LOG.debugv("Bridge gateway relay: could not reach {0}:{1}: {2}", target, String.valueOf(port),
+ ar.cause().getMessage());
+ front.close();
+ return;
+ }
+ NetSocket back = ar.result();
+ front.pipeTo(back).onFailure(err ->
+ LOG.debugv("Bridge gateway relay: pipe to Floci failed: {0}", err.getMessage()));
+ back.pipeTo(front).onFailure(err ->
+ LOG.debugv("Bridge gateway relay: pipe to container failed: {0}", err.getMessage()));
+ });
+ }
+
+ /** The default bridge's IPv4 gateway, or {@code null} when it has none. */
+ static String gatewayOf(Network bridge) {
+ if (bridge == null || bridge.getIpam() == null || bridge.getIpam().getConfig() == null) {
+ return null;
+ }
+ List<Network.Ipam.Config> configs = bridge.getIpam().getConfig();
+ for (Network.Ipam.Config ipam : configs) {
+ String gateway = ipam.getGateway();
+ if (gateway != null && !gateway.isBlank() && !gateway.contains(":")) {
+ return gateway;
+ }
+ }
+ return null;
+ }
+
+ void onStop(@Observes ShutdownEvent ignored) {
+ // A startup still inspecting the network or binding checks this flag and closes what it opens.
+ stopped = true;
+ for (NetServer server : servers) {
+ server.close();
+ }
+ NetClient currentClient = client;
+ if (currentClient != null) {
+ currentClient.close();
+ }
+ }
+}
diff --git a/src/test/java/io/github/hectorvent/floci/core/common/docker/BridgeGatewayRelayTest.java b/src/test/java/io/github/hectorvent/floci/core/common/docker/BridgeGatewayRelayTest.java
new file mode 100644
index 0000000000..b15ab85ff7
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/core/common/docker/BridgeGatewayRelayTest.java
@@ -0,0 +1,99 @@
+package io.github.hectorvent.floci.core.common.docker;
+
+import com.github.dockerjava.api.model.Network;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.is;
+import static org.hamcrest.Matchers.nullValue;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+class BridgeGatewayRelayTest {
+
+ @Test
+ void runsOnlyOnALinuxHostListeningOnLoopback() {
+ assertThat(BridgeGatewayRelay.shouldRun("Linux", false, "127.0.0.1"), is(true));
+ assertThat(BridgeGatewayRelay.shouldRun("Linux", false, "localhost"), is(true));
+ assertThat(BridgeGatewayRelay.shouldRun("Linux", true, "127.0.0.1"), is(false));
+ assertThat(BridgeGatewayRelay.shouldRun("Linux", false, "0.0.0.0"), is(false));
+ assertThat(BridgeGatewayRelay.shouldRun("Mac OS X", false, "127.0.0.1"), is(false));
+ assertThat(BridgeGatewayRelay.shouldRun("Windows 11", false, "127.0.0.1"), is(false));
+ }
+
+ @Test
+ void withoutTlsTheHttpPortIsRelayedEvenWhenItDiffersFromTheFlociPort() {
+ assertThat(BridgeGatewayRelay.relayPorts(false, 4566, 4570, 443), equalTo(List.of(4570)));
+ }
+
+ @Test
+ void withTlsTheProxyPortsAreRelayed() {
+ assertThat(BridgeGatewayRelay.relayPorts(true, 4566, 4510, 443), equalTo(List.of(4566, 443)));
+ assertThat(BridgeGatewayRelay.relayPorts(true, 4566, 4510, 0), equalTo(List.of(4566)));
+ assertThat(BridgeGatewayRelay.relayPorts(true, 443, 4510, 443), equalTo(List.of(443)));
+ }
+
+ @Test
+ void onlySourcesOnADockerNetworkAreRelayed() {
+ List<String> subnets = List.of("172.17.0.0/16", "172.18.0.0/16", "fd00:d0c::/64");
+
+ assertThat(BridgeGatewayRelay.inAnySubnet("172.17.0.5", subnets), is(true));
+ assertThat(BridgeGatewayRelay.inAnySubnet("172.18.3.9", subnets), is(true));
+ assertThat(BridgeGatewayRelay.inAnySubnet("::ffff:172.17.0.5", subnets), is(true));
+ assertThat(BridgeGatewayRelay.inAnySubnet("fd00:d0c::7", subnets), is(true));
+ // A LAN neighbour routing 172.17.0.1 through this host.
+ assertThat(BridgeGatewayRelay.inAnySubnet("192.168.1.20", subnets), is(false));
+ assertThat(BridgeGatewayRelay.inAnySubnet("172.19.0.5", subnets), is(false));
+ assertThat(BridgeGatewayRelay.inAnySubnet("192.168.1.20", List.of()), is(false));
+ }
+
+ @Test
+ void subnetMatchingRejectsWhatIsNotAnIpOrACidr() {
+ assertThat(BridgeGatewayRelay.inSubnet("example.com", "172.17.0.0/16"), is(false));
+ assertThat(BridgeGatewayRelay.inSubnet("172.17.0.5", "172.17.0.0/x"), is(false));
+ assertThat(BridgeGatewayRelay.inSubnet("172.17.0.5", "172.17.0.0/40"), is(false));
+ assertThat(BridgeGatewayRelay.inSubnet("10.1.2.3", "0.0.0.0/0"), is(true));
+ }
+
+ @Test
+ void subnetsAreReadFromEveryNetwork() {
+ assertThat(BridgeGatewayRelay.subnetsOf(List.of(network(subnet("172.17.0.0/16"), subnet(null)),
+ network(subnet("172.18.0.0/16"), subnet("fd00:d0c::/64")), mock(Network.class))),
+ equalTo(List.of("172.17.0.0/16", "172.18.0.0/16", "fd00:d0c::/64")));
+ }
+
+ @Test
+ void gatewayIsTheFirstIpv4Gateway() {
+ assertThat(BridgeGatewayRelay.gatewayOf(network(ipam("fd00::1"), ipam("172.17.0.1"))), equalTo("172.17.0.1"));
+ }
+
+ @Test
+ void noGatewayWhenTheBridgeHasNone() {
+ assertThat(BridgeGatewayRelay.gatewayOf(network(ipam(null))), is(nullValue()));
+ assertThat(BridgeGatewayRelay.gatewayOf(null), is(nullValue()));
+ assertThat(BridgeGatewayRelay.gatewayOf(mock(Network.class)), is(nullValue()));
+ }
+
+ private static Network.Ipam.Config ipam(String gateway) {
+ Network.Ipam.Config config = mock(Network.Ipam.Config.class);
+ when(config.getGateway()).thenReturn(gateway);
+ return config;
+ }
+
+ private static Network.Ipam.Config subnet(String subnet) {
+ Network.Ipam.Config config = mock(Network.Ipam.Config.class);
+ when(config.getSubnet()).thenReturn(subnet);
+ return config;
+ }
+
+ private static Network network(Network.Ipam.Config... configs) {
+ Network network = mock(Network.class);
+ Network.Ipam ipam = mock(Network.Ipam.class);
+ when(network.getIpam()).thenReturn(ipam);
+ when(ipam.getConfig()).thenReturn(List.of(configs));
+ return network;
+ }
+}