/*
 * The contents of this file are subject to the terms of the Common Development and
 * Distribution License (the License). You may not use this file except in compliance with the
 * License.
 *
 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
 * specific language governing permission and limitations under the License.
 *
 * When distributing Covered Software, include this CDDL Header Notice in each file and include
 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
 * Header, with the fields enclosed by brackets [] replaced by your own identifying
 * information: "Portions copyright [year] [name of copyright owner]".
 *
 * Copyright 2012-2016 ForgeRock AS.
 * Portions copyright 2026 Wren Security
 */
package org.forgerock.json.resource.http;

import static org.forgerock.http.protocol.Responses.newInternalServerError;
import static org.forgerock.http.routing.Version.version;
import static org.forgerock.json.resource.ActionRequest.ACTION_ID_CREATE;
import static org.forgerock.util.Utils.closeSilently;
import static org.forgerock.util.promise.Promises.newResultPromise;

import com.fasterxml.jackson.core.JsonGenerator;
import com.fasterxml.jackson.core.JsonParseException;
import com.fasterxml.jackson.core.JsonParser;
import com.fasterxml.jackson.databind.JsonMappingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import jakarta.activation.DataSource;
import jakarta.mail.BodyPart;
import jakarta.mail.MessagingException;
import jakarta.mail.internet.ContentDisposition;
import jakarta.mail.internet.ContentType;
import jakarta.mail.internet.MimeBodyPart;
import jakarta.mail.internet.MimeMultipart;
import jakarta.mail.internet.ParseException;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.ArrayDeque;
import java.util.Arrays;
import java.util.Collection;
import java.util.Iterator;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.forgerock.http.header.AcceptApiVersionHeader;
import org.forgerock.http.header.ContentTypeHeader;
import org.forgerock.http.header.MalformedHeaderException;
import org.forgerock.http.io.PipeBufferedStream;
import org.forgerock.http.protocol.Response;
import org.forgerock.http.protocol.Status;
import org.forgerock.http.routing.Version;
import org.forgerock.http.util.Json;
import org.forgerock.json.JsonValue;
import org.forgerock.json.resource.ActionRequest;
import org.forgerock.json.resource.BadRequestException;
import org.forgerock.json.resource.InternalServerErrorException;
import org.forgerock.json.resource.NotSupportedException;
import org.forgerock.json.resource.PatchOperation;
import org.forgerock.json.resource.PreconditionFailedException;
import org.forgerock.json.resource.QueryRequest;
import org.forgerock.json.resource.Request;
import org.forgerock.json.resource.RequestType;
import org.forgerock.json.resource.ResourceException;
import org.forgerock.services.context.Context;
import org.forgerock.util.encode.Base64url;
import org.forgerock.util.promise.NeverThrowsException;
import org.forgerock.util.promise.Promise;

/**
 * HTTP utility methods and constants.
 */
public final class HttpUtils {
    static final String CACHE_CONTROL = "no-cache";
    static final String CHARACTER_ENCODING = "UTF-8";
    static final Pattern CONTENT_TYPE_REGEX = Pattern.compile(
            "^application/json([ ]*;[ ]*charset=utf-8)?$", Pattern.CASE_INSENSITIVE);
    static final String CRLF = "\r\n";
    static final String ETAG_ANY = "*";

    static final String MIME_TYPE_APPLICATION_JSON = "application/json";
    static final String MIME_TYPE_MULTIPART_FORM_DATA = "multipart/form-data";
    static final String MIME_TYPE_TEXT_PLAIN = "text/plain";

    static final String HEADER_CACHE_CONTROL = "Cache-Control";
    static final String HEADER_ETAG = "ETag";
    static final String HEADER_IF_MATCH = "If-Match";
    static final String HEADER_IF_NONE_MATCH = "If-None-Match";
    static final String HEADER_IF_MODIFIED_SINCE = "If-Modified-Since";
    static final String HEADER_IF_UNMODIFIED_SINCE = "If-Unmodified-Since";
    static final String HEADER_LOCATION = "Location";
    static final String HEADER_X_HTTP_METHOD_OVERRIDE = "X-HTTP-Method-Override";
    /** the HTTP header for {@literal Content-Disposition}. */
    public static final String CONTENT_DISPOSITION = "Content-Disposition";
    static final Collection<String> RESTRICTED_HEADER_NAMES = Arrays.asList(
            ContentTypeHeader.NAME,
            AcceptApiVersionHeader.NAME,
            HEADER_IF_MODIFIED_SINCE,
            HEADER_IF_UNMODIFIED_SINCE,
            HEADER_IF_MATCH,
            HEADER_IF_NONE_MATCH,
            HEADER_CACHE_CONTROL,
            HEADER_ETAG,
            HEADER_LOCATION,
            HEADER_X_HTTP_METHOD_OVERRIDE,
            CONTENT_DISPOSITION
    );

