Add "url-safe" encoding to base64 in dart:convert.

sdk/lib/convert/base64.dart

 // Copyright (c) 2015, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.convert;
 
 /**
- * An instance of [Base64Codec].
+ * A [base64](https://tools.ietf.org/html/rfc4648) encoder and decoder.
  *
- * This instance provides a convenient access to
- * [base64](https://tools.ietf.org/html/rfc4648) encoding and decoding.
- *
- * It encodes and decodes using the default base64 alphabet, does not allow
- * any invalid characters when decoding, and requires padding.
+ * It encodes using the default base64 alphabet,
+ * decodes using both the base64 and base64url alphabets,
+ * does not allow invalid characters and requires padding.
  *
  * Examples:
  *
  *     var encoded = BASE64.encode([0x62, 0x6c, 0xc3, 0xa5, 0x62, 0xc3, 0xa6,
  *                                  0x72, 0x67, 0x72, 0xc3, 0xb8, 0x64]);
  *     var decoded = BASE64.decode("YmzDpWLDpnJncsO4ZAo=");
  */
 const Base64Codec BASE64 = const Base64Codec();
 
+/**
+ * A [base64url](https://tools.ietf.org/html/rfc4648) encoder and decoder.
+ *
+ * It encodes and decodes using the base64url alphabet,
+ * decodes using both the base64 and base64url alphabets,
+ * does not allow invalid characters and requires padding.
+ *
+ * Examples:
+ *
+ *     var encoded = BASE64.encode([0x62, 0x6c, 0xc3, 0xa5, 0x62, 0xc3, 0xa6,
+ *                                  0x72, 0x67, 0x72, 0xc3, 0xb8, 0x64]);
+ *     var decoded = BASE64.decode("YmzDpWLDpnJncsO4ZAo=");
+ */
+const Base64Codec BASE64URL = const Base64Codec.urlSafe();
+
 // Constants used in more than one class.
 const int _paddingChar = 0x3d;  // '='.
 
 /**
  * A [base64](https://tools.ietf.org/html/rfc4648) encoder and decoder.
  *
  * A [Base64Codec] allows base64 encoding bytes into ASCII strings and
  * decoding valid encodings back to bytes.
  *
- * This implementation only handles the simplest RFC 4648 base-64 encoding.
+ * This implementation only handles the simplest RFC 4648 base64 and base64url
+ * encodings.
  * It does not allow invalid characters when decoding and it requires,
  * and generates, padding so that the input is always a multiple of four
  * characters.
  */
 class Base64Codec extends Codec<List<int>, String> {
-  const Base64Codec();
+  final Base64Encoder _encoder;
+  const Base64Codec() : _encoder = const Base64Encoder();
+  const Base64Codec.urlSafe() : _encoder = const Base64Encoder.urlSafe();
 
-  Base64Encoder get encoder => const Base64Encoder();
+  Base64Encoder get encoder => _encoder;
 
   Base64Decoder get decoder => const Base64Decoder();
 }
 
 // ------------------------------------------------------------------------
 // Encoder
 // ------------------------------------------------------------------------
 
 /**
- * Base-64 encoding converter.
+ * Base64 and base64url encoding converter.
  *
- * Encodes lists of bytes using base64 encoding.
- * The result are ASCII strings using a restricted alphabet.
+ * Encodes lists of bytes using base64 or base64url encoding.
+ *
+ * The results are ASCII strings using a restricted alphabet.
  */
 class Base64Encoder extends Converter<List<int>, String> {
-  const Base64Encoder();
+  final bool _urlSafe;
+
+  const Base64Encoder() : _urlSafe = false;
+  const Base64Encoder.urlSafe() : _urlSafe = true;
 
   String convert(List<int> input) {
     if (input.isEmpty) return "";
-    var encoder = new _Base64Encoder();
+    var encoder = new _Base64Encoder(_urlSafe);
     Uint8List buffer = encoder.encode(input, 0, input.length, true);
     return new String.fromCharCodes(buffer);
   }
 
   ByteConversionSink startChunkedConversion(Sink<String> sink) {
     if (sink is StringConversionSink) {
-      return new _Utf8Base64EncoderSink(sink.asUtf8Sink(false));
+      return new _Utf8Base64EncoderSink(sink.asUtf8Sink(false), _urlSafe);
     }
-    return new _AsciiBase64EncoderSink(sink);
+    return new _AsciiBase64EncoderSink(sink, _urlSafe);
   }
 
   Stream<String> bind(Stream<List<int>> stream) {
     return new Stream<String>.eventTransformed(
         stream,
         (EventSink sink) =>
-            new _ConverterStreamEventSink<List<int>, String>(this, sink));
+            new _ConverterStreamEventSink<List<int>, String>(
+                this, sink));
   }
 }
 
 /**
- * Helper class for encoding bytes to BASE-64.
+ * Helper class for encoding bytes to base64.
  */
 class _Base64Encoder {
   /** The RFC 4648 base64 encoding alphabet. */
   static const String _base64Alphabet =
       "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 
+  /** The RFC 4648 base64url encoding alphabet. */
+  static const String _base64urlAlphabet =
+      "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
   /** Shift-count to extract the values stored in [_state]. */
   static const int _valueShift = 2;
 
   /** Mask to extract the count value stored in [_state]. */
   static const int _countMask = 3;
 
   static const int _sixBitMask = 0x3F;
 
   /**
    * Intermediate state between chunks.
    *
    * Encoding handles three bytes at a time.
    * If fewer than three bytes has been seen, this value encodes
    * the number of bytes seen (0, 1 or 2) and their values.
    */
   int _state = 0;
 
+  /** Alphabet used for encoding. */
+  final String _alphabet;
+
+  _Base64Encoder(bool urlSafe)
+      : _alphabet = urlSafe ? _base64urlAlphabet : _base64Alphabet;
+
   /** Encode count and bits into a value to be stored in [_state]. */
   static int _encodeState(int count, int bits) {
     assert(count <= _countMask);
     return bits << _valueShift | count;
   }
 
   /** Extract bits from encoded state. */
   static int _stateBits(int state) => state >> _valueShift;
 
   /** Extract count from encoded state. */
@@ skipping 25 matching lines @@
 
     int count = _stateCount(_state);
     int byteCount = (count + length);
     int fullChunks = byteCount ~/ 3;
     int partialChunkLength = byteCount - fullChunks * 3;
     int bufferLength = fullChunks * 4;
     if (isLast && partialChunkLength > 0) {
       bufferLength += 4;  // Room for padding.
     }
     var output = createBuffer(bufferLength);
-    _state = encodeChunk(bytes, start, end, isLast, output, 0, _state);
+    _state = encodeChunk(_alphabet, bytes, start, end, isLast,
+                         output, 0, _state);
     if (bufferLength > 0) return output;
     // If the input plus the data in state is still less than three bytes,
     // there may not be any output.
     return null;
   }
 
