// Derived from moonbitlang/core archive/zip/directory_reader.mbt at 25a579771; modified.
// 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.

///|
/// Tail lookup includes the largest classic EOCD and its 16-bit comment.
const DIRECTORY_TAIL_SIZE : Int32 = 65557

///|
const DIRECTORY_CHUNK_SIZE : Int32 = 65536

///|
priv struct ClassicDirectoryEnd {
  offset : UInt64
  disk : UInt32
  central_disk : UInt32
  disk_entries : Int32
  entries : Int32
  central_size : UInt32
  central_offset : UInt32
  comment : BytesView
  probe_zip64 : Bool
}

///|
priv struct DirectoryBounds {
  offset : UInt64
  size : UInt64
  entries : UInt64
  comment : Bytes
}

///|
priv enum DirectoryPhase {
  Initial
  Tail(ReadRange)
  Locator(ClassicDirectoryEnd)
  Zip64(ClassicDirectoryEnd, UInt64)
  Zip64Probe(ClassicDirectoryEnd)
  DirectoryProbe(DirectoryReading)
  Records(DirectoryBounds, UInt64)
  Complete(Directory)
  Failed(ZipErrorKind, String)
}

///|
/// Metadata-only ZIP reader driven by caller-supplied byte ranges. Supports
/// classic ZIP and ZIP64 beyond 2 GiB without retaining the archive or inflating
/// payloads. Retains owned metadata plus a bounded incomplete directory record.
/// File reads, HTTP requests, source consistency, and cancellation between
/// calls belong to the caller. No I/O callback is retained or invoked.
struct DirectoryReader {
  archive_size : UInt64
  limits : DirectoryLimits
  mut phase : DirectoryPhase
  mut entries : Array[DirectoryEntry]
  mut pending : Bytes
  mut offset_gap : UInt64
  mut zip64_declared : UInt64
  mut selected_end : ClassicDirectoryEnd?
  mut selected_zip64 : UInt64?
  mut selected_size : UInt64
  mut selection : EndSelection?
}

///|
/// Start reading an archive of the supplied total byte size. No bytes are read
/// until the caller drives `advance` and fulfills the returned ranges.
pub fn DirectoryReader::DirectoryReader(
  archive_size : UInt64,
  limits~ : DirectoryLimits = DirectoryLimits(),
) -> DirectoryReader {
  {
    archive_size,
    limits,
    phase: Initial,
    entries: [],
    pending: b"",
    offset_gap: 0UL,
    zip64_declared: 0UL,
    selected_end: None,
    selected_zip64: None,
    selected_size: 0UL,
    selection: None,
  }
}

///|
/// Initially supply empty input; thereafter supply exactly the bytes requested
/// by the preceding `NeedRead`. Accumulate transport short reads before calling.
/// All ranges must refer to the same immutable archive. Input is borrowed only
/// for this call; retained metadata and incomplete records are copied.
/// Requests are at most 65,557 bytes, and directory chunks at most 64 KiB.
/// `Done` validates directory structure and referenced bounds, not local headers
/// or payload integrity. Empty calls after completion return the same listing.
/// Any error is latched and rethrown on subsequent calls.
pub fn DirectoryReader::advance(
  self : DirectoryReader,
  input : BytesView,
) -> DirectoryStep raise ZipError {
  if self.phase is Failed(kind, message) {
    raise ZipError(kind, message)
  }
  self.advance_selection(input) catch {
    ZipError(kind, message) => {
      self.phase = Failed(kind, message)
      self.entries = []
      self.pending = b""
      self.selected_end = None
      self.selection = None
      raise ZipError(kind, message)
    }
  }
}

///|
fn DirectoryReader::advance_selection(
  self : DirectoryReader,
  input : BytesView,
) -> DirectoryStep raise ZipError {
  self.advance_with_classic_fallback(input) catch {
    ZipError(kind, message) => {
      if kind.directory_failure() && self.selection is Some(selection) {
        return self.reject_candidate(selection, ZipError(kind, message))
      }
      raise ZipError(kind, message)
    }
  }
}