    static final String METHOD_DELETE = "DELETE";
    static final String METHOD_GET = "GET";
    static final String METHOD_HEAD = "HEAD";
    static final String METHOD_OPTIONS = "OPTIONS";
    static final String METHOD_PATCH = "PATCH";
    static final String METHOD_POST = "POST";
    static final String METHOD_PUT = "PUT";
    static final String METHOD_TRACE = "TRACE";

    /** the HTTP request parameter for an action. */
    public static final String PARAM_ACTION = param(ActionRequest.FIELD_ACTION);
    /** the HTTP request parameter to specify which fields to return. */
    public static final String PARAM_FIELDS = param(Request.FIELD_FIELDS);
    /** the HTTP request parameter to request a certain mimetype for a filed. */
    public static final String PARAM_MIME_TYPE = param("mimeType");
    /** the HTTP request parameter to request a certain page size. */
    public static final String PARAM_PAGE_SIZE = param(QueryRequest.FIELD_PAGE_SIZE);
    /** the HTTP request parameter to specify a paged results cookie. */
    public static final String PARAM_PAGED_RESULTS_COOKIE =
            param(QueryRequest.FIELD_PAGED_RESULTS_COOKIE);
    /** the HTTP request parameter to specify a paged results offset. */
    public static final String PARAM_PAGED_RESULTS_OFFSET =
            param(QueryRequest.FIELD_PAGED_RESULTS_OFFSET);
    /** the HTTP request parameter to request pretty printing. */
    public static final String PARAM_PRETTY_PRINT = "_prettyPrint";
    /** the HTTP request parameter to specify a query expression. */
    public static final String PARAM_QUERY_EXPRESSION = param(QueryRequest.FIELD_QUERY_EXPRESSION);
    /** the HTTP request parameter to specify a query filter. */
    public static final String PARAM_QUERY_FILTER = param(QueryRequest.FIELD_QUERY_FILTER);
    /** the HTTP request parameter to specify a query id. */
    public static final String PARAM_QUERY_ID = param(QueryRequest.FIELD_QUERY_ID);
    /** the HTTP request parameter to specify the sort keys. */
    public static final String PARAM_SORT_KEYS = param(QueryRequest.FIELD_SORT_KEYS);
    /** The policy used for counting total paged results. */
    public static final String PARAM_TOTAL_PAGED_RESULTS_POLICY = param(QueryRequest.FIELD_TOTAL_PAGED_RESULTS_POLICY);
    /** Request the CREST API Descriptor. */
    public static final String PARAM_CREST_API = param("crestapi");

    /** Protocol Version 1. */
    public static final Version PROTOCOL_VERSION_1 = version(1);
    /** Protocol Version 2 - supports upsert on PUT. */
    public static final Version PROTOCOL_VERSION_2 = version(2);
    /**
     * Protocol Version 2.1 - supports defacto standard for create requests when the ID of the created resource is
     * to be allocated by the server, which are represented as a POST to the collection endpoint without an
     * {@code _action} query parameter.
     */
    public static final Version PROTOCOL_VERSION_2_1 = version(2, 1);
    /** The default version of the named protocol. */
    public static final Version DEFAULT_PROTOCOL_VERSION = PROTOCOL_VERSION_2_1;
    static final String FIELDS_DELIMITER = ",";
    static final String SORT_KEYS_DELIMITER = ",";

    static final ObjectMapper JSON_MAPPER = new ObjectMapper()
            .registerModules(new Json.JsonValueModule(), new Json.LocalizableStringModule());

    private static final String FILENAME = "filename";
    private static final String MIME_TYPE = "mimetype";
    private static final String CONTENT = "content";
    private static final String NAME = "name";
    private static final Pattern MULTIPART_FIELD_REGEX = Pattern.compile("^cid:(.*)#(" + FILENAME
            + "|" + MIME_TYPE + "|" + CONTENT + ")$", Pattern.CASE_INSENSITIVE);
    private static final int PART_NAME = 1;
    private static final int PART_DATA_TYPE = 2;
    private static final String REFERENCE_TAG = "$ref";