-  static int encodeChunk(List<int> bytes, int start, int end, bool isLast,
-                          Uint8List output, int outputIndex, int state) {
+  static int encodeChunk(String alphabet,
+                         List<int> bytes, int start, int end, bool isLast,
+                         Uint8List output, int outputIndex, int state) {
     int bits = _stateBits(state);
     // Count number of missing bytes in three-byte chunk.
     int expectedChars = 3 - _stateCount(state);
 
     // The input must be a list of bytes (integers in the range 0..255).
     // The value of `byteOr` will be the bitwise or of all the values in
     // `bytes` and a later check will validate that they were all valid bytes.
     int byteOr = 0;
     for (int i = start; i < end; i++) {
       int byte = bytes[i];
       byteOr |= byte;
       bits = ((bits << 8) | byte) & 0xFFFFFF;  // Never store more than 24 bits.
       expectedChars--;
       if (expectedChars == 0) {
         output[outputIndex++] =
-            _base64Alphabet.codeUnitAt((bits >> 18) & _sixBitMask);
+            alphabet.codeUnitAt((bits >> 18) & _sixBitMask);
         output[outputIndex++] =
-            _base64Alphabet.codeUnitAt((bits >> 12) & _sixBitMask);
+            alphabet.codeUnitAt((bits >> 12) & _sixBitMask);
         output[outputIndex++] =
-            _base64Alphabet.codeUnitAt((bits >> 6) & _sixBitMask);
+            alphabet.codeUnitAt((bits >> 6) & _sixBitMask);
         output[outputIndex++] =
-            _base64Alphabet.codeUnitAt(bits & _sixBitMask);
+            alphabet.codeUnitAt(bits & _sixBitMask);
         expectedChars = 3;
         bits = 0;
       }
     }
     if (byteOr >= 0 && byteOr <= 255) {
       if (isLast && expectedChars < 3) {
-        writeFinalChunk(output, outputIndex, 3 - expectedChars, bits);
+        writeFinalChunk(alphabet, output, outputIndex, 3 - expectedChars, bits);
         return 0;
       }
       return _encodeState(3 - expectedChars, bits);
     }
 
     // There was an invalid byte value somewhere in the input - find it!
     int i = start;
     while (i < end) {
       int byte = bytes[i];
       if (byte < 0 || byte > 255) break;
       i++;
     }
     throw new ArgumentError.value(bytes,
         "Not a byte value at index $i: 0x${bytes[i].toRadixString(16)}");
   }
 
   /**
    * Writes a final encoded four-character chunk.
    *
    * Only used when the [_state] contains a partial (1 or 2 byte)
    * input.
    */
-  static void writeFinalChunk(Uint8List output, int outputIndex,
+  static void writeFinalChunk(String alphabet,
+                              Uint8List output, int outputIndex,
                               int count, int bits) {
     assert(count > 0);
     if (count == 1) {
       output[outputIndex++] =
-          _base64Alphabet.codeUnitAt((bits >> 2) & _sixBitMask);
+          alphabet.codeUnitAt((bits >> 2) & _sixBitMask);
       output[outputIndex++] =
-          _base64Alphabet.codeUnitAt((bits << 4) & _sixBitMask);
+          alphabet.codeUnitAt((bits << 4) & _sixBitMask);
       output[outputIndex++] = _paddingChar;
       output[outputIndex++] = _paddingChar;
     } else {
       assert(count == 2);
       output[outputIndex++] =
-          _base64Alphabet.codeUnitAt((bits >> 10) & _sixBitMask);
+          alphabet.codeUnitAt((bits >> 10) & _sixBitMask);
       output[outputIndex++] =
-          _base64Alphabet.codeUnitAt((bits >> 4) & _sixBitMask);
+          alphabet.codeUnitAt((bits >> 4) & _sixBitMask);
       output[outputIndex++] =
-          _base64Alphabet.codeUnitAt((bits << 2) & _sixBitMask);
+          alphabet.codeUnitAt((bits << 2) & _sixBitMask);
       output[outputIndex++] = _paddingChar;
     }
   }
 }
 
 class _BufferCachingBase64Encoder extends _Base64Encoder {
   /**
    * Reused buffer.
    *
    * When the buffer isn't released to the sink, only used to create another
    * value (a string), the buffer can be reused between chunks.
    */
   Uint8List bufferCache;
 
+  _BufferCachingBase64Encoder(bool urlSafe) : super(urlSafe);
+
   Uint8List createBuffer(int bufferLength) {
     if (bufferCache == null || bufferCache.length < bufferLength) {
       bufferCache = new Uint8List(bufferLength);
     }
     // Return a view of the buffer, so it has the reuested length.
     return new Uint8List.view(bufferCache.buffer, 0, bufferLength);
   }
 }
 
 abstract class _Base64EncoderSink extends ByteConversionSinkBase {
   void add(List<int> source) {
     _add(source, 0, source.length, false);
   }
 
   void close() {
     _add(null, 0, 0, true);
   }
 
   void addSlice(List<int> source, int start, int end, bool isLast) {
     if (end == null) throw new ArgumentError.notNull("end");
     RangeError.checkValidRange(start, end, source.length);
     _add(source, start, end, isLast);
   }
 
   void _add(List<int> source, int start, int end, bool isLast);
 }
 
 class _AsciiBase64EncoderSink extends _Base64EncoderSink {
-  final _Base64Encoder _encoder = new _BufferCachingBase64Encoder();
+  final Sink<String> _sink;
+  final _Base64Encoder _encoder;
 
-  final Sink<String> _sink;
-
-  _AsciiBase64EncoderSink(this._sink);
+  _AsciiBase64EncoderSink(this._sink, bool urlSafe)
+      : _encoder = new _BufferCachingBase64Encoder(urlSafe);
 
   void _add(List<int> source, int start, int end, bool isLast) {
     Uint8List buffer = _encoder.encode(source, start, end, isLast);
     if (buffer != null) {
       String string = new String.fromCharCodes(buffer);
       _sink.add(string);
     }
     if (isLast) {
       _sink.close();
     }
   }
 }
 
 class _Utf8Base64EncoderSink extends _Base64EncoderSink {
   final ByteConversionSink _sink;
-  final _Base64Encoder _encoder = new _Base64Encoder();
+  final _Base64Encoder _encoder;
 
-  _Utf8Base64EncoderSink(this._sink);
+  _Utf8Base64EncoderSink(this._sink, bool urlSafe)
+      : _encoder = new _Base64Encoder(urlSafe);
 
   void _add(List<int> source, int start, int end, bool isLast) {
     Uint8List buffer = _encoder.encode(source, start, end, isLast);
     if (buffer != null) {
       _sink.addSlice(buffer, 0, buffer.length, isLast);
     }
   }
 }
 
 // ------------------------------------------------------------------------
 // Decoder
 // ------------------------------------------------------------------------
 
+/**
+ * Decoder for base64 encoded data.
+ *
+ * This decoder accepts both base64 and base64url ("url-safe") encodings.
+ *
+ * The encoding is required to be properly padded.
+ */
 class Base64Decoder extends Converter<String, List<int>> {
   const Base64Decoder();
 
   List<int> convert(String input, [int start = 0, int end]) {
     end = RangeError.checkValidRange(start, end, input.length);
     if (start == end) return new Uint8List(0);
     var decoder = new _Base64Decoder();
     Uint8List buffer = decoder.decode(input, start, end);
     decoder.close(input, end);
     return buffer;
@@ skipping 25 matching lines @@
   static const int _p = _padding;
 
   /**
    * Mapping from ASCII characters to their index in the base64 alphabet.
    *
    * Uses [_invalid] for invalid indices and [_padding] for the padding
    * character.
    *
    * Accepts the "URL-safe" alphabet as well (`-` and `_` are the
    * 62nd and 63rd alphabet characters), and considers `%` a padding
-   * character which mush be followed by `3D`, the percent-escape
+   * character, which mush then be followed by `3D`, the percent-escape
    * for `=`.
    */
   static final List<int> _inverseAlphabet = new Int8List.fromList([
     __, __, __, __, __, __, __, __, __, __, __, __, __, __, __, __,
     __, __, __, __, __, __, __, __, __, __, __, __, __, __, __, __,
     __, __, __, __, __, _p, __, __, __, __, __, 62, __, 62, __, 63,
     52, 53, 54, 55, 56, 57, 58, 59, 60, 61, __, __, __, _p, __, __,
     __,  0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14,
     15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, __, __, __, __, 63,
     __, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40,
     41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, __, __, __, __, __,
   ]);
 
   // Character constants.
   static const int _char_percent = 0x25;  // '%'.
   static const int _char_3       = 0x33;  // '3'.
   static const int _char_d       = 0x64;  // 'd'.
 
   /**
    * Maintains the intermediate state of a partly-decoded input.
    *
-   * BASE-64 is decoded in chunks of four characters. If a chunk does not
+   * Base64 is decoded in chunks of four characters. If a chunk does not
    * contain a full block, the decoded bits (six per character) of the
    * available characters are stored in [_state] until the next call to
    * [_decode] or [_close].
    *
    * If no padding has been seen, the value is
    *   `numberOfCharactersSeen | (decodedBits << 2)`
    * where `numberOfCharactersSeen` is between 0 and 3 and decoded bits
    * contains six bits per seen character.
    *
    * If padding has been seen the value is negative. It's the bitwise negation
@@ skipping 226 matching lines @@
       }
       break;
     }
     return newEnd;
   }
 
   /**
    * Check that the remainder of the string is valid padding.
    *
    * Valid padding is a correct number (0, 1 or 2) of `=` characters
-   * or `%3D` sequences depending on the number of preceding BASE-64 characters.
+   * or `%3D` sequences depending on the number of preceding base64 characters.
    * The [state] parameter encodes which padding continuations are allowed
    * as the number of expected characters. That number is the number of
    * expected padding characters times 3 minus the number of padding characters
    * seen so far, where `=` counts as 3 counts as three characters,
    * and the padding sequence `%3D` counts as one character per character.
    *
    * The number of missing characters is always between 0 and 5 because we
    * only call this function after having seen at least one `=` or `%`
    * character.
    * If the number of missing characters is not 3 or 0, we have seen (at least)
@@ skipping 72 matching lines @@
     end = RangeError.checkValidRange(start, end, string.length);
     if (start == end) return;
     Uint8List buffer = _decoder.decode(string, start, end);
     if (buffer != null) _sink.add(buffer);
     if (isLast) {
       _decoder.close(string, end);
       _sink.close();
     }
   }
 }