///|
fn DirectoryReader::advance_with_classic_fallback(
  self : DirectoryReader,
  input : BytesView,
) -> DirectoryStep raise ZipError {
  self.advance_active(input) catch {
    ZipError(kind, _) as error =>
      if kind.directory_failure() && self.selected_zip64 is Some(_) {
        self.begin_classic_records(self.selected_end.unwrap())
      } else {
        raise error
      }
  }
}

///|
fn expect_range_input(input : BytesView, length : Int32) -> Unit raise ZipError {
  guard input.length() == length else {
    raise ZipError(
      InvalidRead(expected=length, actual=input.length()),
      "zip: response length differs from requested range",
    )
  }
}

///|
fn range_read_length(remaining : UInt64, maximum : Int32) -> Int32 {
  if remaining < maximum.to_uint64() {
    remaining.to_int()
  } else {
    maximum
  }
}

///|
fn check_directory_limit(
  kind : LimitKind,
  limit : UInt64,
  actual : UInt64,
) -> Unit raise ZipError {
  guard actual <= limit else {
    raise ZipError(
      LimitExceeded(kind~, limit~, observed=actual),
      "zip: directory limit exceeded",
    )
  }
}

///|
fn DirectoryReader::advance_active(
  self : DirectoryReader,
  input : BytesView,
) -> DirectoryStep raise ZipError {
  match self.phase {
    Initial => {
      expect_range_input(input, 0)
      guard self.archive_size >= 22UL else {
        raise ZipError(
          MissingEndOfCentral,
          "zip: end of central directory not found",
        )
      }
      let length = range_read_length(self.archive_size, DIRECTORY_TAIL_SIZE)
      let range = { offset: self.archive_size - length.to_uint64(), length, }
      self.phase = Tail(range)
      NeedRead(range)
    }
    Tail(range) => {
      expect_range_input(input, range.length)
      self.begin_selection(copy_zip_input(input), range.offset)
    }
    DirectoryProbe(reading) => {
      expect_range_input(input, 4)
      guard input is [u32le(CENTRAL_HEADER_SIG)] else {
        raise ZipError(
          InvalidSignature,
          "zip: invalid central header signature",
        )
      }
      self.after_directory_probe(reading)
    }
    Locator(classic) => {
      expect_range_input(input, 20)
      if !(input is [u32le(ZIP64_LOCATOR_SIG), ..]) &&
        classic.central_size != MAX_U32 &&
        classic.central_offset != MAX_U32 {
        return self.begin_classic_records(classic)
      }
      guard input
        is [u32le(ZIP64_LOCATOR_SIG), u32le(disk), u64le(offset), u32le(disks)] else {
        return self.begin_classic_records(classic)
      }
      guard disk == 0 && disks == 1 else {
        return self.begin_classic_records(classic)
      }
      let locator = classic.offset - 20UL
      self.zip64_declared = offset
      guard offset <= locator && 56UL <= locator - offset else {
        return self.probe_zip64(classic)
      }
      self.phase = Zip64(classic, offset)
      NeedRead({ offset, length: 56, })
    }
    Zip64Probe(classic) => {
      expect_range_input(input, 56)
      let offset = classic.offset - 76UL
      let (entries, size, central) = checked_zip64_end(
        input,
        offset,
        classic.offset - 20UL,
        self.zip64_declared,
      ) catch {
        _ => return self.begin_classic_records(classic)
      }
      self.begin_zip64_records(
        classic,
        offset,
        entries,
        size,
        central,
        fallback=true,
      )
    }
    Zip64(classic, offset) => {
      expect_range_input(input, 56)
      let (entries, size, central) = checked_zip64_end(
        input,
        offset,
        classic.offset - 20UL,
        self.zip64_declared,
      ) catch {
        _ => return self.probe_zip64(classic)
      }
      self.begin_zip64_records(classic, offset, entries, size, central)
    }
    Records(bounds, offset) => {
      let end = bounds.offset + bounds.size
      let length = range_read_length(end - offset, DIRECTORY_CHUNK_SIZE)
      expect_range_input(input, length)
      let bytes : BytesView = if self.pending.length() == 0 {
        input
      } else {
        self.pending + input.to_owned()
      }
      let mut position = 0
      // Variable-length sizes sit at offset 28 of each 46-byte fixed header.
      while self.entries.length().to_uint64() < bounds.entries &&
            bytes.length() - position >= 46 &&
            bytes[position + 28:]
            is [u16le(name_size), u16le(extra_size), u16le(comment_size), ..] {
        let record_size = 46 +
          (name_size + extra_size + comment_size).reinterpret_as_int()
        guard record_size <= bytes.length() - position else { break }
        let parsed = parse_directory_record(
          Cursor(bytes[position:position + record_size], 0),
        )
        let raw = parsed.entry
        guard raw.local_offset <= bounds.offset - self.offset_gap else {
          raise ZipError(Truncated, "zip: local offset out of bounds")
        }
        let entry = { ..raw, local_offset: raw.local_offset + self.offset_gap, }
        // Local variable-length headers are deferred; their fixed prefix and
        // declared payload must at least fit before the central directory.
        guard entry.local_offset <= bounds.offset &&
          30UL <= bounds.offset - entry.local_offset &&
          entry.compressed_size <= bounds.offset - entry.local_offset - 30UL else {
          raise ZipError(
            Truncated,
            "zip: local record or payload out of bounds",
          )
        }
        self.entries.push(entry)
        position += record_size
      }
      let next = offset + length.to_uint64()
      let entries_done = self.entries.length().to_uint64() == bounds.entries
      if entries_done {
        validate_directory_signature(
          bytes[position:],
          end - next + (bytes.length() - position).to_uint64(),
        )
      }
      if next == end {
        guard entries_done else {
          raise ZipError(
            UnsupportedFeature,
            "zip: central directory size/count mismatch",
          )
        }
        self.complete(bounds.comment, bounds.offset)
      } else {
        self.pending = copy_zip_input(bytes[position:])
        self.phase = Records(bounds, next)
        NeedRead({
          offset: next,
          length: range_read_length(end - next, DIRECTORY_CHUNK_SIZE),
        })
      }
    }
    Complete(directory) => {
      expect_range_input(input, 0)
      Done(directory)
    }
    Failed(kind, message) => raise ZipError(kind, message)
  }
}