    private static final int BUFFER_SIZE = 1_024;
    private static final int EOF = -1;

    /**
     * Adapts an {@code Exception} to a {@code ResourceException}.
     *
     * @param t
     *            The exception which caused the request to fail.
     * @return The equivalent resource exception.
     */
    static ResourceException adapt(final Throwable t) {
        if (t instanceof ResourceException) {
            return (ResourceException) t;
        } else {
            return new InternalServerErrorException(t);
        }
    }

    /**
     * Parses a header or request parameter as a boolean value.
     *
     * @param name
     *            The name of the header or parameter.
     * @param values
     *            The header or parameter values.
     * @return The boolean value.
     * @throws ResourceException
     *             If the value could not be parsed as a boolean.
     */
    static boolean asBooleanValue(final String name, final List<String> values)
            throws ResourceException {
        final String value = asSingleValue(name, values);
        return Boolean.parseBoolean(value);
    }

    /**
     * Parses a header or request parameter as an integer value.
     *
     * @param name
     *            The name of the header or parameter.
     * @param values
     *            The header or parameter values.
     * @return The integer value.
     * @throws ResourceException
     *             If the value could not be parsed as a integer.
     */
    static int asIntValue(final String name, final List<String> values) throws ResourceException {
        final String value = asSingleValue(name, values);
        try {
            return Integer.parseInt(value);
        } catch (final NumberFormatException e) {
            // FIXME: i18n.
            throw new BadRequestException("The value \'" + value + "\' for parameter '" + name
                    + "' could not be parsed as a valid integer");
        }
    }

    /**
     * Parses a header or request parameter as a single string value.
     *
     * @param name
     *            The name of the header or parameter.
     * @param values
     *            The header or parameter values.
     * @return The single string value.
     * @throws ResourceException
     *             If the value could not be parsed as a single string.
     */
    static String asSingleValue(final String name, final List<String> values) throws ResourceException {
        if (values == null || values.isEmpty()) {
            // FIXME: i18n.
            throw new BadRequestException("No values provided for the request parameter \'" + name
                    + "\'");
        } else if (values.size() > 1) {
            // FIXME: i18n.
            throw new BadRequestException(
                    "Multiple values provided for the single-valued request parameter \'" + name
                            + "\'");
        }
        return values.get(0);
    }

    /**
     * Safely fail an HTTP request using the provided {@code Exception}.
     *
     * @param req
     *            The HTTP request.
     * @param t
     *            The resource exception indicating why the request failed.
     */
    static Promise<Response, NeverThrowsException> fail(org.forgerock.http.protocol.Request req, final Throwable t) {
        return fail0(req, null, t);
    }

    /**
     * Safely fail an HTTP request using the provided {@code Exception}.
     *
     * @param req
     *            The HTTP request.
     * @param resp
     *            The HTTP response.
     * @param t
     *            The resource exception indicating why the request failed.
     */
    static Promise<Response, NeverThrowsException> fail(org.forgerock.http.protocol.Request req,
            org.forgerock.http.protocol.Response resp, final Throwable t) {
        return fail0(req, resp, t);
    }

    private static Promise<Response, NeverThrowsException> fail0(org.forgerock.http.protocol.Request req,
            org.forgerock.http.protocol.Response resp, Throwable t) {
        final ResourceException re = adapt(t);
        try {
            if (resp == null) {
                resp = new Response(Status.valueOf(re.getCode()));
            } else {
                resp.setStatus(Status.valueOf(re.getCode()));
            }
            writeContentTypeHeader(resp);
            writeCacheControlHeader(resp);
            final JsonGenerator writer = getJsonGenerator(req, resp);
            Json.makeLocalizingObjectWriter(JSON_MAPPER, req).writeValue(writer, re.toJsonValue().getObject());
            closeSilently(writer);
            return newResultPromise(resp);
        } catch (final IOException ignored) {
            // Ignore the error since this was probably the cause.
            return newResultPromise(newInternalServerError());
        } catch (MalformedHeaderException e) {
            return newResultPromise(new Response(Status.BAD_REQUEST).setEntity("Malformed header"));
        }
    }

