Response.java

package com.renomad.minum.web;

import com.renomad.minum.utils.IFileUtils;

import java.io.IOException;
import java.io.RandomAccessFile;
import java.net.URI;
import java.nio.ByteBuffer;
import java.nio.channels.FileChannel;
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import java.util.*;

import static com.renomad.minum.web.StatusLine.StatusCode.CODE_200_OK;
import static com.renomad.minum.web.StatusLine.StatusCode.CODE_206_PARTIAL_CONTENT;

/**
 * Represents an HTTP response. This is what will get sent back to the
 * client (that is, to the browser).  There are a variety of overloads
 * of this record for different situations.  The overarching paradigm is
 * to provide you high flexibility.
 * <p>
 * A response message is sent by a server to a client as a reply to its former request message.
 * </p>
 * <h3>
 * Response syntax
 * </h3>
 * <p>
 * A server sends response messages to the client, which consist of:
 * </p>
 * <ul>
 * <li>
 * a status line, consisting of the protocol version, a space, the
 * response status code, another space, a possibly empty reason
 * phrase, a carriage return and a line feed, e.g.:
 * <pre>
 * HTTP/1.1 200 OK
 * </pre>
 * </li>
 *
 * <li>
 * zero or more response header fields, each consisting of the case-insensitive
 * field name, a colon, optional leading whitespace, the field value, an
 * optional trailing whitespace and ending with a carriage return and a line feed, e.g.:
 * <pre>
 * Content-Type: text/html
 * </pre>
 * </li>
 *
 * <li>
 * an empty line, consisting of a carriage return and a line feed;
 * </li>
 *
 * <li>
 * an optional message body.
 * </li>
 *</ul>

 */
public final class Response implements IResponse {

    private final StatusLine.StatusCode statusCode;
    private final Headers extraHeaders;
    private final byte[] body;
    private final ThrowingConsumer<ISocketWrapper> outputGenerator;
    private final long bodyLength;

    /**
     * If true, the body is text, and therefore would probably benefit
     * from being compressed before sending (presuming sufficiently large
     * to make it worth the time for compression)
     */
    private final boolean isBodyText;

    /**
     * This is the constructor that provides access to all fields.  It is not intended
     * to be used from outside this class.
     * @param extraHeaders extra headers we want to return with the response.
     * @param outputGenerator a {@link ThrowingConsumer} that will use a {@link ISocketWrapper} parameter
     *                        to send bytes on the wire back to the client.  See the static factory methods
     *                        such as {@link #buildResponse(StatusLine.StatusCode, Map, byte[])} for more details on this.
     * @param bodyLength this is used to set the content-length header for the response.  If this is
     *                   not provided, we set the header to "transfer-encoding: chunked", or in other words, streaming.
     * @param isBodyText If true, the body is text, and therefore would probably benefit
     *                   from being compressed before sending (presuming sufficiently large
     *                   to make it worth the time for compression)
     */
    public Response(StatusLine.StatusCode statusCode, Headers extraHeaders, byte[] body,
             ThrowingConsumer<ISocketWrapper> outputGenerator, long bodyLength, boolean isBodyText) {
        if (statusCode == null) throw new IllegalArgumentException("Status code must not be null");
        if (extraHeaders == null) throw new IllegalArgumentException("Extra headers must not be null (may use Headers.EMPTY)");
        this.statusCode = statusCode;
        this.extraHeaders = extraHeaders;
        this.body = body;
        this.outputGenerator = outputGenerator;
        this.bodyLength = bodyLength;
        this.isBodyText = isBodyText;
    }

    /**
     * This factory method is intended for situations where the user wishes to stream data
     * but lacks the content length.  This is only for unusual situations where the developer
     * needs the extra control.  In most cases, other methods are more suitable.
     * @param extraHeaders any extra headers for the response, such as the content-type
     * @param outputGenerator a function that will be given a {@link ISocketWrapper}, providing the
     *                        ability to send bytes on the socket.
     * @deprecated analysis showed that this will return a content-length of zero, thus will
     * malfunction when used with clients.  See AIFindingsWebTests#test_Finding_StreamingResponseAdvertisesZeroContentLength
     */
    @Deprecated
    public static IResponse buildStreamingResponse(StatusLine.StatusCode statusCode, Headers extraHeaders, ThrowingConsumer<ISocketWrapper> outputGenerator) {
        return new Response(statusCode, extraHeaders, null, outputGenerator, 0L, false);
    }

