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.concurrent.locks.ReentrantLock;

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;

    /**

     * This contains the directory path to the static files, as

     * specified in the configuration file.  See {@link Constants#staticFilesDirectory}

     */

    private final Path staticFilesDirectoryPathBase;

    public Map<String,String> getSuffixToMimeMappings() {

    }

    /**

     * This is used as a key when registering endpoints

     */

    /**

     * 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)},

     */

        @Override

        public ThrowingFunction<IRequest, IResponse> apply(String path) {

        }

    }

    /**

     * 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;

    /**

     * A map between a key of file suffixes and a value of mime type,

     * used for determining a proper mime for response on a file in

     * the static files directory

     */

    private final Map<String, String> fileSuffixToMime;

    /**

     * This is a map of path to a boolean valuable for whether the

     * file benefits from compression.

     */

    private final Map<String, Boolean> fileIsCompressible;

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

    /**

     * For static files (See {@link Constants#staticFilesDirectory}), This is

     * the cutoff for the maximum quantity of bytes where we will

     * use {@link FileReader#readFile(String)} and caching for the data.

     * Past this point, we will use {@link #createOkResponseForLargeStaticFiles}

     * and not use caching.

     */

    static final int MAX_CACHED_BYTES = 100_000;

    void httpProcessing(ISocketWrapper sw) {

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

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

                RequestLine requestLine;

                IRequest request;

                Headers headers;

                IResponse response;

                boolean isKeepAlive;

                IResponse adjustedResponse;

                try {

                        // here, the client connected, sent nothing, and closed.

                        // nothing to do but return.

                    }

                    // check if the user is seeming to attack us.

                    // React to what the user requested, generate a result

                    // check that the response is non-null.  If it is null, that suggests

                    // the developer made a mistake.

                    }

                    // calculate proper headers for the response

                    // if the response is text (i.e. probably good compressibility) and large enough

                    // to be worth compressing, we'll compress it.

                    }

                    // 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.

                                ".  Excluding body from response");

                    }

                    // this catch block needs to be down below the scope where

                    // the request variable is needed.

                // send the headers

                    // send the body

                }

                // ship it out

                // print how long this processing took

                }

    /**

     * 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.

            } else {

            }

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

        } else {

        }

    static void handleForbiddenUse(ISocketWrapper sw, ForbiddenUseException ex, ILogger logger, ITheBrig theBrig, int vulnSeekingJailDuration) {

        } else {

        }

    /**

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

    }

    /**

     * 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;

        } else {

            try {

                } else {

                }

                // 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.

        }

        }

    }

    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.

    */

    }

    /**

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

        }

            // if there was a body and the user has not read it by this point, we will log the

            // discrepancy and close the socket.

        }

    }

    RequestLine getProcessedRequestLine(ISocketWrapper sw, String rawStartLine) {

    }

    void checkIfSuspiciousPath(ISocketWrapper sw, RequestLine requestLine) {

        }

    /**

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

        } else {

        }

    }

    void dumpIfAttacker(ISocketWrapper sw, ITheBrig theBrig) {

            // if this client is a vulnerability seeker, throw an exception,

            // causing them to get dumped unceremoniously

        }

    /**

     * Prepare some of the basic server response headers, like the status code, the

     * date-time stamp, the server name.

     */

    private void addDefaultHeaders(IResponse response, StringBuilder headerStringBuilder) {

        // add the status line

        // add a date-timestamp

        // add the server name

    /**

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

        // if there *is* data, we had better be returning a content type

        }

    /**

     * 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

        }

    /**

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

    /**

     * 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.

     *

     * @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 endpointPath the endpoint whose data we are compressing, e.g. "foo?bar=baz",

     *                     used for logging.

     */

    static IResponse compressBodyIfRequested(IResponse response, List<String> acceptEncoding, StringBuilder stringBuilder, ILogger logger, String endpointPath) {

            );

        }

    }

    /**

     * 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 void compressBody(OutputStream out, byte[] body) {

    /**

     * 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;

        // first we check if there's a simple direct match

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

        }

        }

        // we'll return this, and it could be a null.

    }

    /**

     * last ditch effort - look on disk.  This response will either

     * be the file to return, or null if we didn't find anything.

     * The request method has to be GET or HEAD.

     */

    private ThrowingFunction<IRequest, IResponse> findHandlerByFilesOnDisk(RequestLine sl, Headers requestHeaders) {

        } else {

        }

    }

    /**

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

        Path staticFilePath;

        try {

        // move value to a variable - used in several places, may as well

            try {

                }

            } finally {

        }

        try {

        try {

        try {

            }

            } else {

            }

        }

    }

    private String getMimeString(String path) {

        // if the provided path has a dot in it, use that

        // to obtain a suffix for determining file type

        }

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

        }

    }

    /**

     * A method used for handling smaller files in the static files directory

     * (less than {@link #MAX_CACHED_BYTES})

     * All static responses will get a cache time of STATIC_FILE_CACHE_TIME seconds

     */

    private IResponse createOkResponseForStaticFiles(byte[] fileContents, String mimeType, String path) {

                "Cache-Control: max-age=" + constants.staticFileCacheTime,

                "Content-Type: " + mimeType));

        // if the map does not have this key, then we haven't analyzed this file yet.

            // we only want to compress it if we get a decent compression.

            // 30% smaller seems fine.

        }

    }

    /**

     * A method used for handling larger files in the static files directory

     * (greater-than or equal to {@link #MAX_CACHED_BYTES})

     * All static responses will get a cache time of STATIC_FILE_CACHE_TIME seconds

     */

    private IResponse createOkResponseForLargeStaticFiles(String mimeType, Path filePath, Headers requestHeaders) {

                "Cache-Control: max-age=" + constants.staticFileCacheTime,

                "Content-Type: " + mimeType,

                "Accept-Ranges: bytes"

                ));

                headers,

                requestHeaders,

                fileUtils

                );

    }

    /**

     * These are the default starting values for mappings

     * between file suffixes and appropriate mime types

     */

    private void addDefaultValuesForMimeMap() {

    /**

     * let's see if we can match the registered paths against a path function

     */

    ThrowingFunction<IRequest, IResponse> findHandlerByPathFunction(RequestLine sl) {

        }

    }

    /**

     * This constructor is used for the real production system

     */

    WebFramework(Context context) {

    /**

     * This constructor is mainly used for testing

     */

    WebFramework(Context context, ZonedDateTime overrideForDateTime) {

    /**

     * 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.