    /**
     * Determines which CREST operation (CRUDPAQ) of the incoming request.
     *
     * @param request The request.
     * @return The Operation.
     * @throws ResourceException If the request operation could not be
     * determined or is not supported.
     */
    public static RequestType determineRequestType(org.forgerock.http.protocol.Request request)
            throws ResourceException {
        // Dispatch the request based on method, taking into account
        // method override header.
        final String method = getMethod(request);
        if (METHOD_DELETE.equals(method)) {
            return RequestType.DELETE;
        } else if (METHOD_GET.equals(method)) {
            if (hasParameter(request, PARAM_QUERY_ID)
                    || hasParameter(request, PARAM_QUERY_EXPRESSION)
                    || hasParameter(request, PARAM_QUERY_FILTER)) {
                return RequestType.QUERY;
            } else if (hasParameter(request, PARAM_CREST_API)) {
                return RequestType.API;
            } else {
                return RequestType.READ;
            }
        } else if (METHOD_PATCH.equals(method)) {
            return RequestType.PATCH;
        } else if (METHOD_POST.equals(method)) {
            return determinePostRequestType(request);
        } else if (METHOD_PUT.equals(method)) {
            return determinePutRequestType(request);
        } else {
            // TODO: i18n
            throw new NotSupportedException("Method " + method + " not supported");
        }
    }

    private static RequestType determinePostRequestType(org.forgerock.http.protocol.Request request)
            throws ResourceException {
        List<String> parameter = getParameter(request, PARAM_ACTION);

        boolean defactoCreate = getRequestedProtocolVersion(request).compareTo(PROTOCOL_VERSION_2_1) >= 0
                && (parameter == null || parameter.isEmpty());

        return defactoCreate || asSingleValue(PARAM_ACTION, parameter).equalsIgnoreCase(ACTION_ID_CREATE)
                ? RequestType.CREATE
                : RequestType.ACTION;
    }

    /**
     * Determine whether the PUT request should be interpreted as a CREATE or an UPDATE depending on
     * If-None-Match header, If-Match header, and protocol version.
     *
     * @param request The request.
     * @return true if request is interpreted as a create; false if interpreted as an update
     */
    private static RequestType determinePutRequestType(org.forgerock.http.protocol.Request request)
            throws BadRequestException {

        final Version protocolVersion = getRequestedProtocolVersion(request);
        final String ifNoneMatch = getIfNoneMatch(request);
        final String ifMatch = getIfMatch(request, protocolVersion);

        /* CREST-100
         * For protocol version 1:
         *
         *  - "If-None-Match: x" is present, where 'x' is any non-* value: this is a bad request
         *  - "If-None-Match: *" is present: this is a create which will fail if the object already exists.
         *  - "If-None-Match: *" is not present:
         *          This is an update which will fail if the object does not exist.  There are two ways to
         *          perform the update, using the value of the If-Match header:
         *           - "If-Match: <rev>" : update the object if its revision matches the header value
         *           - "If-Match: * : update the object regardless of the object's revision
         *           - "If-Match:" header is not present : same as "If-Match: *"; update regardless of object revision
         *
         * For protocol version 2 onward:
         *
         * Two methods of create are implied by PUT:
         *
         *  - "If-None-Match: x" is present, where 'x' is any non-* value: this is a bad request
         *  - "If-None-Match: *" is present, this is a create which will fail if the object already exists.
         *  - "If-Match" is present; this is an update only:
         *           - "If-Match: <rev>" : update the object if its revision matches the header value
         *           - "If-Match: * : update the object regardless of the object's revision
         *  - Neither "If-None-Match" nor "If-Match" are present, this is either a create or an update ("upsert"):
         *          Attempt a create; if it fails, attempt an update.  If the update fails, return an error
         *          (the record could have been deleted between the create-failure and the update, for example).
         */

        /* CREST-346 */
        if (ifNoneMatch != null && !ETAG_ANY.equals(ifNoneMatch)) {
            throw new BadRequestException("\"" + ifNoneMatch + "\" is not a supported value for If-None-Match on PUT");
        }

        if (ETAG_ANY.equals(ifNoneMatch)) {
            return RequestType.CREATE;
        } else if (ifNoneMatch == null && ifMatch == null && protocolVersion.getMajor() >= 2) {
            return RequestType.CREATE;
        } else {
            return RequestType.UPDATE;
        }
    }

    /**
     * Attempts to parse the version header and return a corresponding resource {@link Version} representation.
     * Further validates that the specified versions are valid. That being not in the future and no earlier
     * that the current major version.
     *
     * @param req
     *         The HTTP servlet request
     *
     * @return A non-null resource  {@link Version} instance
     *
     * @throws BadRequestException
     *         If an invalid version is requested
     */
    static Version getRequestedResourceVersion(org.forgerock.http.protocol.Request req) throws BadRequestException {
        return getAcceptApiVersionHeader(req).getResourceVersion();
    }