    /**
     * This factory method is intended for situations where the user wishes to stream data
     * but lacks the content length.  This is only for unusual situations where the developer
     * needs the extra control.  In most cases, other methods are more suitable.
     * @param extraHeaders any extra headers for the response, such as the content-type, as a map, where the
     *                     key is the header key and the value is the header value. No colon necessary.
     * @param outputGenerator a function that will be given a {@link ISocketWrapper}, providing the
     *                        ability to send bytes on the socket.
     * @deprecated analysis showed that this will return a content-length of zero, thus will
     * malfunction when used with clients.  See AIFindingsWebTests#test_Finding_StreamingResponseAdvertisesZeroContentLength
     */
    @Deprecated
    public static IResponse buildStreamingResponse(StatusLine.StatusCode statusCode, Map<String,String> extraHeaders, ThrowingConsumer<ISocketWrapper> outputGenerator) {
        return buildStreamingResponse(statusCode, convertMapToHeaders(extraHeaders), outputGenerator);
    }

    /**
     * Similar to {@link Response#buildStreamingResponse(StatusLine.StatusCode, Headers, ThrowingConsumer)} but here we know
     * the body length, so that will be sent to the client as content-length.
     * @param extraHeaders any extra headers for the response, such as the content-type
     * @param outputGenerator a function that will be given a {@link ISocketWrapper}, providing the
     *                        ability to send bytes on the socket.
     * @param bodyLength the length, in bytes, of the data to be sent to the client
     */
    public static IResponse buildStreamingResponse(StatusLine.StatusCode statusCode, Headers extraHeaders, ThrowingConsumer<ISocketWrapper> outputGenerator, long bodyLength) {
        return new Response(statusCode, extraHeaders, null, outputGenerator, bodyLength, false);
    }

    /**
     * Similar to {@link Response#buildStreamingResponse(StatusLine.StatusCode, Headers, ThrowingConsumer)} but here we know
     * the body length, so that will be sent to the client as content-length.
     * @param extraHeaders any extra headers for the response, such as the content-type, as a map, where the
     *                     key is the header key and the value is the header value. No colon necessary.
     * @param outputGenerator a function that will be given a {@link ISocketWrapper}, providing the
     *                        ability to send bytes on the socket.
     * @param bodyLength the length, in bytes, of the data to be sent to the client
     */
    public static IResponse buildStreamingResponse(StatusLine.StatusCode statusCode, Map<String,String> extraHeaders, ThrowingConsumer<ISocketWrapper> outputGenerator, long bodyLength) {
        return buildStreamingResponse(statusCode, convertMapToHeaders(extraHeaders), outputGenerator, bodyLength);
    }

    /**
     * A constructor for situations where the developer wishes to send a small (less than a megabyte) byte array
     * to the client.  If there is need to send something of larger size, choose one these
     * alternate constructors:
     * FileChannel - for sending a large file: {@link Response#buildLargeFileResponse(Headers, String, String, Headers, IFileUtils)}
     * Streaming - for more custom streaming control with a known body size: {@link Response#buildStreamingResponse(StatusLine.StatusCode, Map, ThrowingConsumer, long)}
     * Streaming - for more custom streaming control with body size unknown: {@link Response#buildStreamingResponse(StatusLine.StatusCode, Map, ThrowingConsumer)}
     *
     * @param extraHeaders any extra headers for the response, such as the content-type.
     */
    public static IResponse buildResponse(StatusLine.StatusCode statusCode, Headers extraHeaders, byte[] body) {
        return new Response(statusCode, extraHeaders, body, socketWrapper -> socketWrapper.send(body), body.length, false);
    }

    /**
     * A constructor for situations where the developer wishes to send a small (less than a megabyte) byte array
     * to the client.  If there is need to send something of larger size, choose one these
     * alternate constructors:
     * FileChannel - for sending a large file: {@link Response#buildLargeFileResponse(Headers, String, String, Headers, IFileUtils)}
     * Streaming - for more custom streaming control with a known body size: {@link Response#buildStreamingResponse(StatusLine.StatusCode, Headers, ThrowingConsumer, long)}
     * Streaming - for more custom streaming control with body size unknown: {@link Response#buildStreamingResponse(StatusLine.StatusCode, Headers, ThrowingConsumer)}
     *
     * @param extraHeaders any extra headers for the response, such as the content-type, as a map, where the
     *                     key is the header key and the value is the header value. No colon necessary.
     */
    public static IResponse buildResponse(StatusLine.StatusCode statusCode, Map<String,String> extraHeaders, byte[] body) {
        return buildResponse(statusCode, convertMapToHeaders(extraHeaders), body);
    }

