001/*
002Copyright 2022 The OpenFunction Authors.
003
004Licensed under the Apache License, Version 2.0 (the "License");
005you may not use this file except in compliance with the License.
006You may obtain a copy of the License at
007
008    http://www.apache.org/licenses/LICENSE-2.0
009
010Unless required by applicable law or agreed to in writing, software
011distributed under the License is distributed on an "AS IS" BASIS,
012WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013See the License for the specific language governing permissions and
014limitations under the License.
015*/
016
017package dev.openfunction.functions;
018
019import java.io.BufferedReader;
020import java.io.IOException;
021import java.io.InputStream;
022import java.util.List;
023import java.util.Map;
024import java.util.Optional;
025
026/**
027 * Represents an HTTP message, either an HTTP request or a part of a multipart HTTP request.
028 */
029public interface HttpMessage {
030    /**
031     * Returns the value of the {@code Content-Type} header, if any.
032     *
033     * @return the content type, if any.
034     */
035    Optional<String> getContentType();
036
037    /**
038     * Returns the numeric value of the {@code Content-Length} header.
039     *
040     * @return the content length.
041     */
042    long getContentLength();
043
044    /**
045     * Returns the character encoding specified in the {@code Content-Type} header, or {@code
046     * Optional.empty()} if there is no {@code Content-Type} header or it does not have the {@code
047     * charset} parameter.
048     *
049     * @return the character encoding for the content type, if one is specified.
050     */
051    Optional<String> getCharacterEncoding();
052
053    /**
054     * Returns an {@link InputStream} that can be used to read the body of this HTTP request. Every
055     * call to this method on the same {@link HttpMessage} will return the same object. This method is
056     * typically used to read binary data. If the body is text, the {@link #getReader()} method is
057     * more appropriate.
058     *
059     * @return an {@link InputStream} that can be used to read the body of this HTTP request.
060     * @throws IOException           if a valid {@link InputStream} cannot be returned for some reason.
061     * @throws IllegalStateException if {@link #getReader()} has already been called on this instance.
062     */
063    InputStream getInputStream() throws IOException;
064
065    /**
066     * Returns a {@link BufferedReader} that can be used to read the text body of this HTTP request.
067     * Every call to this method on the same {@link HttpMessage} will return the same object.
068     *
069     * @return a {@link BufferedReader} that can be used to read the text body of this HTTP request.
070     * @throws IOException           if a valid {@link BufferedReader} cannot be returned for some reason.
071     * @throws IllegalStateException if {@link #getInputStream()} has already been called on this
072     *                               instance.
073     */
074    BufferedReader getReader() throws IOException;
075
076    /**
077     * Returns a map describing the headers of this HTTP request, or this part of a multipart request.
078     * If the headers look like this...
079     *
080     * <pre>
081     *   Content-Type: text/plain
082     *   Some-Header: some value
083     *   Some-Header: another value
084     * </pre>
085     * <p>
086     * ...then the returned value will map {@code "Content-Type"} to a one-element list containing
087     * {@code "text/plain"}, and {@code "Some-Header"} to a two-element list containing {@code "some
088     * value"} and {@code "another value"}.
089     *
090     * @return a map where each key is an HTTP header and the corresponding {@code List} value has one
091     * element for each occurrence of that header.
092     */
093    Map<String, List<String>> getHeaders();
094
095    /**
096     * Convenience method that returns the value of the first header with the given name. If the
097     * headers look like this...
098     *
099     * <pre>
100     *   Content-Type: text/plain
101     *   Some-Header: some value
102     *   Some-Header: another value
103     * </pre>
104     * <p>
105     * ...then {@code getFirstHeader("Some-Header")} will return {@code Optional.of("some value")},
106     * and {@code getFirstHeader("Another-Header")} will return {@code Optional.empty()}.
107     *
108     * @param name an HTTP header name.
109     * @return the first value of the given header, if present.
110     */
111    default Optional<String> getFirstHeader(String name) {
112        List<String> headers = getHeaders().get(name);
113        if (headers == null || headers.isEmpty()) {
114            return Optional.empty();
115        }
116        return Optional.of(headers.get(0));
117    }
118}