HTTP Abstractions

/**
 * Represents an HTTP request or response entity consisting of headers and body
 */
class HttpEntity<T> {
    /** Create entity with body only */
    HttpEntity(T body);
    /** Create entity with headers only */
    HttpEntity(MultiValueMap<String, String> headers);
    /** Create entity with both body and headers */
    HttpEntity(T body, MultiValueMap<String, String> headers);
    
    /** Get the HTTP headers */
    HttpHeaders getHeaders();
    /** Get the body content */
    T getBody();
    /** Check if entity has a body */
    boolean hasBody();
}

/**
 * Extension of HttpEntity that adds HTTP status code for responses
 */
class ResponseEntity<T> extends HttpEntity<T> {
    ResponseEntity(HttpStatusCode status);
    ResponseEntity(T body, HttpStatusCode status);
    ResponseEntity(MultiValueMap<String, String> headers, HttpStatusCode status);
    ResponseEntity(T body, MultiValueMap<String, String> headers, HttpStatusCode status);
    
    /** Get the HTTP status code */
    HttpStatusCode getStatusCode();
    
    // Convenience factory methods
    static <T> ResponseEntity<T> ok(T body);
    static ResponseEntity<Void> ok();
    static ResponseEntity.HeadersBuilder<?> noContent();
    static <T> ResponseEntity<T> badRequest();
    static <T> ResponseEntity<T> notFound();
    static ResponseEntity.BodyBuilder status(HttpStatusCode status);
}

/**
 * Extension of HttpEntity that adds HTTP method and URL for requests
 */
class RequestEntity<T> extends HttpEntity<T> {
    RequestEntity(HttpMethod method, URI url);
    RequestEntity(T body, HttpMethod method, URI url);
    RequestEntity(MultiValueMap<String, String> headers, HttpMethod method, URI url);
    RequestEntity(T body, MultiValueMap<String, String> headers, HttpMethod method, URI url);
    
    /** Get the HTTP method */
    HttpMethod getMethod();
    /** Get the request URL */
    URI getUrl();
    
    // Convenience factory methods
    static RequestEntity.HeadersBuilder<?> get(URI url);
    static RequestEntity.BodyBuilder post(URI url);
    static RequestEntity.BodyBuilder put(URI url);
    static RequestEntity.BodyBuilder patch(URI url);
    static RequestEntity.HeadersBuilder<?> delete(URI url);
    static RequestEntity.BodyBuilder method(HttpMethod method, URI url);
}

// Create response entities
ResponseEntity<User> userResponse = ResponseEntity.ok(user);
ResponseEntity<Void> noContent = ResponseEntity.noContent().build();
ResponseEntity<String> badRequest = ResponseEntity.badRequest().body("Invalid input");

// Create request entities
RequestEntity<User> postRequest = RequestEntity.post(uri)
    .contentType(MediaType.APPLICATION_JSON)
    .body(user);

RequestEntity<Void> getRequest = RequestEntity.get(uri)
    .header("Authorization", "Bearer token")
    .build();

/**
 * HTTP request and response headers as a multi-value map
 */
class HttpHeaders implements MultiValueMap<String, String> {
    HttpHeaders();
    HttpHeaders(MultiValueMap<String, String> otherHeaders);
    
    // Content negotiation headers
    void setAccept(List<MediaType> acceptableMediaTypes);
    List<MediaType> getAccept();
    void setContentType(MediaType mediaType);
    MediaType getContentType();
    
    // Content metadata
    void setContentLength(long contentLength);
    long getContentLength();
    void setContentDisposition(ContentDisposition contentDisposition);
    ContentDisposition getContentDisposition();
    
    // Caching headers
    void setDate(long date);
    long getDate();
    void setETag(String etag);
    String getETag();
    void setLastModified(long lastModified);
    long getLastModified();
    void setCacheControl(CacheControl cacheControl);
    String getCacheControl();
    
    // Authentication and authorization
    void setBearerAuth(String token);
    void setBasicAuth(String username, String password);
    void setBasicAuth(String username, String password, Charset charset);
    
    // CORS headers
    void setAccessControlAllowCredentials(boolean allowCredentials);
    void setAccessControlAllowHeaders(List<String> allowedHeaders);
    void setAccessControlAllowMethods(List<HttpMethod> allowedMethods);
    void setAccessControlAllowOrigin(String allowedOrigin);
    void setAccessControlExposeHeaders(List<String> exposedHeaders);
    void setAccessControlMaxAge(Duration maxAge);
    