    private static Headers convertMapToHeaders(Map<String, String> extraHeaders) {
        if (extraHeaders.isEmpty()) return Headers.EMPTY;
        return new Headers(extraHeaders.entrySet().stream().map(x -> x.getKey() + ": " + x.getValue()).toList());
    }

    /**
     * Build an ordinary response, with a known body
     * @param extraHeaders extra HTTP headers, like <pre>content-type: text/html</pre>
     */
    public static IResponse buildResponse(StatusLine.StatusCode statusCode, Headers extraHeaders, String body) {
        byte[] bytes = body.getBytes(StandardCharsets.UTF_8);
        return new Response(statusCode, extraHeaders, bytes, socketWrapper -> socketWrapper.send(bytes), bytes.length, true);
    }

    /**
     * Build an ordinary response, with a known body
     * @param extraHeaders any extra headers for the response, such as the content-type, as a map, where the
     *                     key is the header key and the value is the header value. No colon necessary.
     */
    public static IResponse buildResponse(StatusLine.StatusCode statusCode, Map<String,String> extraHeaders, String body) {
        return buildResponse(statusCode, convertMapToHeaders(extraHeaders), body);
    }


    /**
     * This will send a large file to the client as a stream.
     * <em>Note that this does not check that the requested file is within a directory. If you expect the
     * path value to be untrusted - that is, set by a user - use {@link #buildLargeFileResponse(Headers, String, String, Headers, IFileUtils)}</em>
     * @param extraHeaders any extra headers for the response, such as the content-type, as a map, where the
     *                     key is the header key and the value is the header value. No colon necessary.
     *                     For example "Content-Type: video/mp4" or "Content-Type: application/zip"
     * @param filePath the string value of the path to this file. <em>Caution! if this is set by the user.  See notes above</em>
     * @param requestHeaders these are the headers from the request, which is needed here to set proper
     *                       response headers in some cases.
     */
    public static IResponse buildLargeFileResponse(Map<String,String> extraHeaders, String filePath, Headers requestHeaders, IFileUtils fileUtils) {
        return buildLargeFileResponse(convertMapToHeaders(extraHeaders), filePath, requestHeaders, fileUtils);
    }

    /**
     * This will send a large file to the client as a stream.
     * <em>Note that this does not check that the requested file is within a directory. If you expect the
     * path value to be untrusted - that is, set by a user - use {@link #buildLargeFileResponse(Headers, String, String, Headers, IFileUtils)}</em>
     * @param extraHeaders extra headers you would like in the response, as key-value pairs in a map - for
     *                     example "Content-Type: video/mp4" or "Content-Type: application/zip"
     * @param filePath the string value of the path to this file. <em>Caution! if this is set by the user.  See notes above</em>
     * @param requestHeaders these are the headers from the request, which is needed here to set proper
     *                       response headers in some cases.
     */
    public static IResponse buildLargeFileResponse(Headers extraHeaders, String filePath, Headers requestHeaders, IFileUtils fileUtils) {
        Headers adjustedHeaders = extraHeaders;
        long fileSize;
        try {
            fileSize = fileUtils.size(Path.of(filePath));
        } catch (IOException e) {
            throw new WebServerException("Error in Response.buildLargeFileResponse", e);
        }
        var range = new Range(requestHeaders, fileSize);
        StatusLine.StatusCode responseCode = CODE_200_OK;
        long length = fileSize;
        if (range.hasRangeHeader()) {
            long offset = range.getOffset();
            length = range.getLength();
            var lastIndex = (offset + length) - 1;
            List<String> headerStrings = new ArrayList<>(extraHeaders.getHeaderStrings());
            headerStrings.add("Content-Range: " + String.format("bytes %d-%d/%d", offset, lastIndex, fileSize));
            adjustedHeaders = new Headers(headerStrings);
            responseCode = CODE_206_PARTIAL_CONTENT;
        }

        ThrowingConsumer<ISocketWrapper> outputGenerator = socketWrapper -> {
            try (RandomAccessFile reader = new RandomAccessFile(filePath, "r")) {
                reader.seek(range.getOffset());
                var fileChannel = reader.getChannel();
                sendFileChannelResponse(socketWrapper, fileChannel, range.getLength());
            }
        };

        return new Response(responseCode, adjustedHeaders, null, outputGenerator, length, false);
    }