    /**
     * Attempts to parse the version header and return a corresponding protocol {@link Version} representation.
     * Further validates that the specified versions are valid. That being not in the future and no earlier
     * that the current major version.
     *
     * @param req
     *         The HTTP servlet request
     *
     * @return A non-null resource  {@link Version} instance
     *
     * @throws BadRequestException
     *         If an invalid version is requested
     */
    static Version getRequestedProtocolVersion(org.forgerock.http.protocol.Request req) throws BadRequestException {
        Version protocolVersion = getAcceptApiVersionHeader(req).getProtocolVersion();
        return protocolVersion != null ? protocolVersion : DEFAULT_PROTOCOL_VERSION;
    }

    /**
     * Validate and return the AcceptApiVersionHeader.
     *
     * @param req
     *         The HTTP servlet request
     *
     * @return A non-null resource  {@link Version} instance
     *
     * @throws BadRequestException
     *         If an invalid version is requested
     */
    private static AcceptApiVersionHeader getAcceptApiVersionHeader(org.forgerock.http.protocol.Request req)
            throws BadRequestException {
        AcceptApiVersionHeader apiVersionHeader;
        try {
            apiVersionHeader = AcceptApiVersionHeader.valueOf(req);
        } catch (IllegalArgumentException e) {
            throw new BadRequestException(e);
        }
        validateProtocolVersion(apiVersionHeader.getProtocolVersion());
        return apiVersionHeader;
    }

    /**
     * Validate the Protocol version as not in the future.
     *
     * @param protocolVersion the protocol version from the request
     * @throws BadRequestException if the request marks a protocol version greater than the current version
     */
    private static void validateProtocolVersion(Version protocolVersion) throws BadRequestException {
        if (protocolVersion != null && protocolVersion.getMajor() > DEFAULT_PROTOCOL_VERSION.getMajor()) {
            throw new BadRequestException("Unsupported major version: " + protocolVersion);
        }
        if (protocolVersion != null && protocolVersion.getMinor() > DEFAULT_PROTOCOL_VERSION.getMinor()) {
            throw new BadRequestException("Unsupported minor version: " + protocolVersion);
        }
    }

    static String getIfMatch(org.forgerock.http.protocol.Request req, Version protocolVersion) {
        final String etag = req.getHeaders().getFirst(HEADER_IF_MATCH);
        if (etag != null) {
            if (etag.length() >= 2) {
                // Remove quotes.
                if (etag.charAt(0) == '"') {
                    return etag.substring(1, etag.length() - 1);
                }
            } else if (etag.equals(ETAG_ANY) && protocolVersion.getMajor() < 2) {
                // If-Match * is implied prior to version 2
                return null;
            }
        }
        return etag;
    }

    static String getIfNoneMatch(org.forgerock.http.protocol.Request req) {
        final String etag = req.getHeaders().getFirst(HEADER_IF_NONE_MATCH);
        if (etag != null) {
            if (etag.length() >= 2) {
                // Remove quotes.
                if (etag.charAt(0) == '"') {
                    return etag.substring(1, etag.length() - 1);
                }
            } else if (etag.equals(ETAG_ANY)) {
                // If-None-Match *.
                return ETAG_ANY;
            }
        }
        return etag;
    }

    /**
     * Returns the content of the provided HTTP request decoded as a JSON
     * object. The content is allowed to be empty, in which case an empty JSON
     * object is returned.
     *
     * @param req
     *            The HTTP request.
     * @return The content of the provided HTTP request decoded as a JSON
     *         object.
     * @throws ResourceException
     *             If the content could not be read or if the content was not
     *             valid JSON.
     */
    static JsonValue getJsonContentIfPresent(org.forgerock.http.protocol.Request req) throws ResourceException {
        return getJsonContent0(req, true);
    }

    /**
     * Returns the content of the provided HTTP request decoded as a JSON
     * object. If there is no content then a {@link BadRequestException} will be
     * thrown.
     *
     * @param req
     *            The HTTP request.
     * @return The content of the provided HTTP request decoded as a JSON
     *         object.
     * @throws ResourceException
     *             If the content could not be read or if the content was not
     *             valid JSON.
     */
    static JsonValue getJsonContent(org.forgerock.http.protocol.Request req) throws ResourceException {
        return getJsonContent0(req, false);
    }

