feat: Enable HTTPS via Builder.https(certChain, privateKey)

Author: thced

docs/superpowers/plans/2026-05-21-https-support.md

@@ -495,7 +495,7 @@ SKIP=commitlint git commit -m "test: Cover PemSslContext error paths"
 
 This task adds the public builder method, switches the constructor to create `HttpsServer` when HTTPS is configured, and proves it end-to-end with a real HTTPS round-trip.
 
-- [ ] **Step 1: Add an OpenAPI fixture for the HTTPS IT**
+- [x] **Step 1: Add an OpenAPI fixture for the HTTPS IT**
 
 Reuse the existing `src/test/resources/openapi.json` (or whichever spec the existing `OpenApiServerIT` uses). Confirm the spec path used by the existing IT:
 
@@ -505,7 +505,7 @@ grep -l "Spec.from\|fromPath\|fromJson\|fromYaml" src/test/java/com/retailsvc/ht
 
 Read the resolved test spec path and reuse it in the new IT.
 
-- [ ] **Step 2: Write the failing integration test**
+- [x] **Step 2: Write the failing integration test**
 
 Write `src/test/java/com/retailsvc/http/OpenApiServerHttpsIT.java`:
 
@@ -598,15 +598,15 @@ class OpenApiServerHttpsIT {
 
 NOTE: This IT assumes the test spec at `/openapi.json` declares an operationId `getThings` on `GET /things` with no required parameters, no required body, and no security. If the existing test spec uses different operationIds, adjust the `handler` map and the URI path to match an operation that returns a `Response.ok(...)` cleanly. Confirm by skimming `src/test/resources/openapi.json` before running.
 
-- [ ] **Step 3: Run, confirm it fails to compile**
+- [x] **Step 3: Run, confirm it fails to compile**
 
 ```bash
 mvn verify -Dit.test=OpenApiServerHttpsIT -DfailIfNoTests=false
 ```
 
 Expected: compilation failure — `OpenApiServer.Builder.https(Path, Path)` does not exist.
 
-- [ ] **Step 4: Add HTTPS fields and the public method on `Builder`**
+- [x] **Step 4: Add HTTPS fields and the public method on `Builder`**
 
 In `src/main/java/com/retailsvc/http/OpenApiServer.java`:
 
@@ -700,7 +700,7 @@ with:
           spec, resolved, handlerConfig, resolvedPort, bindAddress, shutdownTimeoutSeconds, sslContext);
 ```
 
-- [ ] **Step 5: Update the constructor to optionally build an `HttpsServer`**
+- [x] **Step 5: Update the constructor to optionally build an `HttpsServer`**
 
 In `OpenApiServer.java`, change the constructor signature from:
 
@@ -747,23 +747,23 @@ with:
     }
 ```
 
-- [ ] **Step 6: Run unit tests, confirm nothing regressed**
+- [x] **Step 6: Run unit tests, confirm nothing regressed**
 
 ```bash
 mvn test
 ```
 
 Expected: every existing test still passes. The `Builder` change from `int port = DEFAULT_PORT` to `Integer port` plus default-resolution in `build()` is observationally identical to the old behaviour for HTTP callers.
 
-- [ ] **Step 7: Run the new HTTPS IT**
+- [x] **Step 7: Run the new HTTPS IT**
 
 ```bash
 mvn verify -Dit.test=OpenApiServerHttpsIT -DfailIfNoTests=false
 ```
 
 Expected: both `[rsa]` and `[ec]` parameterised cases pass.
 
