feat: exceptions for base64 errors

Closes #26

Author: rafamizes

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Dart Package Versioning](https://dart.dev/tools/pub
 
 ## [Unreleased]
 
+### Added
+
+- specific exception for base64 decoding errors — [26](https://github.com/dartoos-dev/dartoos/issues/26)
+
 ## [0.3.0] - 2021-12-09
 
 ### Added

example/encoding/base64_benchmark.dart

@@ -2,8 +2,7 @@
 import 'dart:convert';
 import 'dart:typed_data';
 
-import 'package:dartoos/dartoos.dart';
-import 'package:dartoos/src/encoding/base64/base64_enc.dart';
+import 'package:dartoos/dartoos.dart' as dartoos;
 
 import '../utils/perf_gain.dart';
 
@@ -27,7 +26,7 @@ void main() {
   const len = 50000000;
   const alphabet =
       'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
-  final bytes = BytesOf.text(Rand(len, alphabet)).value;
+  final bytes = dartoos.BytesOf.text(dartoos.Rand(len, alphabet)).value;
   print('\nLength of the data to be encoded: ${bytes.length} bytes.');
 
   print('\n--- Encoding elapsed times ---');
@@ -39,8 +38,7 @@ void main() {
   watch.reset();
 
   watch.start();
-  const dartoosBase64Enc = Base64Enc();
-  final dartoosEnc = dartoosBase64Enc(bytes);
+  final dartoosEnc = dartoos.base64(bytes);
   final dartoosEncTime = watch.elapsedMicroseconds / 1000;
   print('Dartoos base64-encoding...: $dartoosEncTime milliseconds');
   watch.stop();
@@ -57,8 +55,7 @@ void main() {
   watch.reset();
 
   watch.start();
-  const dartoosDecoder = Base64Dec();
-  final dartoosDec = dartoosDecoder(dartoosEnc);
+  final dartoosDec = dartoos.base64Dec(dartoosEnc);
   final dartoosDecTime = watch.elapsedMicroseconds / 1000;
   print('Dartoos base64-decoding...: $dartoosDecTime milliseconds');
   watch.stop();
@@ -80,13 +77,3 @@ bool bytesEqual(Uint8List first, Uint8List second) {
   }
   return i == length;
 }
-
-/// Returns a formatted string describing the performance gain ('+', positive
-/// values) or loss ('-', negative values).
-///
-/// Examples: +12% for a performance gain; -5.5% for a performance loss.
-// String perfGain(double dartTime, double dartoosTime) {
-// final perc = ((dartTime / dartoosTime) * 100) - 100;
-// final sign = perc > 0 ? '+' : '';
-// return "$sign${perc.toStringAsFixed(2)}% ('+' gain; '-' loss)";
-// }

lib/base64.dart

@@ -7,8 +7,13 @@
 /// >
 /// > — [Base64 encoding. In Wikipedia, The Free
 /// > Encyclopedia](https://en.wikipedia.org/w/index.php?title=Base64&oldid=1054311270)
+///
+/// Specification:
+///
+/// - [RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648)
 library base64;
 
 export 'src/encoding/base64/base64.dart';
 export 'src/encoding/base64/base64_dec.dart';
+export 'src/encoding/base64/base64_enc.dart';
 export 'src/encoding/base64/base64_norm.dart';

lib/src/encoding/base64/base64.dart

@@ -24,3 +24,101 @@ abstract class Base64Decoder implements BinToTextDec {
   @override
   Uint8List call(String encoded);
 }
+
+/// Thrown when trying to decode strings that do not have a proper base64
+/// format.
+class Base64Exception extends FormatException {
+  /// Creates a `Base64FormatException` with an error [message].
+  ///
+  /// Optionally, you can also supply the [source] with the incorrect format and
+  /// the [offset] where the error was detected.
+  const Base64Exception(
+    this.errorType,
+    String message, [
+    dynamic source,
+    int? offset,
+  ]) : super(message, source, offset);
+
+  /// Invalid base64-encoded text length
+  ///
+  /// Optionally, you can also supply the [source] with the incorrect format and
+  /// the [offset] where the error was detected.
+  const Base64Exception.length({
+    String message = 'Invalid base64 length.',
+    dynamic source,
+    int? offset,
+  }) : this(Base64FormatError.length, message, source, offset);
+
+  /// Invalid percent-encoding of '=' — Base64Url.
+  ///
+  /// Optionally, you can also supply the [source] with the incorrect format and
+  /// the [offset] where the error was detected.
+  const Base64Exception.percEnc({
+    String message = "Base64 invalid percent-encoding of '='.",
+    dynamic source,
+    int? offset,
+  }) : this(Base64FormatError.percEnc, message, source, offset);
+
+  /// Encoded text contains non-ascii character(s).
+  ///
+  /// Optionally, you can also supply the [source] with the incorrect format and
+  /// the [offset] where the error was detected.
+  const Base64Exception.nonAscii({
+    String message = 'Base64-encoded text contains non-ascii character(s).',
+    dynamic source,
+    int? offset,
+  }) : this(Base64FormatError.nonAscii, message, source, offset);
+
+  /// Encoded text conains illegal ascii symbol(s).
+  ///
+  /// Optionally, you can also supply the [source] with the incorrect format and
+  /// the [offset] where the error was detected.
+  const Base64Exception.illegalAscii({
+    String message =
+        "Base64-encoded text contains illegal ascii symbol(s) (characters other than 'A–Za–z0–9+-/_').",
+    dynamic source,
+    int? offset,
+  }) : this(Base64FormatError.illegalAscii, message, source, offset);
+
+  /// Invalid base64-encoded padding.
+  ///
+  /// Optionally, you can also supply the [source] with the incorrect format and
+  /// the [offset] where the error was detected.
+  const Base64Exception.padding({
+    String message = "Base64 invalid padding",
+    dynamic source,
+    int? offset,
+  }) : this(Base64FormatError.padding, message, source, offset);
+
+  /// The actual type of the format error.
+  final Base64FormatError errorType;
+}
+
+/// Specific error types to be used along with [Base64Exception].
+///
+/// Useful for fine-grained error handling.
+enum Base64FormatError {
+  /// Invalid base64-encoded text length
+  length,
+
+  /// Invalid percent-encoding of trailing '=' — Base64Url
+  percEnc,
+
+  /// Encoded text contains non-ascii character(s)
+  nonAscii,
+
+  /// Encoded text conains an illegal ascii symbol
+  ///
+  /// Any character other than 'A-Za-z0-9+-/_' have been found.
+  illegalAscii,
+
+  /// Invalid padding
+  ///
+  /// Examples:
+  ///
+  /// - unnecessary trailing '='.
+  /// - missing '==' at the end of the encoded text.
+  /// - there should be a single '=' padding character but multiple '=' were
+  ///   found.
+  padding
+}

lib/src/encoding/base64/base64_dec.dart

@@ -4,8 +4,35 @@ import '../../byte.dart';
 import 'base64.dart';
 import 'base64_norm.dart';
 
+/// Strict Base64 Decoder
+///
+/// **alphabet**: A–Za–z0–9+/
+///
+/// It requires padding and throws [Base64Exception] if the incoming text is
+/// ill-formed. For a more relaxed decoder, see [base64DecNorm].
+///
+/// Base64 encoding scheme —
+/// [RFC 4648 section 4](https://datatracker.ietf.org/doc/html/rfc4648#section-4)
+const base64Dec = Base64Dec();
+
+/// Normalizing Base64 Decoder
+///
+/// It normalizes the encoded text before trying to decode it.
+///
+/// Normalization process:
+///
+/// - Unescape any '%' that preceeds '3D' (percent-encoded '=').
+/// - Replace '_' or '-' with '/' or '+'.
+/// - Add trailing padding '=' if needed.
+/// - Only base64 characters (A–Za–z0–9/+).
+/// - The total length will always be a multiple of four.
+const base64DecNorm = Base64Dec.norm();
+
 /// Base64 Decoder.
 ///
+/// Throws [Base64Exception] when [encoded] does not have the expected base64
+/// format and cannot be parsed.
+///
 /// Base64 encoding scheme —
 /// [RFC 4648 section 4](https://datatracker.ietf.org/doc/html/rfc4648#section-4)
 class Base64Dec implements Base64Decoder {
@@ -30,31 +57,32 @@ class Base64Dec implements Base64Decoder {
   /// - Add trailing padding '=' if needed.
   /// - Only base64 characters (A–Za–z0–9/+).
   /// - The total length will always be a multiple of four.
-  const Base64Dec.norm() : this(const Base64Norm());
+  const Base64Dec.norm() : this(base64Norm);
 
   // Restores the original bytes.
   final _ProperlyPadded _decode;
 
   // The normalization phase.
   final Base64NormText _norm;
 
+  /// Returns the decoded bytes of [encoded].
+  ///
+  /// Throws [Base64Exception] when [encoded] does not have the expected base64
+  /// format and cannot be parsed.
   @override
   Uint8List call(String encoded) => _decode(_norm(encoded));
 }
 
 /// Convenience Base64 decoder implementation over [Base64Dec].
 class Base64DecOf implements Bytes {
   /// Decoded bytes of [encoded] text.
-  const Base64DecOf(String encoded, [Base64Dec dec = const Base64Dec()])
-      : _encoded = encoded,
-        _dec = dec;
+  const Base64DecOf(String encoded) : this._set(encoded, base64Dec);
 
   /// Normalizes [encoded] before trying to decode it.
-  const Base64DecOf.norm(String encoded)
-      : this(encoded, const Base64Dec.norm());
+  const Base64DecOf.norm(String encoded) : this._set(encoded, base64DecNorm);
 
-  /// Custom
-  const Base64DecOf.custom(this._encoded, this._dec);
+  /// Sets the encoded text and decoder instance.
+  const Base64DecOf._set(this._encoded, this._dec);
 
   final String _encoded;
   final Base64Dec _dec;
@@ -95,32 +123,38 @@ class _ProperlyPadded {
   Uint8List call(String base64) {
     final info = _Base64Info(base64);
     if (info.totalLength % 4 != 0) {
-      throw const FormatException('Invalid base64 encoding length');
+      throw const Base64Exception.length(
+        message: 'Base64 encoding length must be a multiple of 4.',
+      );
     }
     switch (info.payloadLength % 4) {
       case 1:
-        throw const FormatException('Invalid base64 payload length');
+        throw const Base64Exception.length(
+          message: 'Invalid base64 payload length',
+        );
       case 0:
         // There must be no padding.
         if (info.numOfPadChars != 0) {
-          throw const FormatException(
-            "Invalid base64 padding: unnecessary trailing '='.",
+          throw const Base64Exception.padding(
+            message: "Invalid base64 padding: unnecessary trailing '='.",
           );
         }
         break;
       case 2:
         // There must be exactly 2 padding chars.
         if (info.numOfPadChars != 2) {
-          throw const FormatException(
-            "Invalid base64 padding: missing '==' at the end of the encoded text.",
+          throw const Base64Exception.padding(
+            message:
+                "Invalid base64 padding: missing '==' at the end of the encoded text.",
           );
         }
         break;
       case 3:
         // There must be a single padding char at the end.
         if (info.numOfPadChars != 1) {
-          throw const FormatException(
-            "Invalid base64 padding: there should only be one '=' at the end of the encoded text.",
+          throw const Base64Exception.padding(
+            message:
+                "Invalid base64 padding: there should be a single '=' at the end of the encoded text.",
           );
         }
     }
@@ -192,15 +226,11 @@ class _Base64Indexes {
   int operator [](int i) {
     final code = _base64.codeUnitAt(i);
     if (code < 0 || code > 127) {
-      throw const FormatException(
-        'Illegal base64 character: non-ascii character found.',
-      );
+      throw const Base64Exception.nonAscii();
     }
     final index = _asciiBase64Indexes[code];
     if (index < 0) {
-      throw const FormatException(
-        "Invalid base64 character: ascii character other than '[A-Za-z][0-9]+/'.",
-      );
+      throw const Base64Exception.illegalAscii();
     }
     return index;
   }

lib/src/encoding/base64/base64_enc.dart

@@ -2,17 +2,47 @@ import 'dart:typed_data';
 
 import 'base64.dart';
 
+/// Standard base64 encoding.
+///
+/// **alphabet**: A–Za–z0–9+/
+/// **padding**: '=' or '==', if needed.
+///
+/// [Base64](https://datatracker.ietf.org/doc/html/rfc4648#section-4)
+const base64 = Base64Enc();
+
+/// Standard base64 encoding without padding '=' signs.
+///
+/// **alphabet**: A–Za–z0–9+/
+///
+/// [Base64](https://datatracker.ietf.org/doc/html/rfc4648#section-4)
+const base64NoPad = Base64Enc.noPad();
+
+/// URL- and filename-safe base64 encoding.
+///
+/// **alphabet**: A–Za–z0–9-_
+/// **padding**: '=' or '==', if needed.
+///
+/// [Base64Url](https://datatracker.ietf.org/doc/html/rfc4648#section-5)
+const base64Url = Base64UrlEnc();
+
+/// URL- and filename-safe base64 encoding without padding '=' signs
+///
+/// **alphabet**: A–Za–z0–9-_
+///
+/// [Base64Url](https://datatracker.ietf.org/doc/html/rfc4648#section-5)
+const base64UrlNoPad = Base64UrlEnc.noPad();
+
 /// Standard Base64 Encoder
 ///
 /// [Base64](https://datatracker.ietf.org/doc/html/rfc4648#section-4)
 class Base64Enc implements Base64Encoder {
-  /// Base64.
+  /// Base64 Encoding
   ///
   /// **alphabet**: A–Za–z0–9+/
-  /// **padding**: '='
+  /// **padding**: '=' or '==', if needed.
   const Base64Enc() : this._set(const _Base64Str(_Pad(_Base64Indexes(_std))));
 
-  /// Base64 without padding '=' signs.
+  /// Base64 encoding without padding '=' signs
   ///
   /// **alphabet**: A–Za–z0–9+/
   const Base64Enc.noPad()
@@ -38,14 +68,14 @@ class Base64Enc implements Base64Encoder {
 ///
 /// [Base64Url](https://datatracker.ietf.org/doc/html/rfc4648#section-5)
 class Base64UrlEnc implements Base64Encoder {
-  /// Base64Url
+  /// Base64Url Encoding
   ///
   /// **default alphabet**: A–Za–z0–9-_
-  /// **padding**: '='.
+  /// **padding**: '=' or '==', if needed.
   const Base64UrlEnc()
       : this._set(const _Base64Str(_Pad(_Base64Indexes(_url))));
 
-  /// Base64Url without padding '=' signs.
+  /// Base64Url encoding without padding '=' signs
   ///
   /// **alphabet**: A–Za–z0–9-_
   const Base64UrlEnc.noPad()