    /**
     * Creates a JSON generator which can be used for serializing JSON content
     * in HTTP responses.
     *
     * @param req
     *            The HTTP request.
     * @param resp
     *            The HTTP response.
     * @return A JSON generator which can be used to write out a JSON response.
     * @throws IOException
     *             If an error occurred while obtaining an output stream.
     */
    static JsonGenerator getJsonGenerator(org.forgerock.http.protocol.Request req,
            Response resp) throws IOException {

        PipeBufferedStream pipeStream = new PipeBufferedStream();
        resp.setEntity(pipeStream.getOut());

        final JsonGenerator writer =
                JSON_MAPPER.getFactory().createGenerator(pipeStream.getIn());

        // Need to have the JsonGenerator close the stream so that it is
        // properly released.
        writer.configure(JsonGenerator.Feature.AUTO_CLOSE_TARGET, true);

        // Enable pretty printer if requested.
        final List<String> values = getParameter(req, PARAM_PRETTY_PRINT);
        if (values != null) {
            try {
                if (asBooleanValue(PARAM_PRETTY_PRINT, values)) {
                    writer.useDefaultPrettyPrinter();
                }
            } catch (final ResourceException e) {
                // Ignore because we may be trying to obtain a generator in
                // order to output an error.
            }
        }
        return writer;
    }

    /**
     * Returns the content of the provided HTTP request decoded as a JSON patch
     * object.
     *
     * @param req
     *            The HTTP request.
     * @return The content of the provided HTTP request decoded as a JSON patch
     *         object.
     * @throws ResourceException
     *             If the content could not be read or if the content was not a
     *             valid JSON patch.
     */
    static List<PatchOperation> getJsonPatchContent(org.forgerock.http.protocol.Request req)
            throws ResourceException {
        return PatchOperation.valueOfList(new JsonValue(parseJsonBody(req, false)));
    }

    /**
     * Returns the content of the provided HTTP request decoded as a JSON action
     * content.
     *
     * @param req
     *            The HTTP request.
     * @return The content of the provided HTTP request decoded as a JSON action
     *         content.
     * @throws ResourceException
     *             If the content could not be read or if the content was not
     *             valid JSON.
     */
    static JsonValue getJsonActionContent(org.forgerock.http.protocol.Request req) throws ResourceException {
        return new JsonValue(parseJsonBody(req, true));
    }

    /**
     * Returns the effective method name for an HTTP request taking into account
     * the "X-HTTP-Method-Override" header.
     *
     * @param req
     *            The HTTP request.
     * @return The effective method name.
     */
    static String getMethod(org.forgerock.http.protocol.Request req) {
        String method = req.getMethod();
        if (HttpUtils.METHOD_POST.equals(method)
                && req.getHeaders().getFirst(HttpUtils.HEADER_X_HTTP_METHOD_OVERRIDE) != null) {
            method = req.getHeaders().getFirst(HttpUtils.HEADER_X_HTTP_METHOD_OVERRIDE);
        }
        return method;
    }

    /**
     * Returns the named parameter from the provided HTTP request using case
     * insensitive matching.
     *
     * @param req
     *            The HTTP request.
     * @param parameter
     *            The parameter to return.
     * @return The parameter values or {@code null} if it wasn't present.
     */
    static List<String> getParameter(org.forgerock.http.protocol.Request req, String parameter) {
        // Need to do case-insensitive matching.
        for (final Map.Entry<String, List<String>> p : req.getForm().entrySet()) {
            if (p.getKey().equalsIgnoreCase(parameter)) {
                return p.getValue();
            }
        }
        return null;
    }

    /**
     * Returns {@code true} if the named parameter is present in the provided
     * HTTP request using case insensitive matching.
     *
     * @param req
     *            The HTTP request.
     * @param parameter
     *            The parameter to return.
     * @return {@code true} if the named parameter is present.
     */
    static boolean hasParameter(org.forgerock.http.protocol.Request req, String parameter) {
        return getParameter(req, parameter) != null;
    }

    static void writeContentTypeHeader(org.forgerock.http.protocol.Response resp) {
        if (!resp.getHeaders().containsKey(ContentTypeHeader.NAME)) {
            resp.getHeaders().add(new ContentTypeHeader(MIME_TYPE_APPLICATION_JSON, CHARACTER_ENCODING, null));
        }
    }

    static void writeCacheControlHeader(org.forgerock.http.protocol.Response resp) {
        resp.getHeaders().put(HEADER_CACHE_CONTROL, CACHE_CONTROL);
    }