///|
fn DirectoryReader::begin_classic_records(
  self : DirectoryReader,
  classic : ClassicDirectoryEnd,
) -> DirectoryStep raise ZipError {
  self.selected_zip64 = None
  self.entries = []
  self.pending = b""
  guard classic.disk_entries == classic.entries else {
    raise ZipError(
      UnsupportedFeature,
      "zip: multi-disk archives are not supported",
    )
  }
  self.begin_records(
    classic.central_offset.to_uint64(),
    classic.central_size.to_uint64(),
    classic.entries.to_uint64(),
    classic.offset,
  )
}

///|
/// Try the physical SFX position only after the locator's own target failed.
fn DirectoryReader::probe_zip64(
  self : DirectoryReader,
  classic : ClassicDirectoryEnd,
) -> DirectoryStep raise ZipError {
  guard classic.offset >= 76UL && self.zip64_declared != classic.offset - 76UL else {
    return self.begin_classic_records(classic)
  }
  self.phase = Zip64Probe(classic)
  NeedRead({ offset: classic.offset - 76UL, length: 56, })
}

///|
fn DirectoryReader::begin_zip64_records(
  self : DirectoryReader,
  classic : ClassicDirectoryEnd,
  offset : UInt64,
  entries : UInt64,
  central_size : UInt64,
  central_offset : UInt64,
  fallback~ : Bool = false,
) -> DirectoryStep raise ZipError {
  check_zip64_classic(
    classic.disk_entries,
    classic.entries,
    classic.central_size,
    classic.central_offset,
    entries,
    central_size,
    central_offset,
  ) catch {
    _ => {
      if fallback {
        return self.begin_classic_records(classic)
      }
      return self.probe_zip64(classic)
    }
  }
  self.selected_zip64 = Some(offset)
  self.begin_records(central_offset, central_size, entries, offset)
}

