feat(http-servers-core): add unified request abstraction and headers to response

- Introduced `Request` interface to standardize handling across FusionAuth, JDK, and Jetty servers.
- Added custom headers support to `HttpResponse`, including `withHeader` for easy modifications.
- Updated query handler methods to utilize the new `Request` abstraction for consistency.
- Refactored FusionAuth, JDK, and Jetty query handlers to integrate `Request` and headers.
- Bumped Solana BOM version to `25.22.1` in `sava.properties`.

Author: jpe7s

.gitignore

@@ -65,3 +65,4 @@ replay_pid*
 *.local
 secrets/
 /.junie/
+/symlinks/

gradle/modules.properties

@@ -1,6 +1,8 @@
 systems.comodal.json_iterator=software.sava:json-iterator
 software.sava.core=software.sava:sava-core
 software.sava.rpc=software.sava:sava-rpc
+software.sava.idl.clients.core=software.sava:idl-clients-core
+software.sava.idl.clients.spl=software.sava:idl-clients-spl
 software.sava.ravina_core=software.sava:ravina-core
 software.sava.ravina_solana=software.sava:ravina-solana
 io.fusionauth.http=io.fusionauth:java-http

gradle/sava.properties

@@ -1,3 +1,3 @@
 productDescription=Http Servers
 javaVersion=25
-solanaBOMVersion=25.21.5
+solanaBOMVersion=25.22.1

http-servers-core/src/main/java/module-info.java

@@ -1,6 +1,7 @@
 import software.sava.http_servers.core.server.HttpServerBuilderFactory;
 
 module software.sava.http_servers.core {
+  exports software.sava.http_servers.core.request;
   exports software.sava.http_servers.core.response;
   exports software.sava.http_servers.core.handlers;
   exports software.sava.http_servers.core.server;

http-servers-core/src/main/java/software/sava/http_servers/core/request/Request.java

@@ -0,0 +1,12 @@
+package software.sava.http_servers.core.request;
+
+public interface Request {
+
+  String path();
+
+  String query();
+
+  String header(final String name);
+
+  byte[] body();
+}

http-servers-core/src/main/java/software/sava/http_servers/core/response/HttpBytesResponse.java

@@ -1,5 +1,10 @@
 package software.sava.http_servers.core.response;
 
-record HttpBytesResponse(int statusCode, String contentType, byte[] body) implements HttpResponse {
+import java.util.Map;
+
+record HttpBytesResponse(int statusCode,
+                         String contentType,
+                         Map<String, String> headers,
+                         byte[] body) implements HttpResponse {
 
 }

http-servers-core/src/main/java/software/sava/http_servers/core/response/HttpResponse.java

@@ -1,13 +1,22 @@
 package software.sava.http_servers.core.response;
 
 import java.nio.charset.StandardCharsets;
+import java.util.LinkedHashMap;
+import java.util.Map;
 
 public interface HttpResponse {
 
   HttpResponse EMPTY = response(200, "application/json", "{}".getBytes(StandardCharsets.US_ASCII));
 
   static HttpResponse response(final int statusCode, final String contentType, final byte[] body) {
-    return new HttpBytesResponse(statusCode, contentType, body);
+    return new HttpBytesResponse(statusCode, contentType, Map.of(), body);
+  }
+
+  static HttpResponse response(final int statusCode,
+                               final String contentType,
+                               final Map<String, String> headers,
+                               final byte[] body) {
+    return new HttpBytesResponse(statusCode, contentType, headers, body);
   }
 
   static HttpResponse response(final String contentType, final byte[] body) {
@@ -38,5 +47,17 @@ static HttpResponse json(final String body) {
 
   String contentType();
 
+  /// @return additional response headers (beyond {@code Content-Type}) to be written, never {@code null}.
+  default Map<String, String> headers() {
+    return Map.of();
+  }
+
+  /// @return a copy of this response with the given response header set.
+  default HttpResponse withHeader(final String name, final String value) {
+    final var headers = new LinkedHashMap<>(headers());
+    headers.put(name, value);
+    return new HttpBytesResponse(statusCode(), contentType(), headers, body());
+  }
+
   byte[] body();
 }

http-servers-core/src/main/java/software/sava/http_servers/core/response/QueryHandler.java

@@ -1,6 +1,13 @@
 package software.sava.http_servers.core.response;
 
+import software.sava.http_servers.core.request.Request;
+
 public interface QueryHandler {
 
+  @Deprecated
   HttpResponse httpResponse(final String path, final String query);
+
+  default HttpResponse httpResponse(final Request request) {
+    return httpResponse(request.path(), request.query());
+  }
 }

http-servers-fusionauth/src/main/java/software/sava/http_servers/fusionauth/FusionAuthQueryHandler.java

@@ -17,7 +17,7 @@ final class FusionAuthQueryHandler implements HTTPHandler {
 
   @Override
   public void handle(final HTTPRequest request, final HTTPResponse response) throws Exception {
-    final var httpResponse = queryHandler.httpResponse(request.getPath(), request.getQueryString());
+    final var httpResponse = queryHandler.httpResponse(new FusionAuthRequest(request));
     writeResponse(response, httpResponse);
   }
 }

http-servers-fusionauth/src/main/java/software/sava/http_servers/fusionauth/FusionAuthRequest.java

@@ -0,0 +1,34 @@
+package software.sava.http_servers.fusionauth;
+
+import io.fusionauth.http.server.HTTPRequest;
+import software.sava.http_servers.core.request.Request;
+
+final class FusionAuthRequest implements Request {
+
+  private final HTTPRequest request;
+
+  FusionAuthRequest(final HTTPRequest request) {
+    this.request = request;
+  }
+
+  @Override
+  public String path() {
+    return request.getPath();
+  }
+
+  @Override
+  public String query() {
+    return request.getQueryString();
+  }
+
+  @Override
+  public String header(final String name) {
+    return request.getHeader(name);
+  }
+
+  @Override
+  public byte[] body() {
+    final var body = request.getBodyBytes();
+    return body == null ? new byte[0] : body;
+  }
+}