    static void rejectIfMatch(org.forgerock.http.protocol.Request req) throws ResourceException {
        if (req.getHeaders().getFirst(HEADER_IF_MATCH) != null) {
            // FIXME: i18n
            throw new PreconditionFailedException("If-Match not supported for " + getMethod(req) + " requests");
        }
    }

    static void rejectIfNoneMatch(org.forgerock.http.protocol.Request req) throws ResourceException,
            PreconditionFailedException {
        if (req.getHeaders().getFirst(HEADER_IF_NONE_MATCH) != null) {
            // FIXME: i18n
            throw new PreconditionFailedException("If-None-Match not supported for "
                    + getMethod(req) + " requests");
        }
    }

    private static JsonValue getJsonContent0(org.forgerock.http.protocol.Request req, boolean allowEmpty)
            throws ResourceException {
        final Object body = parseJsonBody(req, allowEmpty);
        if (body == null) {
            return new JsonValue(new LinkedHashMap<>(0));
        } else if (!(body instanceof Map)) {
            throw new BadRequestException(
                    "The request could not be processed because the provided "
                            + "content is not a JSON object");
        } else {
            return new JsonValue(body);
        }
    }

    private static BodyPart getJsonRequestPart(final MimeMultipart mimeMultiparts)
            throws BadRequestException, ResourceException {
        try {
            for (int i = 0; i < mimeMultiparts.getCount(); i++) {
                BodyPart part = mimeMultiparts.getBodyPart(i);
                ContentType contentType = new ContentType(part.getContentType());
                if (contentType.match(MIME_TYPE_APPLICATION_JSON)) {
                    return part;
                }
            }
            throw new BadRequestException(
                    "The request could not be processed because the multipart request "
                    + "does not include Content-Type: " + MIME_TYPE_APPLICATION_JSON);
        } catch (final MessagingException e) {
            throw new BadRequestException(
                    "The request could not be processed because the request cant be parsed", e);
        } catch (final IOException e) {
            throw adapt(e);
        }

    }

    private static String getRequestPartData(final MimeMultipart mimeMultiparts,
            final String partName, final String partDataType) throws IOException, MessagingException {
        if (mimeMultiparts == null) {
            throw new BadRequestException(
                    "The request parameter is null when retrieving part data for part name: "
                            + partName);
        }

        if (partDataType == null || partDataType.isEmpty()) {
            throw new BadRequestException("The request is requesting an unknown part field");
        }
        MimeBodyPart part = null;
        for (int i = 0; i < mimeMultiparts.getCount(); i++) {
            part = (MimeBodyPart) mimeMultiparts.getBodyPart(i);
            ContentDisposition disposition =
                    new ContentDisposition(part.getHeader(CONTENT_DISPOSITION, null));
            if (disposition.getParameter(NAME).equalsIgnoreCase(partName)) {
                break;
            }
        }

        if (part == null) {
            throw new BadRequestException(
                    "The request is missing a referenced part for part name: " + partName);
        }

        if (MIME_TYPE.equalsIgnoreCase(partDataType)) {
            return new ContentType(part.getContentType()).toString();
        } else if (FILENAME.equalsIgnoreCase(partDataType)) {
            return part.getFileName();
        } else if (CONTENT.equalsIgnoreCase(partDataType)) {
            return Base64url.encode(toByteArray(part.getInputStream()));
        } else {
            throw new BadRequestException(
                    "The request could not be processed because the multipart request "
                            + "requests data from the part that isn't supported. Data requested: "
                            + partDataType);
        }
    }

    private static boolean isAReferenceJsonObject(JsonValue node) {
        return node.keys() != null && node.keys().size() == 1
                && REFERENCE_TAG.equalsIgnoreCase(node.keys().iterator().next());
    }

    private static Object swapRequestPartsIntoContent(final MimeMultipart mimeMultiparts,
            Object content) throws ResourceException {
        try {
            JsonValue root = new JsonValue(content);

            ArrayDeque<JsonValue> stack = new ArrayDeque<>();
            stack.push(root);

            while (!stack.isEmpty()) {
                JsonValue node = stack.pop();
                if (isAReferenceJsonObject(node)) {
                    Matcher matcher =
                            MULTIPART_FIELD_REGEX.matcher(node.get(REFERENCE_TAG).asString());
                    if (matcher.matches()) {
                        String partName = matcher.group(PART_NAME);
                        String requestPartData =
                                getRequestPartData(mimeMultiparts, partName, matcher
                                        .group(PART_DATA_TYPE));
                        root.put(node.getPointer(), requestPartData);
                    } else {
                        throw new BadRequestException("Invalid reference tag '" + node.toString()
                                + "'");
                    }
                } else {
                    Iterator<JsonValue> iter = node.iterator();
                    while (iter.hasNext()) {
                        stack.push(iter.next());
                    }
                }
            }
            return root;
        } catch (final IOException e) {
            throw adapt(e);
        } catch (final MessagingException e) {
            throw new BadRequestException(
                    "The request could not be processed because the request is not a valid multipart request");
        }
    }

