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

    }

    /**

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

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

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

                    // nothing to do but return.

                }

                    // here, the client sent something we cannot parse.

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

                // inspect the response being sent, see whether we can compress the data.

                // send the headers

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

                } else {

                    // send the body

                }

                // print how long this processing took

    static void handleIOException(ISocketWrapper sw, IOException ex, ILogger logger, ITheBrig theBrig, int vulnSeekingJailDuration, Set<String> suspiciousErrors) {

        }

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

        } else {

        }

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

        */

        } else {

        }

    /**

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

        }

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

        }

    }

    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.

    */

    }

    /**

     * determine if we are in a keep-alive connection

     */

    static boolean determineIfKeepAlive(RequestLine sl, Headers hi, ILogger logger) {

        }

    }

    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 StringBuilder addDefaultHeaders(IResponse response) {

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

        // add the status line

        // add a date-timestamp

        // add the server name

    }

    /**

     * Add extra headers specified by the business logic (set by the developer)

     */

    private static void addOptionalExtraHeaders(IResponse response, StringBuilder stringBuilder) {

    /**

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

        }

    }

    /**

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

        }

    }

    /**

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

     */

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

        }

    }

    /**

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

        try {

        try {

            }

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

            }

            } else {

            }

        }

    }

    /**

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

     */

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

                "cache-control", "max-age=" + constants.staticFileCacheTime,

                "content-type", mimeType);

                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 {

                "cache-control", "max-age=" + constants.staticFileCacheTime,

                "content-type", mimeType,

                "Accept-Ranges", "bytes"

                );

                headers,

                requestHeaders

                );

    }

    /**

     * 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 **portion** of the startline

     */

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

        } else {

        }

    }

    /**

     * This constructor is used for the real production system

     */

    WebFramework(Context context) {

    WebFramework(Context context, ZonedDateTime overrideForDateTime) {

    /**

     * 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

     */

        // This random value is purely to help provide correlation between

        // error messages in the UI and error logs.  There are no security concerns.

                RequestLine.Method.NONE,

                PathDetails.empty,

                HttpVersion.NONE,

                "", logger);

        // this allows us to inject a IFileReader for deeper testing

        } else {

                    constants.useCacheForStaticFiles,

                    logger);

        }

    void readExtraMimeMappings(List<String> input) {

        }

        }

    /**

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

        }

        }

    /**

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

        }

        }

    /**

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

    /**

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