    // Utility methods
    String getFirst(String headerName);
    void add(String headerName, String headerValue);
    void set(String headerName, String headerValue);
    void setAll(Map<String, String> values);
    Map<String, String> toSingleValueMap();
}

HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);
headers.setAccept(Arrays.asList(MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML));
headers.setBearerAuth("your-jwt-token");
headers.add("X-Custom-Header", "custom-value");

// CORS configuration
headers.setAccessControlAllowOrigin("*");
headers.setAccessControlAllowMethods(Arrays.asList(HttpMethod.GET, HttpMethod.POST));

/**
 * Enumeration of HTTP request methods
 */
enum HttpMethod {
    GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE;
    
    /** Check if method name matches this enum value */
    boolean matches(String method);
    
    /** Resolve string method name to HttpMethod enum */
    static HttpMethod resolve(String method);
}

/**
 * Enumeration of HTTP status codes with utility methods
 */
enum HttpStatus implements HttpStatusCode {
    // 1xx Informational
    CONTINUE(100), SWITCHING_PROTOCOLS(101), PROCESSING(102), EARLY_HINTS(103),
    
    // 2xx Success
    OK(200), CREATED(201), ACCEPTED(202), NON_AUTHORITATIVE_INFORMATION(203),
    NO_CONTENT(204), RESET_CONTENT(205), PARTIAL_CONTENT(206), MULTI_STATUS(207),
    
    // 3xx Redirection
    MULTIPLE_CHOICES(300), MOVED_PERMANENTLY(301), FOUND(302), SEE_OTHER(303),
    NOT_MODIFIED(304), USE_PROXY(305), TEMPORARY_REDIRECT(307), PERMANENT_REDIRECT(308),
    
    // 4xx Client Error
    BAD_REQUEST(400), UNAUTHORIZED(401), PAYMENT_REQUIRED(402), FORBIDDEN(403),
    NOT_FOUND(404), METHOD_NOT_ALLOWED(405), NOT_ACCEPTABLE(406), PROXY_AUTHENTICATION_REQUIRED(407),
    REQUEST_TIMEOUT(408), CONFLICT(409), GONE(410), LENGTH_REQUIRED(411),
    
    // 5xx Server Error
    INTERNAL_SERVER_ERROR(500), NOT_IMPLEMENTED(501), BAD_GATEWAY(502), SERVICE_UNAVAILABLE(503),
    GATEWAY_TIMEOUT(504), HTTP_VERSION_NOT_SUPPORTED(505);
    
    /** Get numeric status code value */
    int value();
    /** Get standard reason phrase */
    String getReasonPhrase();
    /** Get status series (1xx, 2xx, etc.) */
    HttpStatus.Series series();
    
    // Status classification methods
    boolean is1xxInformational();
    boolean is2xxSuccessful();
    boolean is3xxRedirection();
    boolean is4xxClientError();
    boolean is5xxServerError();
    boolean isError();
    
    /** Resolve numeric status code to HttpStatus enum */
    static HttpStatus valueOf(int statusCode);
    /** Resolve status code, returning null if not found */
    static HttpStatus resolve(int statusCode);
}

/**
 * Series of HTTP status codes
 */
enum HttpStatus.Series {
    INFORMATIONAL(1), SUCCESSFUL(2), REDIRECTION(3), CLIENT_ERROR(4), SERVER_ERROR(5);
    
    int value();
    static HttpStatus.Series valueOf(int status);
    static HttpStatus.Series resolve(int statusCode);
}

/**
 * Represents an Internet Media Type (MIME type)
 */
