Line data    Source code

       1              : // Copyright 2026 The Authors
       2              : //
       3              : // Licensed under the Apache License, Version 2.0 (the "License");
       4              : // you may not use this file except in compliance with the License.
       5              : // You may obtain a copy of the License at
       6              : //
       7              : //     http://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              : /// Thrown when the Zstd library reports a compression or decompression error,
      16              : /// or when the frame header is invalid or missing content size information.
      17              : ///
      18              : /// Catch as [ZstdException] for specific handling, or as [Exception] for broad
      19              : /// error handling alongside other exception types.
      20              : class ZstdException implements Exception {
      21              :   /// The error message describing what went wrong.
      22              :   final String message;
      23              : 
      24            2 :   const ZstdException(this.message);
      25              : 
      26            1 :   @override
      27            2 :   String toString() => 'ZstdException: $message';
      28              : }
      29              : 
      30              : /// Thrown by `decompress` when a frame's declared decompressed size exceeds
      31              : /// the caller's `maxOutputBytes` limit.
      32              : ///
      33              : /// This is thrown *before* any output buffer is allocated, so it also covers
      34              : /// the case where the declared size arrives as a negative number (which can
      35              : /// happen on both native and web — see `ZstdSimple.decompress` for details).
      36              : ///
      37              : /// [declaredSize] and [limit] are exposed as plain `int` fields — not just
      38              : /// folded into [ZstdException.message] — so callers such as KMDB's quarantine
      39              : /// path can make a decision (quarantine vs. reject) without parsing prose out
      40              : /// of the exception message.
      41              : class ZstdLimitExceededException extends ZstdException {
      42              :   /// The decompressed content size declared in the frame header.
      43              :   ///
      44              :   /// May be negative: a declared size that overflows the platform's
      45              :   /// interop representation (64-bit two's-complement on native, 32-bit
      46              :   /// sign-extension on web) arrives as a negative Dart `int`, and is still
      47              :   /// rejected by this exception rather than reaching the allocator.
      48              :   final int declaredSize;
      49              : 
      50              :   /// The `maxOutputBytes` limit that [declaredSize] exceeded.
      51              :   final int limit;
      52              : 
      53              :   /// Creates a [ZstdLimitExceededException] for a [declaredSize] that
      54              :   /// exceeded [limit].
      55            2 :   ZstdLimitExceededException(this.declaredSize, this.limit)
      56            4 :     : super('declared content size $declaredSize exceeds limit $limit');
      57              : }