View Javadoc
1   /*
2    * Copyright (c) 2002-2026 Gargoyle Software Inc.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * https://www.apache.org/licenses/LICENSE-2.0
8    *
9    * Unless required by applicable law or agreed to in writing, software
10   * distributed under the License is distributed on an "AS IS" BASIS,
11   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12   * See the License for the specific language governing permissions and
13   * limitations under the License.
14   */
15  package org.htmlunit.util;
16  
17  import static java.nio.charset.StandardCharsets.US_ASCII;
18  import static java.nio.charset.StandardCharsets.UTF_16BE;
19  import static java.nio.charset.StandardCharsets.UTF_16LE;
20  import static java.nio.charset.StandardCharsets.UTF_8;
21  
22  import java.io.IOException;
23  import java.io.InputStream;
24  import java.nio.charset.Charset;
25  import java.nio.charset.IllegalCharsetNameException;
26  import java.nio.charset.UnsupportedCharsetException;
27  import java.util.Arrays;
28  import java.util.List;
29  import java.util.Locale;
30  
31  import org.apache.commons.io.ByteOrderMark;
32  import org.apache.commons.io.IOUtils;
33  import org.apache.commons.lang3.ArrayUtils;
34  import org.apache.commons.logging.Log;
35  import org.apache.commons.logging.LogFactory;
36  import org.htmlunit.HttpHeader;
37  import org.htmlunit.cyberneko.xerces.util.StandardEncodingTranslator;
38  
39  /**
40   * Sniffs encoding settings from HTML, XML or other content. The HTML encoding sniffing algorithm is based on the
41   * <a href="https://html.spec.whatwg.org/multipage/parsing.html#determining-the-character-encoding">HTML5
42   * encoding sniffing algorithm</a>.
43   *
44   * @author Daniel Gredler
45   * @author Ahmed Ashour
46   * @author Ronald Brill
47   * @author Lai Quang Duong
48   */
49  public final class EncodingSniffer {
50  
51      /** Logging support. */
52      private static final Log LOG = LogFactory.getLog(EncodingSniffer.class);
53  
54      /** Sequence(s) of bytes indicating the beginning of a comment. */
55      private static final byte[][] COMMENT_START = {
56          new byte[] {'<'},
57          new byte[] {'!'},
58          new byte[] {'-'},
59          new byte[] {'-'}
60      };
61  
62      /** Sequence(s) of bytes indicating the beginning of a {@code meta} HTML tag. */
63      private static final byte[][] META_START = {
64          new byte[] {'<'},
65          new byte[] {'m', 'M'},
66          new byte[] {'e', 'E'},
67          new byte[] {'t', 'T'},
68          new byte[] {'a', 'A'},
69          new byte[] {0x09, 0x0A, 0x0C, 0x0D, 0x20, 0x2F}
70      };
71  
72      /** Sequence(s) of bytes indicating the beginning of miscellaneous HTML content. */
73      private static final byte[][] OTHER_START = {
74          new byte[] {'<'},
75          new byte[] {'!', '/', '?'}
76      };
77  
78      /** Sequence(s) of bytes indicating the beginning of a charset specification. */
79      private static final byte[][] CHARSET_START = {
80          new byte[] {'c', 'C'},
81          new byte[] {'h', 'H'},
82          new byte[] {'a', 'A'},
83          new byte[] {'r', 'R'},
84          new byte[] {'s', 'S'},
85          new byte[] {'e', 'E'},
86          new byte[] {'t', 'T'}
87      };
88  
89      private static final byte[] WHITESPACE = {0x09, 0x0A, 0x0C, 0x0D, 0x20, 0x3E};
90      private static final byte[] COMMENT_END = {'-', '-', '>'};
91  
92      private static final byte[] XML_DECLARATION_PREFIX = "<?xml ".getBytes(US_ASCII);
93  
94      private static final byte[] CSS_CHARSET_DECLARATION_PREFIX = "@charset \"".getBytes(US_ASCII);
95  
96      /**
97       * The number of HTML bytes to sniff for encoding info embedded in {@code meta} tags.
98       */
99      private static final int SIZE_OF_HTML_CONTENT_SNIFFED = 1024;
100 
101     /**
102      * The number of XML bytes to sniff for encoding info embedded in the XML declaration;
103      * relatively small because it is always at the very beginning of the file.
104      */
105     private static final int SIZE_OF_XML_CONTENT_SNIFFED = 512;
106 
107     private static final int SIZE_OF_CSS_CONTENT_SNIFFED = 1024;
108 
109     /**
110      * Disallow instantiation of this class.
111      */
112     private EncodingSniffer() {
113         // Empty.
114     }
115 
116     /**
117      * Returns {@code true} if the specified HTTP response headers contain a {@code Content-Type} that
118      * ends with one of the specified strings.
119      *
120      * @param headers the HTTP response headers
121      * @param contentTypeEndings the content type endings to search for
122      * @return {@code true} if the {@code Content-Type} header ends with one of the specified strings
123      */
124     static boolean contentTypeEndsWith(final List<NameValuePair> headers, final String... contentTypeEndings) {
125         for (final NameValuePair pair : headers) {
126             final String name = pair.getName();
127             if (HttpHeader.CONTENT_TYPE_LC.equalsIgnoreCase(name)) {
128                 String value = pair.getValue();
129                 final int i = value.indexOf(';');
130                 if (i != -1) {
131                     value = value.substring(0, i);
132                 }
133                 value = value.trim().toLowerCase(Locale.ROOT);
134                 for (final String ending : contentTypeEndings) {
135                     if (value.endsWith(ending.toLowerCase(Locale.ROOT))) {
136                         return true;
137                     }
138                 }
139                 return false;
140             }
141         }
142         return false;
143     }
144 
145     /**
146      * Attempts to sniff an encoding from a
147      * <a href="https://en.wikipedia.org/wiki/Byte_order_mark">Byte Order Mark</a>
148      * in the specified byte array.
149      *
150      * @param bytes the bytes to check for a Byte Order Mark
151      * @return the encoding sniffed from the specified bytes, or {@code null} if it could not be determined
152      */
153     static Charset sniffEncodingFromUnicodeBom(final byte[] bytes) {
154         if (bytes == null) {
155             return null;
156         }
157 
158         Charset encoding = null;
159         if (startsWith(bytes, ByteOrderMark.UTF_8)) {
160             encoding = UTF_8;
161         }
162         else if (startsWith(bytes, ByteOrderMark.UTF_16BE)) {
163             encoding = UTF_16BE;
164         }
165         else if (startsWith(bytes, ByteOrderMark.UTF_16LE)) {
166             encoding = UTF_16LE;
167         }
168 
169         if (encoding != null && LOG.isDebugEnabled()) {
170             LOG.debug("Encoding found in Unicode Byte Order Mark: '" + encoding + "'.");
171         }
172         return encoding;
173     }
174 
175     /**
176      * Returns whether the specified byte array starts with the given {@link ByteOrderMark}.
177      *
178      * @param bytes the byte array to check
179      * @param bom the {@link ByteOrderMark} to look for
180      * @return {@code true} if the byte array starts with the given {@link ByteOrderMark}
181      */
182     private static boolean startsWith(final byte[] bytes, final ByteOrderMark bom) {
183         final byte[] bomBytes = bom.getBytes();
184         final byte[] firstBytes = Arrays.copyOfRange(bytes, 0, Math.min(bytes.length, bomBytes.length));
185         return Arrays.equals(firstBytes, bomBytes);
186     }
187 
188     /**
189      * Attempts to sniff an encoding from an HTML {@code meta} tag in the specified input stream.
190      *
191      * @param is the content stream to check for an HTML {@code meta} tag
192      * @return the encoding sniffed from the stream, or {@code null} if it could not be determined
193      * @throws IOException if an I/O error occurs
194      */
195     public static Charset sniffEncodingFromMetaTag(final InputStream is) throws IOException {
196         final byte[] bytes = read(is, SIZE_OF_HTML_CONTENT_SNIFFED);
197         for (int i = 0; i < bytes.length; i++) {
198             if (matches(bytes, i, COMMENT_START)) {
199                 i = indexOfSubArray(bytes, COMMENT_END, i);
200                 if (i == -1) {
201                     break;
202                 }
203                 i += 2;
204             }
205             else if (matches(bytes, i, META_START)) {
206                 i += META_START.length;
207                 for (Attribute att = getAttribute(bytes, i); att != null; att = getAttribute(bytes, i)) {
208                     i = att.getUpdatedIndex();
209                     final String name = att.getName().toLowerCase(Locale.ROOT);
210                     if ("charset".equals(name) || "content".equals(name)) {
211                         final String value = att.getValue().toLowerCase(Locale.ROOT);
212                         Charset charset = null;
213                         if ("charset".equals(name)) {
214                             charset = toCharset(value);
215                             // https://html.spec.whatwg.org/multipage/parsing.html#prescan-a-byte-stream-to-determine-its-encoding
216                             if (charset == null && "x-user-defined".equals(value)) {
217                                 charset = Charset.forName("windows-1252");
218                             }
219                         }
220                         else if ("content".equals(name)) {
221                             charset = extractEncodingFromContentType(value);
222                             // https://html.spec.whatwg.org/multipage/parsing.html#prescan-a-byte-stream-to-determine-its-encoding
223                             if (charset == null && value != null && value.contains("x-user-defined")) {
224                                 charset = Charset.forName("windows-1252");
225                             }
226                             if (charset == null) {
227                                 continue;
228                             }
229                         }
230                         if (UTF_16BE == charset || UTF_16LE == charset) {
231                             charset = UTF_8;
232                         }
233                         if (charset != null) {
234                             if (LOG.isDebugEnabled()) {
235                                 LOG.debug("Encoding found in meta tag: '" + charset + "'.");
236                             }
237                             return charset;
238                         }
239                     }
240                 }
241             }
242             else if (i + 1 < bytes.length && bytes[i] == '<' && Character.isLetter(bytes[i + 1])) {
243                 i = skipToAnyOf(bytes, i, WHITESPACE);
244                 if (i == -1) {
245                     break;
246                 }
247                 Attribute att = getAttribute(bytes, i);
248                 while (att != null) {
249                     i = att.getUpdatedIndex();
250                     att = getAttribute(bytes, i);
251                 }
252             }
253             else if (i + 2 < bytes.length && bytes[i] == '<' && bytes[i + 1] == '/' && Character.isLetter(bytes[i + 2])) {
254                 i = skipToAnyOf(bytes, i, new byte[] {0x09, 0x0A, 0x0C, 0x0D, 0x20, 0x3E});
255                 if (i == -1) {
256                     break;
257                 }
258                 Attribute attribute = getAttribute(bytes, i);
259                 while (attribute != null) {
260                     i = attribute.getUpdatedIndex();
261                     attribute = getAttribute(bytes, i);
262                 }
263             }
264             else if (matches(bytes, i, OTHER_START)) {
265                 i = skipToAnyOf(bytes, i, new byte[] {0x3E});
266                 if (i == -1) {
267                     break;
268                 }
269             }
270         }
271         return null;
272     }
273 
274     /**
275      * Extracts an attribute from the specified byte array starting at the specified index, using the
276      * <a href="https://html.spec.whatwg.org/multipage/parsing.html#concept-get-attributes-when-sniffing">HTML5
277      * attribute algorithm</a>.
278      *
279      * @param bytes the byte array to extract an attribute from
280      * @param startFrom the index to start searching from
281      * @return the next attribute in the specified byte array, or {@code null} if none is available
282      */
283     static Attribute getAttribute(final byte[] bytes, final int startFrom) {
284         if (startFrom >= bytes.length) {
285             return null;
286         }
287 
288         int pos = startFrom;
289         while (bytes[pos] == 0x09 || bytes[pos] == 0x0A || bytes[pos] == 0x0C || bytes[pos] == 0x0D || bytes[pos] == 0x20 || bytes[pos] == 0x2F) {
290             pos++;
291             if (pos >= bytes.length) {
292                 return null;
293             }
294         }
295         if (bytes[pos] == '>') {
296             return null;
297         }
298         final StringBuilder name = new StringBuilder();
299         final StringBuilder value = new StringBuilder();
300         for ( ;; pos++) {
301             if (pos >= bytes.length) {
302                 return new Attribute(name.toString(), value.toString(), pos);
303             }
304             if (bytes[pos] == '=' && name.length() != 0) {
305                 pos++;
306                 break;
307             }
308             if (bytes[pos] == 0x09 || bytes[pos] == 0x0A || bytes[pos] == 0x0C || bytes[pos] == 0x0D || bytes[pos] == 0x20) {
309                 while (bytes[pos] == 0x09 || bytes[pos] == 0x0A || bytes[pos] == 0x0C || bytes[pos] == 0x0D || bytes[pos] == 0x20) {
310                     pos++;
311                     if (pos >= bytes.length) {
312                         return new Attribute(name.toString(), value.toString(), pos);
313                     }
314                 }
315                 if (bytes[pos] != '=') {
316                     return new Attribute(name.toString(), value.toString(), pos);
317                 }
318                 pos++;
319                 break;
320             }
321             if (bytes[pos] == '/' || bytes[pos] == '>') {
322                 return new Attribute(name.toString(), value.toString(), pos);
323             }
324             name.append((char) bytes[pos]);
325         }
326         if (pos >= bytes.length) {
327             return new Attribute(name.toString(), value.toString(), pos);
328         }
329         while (bytes[pos] == 0x09 || bytes[pos] == 0x0A || bytes[pos] == 0x0C || bytes[pos] == 0x0D || bytes[pos] == 0x20) {
330             pos++;
331             if (pos >= bytes.length) {
332                 return new Attribute(name.toString(), value.toString(), pos);
333             }
334         }
335         if (bytes[pos] == '"' || bytes[pos] == '\'') {
336             final byte b = bytes[pos];
337             for (pos++; pos < bytes.length; pos++) {
338                 if (bytes[pos] == b) {
339                     pos++;
340                     return new Attribute(name.toString(), value.toString(), pos);
341                 }
342                 else if (bytes[pos] >= 'A' && bytes[pos] <= 'Z') {
343                     final byte b2 = (byte) (bytes[pos] + 0x20);
344                     value.append((char) b2);
345                 }
346                 else {
347                     value.append((char) bytes[pos]);
348                 }
349             }
350             return new Attribute(name.toString(), value.toString(), pos);
351         }
352         else if (bytes[pos] == '>') {
353             return new Attribute(name.toString(), value.toString(), pos);
354         }
355         else if (bytes[pos] >= 'A' && bytes[pos] <= 'Z') {
356             final byte b = (byte) (bytes[pos] + 0x20);
357             value.append((char) b);
358             pos++;
359         }
360         else {
361             value.append((char) bytes[pos]);
362             pos++;
363         }
364         for ( ; pos < bytes.length; pos++) {
365             if (bytes[pos] == 0x09 || bytes[pos] == 0x0A || bytes[pos] == 0x0C || bytes[pos] == 0x0D || bytes[pos] == 0x20 || bytes[pos] == 0x3E) {
366                 return new Attribute(name.toString(), value.toString(), pos);
367             }
368             else if (bytes[pos] >= 'A' && bytes[pos] <= 'Z') {
369                 final byte b = (byte) (bytes[pos] + 0x20);
370                 value.append((char) b);
371             }
372             else {
373                 value.append((char) bytes[pos]);
374             }
375         }
376         return new Attribute(name.toString(), value.toString(), pos);
377     }
378 
379     /**
380      * Extracts an encoding from the specified {@code Content-Type} value using
381      * <a href="https://www.ietf.org/rfc/rfc2616.txt">the IETF algorithm</a>; if
382      * no encoding is found, returns {@code null}.
383      *
384      * @param s the {@code Content-Type} value to search for an encoding
385      * @return the encoding found in the specified value, or {@code null} if none was found
386      */
387     public static Charset extractEncodingFromContentType(final String s) {
388         if (s == null) {
389             return null;
390         }
391         final byte[] bytes = s.getBytes(US_ASCII);
392         int i;
393         for (i = 0; i < bytes.length; i++) {
394             if (matches(bytes, i, CHARSET_START)) {
395                 i += CHARSET_START.length;
396                 break;
397             }
398         }
399         if (i == bytes.length) {
400             return null;
401         }
402         while (bytes[i] == 0x09 || bytes[i] == 0x0A || bytes[i] == 0x0C || bytes[i] == 0x0D || bytes[i] == 0x20) {
403             i++;
404             if (i == bytes.length) {
405                 return null;
406             }
407         }
408         if (bytes[i] != '=') {
409             return null;
410         }
411         do {
412             i++;
413             if (i == bytes.length) {
414                 return null;
415             }
416         }
417         while (bytes[i] == 0x09 || bytes[i] == 0x0A || bytes[i] == 0x0C || bytes[i] == 0x0D || bytes[i] == 0x20);
418 
419         if (bytes[i] == '"') {
420             if (bytes.length <= i + 1) {
421                 return null;
422             }
423             final int index = ArrayUtils.indexOf(bytes, (byte) '"', i + 1);
424             if (index == -1) {
425                 return null;
426             }
427             final String charsetName = new String(ArrayUtils.subarray(bytes, i + 1, index), US_ASCII);
428             return toCharset(charsetName);
429         }
430         if (bytes[i] == '\'') {
431             if (bytes.length <= i + 1) {
432                 return null;
433             }
434             final int index = ArrayUtils.indexOf(bytes, (byte) '\'', i + 1);
435             if (index == -1) {
436                 return null;
437             }
438             final String charsetName = new String(ArrayUtils.subarray(bytes, i + 1, index), US_ASCII);
439             return toCharset(charsetName);
440         }
441         int end = skipToAnyOf(bytes, i, new byte[] {0x09, 0x0A, 0x0C, 0x0D, 0x20, 0x3B});
442         if (end == -1) {
443             end = bytes.length;
444         }
445         final String charsetName = new String(ArrayUtils.subarray(bytes, i, end), US_ASCII);
446         return toCharset(charsetName);
447     }
448 
449     /**
450      * Searches the specified XML content for an XML declaration and returns the encoding if found,
451      * otherwise returns {@code null}.
452      *
453      * @param is the content stream to check for a charset declaration
454      * @return the encoding of the specified XML content, or {@code null} if it could not be determined
455      * @throws IOException if an I/O error occurs
456      */
457     public static Charset sniffEncodingFromXmlDeclaration(final InputStream is) throws IOException {
458         final byte[] bytes = read(is, SIZE_OF_XML_CONTENT_SNIFFED);
459         Charset encoding = null;
460         if (bytes.length > 5
461                 && XML_DECLARATION_PREFIX[0] == bytes[0]
462                 && XML_DECLARATION_PREFIX[1] == bytes[1]
463                 && XML_DECLARATION_PREFIX[2] == bytes[2]
464                 && XML_DECLARATION_PREFIX[3] == bytes[3]
465                 && XML_DECLARATION_PREFIX[4] == bytes[4]
466                 && XML_DECLARATION_PREFIX[5] == bytes[5]) {
467             final int index = ArrayUtils.indexOf(bytes, (byte) '?', 2);
468             if (index + 1 < bytes.length && bytes[index + 1] == '>') {
469                 final String declaration = new String(bytes, 0, index + 2, US_ASCII);
470 
471                 int start = declaration.indexOf("encoding");
472                 if (start != -1) {
473                     start += 8;
474                     Character delimiter = null;
475                     while (start < declaration.length()) {
476                         final char c = declaration.charAt(start);
477                         if (c == '"' || c == '\'') {
478                             delimiter = c;
479                             start++;
480                             break;
481                         }
482                         start++;
483                     }
484                     if (delimiter != null) {
485                         final int end = declaration.indexOf(delimiter, start);
486                         if (end != -1) {
487                             encoding = toCharset(declaration.substring(start, end));
488                         }
489                     }
490                 }
491             }
492         }
493         if (encoding != null && LOG.isDebugEnabled()) {
494             LOG.debug("Encoding found in XML declaration: '" + encoding + "'.");
495         }
496         return encoding;
497     }
498 
499     /**
500      * Parses and returns the charset declaration at the start of a CSS file if present,
501      * otherwise returns {@code null}.
502      * e.g. {@code @charset "UTF-8"}
503      *
504      * @param is the input stream to parse
505      * @return the charset found at the start of the CSS file, or {@code null} if none
506      * @throws IOException if an I/O error occurs
507      */
508     public static Charset sniffEncodingFromCssDeclaration(final InputStream is) throws IOException {
509         final byte[] bytes = read(is, SIZE_OF_CSS_CONTENT_SNIFFED);
510         if (bytes.length < CSS_CHARSET_DECLARATION_PREFIX.length) {
511             return null;
512         }
513         for (int i = 0; i < CSS_CHARSET_DECLARATION_PREFIX.length; i++) {
514             if (bytes[i] != CSS_CHARSET_DECLARATION_PREFIX[i]) {
515                 return null;
516             }
517         }
518 
519         Charset encoding = null;
520         final int index = ArrayUtils.indexOf(bytes, (byte) '"', CSS_CHARSET_DECLARATION_PREFIX.length);
521         if (index != -1 && index + 1 < bytes.length && bytes[index + 1] == ';') {
522             encoding = toCharset(new String(bytes, CSS_CHARSET_DECLARATION_PREFIX.length, index - CSS_CHARSET_DECLARATION_PREFIX.length, US_ASCII));
523             // https://www.w3.org/TR/css-syntax-3/#input-byte-stream "Why use utf-8 when the declaration says utf-16?"
524             if (encoding == UTF_16BE || encoding == UTF_16LE) {
525                 encoding = UTF_8;
526             }
527         }
528         return encoding;
529     }
530 
531     /**
532      * Returns the {@link Charset} for the specified charset name if it is supported on this platform,
533      * or {@code null} if it is not.
534      *
535      * @param charsetName the charset name to look up
536      * @return the {@link Charset} for the given name, or {@code null} if unsupported
537      */
538     public static Charset toCharset(final String charsetName) {
539         final String nameFromLabel = translateEncodingLabel(charsetName);
540         if (nameFromLabel == null) {
541             return null;
542         }
543         try {
544             return Charset.forName(nameFromLabel);
545         }
546         catch (final IllegalCharsetNameException | UnsupportedCharsetException e) {
547             return null;
548         }
549     }
550 
551     /**
552      * Returns {@code true} if the byte in the specified byte array at the specified index matches
553      * one of the specified byte array patterns.
554      *
555      * @param bytes the byte array to search in
556      * @param i the index at which to search
557      * @param sought the byte array patterns to search for
558      * @return {@code true} if the byte at index {@code i} matches one of the patterns
559      */
560     static boolean matches(final byte[] bytes, final int i, final byte[][] sought) {
561         if (i + sought.length > bytes.length) {
562             return false;
563         }
564         for (int x = 0; x < sought.length; x++) {
565             final byte[] possibilities = sought[x];
566             boolean match = false;
567             for (final byte possibility : possibilities) {
568                 if (bytes[i + x] == possibility) {
569                     match = true;
570                     break;
571                 }
572             }
573             if (!match) {
574                 return false;
575             }
576         }
577         return true;
578     }
579 
580     /**
581      * Skips ahead to the first occurrence of any of the specified target bytes within the specified array,
582      * starting at the specified index. Returns {@code -1} if none of the targets are found.
583      *
584      * @param bytes the array to search through
585      * @param startFrom the index to start looking from
586      * @param targets the target bytes to search for
587      * @return the index of the first occurrence of any target byte, or {@code -1} if not found
588      */
589     static int skipToAnyOf(final byte[] bytes, final int startFrom, final byte[] targets) {
590         int i = startFrom;
591         for ( ; i < bytes.length; i++) {
592             if (org.htmlunit.util.ArrayUtils.contains(targets, bytes[i])) {
593                 break;
594             }
595         }
596         if (i == bytes.length) {
597             i = -1;
598         }
599         return i;
600     }
601 
602     /**
603      * Finds the first index of the specified sub-array inside the specified array, starting at the
604      * specified index. Returns {@code -1} if the sub-array cannot be found.
605      *
606      * @param array the array to traverse
607      * @param subarray the sub-array to find
608      * @param startIndex the index to start traversing from
609      * @return the index of the sub-array within the array, or {@code -1} if not found
610      */
611     static int indexOfSubArray(final byte[] array, final byte[] subarray, final int startIndex) {
612         for (int i = startIndex; i < array.length; i++) {
613             boolean found = true;
614             if (i + subarray.length > array.length) {
615                 break;
616             }
617             for (int j = 0; j < subarray.length; j++) {
618                 final byte a = array[i + j];
619                 final byte b = subarray[j];
620                 if (a != b) {
621                     found = false;
622                     break;
623                 }
624             }
625             if (found) {
626                 return i;
627             }
628         }
629         return -1;
630     }
631 
632     /**
633      * Attempts to read {@code size} bytes from the specified input stream. Note that this method is not guaranteed
634      * to read exactly {@code size} bytes; however, the returned byte array will always be the exact length of the
635      * number of bytes actually read.
636      *
637      * @param content the input stream to read from
638      * @param size the number of bytes to try to read
639      * @return the bytes read from the specified input stream
640      * @throws IOException if an I/O error occurs
641      */
642     static byte[] read(final InputStream content, final int size) throws IOException {
643         byte[] bytes = new byte[size];
644         // using IOUtils guarantees that it will read as many bytes as possible before giving up;
645         // this may not always be the case for subclasses of InputStream - e.g. GZIPInputStream
646         final int count = IOUtils.read(content, bytes);
647         if (count < size) {
648             final byte[] smaller = new byte[count];
649             System.arraycopy(bytes, 0, smaller, 0, count);
650             bytes = smaller;
651         }
652         return bytes;
653     }
654 
655     /**
656      * Attempts to read {@code size} bytes from the specified input stream and then prepends the specified prefix,
657      * returning the resulting byte array. Note that this method is not guaranteed to read exactly {@code size} bytes;
658      * however, the returned byte array will always be the exact length of the number of bytes read plus the prefix length.
659      *
660      * @param content the input stream to read from
661      * @param size the number of bytes to try to read
662      * @param prefix the byte array to prepend to the bytes read
663      * @return the bytes read from the input stream, prepended by the specified prefix
664      * @throws IOException if an I/O error occurs
665      */
666     static byte[] readAndPrepend(final InputStream content, final int size, final byte[] prefix) throws IOException {
667         final int prefixLength = prefix.length;
668         final byte[] joined = new byte[prefixLength + size];
669 
670         // using IOUtils guarantees that it will read as many bytes as possible before giving up;
671         // this may not always be the case for subclasses of InputStream - e.g. GZIPInputStream
672         final int count = IOUtils.read(content, joined, prefixLength, joined.length - prefixLength);
673         if (count < size) {
674             final byte[] smaller = new byte[prefixLength + count];
675             System.arraycopy(prefix, 0, smaller, 0, prefix.length);
676             System.arraycopy(joined, prefixLength, smaller, prefixLength, count);
677             return smaller;
678         }
679 
680         System.arraycopy(prefix, 0, joined, 0, prefix.length);
681         return joined;
682     }
683 
684     static class Attribute {
685         private final String name_;
686         private final String value_;
687         private final int updatedIndex_;
688 
689         Attribute(final String name, final String value, final int updatedIndex) {
690             name_ = name;
691             value_ = value;
692             updatedIndex_ = updatedIndex;
693         }
694 
695         String getName() {
696             return name_;
697         }
698 
699         String getValue() {
700             return value_;
701         }
702 
703         int getUpdatedIndex() {
704             return updatedIndex_;
705         }
706     }
707 
708     /**
709      * Translates the given encoding label into a normalized form
710      * according to the <a href="https://encoding.spec.whatwg.org/#encodings">WHATWG Encoding specification</a>.
711      *
712      * @param encodingLabel the label to translate
713      * @return the normalized encoding name, or {@code null} if not found
714      */
715     public static String translateEncodingLabel(final String encodingLabel) {
716         if (StringUtils.isEmptyOrNull(encodingLabel)) {
717             return null;
718         }
719 
720         final String encLC = encodingLabel.toLowerCase(Locale.ROOT);
721         final String enc = StandardEncodingTranslator.INSTANCE.encodingNameFromLabel(encodingLabel);
722         if (encLC.equals(enc)) {
723             return encLC;
724         }
725         return enc;
726     }
727 }