    /**
     * This will send a large file to the client as a stream.
     * This is a safe version of the method, for when the file path is set by a user, meaning it is untrusted.
     * By setting a parentDirectory, the system will ensure that the requested path is within that directory, thus
     * disallowing path strings that could escape it, like prefixing with a slash.
     * @param extraHeaders extra headers you would like in the response, as key-value pairs in a map - for
     *                     example "Content-Type: video/mp4" or "Content-Type: application/zip"
     * @param filePath the string value of the path to this file. <em>Caution! if this is set by the user.  See notes above</em>
     * @param requestHeaders these are the headers from the request, which is needed here to set proper
     *                       response headers in some cases.
     * @param parentDirectory this value is presumed to be set by the developer, and thus isn't checked for safety. This
     *                        allows the developer to use directories anywhere in the system.
     */
    public static IResponse buildLargeFileResponse(Headers extraHeaders, String filePath, String parentDirectory, Headers requestHeaders, IFileUtils fileUtils) {
        Path path;
        try {
            path = fileUtils.safeResolve(parentDirectory, filePath);
        } catch (IOException e) {
            throw new WebServerException("Error at Response.buildLargeFileResponse", e);
        }
        return buildLargeFileResponse(extraHeaders, path.toString(), requestHeaders, fileUtils);
    }

    /**
     * This will send a large file to the client as a stream.
     * This is a safe version of the method, for when the file path is set by a user, meaning it is untrusted.
     * By setting a parentDirectory, the system will ensure that the requested path is within that directory, thus
     * disallowing path strings that could escape it, like prefixing with a slash.
     * @param extraHeaders any extra headers for the response, such as the content-type, as a map, where the
     *                     key is the header key and the value is the header value. No colon necessary.
     *                     For example "Content-Type: video/mp4" or "Content-Type: application/zip"
     * @param filePath the string value of the path to this file. <em>Caution! if this is set by the user.  See notes above</em>
     * @param requestHeaders these are the headers from the request, which is needed here to set proper
     *                       response headers in some cases.
     * @param parentDirectory this value is presumed to be set by the developer, and thus isn't checked for safety. This
     *                        allows the developer to use directories anywhere in the system.
     */
    public static IResponse buildLargeFileResponse(Map<String,String> extraHeaders, String filePath, String parentDirectory, Headers requestHeaders, IFileUtils fileUtils) {
        return buildLargeFileResponse(convertMapToHeaders(extraHeaders), filePath, parentDirectory, requestHeaders, fileUtils);
    }

    /**
     * Build a {@link Response} with just a status code and headers, without a body
     * @param extraHeaders extra HTTP headers
     */
    public static IResponse buildLeanResponse(StatusLine.StatusCode statusCode, Headers extraHeaders) {
        return new Response(statusCode, extraHeaders, null, socketWrapper -> {}, 0, false);
    }

    /**
     * Build a {@link Response} with just a status code and headers, without a body
     * @param extraHeaders any extra headers for the response, such as the content-type, as a map, where the
     *                     key is the header key and the value is the header value. No colon necessary.
     */
    public static IResponse buildLeanResponse(StatusLine.StatusCode statusCode, Map<String,String> extraHeaders) {
        return buildLeanResponse(statusCode, convertMapToHeaders(extraHeaders));
    }

    /**
     * Build a {@link Response} with only a status code, with no body and no extra headers.
     */
    public static IResponse buildLeanResponse(StatusLine.StatusCode statusCode) {
        return new Response(statusCode, Headers.EMPTY, null, socketWrapper -> {}, 0, false);
    }

    /**
     * A helper method to create a response that returns a
     * 303 status code ("see other").  Provide a url that will
     * be handed to the browser.  This url may be relative or absolute.
     */
    public static IResponse redirectTo(String locationUrl) {
        try {
            // check if we can create a URL from this - any failures indicate invalid syntax.
            URI.create(locationUrl);
        } catch (Exception ex) {
            throw new WebServerException("Failure in redirect to (" + locationUrl + "). Exception: " + ex);
        }
        return buildResponse(StatusLine.StatusCode.CODE_303_SEE_OTHER, new Headers(List.of("location: " + locationUrl, "Content-Type: text/html; charset=UTF-8")), "<p>See <a href=\""+locationUrl+"\">this link</a></p>");
    }

    /**
     * If you are returning HTML text with a 200 ok, this is a helper that
     * lets you skip some of the boilerplate. This version of the helper
     * lets you add extra headers on top of the basic content-type headers
     * that are needed to specify this is HTML.
     */
    public static IResponse htmlOk(String body, Headers extraHeaders) {
        List<String> headersList = new ArrayList<>(extraHeaders.getHeaderStrings());
        headersList.add("Content-Type: text/html; charset=UTF-8");
        var headers =  new Headers(headersList);
        return buildResponse(StatusLine.StatusCode.CODE_200_OK, headers, body);
    }