-- [ ] **Step 8: Commit**
+- [x] **Step 8: Commit**
 
 ```bash
 git add src/main/java/com/retailsvc/http/OpenApiServer.java \

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

@@ -9,6 +9,7 @@
 import com.retailsvc.http.internal.ExtraRouteAdapter;
 import com.retailsvc.http.internal.FormTypeMapper;
 import com.retailsvc.http.internal.NotFoundHandler;
+import com.retailsvc.http.internal.PemSslContext;
 import com.retailsvc.http.internal.RequestPreparationFilter;
 import com.retailsvc.http.internal.ResponseRenderer;
 import com.retailsvc.http.internal.Router;
@@ -22,9 +23,12 @@
 import com.retailsvc.http.validate.DefaultValidator;
 import com.sun.net.httpserver.HttpContext;
 import com.sun.net.httpserver.HttpServer;
+import com.sun.net.httpserver.HttpsConfigurator;
+import com.sun.net.httpserver.HttpsServer;
 import java.io.IOException;
 import java.net.InetAddress;
 import java.net.InetSocketAddress;
+import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.LinkedHashSet;
@@ -35,6 +39,7 @@
 import java.util.Set;
 import java.util.TreeSet;
 import java.util.stream.Collectors;
+import javax.net.ssl.SSLContext;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -47,6 +52,7 @@ public class OpenApiServer implements AutoCloseable {
 
   private static final Logger LOG = LoggerFactory.getLogger(OpenApiServer.class);
   private static final int DEFAULT_PORT = 8080;
+  private static final int DEFAULT_HTTPS_PORT = 8443;
   private static final String JSON = "application/json";
   private static final String GSON_CLASS = "com.google.gson.Gson";
 
@@ -70,7 +76,8 @@ record HandlerConfig(
       HandlerConfig handlerConfig,
       int port,
       InetAddress bindAddress,
-      int shutdownTimeoutSeconds)
+      int shutdownTimeoutSeconds,
+      SSLContext sslContext)
       throws IOException {
 
     requireNonNull(spec, "Spec must not be null");
@@ -89,7 +96,13 @@ record HandlerConfig(
         (bindAddress == null)
             ? new InetSocketAddress(port)
             : new InetSocketAddress(bindAddress, port);
-    this.httpServer = HttpServer.create(socketAddress, 0);
+    if (sslContext != null) {
+      HttpsServer https = HttpsServer.create(socketAddress, 0);
+      https.setHttpsConfigurator(new HttpsConfigurator(sslContext));
+      this.httpServer = https;
+    } else {
+      this.httpServer = HttpServer.create(socketAddress, 0);
+    }
     httpServer.setExecutor(newThreadPerTaskExecutor(ofVirtual().name("http-", 0).factory()));
 
     ResponseRenderer renderer = new ResponseRenderer(bodyMappers);
@@ -189,7 +202,9 @@ public static final class Builder {
     private final List<RequestInterceptor> interceptors = new ArrayList<>();
     private final List<AfterResponseHook> afterHooks = new ArrayList<>();
     private ExceptionHandler exceptionHandler;
-    private int port = DEFAULT_PORT;
+    private Integer port;
+    private Path httpsCertChain;
+    private Path httpsPrivateKey;
     private InetAddress bindAddress;
     private int shutdownTimeoutSeconds = 0;
     private final LinkedHashMap<String, RequestHandler> extras = new LinkedHashMap<>();
@@ -279,8 +294,9 @@ public Builder exceptionHandler(ExceptionHandler exceptionHandler) {
     }
 
     /**
-     * Sets the TCP port to listen on. Defaults to {@value #DEFAULT_PORT} when not set. Use {@code
-     * 0} to bind on an ephemeral port (read it back via {@link OpenApiServer#listenPort()}).
+     * Sets the TCP port to listen on. Defaults to {@value #DEFAULT_PORT} for HTTP and {@value
+     * #DEFAULT_HTTPS_PORT} when {@link #https(Path, Path)} is set. Use {@code 0} to bind on an
+     * ephemeral port (read it back via {@link OpenApiServer#listenPort()}).
      */
     public Builder port(int port) {
       this.port = port;
@@ -297,6 +313,24 @@ public Builder bindAddress(InetAddress bindAddress) {
       return this;
     }
 
+    /**
+     * Enables HTTPS using the given PEM-encoded certificate chain and PKCS#8 private key. Both
+     * files must exist when {@link #build()} runs; failures surface as {@link
+     * IllegalStateException} with the offending path. The certificate file is a PEM concatenation
+     * of the server certificate followed by any intermediates (matches certbot's {@code
+     * fullchain.pem}). The private key is an unencrypted PKCS#8 PEM (matches certbot's {@code
+     * privkey.pem}); RSA and EC keys are both accepted.
+     *
+     * <p>When set, the default port changes from {@value #DEFAULT_PORT} to {@value
+     * #DEFAULT_HTTPS_PORT}; {@link #port(int)} still overrides.
+     */
+    public Builder https(Path certificateChainPem, Path privateKeyPem) {
+      this.httpsCertChain =
+          requireNonNull(certificateChainPem, "certificateChainPem must not be null");
+      this.httpsPrivateKey = requireNonNull(privateKeyPem, "privateKeyPem must not be null");
+      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
@@ -354,8 +388,18 @@ public OpenApiServer build() throws IOException {
               Map.copyOf(securityValidators),
               externalAuth,
               List.copyOf(afterHooks));
+      int resolvedPort =
+          port != null ? port : (httpsCertChain != null ? DEFAULT_HTTPS_PORT : DEFAULT_PORT);
+      SSLContext sslContext =
+          httpsCertChain != null ? PemSslContext.load(httpsCertChain, httpsPrivateKey) : null;
       return new OpenApiServer(
-          spec, resolved, handlerConfig, port, bindAddress, shutdownTimeoutSeconds);
+          spec,
+          resolved,
+          handlerConfig,
+          resolvedPort,
+          bindAddress,
+          shutdownTimeoutSeconds,
+          sslContext);
     }
 
     private static void validateHandlerWiring(Spec spec, Map<String, RequestHandler> handlers) {

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

@@ -0,0 +1,88 @@
+package com.retailsvc.http;
+
+import static com.retailsvc.http.ServerBaseTest.stubAllHandlers;
+import static java.net.http.HttpClient.Version.HTTP_1_1;
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.retailsvc.http.spec.Spec;
+import java.io.ByteArrayInputStream;
+import java.io.InputStream;
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.security.KeyStore;
+import java.security.cert.Certificate;
+import java.security.cert.CertificateFactory;
+import java.util.Map;
+import java.util.Optional;
+import javax.net.ssl.KeyManager;
+import javax.net.ssl.SSLContext;
+import javax.net.ssl.TrustManagerFactory;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+
+class OpenApiServerHttpsIT {
+
+  @ParameterizedTest(name = "{0}")
+  @CsvSource({
+    "rsa, src/test/resources/tls/rsa-cert.pem, src/test/resources/tls/rsa-key.pem",
+    "ec,  src/test/resources/tls/ec-cert.pem,  src/test/resources/tls/ec-key.pem"
+  })
+  void servesHttpsTraffic(String algo, String certPath, String keyPath) throws Exception {
+    Path cert = Path.of(certPath);
+    Path key = Path.of(keyPath);
+
+    Spec spec;
+    try (InputStream in = getClass().getResourceAsStream("/openapi.json")) {
+      spec = Spec.fromJson(in);
+    }
+
+    RequestHandler handler = req -> Response.ok(Map.of("hello", "world"));
+    Map<String, RequestHandler> handlers = stubAllHandlers(spec, Map.of("get-data", handler));
+
+    try (OpenApiServer server =
+        OpenApiServer.builder()
+            .spec(spec)
+            .handlers(handlers)
+            .securityValidator("apiKeyAuth", (req, cred) -> Optional.empty())
+            .securityValidator("bearerAuth", (req, cred) -> Optional.empty())
+            .securityValidator("basicAuth", (req, cred) -> Optional.empty())
+            .port(0)
+            .https(cert, key)
+            .build()) {
+
+      HttpClient client =
+          HttpClient.newBuilder().version(HTTP_1_1).sslContext(trustStoreFor(cert)).build();
+
+      HttpResponse<String> response =
+          client.send(
+              HttpRequest.newBuilder(
+                      URI.create("https://localhost:" + server.listenPort() + "/api/v1/data"))
+                  .GET()
+                  .build(),
+              HttpResponse.BodyHandlers.ofString());
+
+      assertThat(response.statusCode()).isEqualTo(200);
+      assertThat(response.body()).contains("\"hello\":\"world\"");
+    }
+  }
+
+  private static SSLContext trustStoreFor(Path certPath) throws Exception {
+    byte[] bytes = Files.readAllBytes(certPath);
+    Certificate cert =
+        CertificateFactory.getInstance("X.509")
+            .generateCertificate(new ByteArrayInputStream(bytes));
+    KeyStore trust = KeyStore.getInstance("PKCS12");
+    trust.load(null, null);
+    trust.setCertificateEntry("server", cert);
+    TrustManagerFactory tmf =
+        TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
+    tmf.init(trust);
+    SSLContext ctx = SSLContext.getInstance("TLS");
+    ctx.init(new KeyManager[0], tmf.getTrustManagers(), null);
+    return ctx;
+  }
+}