// Copyright 2026 International Digital Economy Academy
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// gzip (RFC 1952): a fixed header with optional fields, raw DEFLATE and an
// 8-byte trailer (CRC-32 and ISIZE, both little-endian).
///|
pub using @flate {
type Strategy,
type Status,
type StepResult,
type DeflateAction,
}
///|
/// Machine-readable category for a gzip decoding failure. The accompanying
/// `GzipError` message remains intended for diagnostics rather than branching.
/// Output limits, cancellation and invalid limits apply to `decompress` only.
#derive(Eq, @debug.Debug)
pub(all) enum GzipErrorKind {
/// The input ended before a complete member, header field, body, or trailer.
Truncated
/// The fixed header, magic bytes, method, or reserved flags are invalid.
InvalidHeader
/// The member's raw DEFLATE payload is malformed.
InvalidDeflate
/// The trailer CRC-32 does not match the decompressed payload.
ChecksumMismatch
/// The trailer ISIZE does not match the decompressed payload length.
LengthMismatch
/// The cumulative output ceiling and observed decoded size when stopped.
/// The observed size need not be the complete multi-member output size.
OutputLimitExceeded(limit~ : UInt64, observed~ : UInt64)
/// The caller's cancellation callback returned true.
Cancelled
/// A caller-supplied output ceiling is negative.
InvalidArgument
}
///|
/// Structured gzip decoding failure: a stable category plus a human-readable
/// diagnostic.
pub suberror GzipError {
GzipError(GzipErrorKind, String)
}
///|
/// Preserve resource failures as well as the diagnostic of malformed DEFLATE.
fn wrap_inflate_error(err : @flate.InflateError) -> GzipError {
let InflateError(kind, message) = err
match kind {
OutputLimitExceeded(limit~, observed~) =>
GzipError(OutputLimitExceeded(limit~, observed~), message)
Cancelled => GzipError(Cancelled, message)
InvalidArgument => GzipError(InvalidArgument, message)
_ => GzipError(InvalidDeflate, message)
}
}
///|
fn check_cancelled(cancelled : (() -> Bool)?) -> Unit raise GzipError {
if cancelled is Some(callback) && callback() {
raise GzipError(Cancelled, "gzip: cancelled by caller")
}
}
///|
/// Poll during checksums as well as during DEFLATE decoding.
fn crc32_cancellable(
input : BytesView,
cancelled : (() -> Bool)?,
) -> UInt32 raise GzipError {
guard cancelled is Some(_) else { return @checksum.crc32(input) }
let crc = @checksum.Crc32()
let mut start = 0
while start < input.length() {
check_cancelled(cancelled)
let end = start + (input.length() - start).min(4096)
crc.update(input[start:end])
start = end
}
check_cancelled(cancelled)
crc.finish()
}
///|
fn u32_le(data : BytesView, off : Int32) -> UInt32 {
data[off].to_uint() |
(data[off + 1].to_uint() << 8) |
(data[off + 2].to_uint() << 16) |
(data[off + 3].to_uint() << 24)
}
///|
/// Wrap a raw DEFLATE stream `deflated` of `input` in the gzip header/trailer.
fn gzip_frame(input : BytesView, deflated : Bytes) -> Bytes {
let out = @buffer.Buffer()
// Header: magic, CM=8 (deflate), FLG=0, MTIME=0, XFL=0, OS=255 (unknown).
out.write_bytes(b"\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\xff")
out.write_bytes(deflated)
out.write_uint_le(@checksum.crc32(input))
out.write_uint_le(input.length().reinterpret_as_uint())
out.to_bytes()
}
///|
/// Compress a complete gzip stream with the selected DEFLATE strategy.
/// `fast_store` may bypass the strategy for sampled inputs, trading ratio for speed.
pub fn compress(
input : BytesView,
strategy~ : @flate.Strategy = Standard(level=6),
fast_store~ : Bool = false,
) -> Bytes {
gzip_frame(input, @flate.deflate_all(input, strategy~, fast_store~))
}
///|
/// Inflate the raw DEFLATE member starting at `input[q:]` with the in-memory
/// decoder, which ignores what follows the member's final block; afterwards
/// The consumed count locates the 8-byte trailer. The caller reuses one
/// decoder across members.
fn inflate_member(
input : BytesView,
q : Int32,
decoder : @flate.Decompressor,
max_output : Int32,
cancelled : (() -> Bool)?,
) -> @flate.Decompressed raise GzipError {
decoder.decompress(input[q:], mode=Prefix, max_output~, cancelled?) catch {
// All remaining input was handed over, yet the stream did not end.
InflateError(Truncated, _) => raise GzipError(Truncated, "gzip: truncated")
err => raise wrap_inflate_error(err)
}
}
///|
/// Whether the bytes at `p` begin a gzip member: the magic pair, with a
/// truncated second byte treated as a (still-to-be-validated) member start so
/// the caller reports `Truncated` rather than ending the stream.
fn gunzip_member_magic(input : BytesView, p : Int32, n : Int32) -> Bool {
input[p].to_int() == 0x1F && (p + 1 >= n || input[p + 1].to_int() == 0x8B)
}
///|
/// Skip a NUL-terminated header field, returning the offset one past the NUL.
/// An unterminated field (bounded by the input end) still consumes its bytes;
/// the caller's truncated-input check rejects it.
fn gunzip_skip_nul_terminated(
input : BytesView,
q : Int32,
cancelled : (() -> Bool)?,
) -> Int32 raise GzipError {
let mut q = q
while q < input.length() && input[q].to_int() != 0 {
if (q & 4095) == 0 {
check_cancelled(cancelled)
}
q = q + 1
}
q + 1
}
///|
/// Offset one past the optional header fields (FEXTRA, FNAME, FCOMMENT, FHCRC)
/// gated by the FLG bits.
fn gunzip_optional_fields_end(
input : BytesView,
q : Int32,
flg : Int32,
cancelled : (() -> Bool)?,
) -> Int32 raise GzipError {
let header_start = q - 10
let mut q = q
if (flg & 4) != 0 { // FEXTRA
let xlen = input[q].to_int() | (input[q + 1].to_int() << 8)
q = q + 2 + xlen
}
if (flg & 8) != 0 { // FNAME (NUL-terminated)
q = gunzip_skip_nul_terminated(input, q, cancelled)
}
if (flg & 16) != 0 { // FCOMMENT (NUL-terminated)
q = gunzip_skip_nul_terminated(input, q, cancelled)
}
if (flg & 2) != 0 { // FHCRC
guard q <= input.length() - 2 else {
raise GzipError(Truncated, "gzip: truncated header CRC")
}
let expected = input[q].to_uint() | (input[q + 1].to_uint() << 8)
guard (crc32_cancellable(input[header_start:q], cancelled) & 0xffff) ==
expected else {
raise GzipError(ChecksumMismatch, "gzip: header CRC-16 mismatch")
}
q = q + 2
}
q
}
///|
/// Decode one member at `p`: fixed header, optional fields, DEFLATE payload,
/// and trailer verification. Returns the payload and the offset of the next
/// member (one past the trailer).
fn gunzip_decode_member(
input : BytesView,
p : Int32,
n : Int32,
decoder : @flate.Decompressor,
max_output : Int32,
cancelled : (() -> Bool)?,
) -> (Bytes, Int32) raise GzipError {
guard n - p >= 18 else { raise GzipError(Truncated, "gzip: truncated") }
guard input[p + 2].to_int() == 0x08 else {
raise GzipError(InvalidHeader, "gzip: unsupported compression method")
}
let flg = input[p + 3].to_int()
guard (flg & 0xE0) == 0 else {
raise GzipError(InvalidHeader, "gzip: reserved flags are set")
}
let q = gunzip_optional_fields_end(input, p + 10, flg, cancelled)
guard q <= n - 8 else { raise GzipError(Truncated, "gzip: truncated") }
let result = inflate_member(input, q, decoder, max_output, cancelled)
let payload = result.data
let trailer = q + result.consumed
guard trailer <= n - 8 else { raise GzipError(Truncated, "gzip: truncated") }
guard crc32_cancellable(payload, cancelled) == u32_le(input, trailer) else {
raise GzipError(ChecksumMismatch, "gzip: CRC-32 mismatch")
}
guard payload.length().reinterpret_as_uint() == u32_le(input, trailer + 4) else {
raise GzipError(LengthMismatch, "gzip: length mismatch")
}
(payload, trailer + 8)
}
///|
/// Decode and join gzip members, verifying each CRC-32 and length trailer.
/// Trailing bytes that do not begin another member are ignored. `max_output`
/// caps cumulative output (default: `Bytes` capacity); exceeding it raises
/// `OutputLimitExceeded(limit~, observed~)`, a negative value `InvalidArgument`.
/// `cancelled` is polled at entry, between members and in 4 KiB intervals during
/// name/comment scanning, decoding, checksumming and joining; true raises `Cancelled`.
pub fn decompress(
input : BytesView,
max_output? : Int32,
cancelled? : () -> Bool,
) -> Bytes raise GzipError {
let limit = max_output.unwrap_or(0x7fff_ffff)
guard limit >= 0 else {
raise GzipError(InvalidArgument, "max_output must be non-negative")
}
check_cancelled(cancelled)
let n = input.length()
guard n >= 18 else { raise GzipError(Truncated, "gzip: input too short") }
let out = @buffer.Buffer()
let decoder = @flate.Decompressor()
let mut p = 0
let mut total = 0
for ;; {
// Stop once no further member begins: clean end or trailing garbage. A
// complete magic prefix does begin another member, however, so it must be
// decoded or reported as truncated rather than silently discarded.
guard p < n else { break }
guard gunzip_member_magic(input, p, n) else {
guard p == 0 else { break }
raise GzipError(InvalidHeader, "gzip: bad magic")
}
check_cancelled(cancelled)
let (payload, next_p) = gunzip_decode_member(
input,
p,
n,
decoder,
limit - total,
cancelled,
) catch {
GzipError(OutputLimitExceeded(limit=_, observed~), message) =>
raise GzipError(
OutputLimitExceeded(
limit=limit.to_uint64(),
observed=total.to_uint64() + observed,
),
message,
)
error => raise error
}
total += payload.length()
// The usual file is one member and nothing else: its payload is the
// result, with no joining buffer to copy it through.
if p == 0 && next_p == n {
return payload
}
if cancelled is Some(_) {
let mut start = 0
while start < payload.length() {
check_cancelled(cancelled)
let end = start + (payload.length() - start).min(4096)
out.write_bytes(payload[start:end])
start = end
}
} else {
out.write_bytes(payload)
}
p = next_p
}
check_cancelled(cancelled)
out.to_bytes()
}