View Javadoc
1   /*
2    * Copyright 2012 The Netty Project
3    *
4    * The Netty Project licenses this file to you under the Apache License,
5    * version 2.0 (the "License"); you may not use this file except in compliance
6    * with the License. You may obtain a copy of the License at:
7    *
8    *   https://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations
14   * under the License.
15   */
16  package io.netty.handler.codec.http;
17  
18  import io.netty.buffer.ByteBuf;
19  import io.netty.channel.ChannelPipeline;
20  
21  /**
22   * Decodes {@link ByteBuf}s into {@link HttpResponse}s and
23   * {@link HttpContent}s.
24   *
25   * <h3>Parameters that prevents excessive memory consumption</h3>
26   * <table border="1">
27   * <tr>
28   * <th>Name</th><th>Meaning</th>
29   * </tr>
30   * <tr>
31   * <td>{@code maxInitialLineLength}</td>
32   * <td>The maximum length of the initial line (e.g. {@code "HTTP/1.0 200 OK"})
33   *     If the length of the initial line exceeds this value, a
34   *     {@link TooLongHttpLineException} will be raised.</td>
35   * </tr>
36   * <tr>
37   * <td>{@code maxHeaderSize}</td>
38   * <td>The maximum length of all headers.  If the sum of the length of each
39   *     header exceeds this value, a {@link TooLongHttpHeaderException} will be raised.</td>
40   * </tr>
41   * <tr>
42   * <td>{@code maxChunkSize}</td>
43   * <td>The maximum length of the content or each chunk.  If the content length
44   *     exceeds this value, the transfer encoding of the decoded response will be
45   *     converted to 'chunked' and the content will be split into multiple
46   *     {@link HttpContent}s.  If the transfer encoding of the HTTP response is
47   *     'chunked' already, each chunk will be split into smaller chunks if the
48   *     length of the chunk exceeds this value.  If you prefer not to handle
49   *     {@link HttpContent}s in your handler, insert {@link HttpObjectAggregator}
50   *     after this decoder in the {@link ChannelPipeline}.</td>
51   * </tr>
52   * </table>
53   *
54   * <h3>Parameters that control parsing behavior</h3>
55   * <table border="1">
56   * <tr>
57   * <th>Name</th><th>Default value</th><th>Meaning</th>
58   * </tr>
59   * <tr>
60   * <td>{@code allowDuplicateContentLengths}</td>
61   * <td>{@value #DEFAULT_ALLOW_DUPLICATE_CONTENT_LENGTHS}</td>
62   * <td>When set to {@code false}, will reject any messages that contain multiple Content-Length header fields.
63   *     When set to {@code true}, will allow multiple Content-Length headers only if they are all the same decimal value.
64   *     The duplicated field-values will be replaced with a single valid Content-Length field.
65   *     See <a href="https://tools.ietf.org/html/rfc7230#section-3.3.2">RFC 7230, Section 3.3.2</a>.</td>
66   * </tr>
67   * <tr>
68   * <td>{@code allowPartialChunks}</td>
69   * <td>{@value #DEFAULT_ALLOW_PARTIAL_CHUNKS}</td>
70   * <td>If the length of a chunk exceeds the {@link ByteBuf}s readable bytes and {@code allowPartialChunks}
71   *     is set to {@code true}, the chunk will be split into multiple {@link HttpContent}s.
72   *     Otherwise, if the chunk size does not exceed {@code maxChunkSize} and {@code allowPartialChunks}
73   *     is set to {@code false}, the {@link ByteBuf} is not decoded into an {@link HttpContent} until
74   *     the readable bytes are greater or equal to the chunk size.</td>
75   * </tr>
76   * </table>
77   *
78   * <h3>Decoding a response for a <tt>HEAD</tt> request</h3>
79   * <p>
80   * Unlike other HTTP requests, the successful response of a <tt>HEAD</tt>
81   * request does not have any content even if there is <tt>Content-Length</tt>
82   * header.  Because {@link HttpResponseDecoder} is not able to determine if the
83   * response currently being decoded is associated with a <tt>HEAD</tt> request,
84   * you must override {@link #isContentAlwaysEmpty(HttpMessage)} to return
85   * <tt>true</tt> for the response of the <tt>HEAD</tt> request.
86   * </p><p>
87   * If you are writing an HTTP client that issues a <tt>HEAD</tt> request,
88   * please use {@link HttpClientCodec} instead of this decoder.  It will perform
89   * additional state management to handle the responses for <tt>HEAD</tt>
90   * requests correctly.
91   * </p>
92   *
93   * <h3>Decoding a response for a <tt>CONNECT</tt> request</h3>
94   * <p>
95   * You also need to do additional state management to handle the response of a
96   * <tt>CONNECT</tt> request properly, like you did for <tt>HEAD</tt>.  One
97   * difference is that the decoder should stop decoding completely after decoding
98   * the successful 200 response since the connection is not an HTTP connection
99   * anymore.
100  * </p><p>
101  * {@link HttpClientCodec} also handles this edge case correctly, so you have to
102  * use {@link HttpClientCodec} if you are writing an HTTP client that issues a
103  * <tt>CONNECT</tt> request.
104  * </p>
105  */
106 public class HttpResponseDecoder extends HttpObjectDecoder {
107 
108     private static final HttpResponseStatus UNKNOWN_STATUS = new HttpResponseStatus(999, "Unknown");
109 
110     /**
111      * Creates a new instance with the default
112      * {@code maxInitialLineLength (4096)}, {@code maxHeaderSize (8192)}, and
113      * {@code maxChunkSize (8192)}.
114      */
115     public HttpResponseDecoder() {
116     }
117 
118     /**
119      * Creates a new instance with the specified parameters.
120      */
121     public HttpResponseDecoder(
122             int maxInitialLineLength, int maxHeaderSize, int maxChunkSize) {
123         super(maxInitialLineLength, maxHeaderSize, maxChunkSize, DEFAULT_CHUNKED_SUPPORTED);
124     }
125 
126     public HttpResponseDecoder(
127             int maxInitialLineLength, int maxHeaderSize, int maxChunkSize, boolean validateHeaders) {
128         super(maxInitialLineLength, maxHeaderSize, maxChunkSize, DEFAULT_CHUNKED_SUPPORTED, validateHeaders);
129     }
130 
131     public HttpResponseDecoder(
132             int maxInitialLineLength, int maxHeaderSize, int maxChunkSize, boolean validateHeaders,
133             int initialBufferSize) {
134         super(maxInitialLineLength, maxHeaderSize, maxChunkSize, DEFAULT_CHUNKED_SUPPORTED, validateHeaders,
135               initialBufferSize);
136     }
137 
138     public HttpResponseDecoder(
139             int maxInitialLineLength, int maxHeaderSize, int maxChunkSize, boolean validateHeaders,
140             int initialBufferSize, boolean allowDuplicateContentLengths) {
141         super(maxInitialLineLength, maxHeaderSize, maxChunkSize, DEFAULT_CHUNKED_SUPPORTED, validateHeaders,
142               initialBufferSize, allowDuplicateContentLengths);
143     }
144 
145     public HttpResponseDecoder(
146             int maxInitialLineLength, int maxHeaderSize, int maxChunkSize, boolean validateHeaders,
147             int initialBufferSize, boolean allowDuplicateContentLengths, boolean allowPartialChunks) {
148         super(maxInitialLineLength, maxHeaderSize, maxChunkSize, DEFAULT_CHUNKED_SUPPORTED, validateHeaders,
149               initialBufferSize, allowDuplicateContentLengths, allowPartialChunks);
150     }
151 
152     @Override
153     protected HttpMessage createMessage(String[] initialLine) {
154         return new DefaultHttpResponse(
155                 HttpVersion.valueOf(initialLine[0]),
156                 HttpResponseStatus.valueOf(Integer.parseInt(initialLine[1]), initialLine[2]), validateHeaders);
157     }
158 
159     @Override
160     protected HttpMessage createInvalidMessage() {
161         return new DefaultFullHttpResponse(HttpVersion.HTTP_1_0, UNKNOWN_STATUS, validateHeaders);
162     }
163 
164     @Override
165     protected boolean isDecodingRequest() {
166         return false;
167     }
168 }