class MediaType extends MimeType {
    // Common media type constants
    static final MediaType ALL;
    static final MediaType APPLICATION_ATOM_XML;
    static final MediaType APPLICATION_CBOR;
    static final MediaType APPLICATION_FORM_URLENCODED;
    static final MediaType APPLICATION_GRAPHQL_RESPONSE;
    static final MediaType APPLICATION_JSON;
    static final MediaType APPLICATION_NDJSON;
    static final MediaType APPLICATION_OCTET_STREAM;
    static final MediaType APPLICATION_PDF;
    static final MediaType APPLICATION_PROBLEM_JSON;
    static final MediaType APPLICATION_PROBLEM_XML;
    static final MediaType APPLICATION_RSS_XML;
    static final MediaType APPLICATION_STREAM_JSON;
    static final MediaType APPLICATION_XHTML_XML;
    static final MediaType APPLICATION_XML;
    static final MediaType IMAGE_GIF;
    static final MediaType IMAGE_JPEG;
    static final MediaType IMAGE_PNG;
    static final MediaType MULTIPART_FORM_DATA;
    static final MediaType MULTIPART_MIXED;
    static final MediaType MULTIPART_RELATED;
    static final MediaType TEXT_EVENT_STREAM;
    static final MediaType TEXT_HTML;
    static final MediaType TEXT_MARKDOWN;
    static final MediaType TEXT_PLAIN;
    static final MediaType TEXT_XML;
    
    MediaType(String type);
    MediaType(String type, String subtype);
    MediaType(String type, String subtype, Charset charset);
    MediaType(String type, String subtype, double qualityValue);
    MediaType(String type, String subtype, Map<String, String> parameters);
    
    /** Get main type (e.g., "text", "application") */
    String getType();
    /** Get subtype (e.g., "plain", "json") */
    String getSubtype();
    /** Get charset parameter */
    Charset getCharset();
    /** Get quality value for content negotiation */
    double getQualityValue();
    
    // Compatibility checking
    boolean includes(MediaType other);
    boolean isCompatibleWith(MediaType other);
    boolean isConcrete();
    boolean isWildcardType();
    boolean isWildcardSubtype();
    
    // Factory methods
    static MediaType parseMediaType(String mediaType);
    static List<MediaType> parseMediaTypes(String mediaTypes);
    static List<MediaType> parseMediaTypes(List<String> mediaTypes);
    static String toString(Collection<MediaType> mediaTypes);
    
    // Utility methods for sorting
    static void sortByQualityValue(List<MediaType> mediaTypes);
    static void sortBySpecificity(List<MediaType> mediaTypes);
    static void sortBySpecificityAndQuality(List<MediaType> mediaTypes);
}

// Create media types
MediaType jsonType = MediaType.APPLICATION_JSON;
MediaType xmlWithCharset = new MediaType("application", "xml", StandardCharsets.UTF_8);

// Parse media types
MediaType parsed = MediaType.parseMediaType("application/json;charset=UTF-8");
List<MediaType> acceptTypes = MediaType.parseMediaTypes("application/json,application/xml;q=0.9");

// Compatibility checking
boolean compatible = MediaType.APPLICATION_JSON.isCompatibleWith(MediaType.APPLICATION_JSON);
boolean includes = MediaType.APPLICATION_JSON.includes(MediaType.ALL);

/**
 * Represents Content-Disposition header value
 */
class ContentDisposition {
    /** Check if disposition type is "attachment" */
    boolean isAttachment();
    /** Check if disposition type is "form-data" */
    boolean isFormData();
    /** Check if disposition type is "inline" */
    boolean isInline();
    
    /** Get disposition type */
    String getType();
    /** Get name parameter (for form-data) */
    String getName();
    /** Get filename parameter */
    String getFilename();
    /** Get charset for filename */
    Charset getCharset();
    /** Get creation date */
    ZonedDateTime getCreationDate();
    /** Get modification date */
    ZonedDateTime getModificationDate();
    /** Get read date */
    ZonedDateTime getReadDate();
    /** Get size parameter */
    Long getSize();
    
    // Builder methods
    static ContentDisposition.Builder attachment();
    static ContentDisposition.Builder formData();
    static ContentDisposition.Builder inline();
    static ContentDisposition parse(String contentDisposition);
}

interface ContentDisposition.Builder {
    ContentDisposition.Builder name(String name);
    ContentDisposition.Builder filename(String filename);
    ContentDisposition.Builder filename(String filename, Charset charset);
    ContentDisposition.Builder creationDate(ZonedDateTime creationDate);
    ContentDisposition.Builder modificationDate(ZonedDateTime modificationDate);
    ContentDisposition.Builder readDate(ZonedDateTime readDate);
    ContentDisposition.Builder size(Long size);
    ContentDisposition build();
}

/**
 * Builder for Cache-Control HTTP header values
 */
class CacheControl {
    // Factory methods
    static CacheControl empty();
    static CacheControl maxAge(long maxAge, TimeUnit unit);
    static CacheControl maxAge(Duration maxAge);
    static CacheControl noCache();
    static CacheControl noStore();
    