///|
/// The central directory may end with one digital-signature record. Validate
/// its framing only, not the signature itself. `remaining` includes bytes in
/// this chunk and later chunks; the 16-bit size bounds retained input even when
/// the header straddles reads or an untrusted directory declares a huge tail.
fn validate_directory_signature(
  bytes : BytesView,
  remaining : UInt64,
) -> Unit raise ZipError {
  guard remaining != 0UL else { return }
  guard remaining >= 6UL && remaining <= 65541UL else {
    raise ZipError(UnsupportedFeature, "zip: invalid directory signature size")
  }
  if bytes is [u32le(signature), ..] {
    guard signature == DIRECTORY_SIGNATURE_SIG else {
      raise ZipError(InvalidSignature, "zip: invalid directory signature")
    }
  }
  if bytes is [u32le(_), u16le(size), ..] {
    guard 6UL + size.to_uint64() == remaining else {
      raise ZipError(
        UnsupportedFeature,
        "zip: directory signature size mismatch",
      )
    }
  }
}

///|
fn DirectoryReader::begin_records(
  self : DirectoryReader,
  offset : UInt64,
  size : UInt64,
  entries : UInt64,
  boundary : UInt64,
) -> DirectoryStep raise ZipError {
  guard offset <= boundary && size <= boundary - offset else {
    raise ZipError(Truncated, "zip: central directory out of bounds")
  }
  let reading = {
    classic: self.selected_end.unwrap(),
    zip64: self.selected_zip64,
    offset,
    size,
    entries,
    boundary,
  }
  // Every new reading, including a post-selection classic retry, must satisfy
  // the tier's structural probe before full parsing or limits can accept it.
  if entries == 0UL && size == 0UL {
    guard offset == boundary else {
      raise ZipError(
        UnsupportedFeature,
        "zip: empty directory has a prefix gap",
      )
    }
    return self.after_directory_probe(reading)
  }
  guard size >= 4UL else {
    raise ZipError(
      Truncated,
      "zip: central directory cannot hold its signature",
    )
  }
  self.phase = DirectoryProbe(reading)
  NeedRead({ offset: boundary - size, length: 4, })
}

///|
/// Parse only a reading that passed the shared signature/empty-gap probe.
fn DirectoryReader::begin_validated_records(
  self : DirectoryReader,
  reading : DirectoryReading,
) -> DirectoryStep raise ZipError {
  let { offset, size, entries, boundary, .. } = reading
  self.offset_gap = boundary - size - offset
  let offset = boundary - size
  self.selected_size = size
  guard entries <= 0x7fff_ffffUL else {
    raise ZipError(
      UnsupportedFeature,
      "zip: directory count exceeds in-memory capacity",
    )
  }
  guard entries <= size / 46UL else {
    raise ZipError(
      Truncated,
      "zip: central directory entry count exceeds its size",
    )
  }
  let comment = copy_zip_input(reading.classic.comment)
  guard size != 0UL else { return self.complete(comment, offset) }
  let bounds = { offset, size, entries, comment, }
  self.phase = Records(bounds, offset)
  NeedRead({ offset, length: range_read_length(size, DIRECTORY_CHUNK_SIZE), })
}

///|
fn DirectoryReader::complete(
  self : DirectoryReader,
  comment : Bytes,
  central_offset : UInt64,
) -> DirectoryStep raise ZipError {
  let order = Array::makei(self.entries.length(), i => i)
  order.sort_by((a, b) => {
    self.entries[a].local_offset.compare(self.entries[b].local_offset)
  })
  let record_ends = Array::make(self.entries.length(), central_offset)
  for i, index in order {
    let entry = self.entries[index]
    let end = if i + 1 < order.length() {
      self.entries[order[i + 1]].local_offset
    } else {
      central_offset
    }
    guard entry.local_offset <= end &&
      30UL <= end - entry.local_offset &&
      entry.compressed_size <= end - entry.local_offset - 30UL else {
      raise ZipError(
        UnsupportedFeature,
        "zip: shared or overlapping local records",
      )
    }
    record_ends[index] = end
  }
  // Limits do not decide between ZIP64 and classic. Only a directory that
  // passed framing, counts and extents is the chosen reading.
  check_directory_limit(
    DirectoryBytes,
    self.limits.max_directory_bytes,
    self.selected_size,
  )
  check_directory_limit(
    Entries,
    self.limits.max_entries,
    self.entries.length().to_uint64(),
  )
  let directory = {
    entries: self.entries,
    comment,
    central_offset,
    record_ends,
  }
  self.entries = []
  self.pending = b""
  self.selected_end = self.selected_end.map(end => { ..end, comment: b""[:], })
  self.phase = Complete(directory)
  Done(directory)
}