    static boolean isMultiPartRequest(final String unknownContentType) throws BadRequestException {
        try {
            if (unknownContentType == null) {
                return false;
            }
            ContentType contentType = new ContentType(unknownContentType);
            return contentType.match(MIME_TYPE_MULTIPART_FORM_DATA);
        } catch (final ParseException e) {
            throw new BadRequestException("The request content type can't be parsed.", e);
        }
    }

    private static Object parseJsonBody(org.forgerock.http.protocol.Request req, boolean allowEmpty)
            throws ResourceException {
        try {
            String contentType = req.getHeaders().getFirst(ContentTypeHeader.class);
            if (contentType == null && !allowEmpty) {
                throw new BadRequestException("The request could not be processed because the "
                        + " content-type was not specified and is required");
            }
            boolean isMultiPartRequest = isMultiPartRequest(contentType);
            MimeMultipart mimeMultiparts = null;
            JsonParser jsonParser;
            if (isMultiPartRequest) {
                mimeMultiparts = new MimeMultipart(new HttpServletRequestDataSource(req));
                BodyPart jsonPart = getJsonRequestPart(mimeMultiparts);
                jsonParser = JSON_MAPPER.getFactory().createParser(jsonPart.getInputStream());
            } else {
                jsonParser = JSON_MAPPER.getFactory().createParser(req.getEntity().getRawContentInputStream());
            }
            try (JsonParser parser = jsonParser) {
                Object content = parser.readValueAs(Object.class);

                // Ensure that there is no trailing data following the JSON resource.
                boolean hasTrailingGarbage;
                try {
                    hasTrailingGarbage = parser.nextToken() != null;
                } catch (JsonParseException e) {
                    hasTrailingGarbage = true;
                }
                if (hasTrailingGarbage) {
                    throw new BadRequestException(
                            "The request could not be processed because there is "
                                    + "trailing data after the JSON content");
                }

                if (isMultiPartRequest) {
                    swapRequestPartsIntoContent(mimeMultiparts, content);
                }

                return content;
            }
        } catch (final JsonParseException e) {
            throw new BadRequestException(
                    "The request could not be processed because the provided "
                            + "content is not valid JSON", e)
                .setDetail(new JsonValue(e.getMessage()));
        } catch (final JsonMappingException e) {
            if (allowEmpty) {
                return null;
            } else {
                throw new BadRequestException("The request could not be processed "
                        + "because it did not contain any JSON content", e);
            }
        } catch (final IOException e) {
            throw adapt(e);
        } catch (final MessagingException e) {
            throw new BadRequestException(
                    "The request could not be processed because it can't be parsed", e);
        }
    }

    private static String param(final String field) {
        return "_" + field;
    }

    private HttpUtils() {
        // Prevent instantiation.
    }

    private static class HttpServletRequestDataSource implements DataSource {
        private org.forgerock.http.protocol.Request request;

        HttpServletRequestDataSource(org.forgerock.http.protocol.Request request) {
            this.request = request;
        }

        @Override
        public InputStream getInputStream() throws IOException {
            return request.getEntity().getRawContentInputStream();
        }

        @Override
        public OutputStream getOutputStream() throws IOException {
            return null;
        }

        @Override
        public String getContentType() {
            return request.getHeaders().getFirst(ContentTypeHeader.class);
        }

        @Override
        public String getName() {
            return "HttpServletRequestDataSource";
        }
    }

    private static byte[] toByteArray(final InputStream inputStream) throws IOException {
        final ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream();
        final byte[] data = new byte[BUFFER_SIZE];
        int size;
        while ((size = inputStream.read(data)) != EOF) {
            byteArrayOutputStream.write(data, 0, size);
        }
        byteArrayOutputStream.flush();
        return byteArrayOutputStream.toByteArray();
    }

    static HttpContextFactory staticContextFactory(final Context parentContext) {
        return new HttpContextFactory() {
            @Override
            public Context createContext(Context parent, org.forgerock.http.protocol.Request request) {
                return parentContext;
            }
        };
    }
}