    // Directive methods
    CacheControl mustRevalidate();
    CacheControl noTransform();
    CacheControl cachePublic();
    CacheControl cachePrivate();
    CacheControl proxyRevalidate();
    CacheControl sMaxAge(long sMaxAge, TimeUnit unit);
    CacheControl sMaxAge(Duration sMaxAge);
    CacheControl staleWhileRevalidate(long staleWhileRevalidate, TimeUnit unit);
    CacheControl staleWhileRevalidate(Duration staleWhileRevalidate);
    CacheControl staleIfError(long staleIfError, TimeUnit unit);
    CacheControl staleIfError(Duration staleIfError);
    
    /** Get the Cache-Control header value */
    String getHeaderValue();
}

// Cache control configurations
CacheControl maxAge = CacheControl.maxAge(1, TimeUnit.HOURS).mustRevalidate();
CacheControl noCache = CacheControl.noCache();
CacheControl publicCache = CacheControl.maxAge(Duration.ofMinutes(30)).cachePublic();

// Use in response
ResponseEntity<String> response = ResponseEntity.ok()
    .cacheControl(maxAge)
    .body("Cached content");

/**
 * Represents an RFC 7807 Problem Detail for HTTP APIs
 */
class ProblemDetail {
    ProblemDetail(int status);
    
    /** Get problem type URI */
    URI getType();
    void setType(URI type);
    
    /** Get human-readable problem title */
    String getTitle();
    void setTitle(String title);
    
    /** Get HTTP status code */
    int getStatus();
    
    /** Get human-readable problem explanation */
    String getDetail();
    void setDetail(String detail);
    
    /** Get problem instance URI */
    URI getInstance();
    void setInstance(URI instance);
    
    /** Get additional properties */
    Map<String, Object> getProperties();
    void setProperty(String name, Object value);
    Object getProperty(String name);
    
    // Factory methods
    static ProblemDetail forStatus(HttpStatusCode status);
    static ProblemDetail forStatus(int status);
    static ProblemDetail forStatusAndDetail(HttpStatusCode status, String detail);
}

// Create problem details
ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
problem.setTitle("Validation Failed");
problem.setDetail("The request contains invalid parameters");
problem.setProperty("invalidFields", Arrays.asList("email", "age"));

// Use in exception handler
@ExceptionHandler(ValidationException.class)
public ResponseEntity<ProblemDetail> handleValidation(ValidationException ex) {
    ProblemDetail problem = ProblemDetail.forStatusAndDetail(
        HttpStatus.BAD_REQUEST, 
        ex.getMessage()
    );
    return ResponseEntity.badRequest().body(problem);
}

/**
 * Base interface for HTTP request and response messages
 */
interface HttpMessage {
    /** Get the HTTP headers */
    HttpHeaders getHeaders();
}

/**
 * HTTP input message with readable body content
 */
interface HttpInputMessage extends HttpMessage {
    /** Get the message body as an input stream */
    InputStream getBody() throws IOException;
}

/**
 * HTTP output message with writable body content
 */
interface HttpOutputMessage extends HttpMessage {
    /** Get the message body as an output stream */
    OutputStream getBody() throws IOException;
}

/**
 * HTTP request message
 */
interface HttpRequest extends HttpMessage {
    /** Get the HTTP method */
    HttpMethod getMethod();
    /** Get the request URI */
    URI getURI();
}

/**
 * Reactive HTTP input message with streaming body
 */
interface ReactiveHttpInputMessage extends HttpMessage {
    /** Get the message body as a reactive stream */
    Flux<DataBuffer> getBody();
}

/**
 * Reactive HTTP output message with streaming body
 */
interface ReactiveHttpOutputMessage extends HttpMessage {
    /** Get the data buffer factory */
    DataBufferFactory bufferFactory();
    /** Register action to execute before commit */
    void beforeCommit(Supplier<? extends Mono<Void>> action);
    /** Check if response is committed */
    boolean isCommitted();
    /** Write body content */
    Mono<Void> writeWith(Publisher<? extends DataBuffer> body);
    /** Write and flush body content */
    Mono<Void> writeAndFlushWith(Publisher<? extends Publisher<? extends DataBuffer>> body);
    /** Complete the response */
    Mono<Void> setComplete();
}