feat: Support configurable bind address

Author: thced

README.md

@@ -218,6 +218,21 @@ Register a custom mapper for any media type via `Builder.bodyMapper(mediaType, m
 
 User-supplied mappers take precedence over built-in defaults, so you can override any of the above.
 
+#### Restricting to the loopback interface
+
+By default the server binds to the wildcard address (all local interfaces). To restrict it to loopback — useful for local development or sidecar processes — supply a bind address:
+
+```java
+import java.net.InetAddress;
+
+OpenApiServer.builder()
+    .spec(spec)
+    .handlers(handlers)
+    .port(8080)
+    .bindAddress(InetAddress.getLoopbackAddress())
+    .build();
+```
+
 ### Response decorators
 
 `Builder.responseDecorator(...)` registers a `ResponseDecorator` — a `(Request, Response) -> Response` transform applied to every handler's return value before rendering. Decorators compose in registration order: the result of one is fed to the next. Decorator-supplied headers override handler-supplied ones; if you want the opposite, set the header inside the handler with `Response.withHeader(...)`.

src/main/java/com/retailsvc/http/OpenApiServer.java

@@ -21,6 +21,7 @@
 import com.sun.net.httpserver.HttpHandler;
 import com.sun.net.httpserver.HttpServer;
 import java.io.IOException;
+import java.net.InetAddress;
 import java.net.InetSocketAddress;
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
@@ -65,6 +66,7 @@ record HandlerConfig(
       Map<String, TypeMapper> bodyMappers,
       HandlerConfig handlerConfig,
       int port,
+      InetAddress bindAddress,
       int shutdownTimeoutSeconds)
       throws IOException {
 
@@ -84,7 +86,11 @@ record HandlerConfig(
             .collect(Collectors.toUnmodifiableMap(Operation::operationId, op -> op));
     DefaultValidator validator = new DefaultValidator(spec::resolveSchema);
 
-    this.httpServer = HttpServer.create(new InetSocketAddress(port), 0);
+    InetSocketAddress socketAddress =
+        (bindAddress == null)
+            ? new InetSocketAddress(port)
+            : new InetSocketAddress(bindAddress, port);
+    this.httpServer = HttpServer.create(socketAddress, 0);
     httpServer.setExecutor(newThreadPerTaskExecutor(ofVirtual().name("http-", 0).factory()));
 
     HttpContext ctx = httpServer.createContext(Optional.ofNullable(spec.basePath()).orElse("/"));
@@ -116,13 +122,25 @@ record HandlerConfig(
 
     this.shutdownTimeoutSeconds = shutdownTimeoutSeconds;
 
-    LOG.info("Server started (port {}) in {}ms", port, System.currentTimeMillis() - t0);
+    LOG.info(
+        "Server started ({}:{}) in {}ms",
+        httpServer.getAddress().getHostString(),
+        httpServer.getAddress().getPort(),
+        System.currentTimeMillis() - t0);
   }
 
   public int listenPort() {
     return httpServer.getAddress().getPort();
   }
 
+  /**
+   * Returns the actual address the server is bound to, including any wildcard resolution by the
+   * underlying {@link HttpServer}. Useful for verifying loopback restriction.
+   */
+  public InetAddress bindAddress() {
+    return httpServer.getAddress().getAddress();
+  }
+
   /**
    * Stops the server, waiting up to {@code delaySeconds} for active exchanges to finish before
    * closing them. {@code 0} stops immediately.
@@ -157,6 +175,7 @@ public static final class Builder {
     private final List<RequestInterceptor> interceptors = new ArrayList<>();
     private ExceptionHandler exceptionHandler;
     private int port = DEFAULT_PORT;
+    private InetAddress bindAddress;
     private int shutdownTimeoutSeconds = 0;
     private final LinkedHashMap<String, HttpHandler> extras = new LinkedHashMap<>();
     private final Map<String, SchemeValidator> securityValidators = new LinkedHashMap<>();
@@ -238,6 +257,16 @@ public Builder port(int port) {
       return this;
     }
 
+    /**
+     * Restricts the server to a specific local interface. {@code null} (the default) binds to the
+     * wildcard address (all interfaces). Use {@link InetAddress#getLoopbackAddress()} to listen on
+     * loopback only.
+     */
+    public Builder bindAddress(InetAddress bindAddress) {
+      this.bindAddress = bindAddress;
+      return this;
+    }
+
     /**
      * Sets the default drain timeout used by {@link OpenApiServer#close()}. {@code 0} (the default)
      * stops immediately; positive values wait up to that many seconds for in-flight exchanges to
@@ -291,7 +320,8 @@ public OpenApiServer build() throws IOException {
               extras,
               Map.copyOf(securityValidators),
               externalAuth);
-      return new OpenApiServer(spec, resolved, handlerConfig, port, shutdownTimeoutSeconds);
+      return new OpenApiServer(
+          spec, resolved, handlerConfig, port, bindAddress, shutdownTimeoutSeconds);
     }
 
     private static void validateSecurityWiring(Spec spec, Map<String, SchemeValidator> validators) {

src/test/java/com/retailsvc/http/OpenApiServerTest.java

@@ -1,10 +1,15 @@
 package com.retailsvc.http;
 
 import static java.util.Collections.emptyMap;
+import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
 
 import com.retailsvc.http.spec.Spec;
+import java.io.IOException;
+import java.net.HttpURLConnection;
+import java.net.InetAddress;
+import java.net.URI;
 import java.util.List;
 import java.util.Map;
 import org.junit.jupiter.api.Test;
@@ -53,6 +58,48 @@ void testExceptionIsThrownOnInvalidHttpPort() {
     assertThatThrownBy(builder::build).isInstanceOf(IllegalArgumentException.class);
   }
 
+  @Test
+  void shouldBindOnlyToLoopbackWhenBindAddressIsLoopback() throws IOException {
+    try (var server =
+        OpenApiServer.builder()
+            .spec(testSpec())
+            .handlers(emptyMap())
+            .port(0)
+            .bindAddress(InetAddress.getLoopbackAddress())
+            .build()) {
+      int port = server.listenPort();
+      HttpURLConnection conn =
+          (HttpURLConnection)
+              URI.create("http://127.0.0.1:" + port + "/api/missing").toURL().openConnection();
+      try {
+        assertThat(conn.getResponseCode()).isEqualTo(HttpURLConnection.HTTP_NOT_FOUND);
+      } finally {
+        conn.disconnect();
+      }
+    }
+  }
+
+  @Test
+  void shouldBindToWildcardWhenBindAddressIsUnset() throws IOException {
+    try (var server =
+        OpenApiServer.builder().spec(testSpec()).handlers(emptyMap()).port(0).build()) {
+      assertThat(server.bindAddress().isAnyLocalAddress()).isTrue();
+    }
+  }
+
+  @Test
+  void shouldBindToWildcardWhenBindAddressIsExplicitlyNull() throws IOException {
+    try (var server =
+        OpenApiServer.builder()
+            .spec(testSpec())
+            .handlers(emptyMap())
+            .port(0)
+            .bindAddress(null)
+            .build()) {
+      assertThat(server.bindAddress().isAnyLocalAddress()).isTrue();
+    }
+  }
+
   private Spec testSpec() {
     Map<String, Object> raw =
         Map.of(