    /**
     * If you are returning HTML text with a 200 ok, this is a helper that
     * lets you skip some of the boilerplate.
     */
    public static IResponse htmlOk(String body) {
        return htmlOk(body, Headers.EMPTY);
    }

    @Override
    public Headers getExtraHeaders() {
        return new Headers(this.extraHeaders.getHeaderStrings());
    }

    @Override
    public StatusLine.StatusCode getStatusCode() {
        return statusCode;
    }

    @Override
    public boolean isBodyText() {
        return isBodyText;
    }

    @Override
    public long getBodyLength() {
        if (body != null) {
            return body.length;
        } else {
            return bodyLength;
        }
    }

    @Override
    public void sendBody(ISocketWrapper sw) throws Exception {
        outputGenerator.accept(sw);
    }

    /**
     * put bytes from a file into the socket, sending to the client
     * @param fileChannel the file we are reading from, based on a {@link RandomAccessFile}
     * @param length the number of bytes to send.  May be less than the full length of this {@link FileChannel}
     */
    private static void sendFileChannelResponse(ISocketWrapper sw, FileChannel fileChannel, long length) throws IOException {
        try {
            int bufferSize = 8 * 1024;
            ByteBuffer buff = ByteBuffer.allocate(bufferSize);
            long countBytesLeftToSend = length;
            while (true) {
                int countBytesRead = fileChannel.read(buff);
                if (countBytesRead <= 0) {
                    break;
                } else {
                    if (countBytesLeftToSend < (long) countBytesRead) {
                        sw.send(buff.array(), 0, (int)countBytesLeftToSend);
                        break;
                    } else {
                        sw.send(buff.array(), 0, countBytesRead);
                    }
                    buff.clear();
                }
                countBytesLeftToSend = countBytesLeftToSend - countBytesRead;
            }
        } finally {
            fileChannel.close();
        }
    }

    @Override
    public byte[] getBody() {
        return body;
    }

    @Override
    public ThrowingConsumer<ISocketWrapper> getOutputGenerator() {
        return outputGenerator;
    }

    @Override
    public boolean equals(Object o) {
        if (o == null || getClass() != o.getClass()) return false;
        Response response = (Response) o;
        return bodyLength == response.bodyLength && isBodyText == response.isBodyText && statusCode == response.statusCode && Objects.equals(extraHeaders, response.extraHeaders) && Objects.deepEquals(body, response.body);
    }

    @Override
    public int hashCode() {
        return Objects.hash(statusCode, extraHeaders, Arrays.hashCode(body), bodyLength, isBodyText);
    }

    @Override
    public String toString() {
        return "Response{" +
                "statusCode=" + statusCode +
                ", extraHeaders=" + extraHeaders +
                ", bodyLength=" + bodyLength +
                ", isBodyText=" + isBodyText +
                '}';
    }
}














































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.ResponseTests (31 ms)
com.renomad.minum.web.BodyProcessorTests (133 ms)
com.renomad.minum.EqualsTests.equalsTest(com.renomad.minum.EqualsTests) (2546 ms)
com.renomad.minum.FunctionalTests.testEndToEnd_Functional(com.renomad.minum.FunctionalTests) (2350 ms)
com.renomad.minum.web.EndpointTests (8 ms)
com.renomad.minum.web.WebFrameworkTests (255 ms)
com.renomad.minum.web.WebTests (637 ms)
com.renomad.minum.web.WebPerformanceTests.webPerfTest(com.renomad.minum.web.WebPerformanceTests) (631 ms)
com.renomad.minum.FunctionalTests.test_EdgeCase_Response_MultiCookies(com.renomad.minum.FunctionalTests) (620 ms)
com.renomad.minum.FunctionalTests.test_EdgeCase_BadRequest(com.renomad.minum.FunctionalTests) (664 ms)
com.renomad.minum.FunctionalTests.test_PathFunction_Response_Range(com.renomad.minum.FunctionalTests) (636 ms)
com.renomad.minum.FunctionalTests.test_PathFunction_Response(com.renomad.minum.FunctionalTests) (638 ms)
com.renomad.minum.FunctionalTests.test_EdgeCase_PostHandler_IgnoreBody(com.renomad.minum.FunctionalTests) (652 ms)
com.renomad.minum.FunctionalTests.test_EdgeCase_BadRequest2(com.renomad.minum.FunctionalTests) (755 ms)
com.renomad.minum.web.CachingAndCompressionTests (402 ms)
Report generated by PIT 1.17.0
Response.java

Mutations

Active mutators

Tests examined
