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.state.Constants;
import com.renomad.minum.state.Context;
import com.renomad.minum.utils.*;

import javax.net.ssl.SSLException;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.net.SocketException;
import java.net.SocketTimeoutException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.util.*;
import java.util.function.Function;
import java.util.zip.GZIPOutputStream;

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 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 validRequestLine;
    private final ITheBrig theBrig;
    private final IFileUtils fileUtils;

    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 cases where the function depends on parts of the path conditionally.
     * Like 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<RequestLine.Method, List<Function<String, ThrowingFunction<IRequest, IResponse>>>> registeredPathFunctions;

    /**
     * A special path function that checks if the path starts with the defined one.
     * It's here to retain the duplication check on {@link #registerPartialPath(RequestLine.Method, String, ThrowingFunction)},
     */
    private record PartialPathFunction(String pathName, ThrowingFunction<IRequest, IResponse> handler) implements Function<String, ThrowingFunction<IRequest, IResponse>> {
        @Override
        public ThrowingFunction<IRequest, IResponse> apply(String path) {
            return path.startsWith(pathName) ? handler : null;
        }
    }

    /**
     * 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) {
        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) {
                // 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

                // set some basic variables we'll need access to throughout
                long startMillis = System.currentTimeMillis();
                RequestLine requestLine = RequestLine.EMPTY;
                IRequest request;
                Headers headers = Headers.EMPTY;
                IResponse response;
                boolean isKeepAlive = false;
                IResponse adjustedResponse;
                boolean isHeadRequest = false;

                final String rawStartLine = inputStreamUtils.readLine(is);

                try {
                    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;
                    }
                    requestLine = getProcessedRequestLine(sw, rawStartLine);

                    // check if the user is seeming to attack us.
                    checkIfSuspiciousPath(sw, requestLine);

                    // React to what the user requested, generate a result
                    headers = getHeaders(sw);
                    request = new Request(headers, requestLine, sw.getRemoteAddr(), sw, bodyProcessor);
                    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()));
                    }

                    isKeepAlive = determineIfKeepAlive(request, logger, request.hasAccessedBody());

                    // calculate proper headers for the response
                    addDefaultHeaders(response, headerStringBuilder);
                    response.getExtraHeaders().appendHeadersToBuilder(headerStringBuilder);
                    addKeepAliveTimeout(isKeepAlive, headerStringBuilder);

                    // inspect the response being sent, see whether we can compress the data.
                    adjustedResponse = potentiallyCompress(headers, response, headerStringBuilder);
                    applyContentLength(headerStringBuilder, adjustedResponse.getBodyLength());
                    confirmBodyHasContentType(request, response);

                    // 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");
                        isHeadRequest = true;
                    }

                } catch (BadRequestException ex) {
                    // this catch block needs to be down below the scope where
                    // the request variable is needed.
                    headerStringBuilder.setLength(0); // clear the contents
                    adjustedResponse = handleBadRequestException(ex);
                    addDefaultHeaders(adjustedResponse, headerStringBuilder);
                    isKeepAlive = false;
                    headerStringBuilder.append("Content-Length: ").append(adjustedResponse.getBodyLength()).append(HTTP_CRLF);
                }

                // send the headers
                sw.send(headerStringBuilder.append(HTTP_CRLF).toString().getBytes(StandardCharsets.US_ASCII));

                if (!isHeadRequest) {
                    // send the body
                    adjustedResponse.sendBody(sw);
                }

                // ship it out
                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, rawStartLine, endMillis - startMillis));

                if (!isKeepAlive) {
                    logger.logTrace(() -> "We will not keep-alive this connection - exiting loop and closing socket");
                    break;
                }

            }
        } catch (ForbiddenUseException ex) {
            handleForbiddenUse(sw, ex, logger, theBrig, constants.vulnSeekingJailDuration);
        } catch (Exception ex) {
            finalExceptionHandler(sw, ex, logger, theBrig, constants.vulnSeekingJailDuration, constants.suspiciousErrors);
        }
    }


    /**
     * Last-chance handler for any exceptions originating in WebFramework.httpProcessing
     */
    static void finalExceptionHandler(ISocketWrapper sw, Throwable ex, ILogger logger, ITheBrig theBrig,
                                      int vulnSeekingJailDuration, Set<String> suspiciousErrors) {
        // This first section catches a lot when clients make eager connections in anticipation of
        // parallel requests, but then let them time out.
        if (ex instanceof SocketException || ex instanceof SocketTimeoutException) {
            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());
            }
        } else if (suspiciousErrors.contains(ex.getMessage()) && theBrig != null) {
            logger.logDebug(() -> sw.getRemoteAddr() + " is looking for vulnerabilities, for this: " + ex.getMessage());
            theBrig.sendToJail(sw.getRemoteAddr() + "_vuln_seeking", vulnSeekingJailDuration);
        } else if (ex instanceof SSLException) {
            // at this point we just want to catch some of the common garbage exceptions that bubble up
            // as a result of clients force-closing their SSl connections
            logger.logTrace(() -> ex.getMessage() + "for remote address: " + sw.getRemoteAddrWithPort());
        } else {
            logger.logWarn(() -> "Exception caught in WebFramework.finalExceptionHandler: " + StacktraceUtils.stackTraceToString(ex));
        }
    }

    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");
        }
    }

    /**
     * if an error happens in parsing a request, and it's not considered an attack (which
     * would instead use ForbiddenUseException), this is the
     * last-chance handling of that error where we return a 400 Bad Request response and a
     * random code to the client, so a developer can find the detailed
     * information in the logs, which have that same value.
     */
    IResponse handleBadRequestException(BadRequestException ex) {
        int randomNumber = randomErrorCorrelationId.nextInt();
        logger.logDebug(() -> "Bad data in request. Code: " + randomNumber + " Error: " + ex.getMessage() + (ex.getCause() == null ? "" : " Cause: " + ex.getCause().getMessage()));
        return Response.buildResponse(CODE_400_BAD_REQUEST, new Headers(List.of("Content-Type: text/plain;charset=UTF-8")), "Bad request from user (HTTP 400) error: " + randomNumber);
    }

    /**
     * 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, new Headers(List.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 (lastMinuteHandler != null) {
            response = lastMinuteHandler.apply(new LastMinuteHandlerInputs(clientRequest, response));
        }

        return response;
    }

    private Headers getHeaders(ISocketWrapper sw) throws IOException {
    /*
       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.
     * <p>
     *     This checks the headers and request-line for characteristics
     *     which require keep-alive on or off.
     * </p>
     * <p>
     *     It also checks whether there are lingering unread bytes from
     *     a request.  If there are, it will set keep-alive to false, so
     *     that the following request will encounter a clean starting point.
     *     Lingering bytes could occur if the responsible handler does not
     *     read the body bytes sent to it.
     * </p>
     * <p>
     *     The algorithm is:
     *     <ul>
     *         <li>If the HTTP version is 1.0, then we keep-alive if there is a header telling us to</li>
     *         <li>If the HTTP version is 1.1, then we *stop* keep-alive if there is a header telling us to</li>
     *         <li>If we are keep-alive, but there are lingering body bytes that have not been read by
     *         the handler, set keep-alive to false</li>
     *     </ul>
     * </p>
     */
    static boolean determineIfKeepAlive(IRequest request, ILogger logger, boolean hasAccessedBody) {
        boolean isKeepAlive = false;
        if (request.getRequestLine().getVersion() == HttpVersion.ONE_DOT_ZERO) {
            isKeepAlive = request.getHeaders().hasKeepAlive();
        } else if (request.getRequestLine().getVersion() == HttpVersion.ONE_DOT_ONE) {
            isKeepAlive = ! request.getHeaders().hasConnectionClose();
        }

        if (isKeepAlive && request.getHeaders().contentLength() >= 0 && !hasAccessedBody) {
            // if there was a body and the user has not read it by this point, we will log the
            // discrepancy and close the socket.
            logger.logDebug(() -> ("A body sized %d bytes was included in the request, but the endpoint (%s) did not access the body. " +
                    "Closing socket after request is finished").formatted(request.getHeaders().contentLength(), request.getRequestLine().getPathDetails().getIsolatedPath()));
            isKeepAlive = false;
        }

        boolean finalIsKeepAlive = isKeepAlive;

        logger.logTrace(() -> "Is this a keep-alive connection? %s".formatted(finalIsKeepAlive));
        return finalIsKeepAlive;
    }

    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) {
        if (constants.suspiciousPaths.contains(requestLine.getPathDetails().getIsolatedPath())) {
            String msg = sw.getRemoteAddr() + " is looking for a vulnerability, for this: " + requestLine.getPathDetails().getIsolatedPath();
            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, StringBuilder headerStringBuilder) {
        String date = Objects.requireNonNullElseGet(overrideForDateTime,
                () -> ZonedDateTime.now(ZoneId.of("UTC"))).format(DateTimeFormatter.RFC_1123_DATE_TIME);

        // 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;
    }

    /**
     * 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().valueByKey("content-type") != null;

        // 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) {
        // 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) {
        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);
            var out = new ByteArrayOutputStream();
            compressBody(out, response.getBody());
            return Response.buildResponse(
                    response.getStatusCode(),
                    response.getExtraHeaders(),
                    out.toByteArray()
            );
        }
        return response;
    }

    /**
     * Compress the data in this body using gzip.
     * <br>
     * This operates by getting the body field from this instance of {@link Response} and
     * creating a new Response with the compressed data.
     * @param out this is provided as a parameter for better control during testing
     */
    static GZIPOutputStream compressBody(OutputStream out, byte[] body) {
        try (var gos = new GZIPOutputStream(out)) {
            gos.write(body);
            gos.finish();
            return gos;
        } catch (IOException e) {
            throw new WebServerException("Error in Response.compressBody", e);
        }
    }

    /**
     * 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 = findHandlerByPathFunction(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 {
            fileUtils.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 (!fileUtils.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 (fileUtils.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 = new Headers(List.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) {
        var headers = new Headers(List.of(
                "Cache-Control: max-age=" + constants.staticFileCacheTime,
                "Content-Type: " + mimeType,
                "Accept-Ranges: bytes"
                ));

        return Response.buildLargeFileResponse(
                headers,
                filePath.toString(),
                requestHeaders,
                fileUtils
                );
    }


    /**
     * 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 path function
     */
    ThrowingFunction<IRequest, IResponse> findHandlerByPathFunction(RequestLine sl) {
        var functionList = registeredPathFunctions.get(sl.getMethod());
        if (functionList == null) {
            return null;
        }
        String requestedPath = sl.getPathDetails().getIsolatedPath();
        return functionList.stream()
                .map(function -> function.apply(requestedPath))
                .filter(Objects::nonNull)
                .findFirst()
                .orElse(null);
    }

    /**
     * This constructor is used for the real production system
     */
    WebFramework(Context context) {
        this(context, null, null, null);
    }

    /**
     * This constructor is mainly used for testing
     */
    WebFramework(Context context, ZonedDateTime overrideForDateTime) {
        this(context, overrideForDateTime, null, null);
    }

    /**
     * A constructor with slots available for testing
     * @param overrideForDateTime for those test cases where we need to control the time. Providing null
     *                            for this parameter will cause code to use ZonedDateTime.now() instead,
     *                            which is the expected behavior during ordinary system use.
     * @param fileReader when we want to provide an instance for better control during testing. Providing
     *                   null here will cause a FileReader to be instantiated in the constructor.
     * @param fileUtils when we want to provide an instance for better control during testing. Providing
     *                  null here will cause a FileUtils to be instantiated in the constructor.
     */
    WebFramework(Context context, ZonedDateTime overrideForDateTime, IFileReader fileReader, IFileUtils fileUtils) {
        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.registeredPathFunctions = new EnumMap<>(RequestLine.Method.class);
        this.inputStreamUtils = new InputStreamUtils(constants.maxReadLineSizeBytes);
        this.bodyProcessor = new BodyProcessor(context);
        if (fileUtils != null) {
            this.fileUtils = fileUtils;
        } else {
            this.fileUtils = new FileUtils(logger, constants);
        }

        // 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 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));
        }

        checkForDuplicatePartialPath(method, pathName);
    }

    /**
     * check if the user had already registered a "partial path" with this pathName, which
     * means it would be duplicate endpoints, and throw an exception if so.
     */
    private void checkForDuplicatePartialPath(RequestLine.Method method, String pathName) {
        List<Function<String, ThrowingFunction<IRequest, IResponse>>> existingPathFunctions = registeredPathFunctions.get(method);
        if (existingPathFunctions != null) {
            if (existingPathFunctions.stream()
                    .filter(PartialPathFunction.class::isInstance)
                    .map(PartialPathFunction.class::cast)
                    .map(function -> function.pathName)
                    .anyMatch(pathName::equals)
            ) {
                throw new WebServerException("Duplicate partial-path endpoint registered: " + new MethodPath(method, pathName));
            }
        }
    }

    /**
     * Allows adding complex path function handling.
     * <p>
     *     <em>Note:</em> This is advanced functionality to provide extra flexibility
     *     to the developer.  It is intended for use in those situations where the
     *     minimalist approach is insufficient.  <em>Think hard whether this is truly
     *     necessary or if the base assumptions should be reconsidered before going this route</em>
     * </p>
     * <h4>
     *     Example use cases:
     * </h4>
     * <pre>{@code
     *
     * // an example helper method by the developer
     * private void registerPatternPath(RequestLine.Method method, Pattern pattern, BiFunction<IRequest, Matcher, IResponse> function) {
     *     webFramework.registerPath(method, path -> {
     *         Matcher matcher = pattern.matcher(path);
     *         if (matcher.matches()) {
     *             return request -> function.apply(request, matcher);
     *         }
     *         return null;
     *     });
     * }
     *
     * // a regular expression to look for paths like "/projects/123" and to
     * // collect the "123" part.
     * Pattern idMatcher = Pattern.compile("projects/(\\d+)");
     *
     * // a regular endpoint, no advanced usage
     * webFramework.registerPath(RequestLine.Method.GET, "projects", request -> {
     *     return Response.htmlOk("Do GET /projects");
     * });
     *
     * // registering a GET handler for the advanced use case
     * registerPatternPath(RequestLine.Method.GET, idMatcher, (request, matcher) -> {
     *     int id = Integer.parseInt(matcher.group(1));
     *     return Response.htmlOk("Do GET /projects/" + id);
     * });
     *
     * }</pre>
     */
    public void registerPath(RequestLine.Method method, Function<String, ThrowingFunction<IRequest, IResponse>> pathFunction) {
        registeredPathFunctions.computeIfAbsent(method, k -> new ArrayList<>()).add(pathFunction);
    }

    /**
     * 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)));
        }

        // if the user had previously registered a normal path with this value, it would
        // conflict and so we will throw an exception.
        if (registeredDynamicPaths.containsKey(new MethodPath(method, pathName))) {
            throw new WebServerException("Duplicate endpoint registered: " + new MethodPath(method, pathName));
        }

        checkForDuplicatePartialPath(method, pathName);
        registerPath(method, new PartialPathFunction(pathName, webHandler));
    }

    /**
     * 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);
    }
}






































































































Active mutators

CONDITIONALS_BOUNDARY
EMPTY_RETURNS
FALSE_RETURNS
INCREMENTS
INVERT_NEGS
MATH
NEGATE_CONDITIONALS
NULL_RETURNS
PRIMITIVE_RETURNS
TRUE_RETURNS
VOID_METHOD_CALLS
Tests examined

com.renomad.minum.web.WebPerformanceTests.test3(com.renomad.minum.web.WebPerformanceTests) (651 ms)
com.renomad.minum.web.WebPerformanceTests.test2(com.renomad.minum.web.WebPerformanceTests) (658 ms)
com.renomad.minum.FunctionalTests.test_PathFunction_Response(com.renomad.minum.FunctionalTests) (625 ms)
com.renomad.minum.FunctionalTests.test_EdgeCase_Response_MultiCookies(com.renomad.minum.FunctionalTests) (640 ms)
com.renomad.minum.FunctionalTests.test_EdgeCase_PostHandler_IgnoreBody(com.renomad.minum.FunctionalTests) (640 ms)
com.renomad.minum.FunctionalTests.test_PathFunction_Response_Range(com.renomad.minum.FunctionalTests) (641 ms)
com.renomad.minum.web.WebPerformanceTests.test1(com.renomad.minum.web.WebPerformanceTests) (784 ms)
com.renomad.minum.web.WebTests (698 ms)
com.renomad.minum.FunctionalTests.testEndToEnd_Functional(com.renomad.minum.FunctionalTests) (2358 ms)
com.renomad.minum.web.WebFrameworkTests (312 ms)
com.renomad.minum.web.WebEngineTests (129 ms)
com.renomad.minum.FunctionalTests.test_EdgeCase_IOExceptionThrown_WebFramework(com.renomad.minum.FunctionalTests) (678 ms)
com.renomad.minum.FunctionalTests.test_EdgeCase_BadRequest(com.renomad.minum.FunctionalTests) (667 ms)
com.renomad.minum.FunctionalTests.test_EdgeCase_BadRequest2(com.renomad.minum.FunctionalTests) (691 ms)
com.renomad.minum.security.TheBrigTests (1040 ms)
com.renomad.minum.web.FullSystemTests (2238 ms)
com.renomad.minum.web.BodyProcessorTests (93 ms)
Report generated by PIT 1.17.0
WebFramework.java

Mutations

Active mutators

Tests examined
