View Javadoc
1   /*
2    * Copyright 2014 The Netty Project
3    *
4    * The Netty Project licenses this file to you under the Apache License, version 2.0 (the
5    * "License"); you may not use this file except in compliance with the License. You may obtain a
6    * copy of the License at:
7    *
8    * http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software distributed under the License
11   * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
12   * or implied. See the License for the specific language governing permissions and limitations under
13   * the License.
14   */
15  
16  package io.netty.handler.codec.http2;
17  
18  import io.netty.buffer.ByteBuf;
19  import io.netty.util.internal.UnstableApi;
20  
21  /**
22   * Encodes {@link Http2Headers} into HPACK-encoded headers blocks.
23   */
24  @UnstableApi
25  public interface Http2HeadersEncoder {
26      /**
27       * Configuration related elements for the {@link Http2HeadersEncoder} interface
28       */
29      interface Configuration {
30          /**
31           * Represents the value for
32           * <a href="https://tools.ietf.org/html/rfc7540#section-6.5.2">SETTINGS_HEADER_TABLE_SIZE</a>.
33           * This method should only be called by Netty (not users) as a result of a receiving a {@code SETTINGS} frame.
34           */
35          void maxHeaderTableSize(long max) throws Http2Exception;
36  
37          /**
38           * Represents the value for
39           * <a href="https://tools.ietf.org/html/rfc7540#section-6.5.2">SETTINGS_HEADER_TABLE_SIZE</a>.
40           * The initial value returned by this method must be {@link Http2CodecUtil#DEFAULT_HEADER_TABLE_SIZE}.
41           */
42          long maxHeaderTableSize();
43  
44          /**
45           * Represents the value for
46           * <a href="https://tools.ietf.org/html/rfc7540#section-6.5.2">SETTINGS_MAX_HEADER_LIST_SIZE</a>.
47           * This method should only be called by Netty (not users) as a result of a receiving a {@code SETTINGS} frame.
48           */
49          void maxHeaderListSize(long max) throws Http2Exception;
50  
51          /**
52           * Represents the value for
53           * <a href="https://tools.ietf.org/html/rfc7540#section-6.5.2">SETTINGS_MAX_HEADER_LIST_SIZE</a>.
54           */
55          long maxHeaderListSize();
56      }
57  
58      /**
59       * Determine if a header name/value pair is treated as
60       * <a href="http://tools.ietf.org/html/draft-ietf-httpbis-header-compression-12#section-7.1.3">sensitive</a>.
61       * If the object can be dynamically modified and shared across multiple connections it may need to be thread safe.
62       */
63      interface SensitivityDetector {
64          /**
65           * Determine if a header {@code name}/{@code value} pair should be treated as
66           * <a href="http://tools.ietf.org/html/draft-ietf-httpbis-header-compression-12#section-7.1.3">sensitive</a>.
67           * @param name The name for the header.
68           * @param value The value of the header.
69           * @return {@code true} if a header {@code name}/{@code value} pair should be treated as
70           * <a href="http://tools.ietf.org/html/draft-ietf-httpbis-header-compression-12#section-7.1.3">sensitive</a>.
71           * {@code false} otherwise.
72           */
73          boolean isSensitive(CharSequence name, CharSequence value);
74      }
75  
76      /**
77       * Encodes the given headers and writes the output headers block to the given output buffer.
78       *
79       * @param streamId  the identifier of the stream for which the headers are encoded.
80       * @param headers the headers to be encoded.
81       * @param buffer the buffer to receive the encoded headers.
82       */
83      void encodeHeaders(int streamId, Http2Headers headers, ByteBuf buffer) throws Http2Exception;
84  
85      /**
86       * Get the {@link Configuration} for this {@link Http2HeadersEncoder}
87       */
88      Configuration configuration();
89  
90      /**
91       * Always return {@code false} for {@link SensitivityDetector#isSensitive(CharSequence, CharSequence)}.
92       */
93      SensitivityDetector NEVER_SENSITIVE = new SensitivityDetector() {
94          @Override
95          public boolean isSensitive(CharSequence name, CharSequence value) {
96              return false;
97          }
98      };
99  
100     /**
101      * Always return {@code true} for {@link SensitivityDetector#isSensitive(CharSequence, CharSequence)}.
102      */
103     SensitivityDetector ALWAYS_SENSITIVE = new SensitivityDetector() {
104         @Override
105         public boolean isSensitive(CharSequence name, CharSequence value) {
106             return true;
107         }
108     };
109 }