WebFramework.java
package com.renomad.minum.web;
import com.renomad.minum.logging.ILogger;
import com.renomad.minum.security.ForbiddenUseException;
import com.renomad.minum.security.ITheBrig;
import com.renomad.minum.security.UnderInvestigation;
import com.renomad.minum.state.Constants;
import com.renomad.minum.state.Context;
import com.renomad.minum.utils.*;
import java.io.IOException;
import java.net.SocketException;
import java.net.SocketTimeoutException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.util.*;
import static com.renomad.minum.utils.FileUtils.checkFileIsWithinDirectory;
import static com.renomad.minum.utils.FileUtils.checkForBadFilePatterns;
import static com.renomad.minum.web.StatusLine.StatusCode.*;
import static com.renomad.minum.web.WebEngine.HTTP_CRLF;
/**
* This class is responsible for the HTTP handling after socket connection.
* <p>
* The public methods are for registering endpoints - code that will be
* run for a given combination of HTTP method and path. See documentation
* for the methods in this class.
* </p>
*/
public final class WebFramework {
private final Constants constants;
private final UnderInvestigation underInvestigation;
private final IInputStreamUtils inputStreamUtils;
private final IBodyProcessor bodyProcessor;
/**
* This is a variable storing a pseudo-random (non-secure) number
* that is shown to users when a serious error occurs, which
* will also be put in the logs, to make finding it easier.
*/
private final Random randomErrorCorrelationId;
private final RequestLine emptyRequestLine;
private final RequestLine validRequestLine;
private final ITheBrig theBrig;
public Map<String,String> getSuffixToMimeMappings() {
return new HashMap<>(fileSuffixToMime);
}
/**
* This is used as a key when registering endpoints
*/
record MethodPath(RequestLine.Method method, String path) { }
/**
* The list of paths that our system is registered to handle.
*/
private final Map<MethodPath, ThrowingFunction<IRequest, IResponse>> registeredDynamicPaths;
/**
* These are registrations for paths that partially match, for example,
* if the client sends us GET /.well-known/acme-challenge/HGr8U1IeTW4kY_Z6UIyaakzOkyQgPr_7ArlLgtZE8SX
* and we want to match ".well-known/acme-challenge"
*/
private final Map<MethodPath, ThrowingFunction<IRequest, IResponse>> registeredPartialPaths;
/**
* A function that will be run instead of the ordinary business code. Has
* provisions for running the business code as well. See {@link #registerPreHandler(ThrowingFunction)}
*/
private ThrowingFunction<PreHandlerInputs, IResponse> preHandler;
/**
* A function run after the ordinary business code
*/
private ThrowingFunction<LastMinuteHandlerInputs, IResponse> lastMinuteHandler;
private final IFileReader fileReader;
private final Map<String, String> fileSuffixToMime;
// This is just used for testing. If it's null, we use the real time.
private final ZonedDateTime overrideForDateTime;
private final FullSystem fs;
private final ILogger logger;
/**
* This is the minimum number of bytes in a text response to apply gzip.
*/
private static final int MINIMUM_NUMBER_OF_BYTES_TO_COMPRESS = 2048;
void httpProcessing(ISocketWrapper sw) throws Exception {
try (sw) {
dumpIfAttacker(sw, fs);
final var is = sw.getInputStream();
// By default, browsers expect the server to run in keep-alive mode.
// We'll break out later if we find that the browser doesn't do keep-alive
while (true) {
final String rawStartLine = inputStreamUtils.readLine(is);
long startMillis = System.currentTimeMillis();
if (rawStartLine == null || rawStartLine.isEmpty()) {
// here, the client connected, sent nothing, and closed.
// nothing to do but return.
logger.logTrace(() -> "rawStartLine was empty. Returning.");
break;
}
final RequestLine requestLine = getProcessedRequestLine(sw, rawStartLine);
if (requestLine.equals(emptyRequestLine)) {
// here, the client sent something we cannot parse.
// nothing to do but return.
logger.logTrace(() -> "RequestLine was unparseable. Returning.");
break;
}
// check if the user is seeming to attack us.
checkIfSuspiciousPath(sw, requestLine);
// React to what the user requested, generate a result
Headers headers = getHeaders(sw);
boolean isKeepAlive = determineIfKeepAlive(requestLine, headers, logger);
IRequest request = new Request(headers, requestLine, sw.getRemoteAddr(), sw, bodyProcessor);
IResponse response = processRequest(request, sw, requestLine, headers);
// check that the response is non-null. If it is null, that suggests
// the developer made a mistake.
if (response == null) {
throw new WebServerException("The returned value for the endpoint \"%s\" was null.".formatted(request.getRequestLine().getPathDetails().getIsolatedPath()));
}
// calculate proper headers for the response
StringBuilder headerStringBuilder = addDefaultHeaders(response);
addOptionalExtraHeaders(response, headerStringBuilder);
addKeepAliveTimeout(isKeepAlive, headerStringBuilder);
// inspect the response being sent, see whether we can compress the data.
IResponse adjustedResponse = potentiallyCompress(request.getHeaders(), response, headerStringBuilder);
applyContentLength(headerStringBuilder, adjustedResponse.getBodyLength());
confirmBodyHasContentType(request, response);
// send the headers
sw.send(headerStringBuilder.append(HTTP_CRLF).toString().getBytes(StandardCharsets.US_ASCII));
// if the user sent a HEAD request, we send everything back except the body.
// even though we skip the body, this requires full processing to get the
// numbers right, like content-length.
if (request.getRequestLine().getMethod().equals(RequestLine.Method.HEAD)) {
logger.logDebug(() -> "client " + request.getRemoteRequester() +
" is requesting HEAD for " + request.getRequestLine().getPathDetails().getIsolatedPath() +
". Excluding body from response");
} else {
// send the body
adjustedResponse.sendBody(sw);
}
sw.flush();
// print how long this processing took
long endMillis = System.currentTimeMillis();
logger.logTrace(() -> String.format("full processing (including communication time) of %s %s took %d millis", sw, requestLine, endMillis - startMillis));
if (!isKeepAlive) break;
}
} catch (SocketException | SocketTimeoutException ex) {
handleReadTimedOut(sw, ex, logger);
} catch (ForbiddenUseException ex) {
handleForbiddenUse(sw, ex, logger, theBrig, constants.vulnSeekingJailDuration);
} catch (IOException ex) {
handleIOException(sw, ex, logger, theBrig, underInvestigation, constants.vulnSeekingJailDuration);
}
}
static void handleIOException(ISocketWrapper sw, IOException ex, ILogger logger, ITheBrig theBrig, UnderInvestigation underInvestigation, int vulnSeekingJailDuration ) {
logger.logDebug(() -> ex.getMessage() + " (at Server.start)");
String suspiciousClues = underInvestigation.isClientLookingForVulnerabilities(ex.getMessage());
if (!suspiciousClues.isEmpty() && theBrig != null) {
logger.logDebug(() -> sw.getRemoteAddr() + " is looking for vulnerabilities, for this: " + suspiciousClues);
theBrig.sendToJail(sw.getRemoteAddr() + "_vuln_seeking", vulnSeekingJailDuration);
}
}
static void handleForbiddenUse(ISocketWrapper sw, ForbiddenUseException ex, ILogger logger, ITheBrig theBrig, int vulnSeekingJailDuration) {
logger.logDebug(() -> sw.getRemoteAddr() + " is looking for vulnerabilities, for this: " + ex.getMessage());
if (theBrig != null) {
theBrig.sendToJail(sw.getRemoteAddr() + "_vuln_seeking", vulnSeekingJailDuration);
} else {
logger.logDebug(() -> "theBrig is null at handleForbiddenUse, will not store address in database");
}
}
static void handleReadTimedOut(ISocketWrapper sw, IOException ex, ILogger logger) {
/*
if we close the application on the server side, there's a good
likelihood a SocketException will come bubbling through here.
NOTE:
it seems that Socket closed is what we get when the client closes the connection in non-SSL, and conversely,
if we are operating in secure (i.e. SSL/TLS) mode, we get "an established connection..."
*/
if (ex.getMessage().equals("Read timed out")) {
logger.logTrace(() -> "Read timed out - remote address: " + sw.getRemoteAddrWithPort());
} else {
logger.logDebug(() -> ex.getMessage() + " - remote address: " + sw.getRemoteAddrWithPort());
}
}
/**
* Logic for how to process an incoming request. For example, did the developer
* write a function to handle this? Is it a request for a static file, like an image
* or script? Did the user provide a "pre" or "post" handler?
*/
IResponse processRequest(
IRequest clientRequest,
ISocketWrapper sw,
RequestLine requestLine,
Headers requestHeaders) throws Exception {
IResponse response;
ThrowingFunction<IRequest, IResponse> endpoint = findEndpointForThisStartline(requestLine, requestHeaders);
if (endpoint == null) {
response = Response.buildLeanResponse(CODE_404_NOT_FOUND);
} else {
long millisAtStart = System.currentTimeMillis();
try {
if (preHandler != null) {
response = preHandler.apply(new PreHandlerInputs(clientRequest, endpoint, sw));
} else {
response = endpoint.apply(clientRequest);
}
} catch (Exception ex) {
// if an error happens while running an endpoint's code, this is the
// last-chance handling of that error where we return a 500 and a
// random code to the client, so a developer can find the detailed
// information in the logs, which have that same value.
int randomNumber = randomErrorCorrelationId.nextInt();
logger.logAsyncError(() -> "error while running endpoint " + endpoint + ". Code: " + randomNumber + ". Error: " + StacktraceUtils.stackTraceToString(ex));
response = Response.buildResponse(CODE_500_INTERNAL_SERVER_ERROR, Map.of("Content-Type", "text/plain;charset=UTF-8"), "Server error: " + randomNumber);
}
long millisAtEnd = System.currentTimeMillis();
logger.logTrace(() -> String.format("handler processing of %s %s took %d millis", sw, requestLine, millisAtEnd - millisAtStart));
}
// if the user has chosen to customize the response based on status code, that will
// be applied now, and it will override the previous response.
if (lastMinuteHandler != null) {
response = lastMinuteHandler.apply(new LastMinuteHandlerInputs(clientRequest, response));
}
return response;
}
private Headers getHeaders(ISocketWrapper sw) {
/*
next we will read the headers (e.g. Content-Type: foo/bar) one-by-one.
the headers tell us vital information about the
body. If, for example, we're getting a POST and receiving a
www form url encoded, there will be a header of "content-length"
that will mention how many bytes to read. On the other hand, if
we're receiving a multipart, there will be no content-length, but
the content-type will include the boundary string.
*/
List<String> allHeaders = Headers.getAllHeaders(sw.getInputStream(), inputStreamUtils);
Headers hi = new Headers(allHeaders);
logger.logTrace(() -> "The headers are: " + hi.getHeaderStrings());
return hi;
}
/**
* determine if we are in a keep-alive connection
*/
static boolean determineIfKeepAlive(RequestLine sl, Headers hi, ILogger logger) {
boolean isKeepAlive = false;
if (sl.getVersion() == HttpVersion.ONE_DOT_ZERO) {
isKeepAlive = hi.hasKeepAlive();
} else if (sl.getVersion() == HttpVersion.ONE_DOT_ONE) {
isKeepAlive = ! hi.hasConnectionClose();
}
boolean finalIsKeepAlive = isKeepAlive;
logger.logTrace(() -> "Is this a keep-alive connection? " + finalIsKeepAlive);
return isKeepAlive;
}
RequestLine getProcessedRequestLine(ISocketWrapper sw, String rawStartLine) {
logger.logTrace(() -> sw + ": raw request line received: " + rawStartLine);
RequestLine extractedRequestLine = validRequestLine.extractRequestLine(rawStartLine);
logger.logTrace(() -> sw + ": RequestLine has been derived: " + extractedRequestLine);
return extractedRequestLine;
}
void checkIfSuspiciousPath(ISocketWrapper sw, RequestLine requestLine) {
String suspiciousClues = underInvestigation.isLookingForSuspiciousPaths(
requestLine.getPathDetails().getIsolatedPath());
if (!suspiciousClues.isEmpty()) {
String msg = sw.getRemoteAddr() + " is looking for a vulnerability, for this: " + suspiciousClues;
throw new ForbiddenUseException(msg);
}
}
/**
* Drops the connection immediately if the client is recognized
* as someone we consider an attacker, by dint of having been
* added to a blacklist in {@link com.renomad.minum.security.TheBrig}.
*/
boolean dumpIfAttacker(ISocketWrapper sw, FullSystem fs) {
if (fs == null) {
return false;
} else if (fs.getTheBrig() == null) {
return false;
} else {
dumpIfAttacker(sw, fs.getTheBrig());
return true;
}
}
void dumpIfAttacker(ISocketWrapper sw, ITheBrig theBrig) {
String remoteClient = sw.getRemoteAddr();
if (theBrig.isInJail(remoteClient + "_vuln_seeking")) {
// if this client is a vulnerability seeker, throw an exception,
// causing them to get dumped unceremoniously
String message = "closing the socket on " + remoteClient + " due to being found in the brig";
logger.logDebug(() -> message);
throw new ForbiddenUseException(message);
}
}
/**
* Prepare some of the basic server response headers, like the status code, the
* date-time stamp, the server name.
*/
private StringBuilder addDefaultHeaders(IResponse response) {
String date = Objects.requireNonNullElseGet(overrideForDateTime, () -> ZonedDateTime.now(ZoneId.of("UTC"))).format(DateTimeFormatter.RFC_1123_DATE_TIME);
// we'll store the status line and headers in this
StringBuilder headerStringBuilder = new StringBuilder(600); // 600 is just a magic arbitrary number I picked, because our response headers
// are not usually too large - even if the user added a bunch, there is a good
// chance it would be far under 600. If that turns out to be wrong, adjust/redesign
// add the status line
headerStringBuilder.append("HTTP/1.1 ").append(response.getStatusCode().code).append(" ").append(response.getStatusCode().shortDescription).append(HTTP_CRLF);
// add a date-timestamp
headerStringBuilder.append("Date: ").append(date).append(HTTP_CRLF);
// add the server name
headerStringBuilder.append("Server: minum").append(HTTP_CRLF);
return headerStringBuilder;
}
/**
* Add extra headers specified by the business logic (set by the developer)
*/
private static void addOptionalExtraHeaders(IResponse response, StringBuilder stringBuilder) {
for (Map.Entry<String,String> header : response.getExtraHeaders().entrySet()) {
stringBuilder.append(header.getKey())
.append(": ")
.append(header.getValue())
.append(HTTP_CRLF);
}
}
/**
* If a response body exists, it needs to have a content-type specified,
* or throw an exception. Otherwise, the user could totally miss they did
* not set a content-type, because the browser will inspect the data and
* do sort-of-the-right-thing a lot of the time, but we want to enforce correctness.
*/
static void confirmBodyHasContentType(IRequest request, IResponse response) {
// check the correctness of the content-type header versus the data length (if any data, that is)
boolean hasContentType = response.getExtraHeaders().keySet().stream().anyMatch(x -> x.toLowerCase(Locale.ROOT).equals("content-type"));
// if there *is* data, we had better be returning a content type
if (response.getBodyLength() > 0 && !hasContentType) {
throw new WebServerException("a Content-Type header must be specified in the Response object if it returns data. Response details: " + response + " Request: " + request);
}
}
/**
* If this is a keep-alive communication, add a header specifying the
* socket timeout for the browser.
*/
private void addKeepAliveTimeout(boolean isKeepAlive, StringBuilder stringBuilder) {
// if we're a keep-alive connection, reply with a keep-alive header
if (isKeepAlive) {
stringBuilder.append("Keep-Alive: timeout=").append(constants.keepAliveTimeoutSeconds).append(HTTP_CRLF);
}
}
/**
* The rules regarding the content-length header are byzantine. Even in the cases
* where you aren't returning anything, servers can use this header to determine when the
* response is finished.
* See <a href="https://www.rfc-editor.org/rfc/rfc9110.html#name-content-length">Content-Length in the HTTP spec</a>
*/
private static void applyContentLength(StringBuilder stringBuilder, long bodyLength) {
stringBuilder.append("Content-Length: ").append(bodyLength).append(HTTP_CRLF);
}
/**
* This method will examine the request headers and response content-type, and
* compress the outgoing data if necessary.
*/
static IResponse potentiallyCompress(Headers requestHeaders, IResponse response, StringBuilder headerStringBuilder) throws IOException {
// we may make modifications to the response body at this point, specifically
// we may compress the data, if the client requested it.
// see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-encoding
List<String> acceptEncoding = requestHeaders.valueByKey("accept-encoding");
if (response.isBodyText()) {
return compressBodyIfRequested(response, acceptEncoding, headerStringBuilder, MINIMUM_NUMBER_OF_BYTES_TO_COMPRESS);
}
return response;
}
/**
* This method will examine the content-encoding headers, and if "gzip" is
* requested by the client, we will replace the body bytes with compressed
* bytes, using the GZIP compression algorithm, as long as the response body
* is greater than minNumberBytes bytes.
*
* @param acceptEncoding headers sent by the client about what compression
* algorithms will be understood.
* @param stringBuilder the string we are gradually building up to send back to
* the client for the status line and headers. We'll use it
* here if we need to append a content-encoding - that is,
* if we successfully compress data as gzip.
* @param minNumberBytes number of bytes must be larger than this to compress.
*/
static IResponse compressBodyIfRequested(IResponse response, List<String> acceptEncoding, StringBuilder stringBuilder, int minNumberBytes) throws IOException {
String allContentEncodingHeaders = acceptEncoding != null ? String.join(";", acceptEncoding) : "";
if (response.getBodyLength() >= minNumberBytes && allContentEncodingHeaders.contains("gzip")) {
stringBuilder.append("Content-Encoding: gzip").append(HTTP_CRLF);
stringBuilder.append("Vary: accept-encoding").append(HTTP_CRLF);
return ((Response)response).compressBody();
}
return response;
}
/**
* Looks through the mappings of {@link MethodPath} and path to registered endpoints
* or the static cache and returns the appropriate one (If we
* do not find anything, return null)
*/
ThrowingFunction<IRequest, IResponse> findEndpointForThisStartline(RequestLine sl, Headers requestHeaders) {
ThrowingFunction<IRequest, IResponse> handler;
logger.logTrace(() -> "Seeking a handler for " + sl);
// first we check if there's a simple direct match
String requestedPath = sl.getPathDetails().getIsolatedPath().toLowerCase(Locale.ROOT);
// if the user is asking for a HEAD request, they want to run a GET command
// but don't want the body. We'll simply exclude sending the body, later on, when returning the data
RequestLine.Method method = sl.getMethod() == RequestLine.Method.HEAD ? RequestLine.Method.GET : sl.getMethod();
MethodPath key = new MethodPath(method, requestedPath);
handler = registeredDynamicPaths.get(key);
if (handler == null) {
logger.logTrace(() -> "No direct handler found. looking for a partial match for " + requestedPath);
handler = findHandlerByPartialMatch(sl);
}
if (handler == null) {
logger.logTrace(() -> "No partial match found, checking files on disk for " + requestedPath );
handler = findHandlerByFilesOnDisk(sl, requestHeaders);
}
// we'll return this, and it could be a null.
return handler;
}
/**
* last ditch effort - look on disk. This response will either
* be the file to return, or null if we didn't find anything.
*/
private ThrowingFunction<IRequest, IResponse> findHandlerByFilesOnDisk(RequestLine sl, Headers requestHeaders) {
if (sl.getMethod() != RequestLine.Method.GET && sl.getMethod() != RequestLine.Method.HEAD) {
return null;
}
String requestedPath = sl.getPathDetails().getIsolatedPath();
IResponse response = readStaticFile(requestedPath, requestHeaders);
return request -> response;
}
/**
* Get a file from a path and create a response for it with a mime type.
* <p>
* Parent directories are made unavailable by searching the path for
* bad characters. see {@link FileUtils#checkForBadFilePatterns}
* </p>
*
* @return a response with the file contents and caching headers and mime if valid.
* if the path has invalid characters, we'll return a "bad request" response.
*/
IResponse readStaticFile(String path, Headers requestHeaders) {
try {
checkForBadFilePatterns(path);
} catch (Exception ex) {
logger.logDebug(() -> String.format("Bad path requested at readStaticFile: %s. Exception: %s", path, ex.getMessage()));
return Response.buildLeanResponse(CODE_400_BAD_REQUEST);
}
String mimeType = null;
try {
checkFileIsWithinDirectory(path, constants.staticFilesDirectory);
} catch (Exception ex) {
logger.logDebug(() -> String.format("Unable to find %s in allowed directories", path));
return Response.buildLeanResponse(CODE_404_NOT_FOUND);
}
try {
Path staticFilePath = Path.of(constants.staticFilesDirectory).resolve(path);
if (!Files.isRegularFile(staticFilePath)) {
logger.logDebug(() -> String.format("No readable regular file found at %s", path));
return Response.buildLeanResponse(CODE_404_NOT_FOUND);
}
// if the provided path has a dot in it, use that
// to obtain a suffix for determining file type
int suffixBeginIndex = path.lastIndexOf('.');
if (suffixBeginIndex > 0) {
String suffix = path.substring(suffixBeginIndex+1);
mimeType = fileSuffixToMime.get(suffix);
}
// if we don't find any registered mime types for this
// suffix, or if it doesn't have a suffix, set the mime type
// to application/octet-stream
if (mimeType == null) {
mimeType = "application/octet-stream";
}
if (Files.size(staticFilePath) < 100_000) {
var fileContents = fileReader.readFile(staticFilePath.toString());
return createOkResponseForStaticFiles(fileContents, mimeType);
} else {
return createOkResponseForLargeStaticFiles(mimeType, staticFilePath, requestHeaders);
}
} catch (IOException e) {
logger.logAsyncError(() -> String.format("Error while reading file: %s. %s", path, StacktraceUtils.stackTraceToString(e)));
return Response.buildLeanResponse(CODE_400_BAD_REQUEST);
}
}
/**
* All static responses will get a cache time of STATIC_FILE_CACHE_TIME seconds
*/
private IResponse createOkResponseForStaticFiles(byte[] fileContents, String mimeType) {
var headers = Map.of(
"cache-control", "max-age=" + constants.staticFileCacheTime,
"content-type", mimeType);
return Response.buildResponse(
CODE_200_OK,
headers,
fileContents);
}
/**
* All static responses will get a cache time of STATIC_FILE_CACHE_TIME seconds
*/
private IResponse createOkResponseForLargeStaticFiles(String mimeType, Path filePath, Headers requestHeaders) throws IOException {
var headers = Map.of(
"cache-control", "max-age=" + constants.staticFileCacheTime,
"content-type", mimeType,
"Accept-Ranges", "bytes"
);
return Response.buildLargeFileResponse(
headers,
filePath.toString(),
requestHeaders
);
}
/**
* These are the default starting values for mappings
* between file suffixes and appropriate mime types
*/
private void addDefaultValuesForMimeMap() {
fileSuffixToMime.put("css", "text/css");
fileSuffixToMime.put("js", "application/javascript");
fileSuffixToMime.put("webp", "image/webp");
fileSuffixToMime.put("jpg", "image/jpeg");
fileSuffixToMime.put("jpeg", "image/jpeg");
fileSuffixToMime.put("htm", "text/html");
fileSuffixToMime.put("html", "text/html");
}
/**
* let's see if we can match the registered paths against a **portion** of the startline
*/
ThrowingFunction<IRequest, IResponse> findHandlerByPartialMatch(RequestLine sl) {
String requestedPath = sl.getPathDetails().getIsolatedPath();
var methodPathFunctionEntry = registeredPartialPaths.entrySet().stream()
.filter(x -> requestedPath.startsWith(x.getKey().path()) &&
x.getKey().method().equals(sl.getMethod()))
.findFirst().orElse(null);
if (methodPathFunctionEntry != null) {
return methodPathFunctionEntry.getValue();
} else {
return null;
}
}
/**
* This constructor is used for the real production system
*/
WebFramework(Context context) {
this(context, null, null);
}
WebFramework(Context context, ZonedDateTime overrideForDateTime) {
this(context, overrideForDateTime, null);
}
/**
* This provides the ZonedDateTime as a parameter so we
* can set the current date (for testing purposes)
* @param overrideForDateTime for those test cases where we need to control the time
*/
WebFramework(Context context, ZonedDateTime overrideForDateTime, IFileReader fileReader) {
this.fs = context.getFullSystem();
this.theBrig = this.fs != null ? this.fs.getTheBrig() : null;
this.logger = context.getLogger();
this.constants = context.getConstants();
this.overrideForDateTime = overrideForDateTime;
this.registeredDynamicPaths = new HashMap<>();
this.registeredPartialPaths = new HashMap<>();
this.underInvestigation = new UnderInvestigation(constants);
this.inputStreamUtils = new InputStreamUtils(constants.maxReadLineSizeBytes);
this.bodyProcessor = new BodyProcessor(context);
// This random value is purely to help provide correlation between
// error messages in the UI and error logs. There are no security concerns.
this.randomErrorCorrelationId = new Random();
this.validRequestLine = new RequestLine(
RequestLine.Method.NONE,
PathDetails.empty,
HttpVersion.NONE,
"", logger);
this.emptyRequestLine = RequestLine.EMPTY;
// this allows us to inject a IFileReader for deeper testing
if (fileReader != null) {
this.fileReader = fileReader;
} else {
this.fileReader = new FileReader(
LRUCache.getLruCache(constants.maxElementsLruCacheStaticFiles),
constants.useCacheForStaticFiles,
logger);
}
this.fileSuffixToMime = new HashMap<>();
addDefaultValuesForMimeMap();
readExtraMimeMappings(constants.extraMimeMappings);
}
void readExtraMimeMappings(List<String> input) {
if (input == null || input.isEmpty()) return;
if (!(input.size() % 2 == 0)) {
throw new WebServerException("input must be even (key + value = 2 items). Your input: " + input);
}
for (int i = 0; i < input.size(); i += 2) {
String fileSuffix = input.get(i);
String mime = input.get(i+1);
logger.logTrace(() -> "Adding mime mapping: " + fileSuffix + " -> " + mime);
fileSuffixToMime.put(fileSuffix, mime);
}
}
/**
* Add a new handler in the web application for a combination
* of a {@link RequestLine.Method}, a path, and then provide
* the code to handle a request.
* <br>
* Note that the path text expected is *after* the first forward slash,
* so for example with {@code http://foo.com/mypath}, provide "mypath" as the path.
* @throws WebServerException if duplicate paths are registered, or if the path is prefixed with a slash
*/
public void registerPath(RequestLine.Method method, String pathName, ThrowingFunction<IRequest, IResponse> webHandler) {
if (pathName.startsWith("\\") || pathName.startsWith("/")) {
throw new WebServerException(
String.format("Path should not be prefixed with a slash. Corrected version: registerPath(%s, \"%s\", ... )", method.name(), pathName.substring(1)));
}
var result = registeredDynamicPaths.put(new MethodPath(method, pathName), webHandler);
if (result != null) {
throw new WebServerException("Duplicate endpoint registered: " + new MethodPath(method, pathName));
}
}
/**
* Similar to {@link WebFramework#registerPath(RequestLine.Method, String, ThrowingFunction)} except that the paths
* registered here may be partially matched.
* <p>
* For example, if you register {@code .well-known/acme-challenge} then it
* can match a client request for {@code .well-known/acme-challenge/HGr8U1IeTW4kY_Z6UIyaakzOkyQgPr_7ArlLgtZE8SX}
* </p>
* <p>
* Be careful here, be thoughtful - partial paths will match a lot, and may
* overlap with other URL's for your app, such as endpoints and static files.
* </p>
* @throws WebServerException if duplicate paths are registered, or if the path is prefixed with a slash
*/
public void registerPartialPath(RequestLine.Method method, String pathName, ThrowingFunction<IRequest, IResponse> webHandler) {
if (pathName.startsWith("\\") || pathName.startsWith("/")) {
throw new WebServerException(
String.format("Path should not be prefixed with a slash. Corrected version: registerPartialPath(%s, \"%s\", ... )", method.name(), pathName.substring(1)));
}
var result = registeredPartialPaths.put(new MethodPath(method, pathName), webHandler);
if (result != null) {
throw new WebServerException("Duplicate partial-path endpoint registered: " + new MethodPath(method, pathName));
}
}
/**
* Sets a handler to process all requests across the board.
* <br>
* <p>
* This is an <b>unusual</b> method. Setting a handler here allows the user to run code of his
* choosing before the regular business code is run. Note that by defining this value, the ordinary
* call to endpoint.apply(request) will not be run.
* </p>
* <p>Here is an example</p>
* <pre>{@code
*
* webFramework.registerPreHandler(preHandlerInputs -> preHandlerCode(preHandlerInputs, auth, context));
*
* ...
*
* private IResponse preHandlerCode(PreHandlerInputs preHandlerInputs, AuthUtils auth, Context context) throws Exception {
* int secureServerPort = context.getConstants().secureServerPort;
* Request request = preHandlerInputs.clientRequest();
* ThrowingFunction<IRequest, IResponse> endpoint = preHandlerInputs.endpoint();
* ISocketWrapper sw = preHandlerInputs.sw();
*
* // log all requests
* logger.logTrace(() -> String.format("Request: %s by %s",
* request.requestLine().getRawValue(),
* request.remoteRequester())
* );
*
* // redirect to https if they are on the plain-text connection and the path is "login"
*
* // get the path from the request line
* String path = request.getRequestLine().getPathDetails().getIsolatedPath();
*
* // redirect to https on the configured secure port if they are on the plain-text connection and the path contains "login"
* if (path.contains("login") &&
* sw.getServerType().equals(HttpServerType.PLAIN_TEXT_HTTP)) {
* return Response.redirectTo("https://%s:%d/%s".formatted(sw.getHostName(), secureServerPort, path));
* }
*
* // adjust behavior if non-authenticated and path includes "secure/"
* if (path.contains("secure/")) {
* AuthResult authResult = auth.processAuth(request);
* if (authResult.isAuthenticated()) {
* return endpoint.apply(request);
* } else {
* return Response.buildLeanResponse(CODE_403_FORBIDDEN);
* }
* }
*
* // if the path does not include /secure, just move the request along unchanged.
* return endpoint.apply(request);
* }
* }</pre>
*/
public void registerPreHandler(ThrowingFunction<PreHandlerInputs, IResponse> preHandler) {
this.preHandler = preHandler;
}
/**
* Sets a handler to be executed after running the ordinary handler, just
* before sending the response.
* <p>
* This is an <b>unusual</b> method, so please be aware of its proper use. Its
* purpose is to allow the user to inject code to run after ordinary code, across
* all requests.
* </p>
* <p>
* For example, if the system would have returned a 404 NOT FOUND response,
* code can handle that situation in a switch case and adjust the response according
* to your programming.
* </p>
* <p>Here is an example</p>
* <pre>{@code
*
*
* webFramework.registerLastMinuteHandler(TheRegister::lastMinuteHandlerCode);
*
* ...
*
* private static IResponse lastMinuteHandlerCode(LastMinuteHandlerInputs inputs) {
* switch (inputs.response().statusCode()) {
* case CODE_404_NOT_FOUND -> {
* return Response.buildResponse(
* CODE_404_NOT_FOUND,
* Map.of("Content-Type", "text/html; charset=UTF-8"),
* "<p>No document was found</p>"));
* }
* case CODE_500_INTERNAL_SERVER_ERROR -> {
* return Response.buildResponse(
* CODE_500_INTERNAL_SERVER_ERROR,
* Map.of("Content-Type", "text/html; charset=UTF-8"),
* "<p>Server error occurred.</p>" ));
* }
* default -> {
* return inputs.response();
* }
* }
* }
* }
* </pre>
* @param lastMinuteHandler a function that will take a request and return a response, exactly like
* we use in the other registration methods for this class.
*/
public void registerLastMinuteHandler(ThrowingFunction<LastMinuteHandlerInputs, IResponse> lastMinuteHandler) {
this.lastMinuteHandler = lastMinuteHandler;
}
/**
* This allows users to add extra mappings
* between file suffixes and mime types, in case
* a user needs one that was not provided.
* <p>
* This is made available through the
* web framework.
* </p>
* <p>
* Example:
* </p>
* <pre>
* {@code webFramework.addMimeForSuffix().put("foo","text/foo")}
* </pre>
*/
public void addMimeForSuffix(String suffix, String mimeType) {
fileSuffixToMime.put(suffix, mimeType);
}
}