001/*
002 * Copyright 2002-2020 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.http.server.reactive;
018
019import java.net.InetSocketAddress;
020import java.net.URI;
021import java.util.function.Consumer;
022
023import org.springframework.http.HttpCookie;
024import org.springframework.http.HttpHeaders;
025import org.springframework.http.HttpMethod;
026import org.springframework.http.HttpRequest;
027import org.springframework.http.ReactiveHttpInputMessage;
028import org.springframework.http.server.RequestPath;
029import org.springframework.lang.Nullable;
030import org.springframework.util.MultiValueMap;
031
032/**
033 * Represents a reactive server-side HTTP request.
034 *
035 * @author Arjen Poutsma
036 * @author Rossen Stoyanchev
037 * @author Sam Brannen
038 * @since 5.0
039 */
040public interface ServerHttpRequest extends HttpRequest, ReactiveHttpInputMessage {
041
042        /**
043         * Return an id that represents the underlying connection, if available,
044         * or the request for the purpose of correlating log messages.
045         * @since 5.1
046         * @see org.springframework.web.server.ServerWebExchange#getLogPrefix()
047         */
048        String getId();
049
050        /**
051         * Returns a structured representation of the request path including the
052         * context path + path within application portions, path segments with
053         * encoded and decoded values, and path parameters.
054         */
055        RequestPath getPath();
056
057        /**
058         * Return a read-only map with parsed and decoded query parameter values.
059         */
060        MultiValueMap<String, String> getQueryParams();
061
062        /**
063         * Return a read-only map of cookies sent by the client.
064         */
065        MultiValueMap<String, HttpCookie> getCookies();
066
067        /**
068         * Return the local address the request was accepted on, if available.
069         * @since 5.2.3
070         */
071        @Nullable
072        default InetSocketAddress getLocalAddress() {
073                return null;
074        }
075
076        /**
077         * Return the remote address where this request is connected to, if available.
078         */
079        @Nullable
080        default InetSocketAddress getRemoteAddress() {
081                return null;
082        }
083
084        /**
085         * Return the SSL session information if the request has been transmitted
086         * over a secure protocol including SSL certificates, if available.
087         * @return the session information, or {@code null} if none available
088         * @since 5.0.2
089         */
090        @Nullable
091        default SslInfo getSslInfo() {
092                return null;
093        }
094
095        /**
096         * Return a builder to mutate properties of this request by wrapping it
097         * with {@link ServerHttpRequestDecorator} and returning either mutated
098         * values or delegating back to this instance.
099         */
100        default ServerHttpRequest.Builder mutate() {
101                return new DefaultServerHttpRequestBuilder(this);
102        }
103
104
105        /**
106         * Builder for mutating an existing {@link ServerHttpRequest}.
107         */
108        interface Builder {
109
110                /**
111                 * Set the HTTP method to return.
112                 */
113                Builder method(HttpMethod httpMethod);
114
115                /**
116                 * Set the URI to use with the following conditions:
117                 * <ul>
118                 * <li>If {@link #path(String) path} is also set, it overrides the path
119                 * of the URI provided here.
120                 * <li>If {@link #contextPath(String) contextPath} is also set, or
121                 * already present, it must match the start of the path of the URI
122                 * provided here.
123                 * </ul>
124                 */
125                Builder uri(URI uri);
126
127                /**
128                 * Set the path to use instead of the {@code "rawPath"} of the URI of
129                 * the request with the following conditions:
130                 * <ul>
131                 * <li>If {@link #uri(URI) uri} is also set, the path given here
132                 * overrides the path of the given URI.
133                 * <li>If {@link #contextPath(String) contextPath} is also set, or
134                 * already present, it must match the start of the path given here.
135                 * <li>The given value must begin with a slash.
136                 * </ul>
137                 */
138                Builder path(String path);
139
140                /**
141                 * Set the contextPath to use.
142                 * <p>The given value must be a valid {@link RequestPath#contextPath()
143                 * contextPath} and it must match the start of the path of the URI of
144                 * the request. That means changing the contextPath, implies also
145                 * changing the path via {@link #path(String)}.
146                 */
147                Builder contextPath(String contextPath);
148
149                /**
150                 * Set or override the specified header values under the given name.
151                 * <p>If you need to add header values, remove headers, etc., use
152                 * {@link #headers(Consumer)} for greater control.
153                 * @param headerName the header name
154                 * @param headerValues the header values
155                 * @since 5.1.9
156                 * @see #headers(Consumer)
157                 */
158                Builder header(String headerName, String... headerValues);
159
160                /**
161                 * Manipulate request headers. The provided {@code HttpHeaders} contains
162                 * current request headers, so that the {@code Consumer} can
163                 * {@linkplain HttpHeaders#set(String, String) overwrite} or
164                 * {@linkplain HttpHeaders#remove(Object) remove} existing values, or
165                 * use any other {@link HttpHeaders} methods.
166                 * @see #header(String, String...)
167                 */
168                Builder headers(Consumer<HttpHeaders> headersConsumer);
169
170                /**
171                 * Set the SSL session information. This may be useful in environments
172                 * where TLS termination is done at the router, but SSL information is
173                 * made available in some other way such as through a header.
174                 * @since 5.0.7
175                 */
176                Builder sslInfo(SslInfo sslInfo);
177
178                /**
179                 * Build a {@link ServerHttpRequest} decorator with the mutated properties.
180                 */
181                ServerHttpRequest build();
182        }
183
184}