HTTP Request/Response Abstraction

import javax.security.cert.X509Certificate;

/**
 * Platform-agnostic HTTP abstraction for Keycloak adapters
 */
public interface HttpFacade {
    /**
     * Gets the HTTP request facade
     * @return Request facade for accessing request data
     */
    Request getRequest();
    
    /**
     * Gets the HTTP response facade  
     * @return Response facade for writing response data
     */
    Response getResponse();
    
    /**
     * Gets the X.509 certificate chain for SSL/TLS connections
     * @return Array of X509Certificate objects, or null if not available
     */
    X509Certificate[] getCertificateChain();
}

import java.io.InputStream;
import java.util.List;

/**
 * HTTP request abstraction
 */
public interface HttpFacade.Request {
    /**
     * Gets the HTTP method (GET, POST, etc.)
     * @return HTTP method string
     */
    String getMethod();
    
    /**
     * Gets the full request URI including query parameters
     * @return Complete request URI
     */
    String getURI();
    
    /**
     * Gets the request relative path without query parameters
     * @return Relative path portion of the request
     */
    String getRelativePath();
    
    /**
     * Checks if the request is using HTTPS
     * @return true if HTTPS is used, false otherwise
     */
    boolean isSecure();
    
    /**
     * Gets the first query or form parameter value
     * @param param Parameter name
     * @return First parameter value, or null if not found
     */
    String getFirstParam(String param);
    
    /**
     * Gets a query parameter value
     * @param param Parameter name  
     * @return Query parameter value, or null if not found
     */
    String getQueryParamValue(String param);
    
    /**
     * Gets a cookie by name
     * @param cookieName Cookie name
     * @return Cookie object, or null if not found
     */
    Cookie getCookie(String cookieName);
    
    /**
     * Gets a header value
     * @param name Header name
     * @return Header value, or null if not found
     */
    String getHeader(String name);
    
    /**
     * Gets all header values for a given name
     * @param name Header name
     * @return List of all header values for the name
     */
    List<String> getHeaders(String name);
    
    /**
     * Gets the request input stream
     * @return InputStream for reading request body
     */
    InputStream getInputStream();
    
    /**
     * Gets the request input stream with buffering option
     * @param buffered Whether to buffer the input stream
     * @return InputStream for reading request body
     */
    InputStream getInputStream(boolean buffered);
    
    /**
     * Gets the remote client address
     * @return Remote address string
     */
    String getRemoteAddr();
    
    /**
     * Sets an authentication error for retrieval by the application
     * @param error Authentication error instance
     */
    void setError(AuthenticationError error);
    
    /**
     * Sets a logout error for retrieval by the application
     * @param error Logout error instance
     */
    void setError(LogoutError error);
}

import java.io.OutputStream;

/**
 * HTTP response abstraction
 */
public interface HttpFacade.Response {
    /**
     * Sets the HTTP response status code
     * @param status HTTP status code (200, 404, 500, etc.)
     */
    void setStatus(int status);
    
    /**
     * Adds a header to the response (allows multiple values)
     * @param name Header name
     * @param value Header value
     */
    void addHeader(String name, String value);
    
    /**
     * Sets a header in the response (replaces existing)
     * @param name Header name
     * @param value Header value
     */
    void setHeader(String name, String value);
    
    /**
     * Resets/clears a cookie by setting it with empty value and past expiration
     * @param name Cookie name
     * @param path Cookie path
     */
    void resetCookie(String name, String path);
    
    /**
     * Sets a cookie with all available options
     * @param name Cookie name
     * @param value Cookie value
     * @param path Cookie path
     * @param domain Cookie domain
     * @param maxAge Cookie max age in seconds
     * @param secure Whether cookie should only be sent over HTTPS
     * @param httpOnly Whether cookie should be HTTP-only (not accessible via JavaScript)
     */
    void setCookie(String name, String value, String path, String domain, 
                   int maxAge, boolean secure, boolean httpOnly);
    
    /**
     * Gets the response output stream for writing response body
     * @return OutputStream for writing response data
     */
    OutputStream getOutputStream();
    
    /**
     * Sends an HTTP error response with status code
     * @param code HTTP error code
     */
    void sendError(int code);
    
    /**
     * Sends an HTTP error response with status code and message
     * @param code HTTP error code
     * @param message Error message
     */
    void sendError(int code, String message);
    
    /**
     * Ends the response if processing is finished
     */
    void end();
}

/**
 * HTTP cookie representation
 */
public static class HttpFacade.Cookie {
    /** Cookie name */
    protected String name;
    
    /** Cookie value */
    protected String value;
    
    /** Cookie version */
    protected int version;
    
    /** Cookie domain */
    protected String domain;
    
    /** Cookie path */
    protected String path;
    
    /**
     * Cookie constructor
     * @param name Cookie name
     * @param value Cookie value
     * @param version Cookie version
     * @param domain Cookie domain
     * @param path Cookie path
     */
    public Cookie(String name, String value, int version, String domain, String path);
    
    /**
     * Gets the cookie name
     * @return Cookie name
     */
    public String getName();
    
    /**
     * Gets the cookie value
     * @return Cookie value
     */
    public String getValue();
    
    /**
     * Gets the cookie version
     * @return Cookie version
     */
    public int getVersion();
    
    /**
     * Gets the cookie domain
     * @return Cookie domain
     */
    public String getDomain();
    
    /**
     * Gets the cookie path
     * @return Cookie path
     */
    public String getPath();
}

import org.keycloak.adapters.spi.HttpFacade;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class ServletHttpFacade implements HttpFacade {
    private final HttpServletRequest request;
    private final HttpServletResponse response;
    
    public ServletHttpFacade(HttpServletRequest request, HttpServletResponse response) {
        this.request = request;
        this.response = response;
    }
    
    @Override
    public Request getRequest() {
        return new ServletRequest(request);
    }
    
    @Override
    public Response getResponse() {
        return new ServletResponse(response);
    }
    
    @Override
    public X509Certificate[] getCertificateChain() {
        return (X509Certificate[]) request.getAttribute("javax.servlet.request.X509Certificate");
    }
}

HttpFacade.Request request = httpFacade.getRequest();

// Check request method and security
if ("POST".equals(request.getMethod()) && request.isSecure()) {
    // Access parameters and headers
    String authCode = request.getFirstParam("code");
    String authHeader = request.getHeader("Authorization");
    
    // Access cookies
    HttpFacade.Cookie sessionCookie = request.getCookie("JSESSIONID");
    if (sessionCookie != null) {
        String sessionId = sessionCookie.getValue();
    }
}

HttpFacade.Response response = httpFacade.getResponse();

// Set response status and headers
response.setStatus(200);
response.setHeader("Content-Type", "application/json");
response.addHeader("Cache-Control", "no-cache");

// Set cookies
response.setCookie("auth-token", "abc123", "/", ".example.com", 3600, true, true);

// Write response body
try (OutputStream out = response.getOutputStream()) {
    out.write("{\"status\":\"success\"}".getBytes());
}
response.end();