ziperu 0.1.1

data/ext/ziperu/src/archive.rs

@@ -0,0 +1,713 @@
+//! `Ziperu::Native::Archive`: a read-only handle on a parsed central directory.
+//!
+//! Entry metadata crosses the Ruby boundary as plain Hashes (all at once via
+//! `entries`, or one at a time via `entry_meta`); afterwards Ruby only talks
+//! to the archive by index.
+
+use std::cell::{RefCell, RefMut};
+use std::collections::HashMap;
+use std::fs;
+use std::io::{self, Read, Seek, SeekFrom};
+
+use magnus::{
+    gc::Marker, typed_data::DataTypeFunctions, value::Opaque, Error, RArray, RHash, RString, Ruby,
+    Symbol, TypedData, Value,
+};
+use zip::read::{read_zipfile_from_stream_with_options, ZipFileEntry, ZipReadOptions};
+use zip::result::{ZipError, ZipResult};
+use zip::ZipArchive;
+
+use crate::errors::{busy_error, io_error, read_error, zip_error};
+use crate::gvl::maybe_without_gvl;
+use crate::reader::{EntryInfo, EntryReader};
+use crate::source::Source;
+
+/// Never pre-allocate more than this on the strength of a header field.
+const CAPACITY_HINT_MAX: u64 = 1 << 20;
+
+#[derive(TypedData)]
+#[magnus(class = "Ziperu::Native::Archive", free_immediately, mark)]
+pub struct Archive {
+    // Borrowed only while holding the GVL and never across a release of it
+    // (work that releases the GVL runs on a clone), so a failed borrow
+    // means another thread is inside a method right now. `None` once
+    // closed, which releases the file handle at once rather than when the
+    // GC gets round to it (commit renames over the file).
+    inner: RefCell<Option<ZipArchive<Source>>>,
+    /// The Ruby IO behind a `Source::Ruby`, kept alive by `mark`.
+    io: Option<Opaque<Value>>,
+    /// True for a Ruby IO source, whose reads must hold the GVL.
+    needs_gvl: bool,
+}
+
+impl DataTypeFunctions for Archive {
+    fn mark(&self, marker: &Marker) {
+        if let Some(io) = self.io {
+            marker.mark(io);
+        }
+    }
+}
+
+impl Archive {
+    pub fn open_path(ruby: &Ruby, path: String) -> Result<Self, Error> {
+        let file = fs::File::open(&path).map_err(|e| io_error(ruby, e))?;
+        Self::from_source(ruby, Source::file(file))
+    }
+
+    pub fn open_bytes(ruby: &Ruby, bytes: RString) -> Result<Self, Error> {
+        // Copy once; the Ruby string may be mutated or GC'd after this call.
+        let vec = unsafe { bytes.as_slice() }.to_vec();
+        Self::from_source(ruby, Source::memory(vec))
+    }
+
+    /// Any seekable IO-like Ruby object; read lazily, never copied.
+    pub fn open_io(ruby: &Ruby, io: Value) -> Result<Self, Error> {
+        Self::from_source(ruby, Source::ruby(io)?)
+    }
+
+    fn from_source(ruby: &Ruby, source: Source) -> Result<Self, Error> {
+        let needs_gvl = source.needs_gvl();
+        let io = source.ruby_io();
+        let archive = maybe_without_gvl(needs_gvl, || ZipArchive::new(source))
+            .map_err(|e| zip_error(ruby, e))?;
+        Ok(Self {
+            inner: RefCell::new(Some(archive)),
+            io,
+            needs_gvl,
+        })
+    }
+
+    pub(crate) fn needs_gvl(&self) -> bool {
+        self.needs_gvl
+    }
+
+    /// The open archive, or an IOError once closed.
+    pub(crate) fn archive(&self, ruby: &Ruby) -> Result<RefMut<'_, ZipArchive<Source>>, Error> {
+        let guard = self
+            .inner
+            .try_borrow_mut()
+            .map_err(|_| busy_error(ruby, "archive"))?;
+        RefMut::filter_map(guard, Option::as_mut)
+            .map_err(|_| Error::new(ruby.exception_io_error(), "closed archive"))
+    }
+
+    /// Releases the underlying file. Readers already opened keep their own
+    /// handle and continue to work.
+    pub fn close(ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
+        rb_self
+            .inner
+            .try_borrow_mut()
+            .map_err(|_| busy_error(ruby, "archive"))?
+            .take();
+        Ok(())
+    }
+
+    pub fn is_closed(&self) -> bool {
+        self.inner.try_borrow().is_ok_and(|a| a.is_none())
+    }
+
+    pub fn entry_count(ruby: &Ruby, rb_self: &Self) -> Result<usize, Error> {
+        Ok(rb_self.archive(ruby)?.len())
+    }
+
+    pub fn comment(ruby: &Ruby, rb_self: &Self) -> Result<RString, Error> {
+        Ok(ruby.str_from_slice(rb_self.archive(ruby)?.comment()))
+    }
+
+    /// True when the central directory holds several records under one
+    /// name. The crate keys its parsed view by name and so keeps only the
+    /// last of them; `entries` then walks the raw records instead.
+    pub fn has_duplicate_names(ruby: &Ruby, rb_self: &Self) -> Result<bool, Error> {
+        Ok(rb_self.archive(ruby)?.has_duplicate_names())
+    }
+
+    /// Sum of the declared uncompressed sizes, for `Ziperu.max_total_size`.
+    pub fn total_size(ruby: &Ruby, rb_self: &Self) -> Result<u64, Error> {
+        let archive = rb_self.archive(ruby)?;
+        let meta = archive.metadata();
+        let mut total: u64 = 0;
+        for i in 0..meta.len() {
+            total = total.saturating_add(meta.entry(i).map_err(|e| zip_error(ruby, e))?.size());
+        }
+        Ok(total)
+    }
+
+    /// Inflates entry `index` to nowhere so the crate checks its CRC (and
+    /// its declared size), with the GVL released when the source allows.
+    pub fn verify_entry(
+        ruby: &Ruby,
+        rb_self: &Self,
+        index: usize,
+        password: Option<RString>,
+    ) -> Result<(), Error> {
+        let password = password.map(|p| unsafe { p.as_slice() }.to_vec());
+        let mut archive = rb_self.archive(ruby)?.clone();
+        maybe_without_gvl(rb_self.needs_gvl, || {
+            let options = ZipReadOptions::new().password(password.as_deref());
+            let mut entry = archive.by_index_with_options(index, options)?;
+            io::copy(&mut entry, &mut io::sink())?;
+            Ok::<_, ZipError>(())
+        })
+        .map_err(|e| match e {
+            ZipError::Io(io) => read_error(ruby, io),
+            other => zip_error(ruby, other),
+        })
+    }
+
+    /// `verify_entry` for a record the crate cannot address by index (one
+    /// of several under the same name): the entry is read from its local
+    /// header with the central record's sizes and CRC, as `open_entry_at`
+    /// reads it.
+    pub fn verify_entry_at(
+        ruby: &Ruby,
+        rb_self: &Self,
+        header_offset: u64,
+        size: u64,
+        compressed_size: u64,
+        crc: u32,
+        password: Option<RString>,
+    ) -> Result<(), Error> {
+        let password = password.map(|p| unsafe { p.as_slice() }.to_vec());
+        let mut source = rb_self.archive(ruby)?.clone().into_inner();
+        maybe_without_gvl(rb_self.needs_gvl, || {
+            source.seek(SeekFrom::Start(header_offset))?;
+            let options = ZipReadOptions::new()
+                .password(password.as_deref())
+                .override_compressed_size(compressed_size)
+                .override_uncompressed_size(size)
+                .override_crc(crc);
+            let mut entry = read_zipfile_from_stream_with_options(&mut source, options)?.ok_or(
+                ZipError::InvalidArchive("expected a local file header".into()),
+            )?;
+            io::copy(&mut entry, &mut io::sink())?;
+            Ok::<_, ZipError>(())
+        })
+        .map_err(|e| match e {
+            ZipError::Io(io) => read_error(ruby, io),
+            other => zip_error(ruby, other),
+        })
+    }
+
+    /// One Hash per entry, in central-directory order.
+    ///
+    /// The parsed central directory already holds nearly everything; the
+    /// few fields read raw come from one sequential pass over the records,
+    /// done without the GVL when the source allows it. An archive with
+    /// several records under one name is listed from the raw records
+    /// alone, since the crate's view keeps only the last of each name: a
+    /// record the crate still addresses carries its index, the others nil.
+    pub fn entries(ruby: &Ruby, rb_self: &Self) -> Result<RArray, Error> {
+        let archive = rb_self.archive(ruby)?;
+        let meta = archive.metadata();
+        let duplicates = archive.has_duplicate_names();
+        let dir_start = archive.central_directory_start();
+        let archive_offset = archive.offset();
+        let mut raw = archive.clone().into_inner();
+        drop(archive);
+        let keys = MetaKeys::new(ruby);
+
+        if duplicates {
+            let records = maybe_without_gvl(rb_self.needs_gvl, || {
+                walk_central_directory(&mut raw, dir_start)
+            })
+            .map_err(|e| io_error(ruby, e))?;
+            let mut by_offset = HashMap::with_capacity(meta.len());
+            for i in 0..meta.len() {
+                let entry = meta.entry(i).map_err(|e| zip_error(ruby, e))?;
+                by_offset.insert(entry.central_header_start(), i);
+            }
+            let out = ruby.ary_new_capa(records.len());
+            for record in &records {
+                let index = by_offset.get(&record.central_offset).copied();
+                out.push(record_hash(ruby, &keys, index, record, archive_offset)?)?;
+            }
+            return Ok(out);
+        }
+
+        let records = maybe_without_gvl(rb_self.needs_gvl, || {
+            (0..meta.len())
+                .map(|i| {
+                    let entry = meta.entry(i)?;
+                    Ok(raw_central_record(&mut raw, entry.central_header_start())?)
+                })
+                .collect::<ZipResult<Vec<_>>>()
+        })
+        .map_err(|e| zip_error(ruby, e))?;
+        let out = ruby.ary_new_capa(meta.len());
+        for (i, record) in records.iter().enumerate() {
+            let entry = meta.entry(i).map_err(|e| zip_error(ruby, e))?;
+            out.push(entry_hash(ruby, &keys, i, &entry, record)?)?;
+        }
+        Ok(out)
+    }
+
+    /// The Hash for a single entry.
+    pub fn entry_meta(ruby: &Ruby, rb_self: &Self, index: usize) -> Result<RHash, Error> {
+        let archive = rb_self.archive(ruby)?;
+        let meta = archive.metadata();
+        let mut raw = archive.clone().into_inner();
+        drop(archive);
+        let entry = meta.entry(index).map_err(|e| zip_error(ruby, e))?;
+        let record = raw_central_record(&mut raw, entry.central_header_start())
+            .map_err(|e| io_error(ruby, e))?;
+        entry_hash(ruby, &MetaKeys::new(ruby), index, &entry, &record)
+    }
+
+    /// The raw extra field bytes of entry `index`'s local header. Some
+    /// fields (Info-ZIP unix uid/gid, extended timestamp atime/ctime) only
+    /// carry their data there; Ruby merges them lazily.
+    pub fn local_extra(ruby: &Ruby, rb_self: &Self, index: usize) -> Result<RString, Error> {
+        let archive = rb_self.archive(ruby)?;
+        let header_start = archive
+            .metadata()
+            .entry(index)
+            .map_err(|e| zip_error(ruby, e))?
+            .header_start();
+        let mut raw = archive.clone().into_inner();
+        drop(archive);
+        let extra = raw_local_extra(&mut raw, header_start).map_err(|e| io_error(ruby, e))?;
+        Ok(ruby.str_from_slice(&extra))
+    }
+
+    /// `local_extra` for a record addressed by its local header offset.
+    pub fn local_extra_at(
+        ruby: &Ruby,
+        rb_self: &Self,
+        header_offset: u64,
+    ) -> Result<RString, Error> {
+        let mut raw = rb_self.archive(ruby)?.clone().into_inner();
+        let extra = raw_local_extra(&mut raw, header_offset).map_err(|e| io_error(ruby, e))?;
+        Ok(ruby.str_from_slice(&extra))
+    }
+
+    /// A chunked reader over entry `index`, with its own cursor. With
+    /// `enforce_size` false it reads past the declared size to the true end
+    /// of the data.
+    pub fn open_entry(
+        ruby: &Ruby,
+        rb_self: &Self,
+        index: usize,
+        password: Option<RString>,
+        enforce_size: bool,
+    ) -> Result<EntryReader, Error> {
+        let password = password.map(|p| unsafe { p.as_slice() }.to_vec());
+        let archive = rb_self.archive(ruby)?.clone();
+        EntryReader::open(
+            ruby,
+            archive,
+            index,
+            password,
+            enforce_size,
+            rb_self.needs_gvl,
+            rb_self.io,
+        )
+    }
+
+    /// `open_entry` for a record the crate cannot address by index: the
+    /// entry is read from its local header, with the sizes and CRC of its
+    /// central record standing in for whatever the local header lacks.
+    #[allow(clippy::too_many_arguments)]
+    pub fn open_entry_at(
+        ruby: &Ruby,
+        rb_self: &Self,
+        header_offset: u64,
+        size: u64,
+        compressed_size: u64,
+        crc: u32,
+        password: Option<RString>,
+        enforce_size: bool,
+    ) -> Result<EntryReader, Error> {
+        let password = password.map(|p| unsafe { p.as_slice() }.to_vec());
+        let archive = rb_self.archive(ruby)?.clone();
+        let info = EntryInfo {
+            index: None,
+            header_start: header_offset,
+            size,
+            compressed_size,
+            crc32: crc,
+        };
+        EntryReader::open_at(
+            ruby,
+            archive,
+            info,
+            password,
+            enforce_size,
+            rb_self.needs_gvl,
+            rb_self.io,
+        )
+    }
+
+    /// Whole decompressed entry as a binary String.
+    pub fn read_entry(ruby: &Ruby, rb_self: &Self, index: usize) -> Result<RString, Error> {
+        // A clone (the central directory is shared behind an Arc) so the
+        // borrow is released before the GVL is.
+        let mut archive = rb_self.archive(ruby)?.clone();
+        let mut entry = archive.by_index(index).map_err(|e| zip_error(ruby, e))?;
+        // A hint only: the declared size is untrusted and may be a lie.
+        let mut buf = Vec::with_capacity(entry.size().min(CAPACITY_HINT_MAX) as usize);
+        maybe_without_gvl(rb_self.needs_gvl, || entry.read_to_end(&mut buf))
+            .map_err(|e| read_error(ruby, e))?;
+        Ok(ruby.str_from_slice(&buf))
+    }
+
+    /// Extracts entries to `dest` in one call; see `extract::extract_entries`.
+    pub fn extract_entries(
+        ruby: &Ruby,
+        rb_self: &Self,
+        dest: String,
+        specs: RArray,
+        enforce_size: bool,
+    ) -> Result<RArray, Error> {
+        let archive = rb_self.archive(ruby)?.clone();
+        crate::extract::extract_entries(ruby, archive, rb_self.needs_gvl, dest, specs, enforce_size)
+    }
+}
+
+/// A central directory record read straight from the bytes.
+///
+/// Two fields are read this way for every entry, where the crate's parsed
+/// view is not what rubyzip exposes: the extra field exactly as stored
+/// (the crate re-serializes the fields it parsed, which drops some, an
+/// extended timestamp without the local-only parts for one), and the DOS
+/// time and date as stored (the crate's `DateTime` rejects values a
+/// calendar would roll over, February 30th, which rubyzip reads as the
+/// next day). The rest only matters for a record the crate does not keep.
+struct RawCentralRecord {
+    /// Where the record starts, which is how it is matched to the crate's
+    /// `central_header_start`.
+    central_offset: u64,
+    version_made_by: u16,
+    flags: u16,
+    method: u16,
+    dos_time: u16,
+    dos_date: u16,
+    crc32: u32,
+    compressed_size: u64,
+    size: u64,
+    external_attributes: u32,
+    /// As stored: relative to the start of the archive proper, before any
+    /// prepended data.
+    header_offset: u64,
+    name: Vec<u8>,
+    extra: Vec<u8>,
+    comment: Vec<u8>,
+}
+
+const CENTRAL_SIGNATURE: u32 = 0x0201_4b50;
+const CENTRAL_HEADER_LEN: usize = 46;
+const ZIP64_EXTRA_ID: u16 = 0x0001;
+
+/// The record at `central_offset`.
+fn raw_central_record(source: &mut Source, central_offset: u64) -> io::Result<RawCentralRecord> {
+    source.seek_to(central_offset)?;
+    read_central_record(source, central_offset)?.ok_or_else(|| {
+        io::Error::new(
+            io::ErrorKind::InvalidData,
+            "central directory signature not found",
+        )
+    })
+}
+
+/// Every record from `dir_start` to the end of the central directory.
+fn walk_central_directory(
+    source: &mut Source,
+    dir_start: u64,
+) -> io::Result<Vec<RawCentralRecord>> {
+    source.seek(SeekFrom::Start(dir_start))?;
+    let mut records = Vec::new();
+    let mut offset = dir_start;
+    while let Some(record) = read_central_record(source, offset)? {
+        offset = record.next_offset();
+        records.push(record);
+    }
+    Ok(records)
+}
+
+/// The record at the source's position, or `None` where the central
+/// directory has ended (an end-of-central-directory signature instead).
+fn read_central_record(
+    source: &mut Source,
+    central_offset: u64,
+) -> io::Result<Option<RawCentralRecord>> {
+    // The signature first: what follows the last record (the end of
+    // central directory) is shorter than a record header.
+    let mut header = [0u8; CENTRAL_HEADER_LEN];
+    source.read_exact(&mut header[..4])?;
+    if le_u32(&header[0..4]) != CENTRAL_SIGNATURE {
+        return Ok(None);
+    }
+    source.read_exact(&mut header[4..])?;
+    let name_len = le_u16(&header[28..30]) as usize;
+    let extra_len = le_u16(&header[30..32]) as usize;
+    let comment_len = le_u16(&header[32..34]) as usize;
+    let mut name = vec![0u8; name_len];
+    source.read_exact(&mut name)?;
+    let mut extra = vec![0u8; extra_len];
+    source.read_exact(&mut extra)?;
+    let mut comment = vec![0u8; comment_len];
+    source.read_exact(&mut comment)?;
+
+    let mut record = RawCentralRecord {
+        central_offset,
+        version_made_by: le_u16(&header[4..6]),
+        flags: le_u16(&header[8..10]),
+        method: le_u16(&header[10..12]),
+        dos_time: le_u16(&header[12..14]),
+        dos_date: le_u16(&header[14..16]),
+        crc32: le_u32(&header[16..20]),
+        compressed_size: u64::from(le_u32(&header[20..24])),
+        size: u64::from(le_u32(&header[24..28])),
+        external_attributes: le_u32(&header[38..42]),
+        header_offset: u64::from(le_u32(&header[42..46])),
+        name,
+        extra,
+        comment,
+    };
+    record.apply_zip64();
+    Ok(Some(record))
+}
+
+impl RawCentralRecord {
+    fn next_offset(&self) -> u64 {
+        self.central_offset
+            + (CENTRAL_HEADER_LEN + self.name.len() + self.extra.len() + self.comment.len()) as u64
+    }
+
+    /// A zip64 extra field carries the 64-bit value of each size or
+    /// offset the record stores as 0xFFFFFFFF, in header order.
+    fn apply_zip64(&mut self) {
+        let mut rest = self.extra.as_slice();
+        while rest.len() >= 4 {
+            let id = le_u16(&rest[0..2]);
+            let len = le_u16(&rest[2..4]) as usize;
+            rest = &rest[4..];
+            if rest.len() < len {
+                return;
+            }
+            let (mut data, tail) = rest.split_at(len);
+            rest = tail;
+            if id != ZIP64_EXTRA_ID {
+                continue;
+            }
+            for field in [
+                &mut self.size,
+                &mut self.compressed_size,
+                &mut self.header_offset,
+            ] {
+                if *field != u64::from(u32::MAX) {
+                    continue;
+                }
+                let Some((value, more)) = data.split_first_chunk::<8>() else {
+                    return;
+                };
+                *field = u64::from_le_bytes(*value);
+                data = more;
+            }
+            return;
+        }
+    }
+}
+
+fn le_u16(bytes: &[u8]) -> u16 {
+    u16::from_le_bytes([bytes[0], bytes[1]])
+}
+
+fn le_u32(bytes: &[u8]) -> u32 {
+    u32::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]])
+}
+
+/// The extra field bytes of a local file header, exactly as stored.
+fn raw_local_extra(source: &mut Source, header_offset: u64) -> io::Result<Vec<u8>> {
+    const SIGNATURE: u32 = 0x0403_4b50;
+    const HEADER_LEN: usize = 30;
+
+    source.seek(SeekFrom::Start(header_offset))?;
+    let mut header = [0u8; HEADER_LEN];
+    source.read_exact(&mut header)?;
+    if u32::from_le_bytes([header[0], header[1], header[2], header[3]]) != SIGNATURE {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidData,
+            "local file header signature not found",
+        ));
+    }
+    let name_len = u16::from_le_bytes([header[26], header[27]]) as i64;
+    let extra_len = u16::from_le_bytes([header[28], header[29]]) as usize;
+    source.seek(SeekFrom::Current(name_len))?;
+    let mut extra = vec![0u8; extra_len];
+    source.read_exact(&mut extra)?;
+    Ok(extra)
+}
+
+/// The Hash keys, interned once per listing rather than once per entry.
+struct MetaKeys {
+    index: Symbol,
+    name: Symbol,
+    size: Symbol,
+    compressed_size: Symbol,
+    crc: Symbol,
+    compression_method: Symbol,
+    flags: Symbol,
+    external_attributes: Symbol,
+    fstype: Symbol,
+    version_made_by: Symbol,
+    dos_date: Symbol,
+    dos_time: Symbol,
+    comment: Symbol,
+    extra: Symbol,
+    header_offset: Symbol,
+}
+
+impl MetaKeys {
+    fn new(ruby: &Ruby) -> Self {
+        Self {
+            index: ruby.to_symbol("index"),
+            name: ruby.to_symbol("name"),
+            size: ruby.to_symbol("size"),
+            compressed_size: ruby.to_symbol("compressed_size"),
+            crc: ruby.to_symbol("crc"),
+            compression_method: ruby.to_symbol("compression_method"),
+            flags: ruby.to_symbol("flags"),
+            external_attributes: ruby.to_symbol("external_attributes"),
+            fstype: ruby.to_symbol("fstype"),
+            version_made_by: ruby.to_symbol("version_made_by"),
+            dos_date: ruby.to_symbol("dos_date"),
+            dos_time: ruby.to_symbol("dos_time"),
+            comment: ruby.to_symbol("comment"),
+            extra: ruby.to_symbol("extra"),
+            header_offset: ruby.to_symbol("header_offset"),
+        }
+    }
+}
+
+fn entry_hash(
+    ruby: &Ruby,
+    keys: &MetaKeys,
+    index: usize,
+    entry: &ZipFileEntry<'_>,
+    raw: &RawCentralRecord,
+) -> Result<RHash, Error> {
+    let h = ruby.hash_new();
+    h.aset(keys.index, index)?;
+    h.aset(keys.name, ruby.str_from_slice(entry.name_raw()))?;
+    h.aset(keys.size, entry.size())?;
+    h.aset(keys.compressed_size, entry.compressed_size())?;
+    h.aset(keys.crc, entry.crc32())?;
+    h.aset(
+        keys.compression_method,
+        compression_code(entry.compression()),
+    )?;
+    h.aset(keys.flags, entry.flags().as_u16())?;
+    h.aset(keys.external_attributes, entry.external_attributes())?;
+    // "Version made by": high byte is the host system, low byte the spec
+    // version; rubyzip keeps them as fstype / version.
+    h.aset(keys.fstype, u8::from(entry.system()))?;
+    let (major, minor) = entry.version_made_by();
+    h.aset(keys.version_made_by, major * 10 + minor)?;
+    h.aset(keys.dos_date, raw.dos_date)?;
+    h.aset(keys.dos_time, raw.dos_time)?;
+    h.aset(
+        keys.comment,
+        ruby.str_from_slice(entry.comment().as_bytes()),
+    )?;
+    h.aset(keys.extra, ruby.str_from_slice(&raw.extra))?;
+    h.aset(keys.header_offset, entry.header_start())?;
+    Ok(h)
+}
+
+/// `entry_hash` from the raw record alone, for an archive the crate's
+/// parsed view does not cover; `index` is nil for a record it dropped.
+fn record_hash(
+    ruby: &Ruby,
+    keys: &MetaKeys,
+    index: Option<usize>,
+    record: &RawCentralRecord,
+    archive_offset: u64,
+) -> Result<RHash, Error> {
+    let h = ruby.hash_new();
+    h.aset(keys.index, index)?;
+    h.aset(keys.name, ruby.str_from_slice(&record.name))?;
+    h.aset(keys.size, record.size)?;
+    h.aset(keys.compressed_size, record.compressed_size)?;
+    h.aset(keys.crc, record.crc32)?;
+    h.aset(keys.compression_method, record.method)?;
+    h.aset(keys.flags, record.flags)?;
+    h.aset(keys.external_attributes, record.external_attributes)?;
+    h.aset(keys.fstype, (record.version_made_by >> 8) as u8)?;
+    h.aset(keys.version_made_by, record.version_made_by & 0xFF)?;
+    h.aset(keys.dos_date, record.dos_date)?;
+    h.aset(keys.dos_time, record.dos_time)?;
+    h.aset(keys.comment, ruby.str_from_slice(&record.comment))?;
+    h.aset(keys.extra, ruby.str_from_slice(&record.extra))?;
+    h.aset(
+        keys.header_offset,
+        record.header_offset.saturating_add(archive_offset),
+    )?;
+    Ok(h)
+}
+
+/// The on-disk compression method code, as rubyzip exposes it.
+///
+/// `to_u16` is deprecated in favour of matching on constants, but it is the
+/// only public way to recover the raw code, which is what we hand to Ruby.
+#[allow(deprecated)]
+fn compression_code(method: zip::CompressionMethod) -> u16 {
+    method.to_u16()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn record(
+        size: u64,
+        compressed_size: u64,
+        header_offset: u64,
+        extra: Vec<u8>,
+    ) -> RawCentralRecord {
+        RawCentralRecord {
+            central_offset: 0,
+            version_made_by: 0,
+            flags: 0,
+            method: 0,
+            dos_time: 0,
+            dos_date: 0,
+            crc32: 0,
+            compressed_size,
+            size,
+            external_attributes: 0,
+            header_offset,
+            name: Vec::new(),
+            extra,
+            comment: Vec::new(),
+        }
+    }
+
+    fn zip64(values: &[u64]) -> Vec<u8> {
+        let mut extra = vec![0x01, 0x00, (values.len() * 8) as u8, 0x00];
+        for v in values {
+            extra.extend_from_slice(&v.to_le_bytes());
+        }
+        extra
+    }
+
+    #[test]
+    fn zip64_fills_only_the_saturated_fields_in_order() {
+        let max = u64::from(u32::MAX);
+        let mut r = record(max, 7, max, zip64(&[1 << 33, 1 << 40]));
+        r.apply_zip64();
+        assert_eq!(
+            (r.size, r.compressed_size, r.header_offset),
+            (1 << 33, 7, 1 << 40)
+        );
+    }
+
+    #[test]
+    fn zip64_is_found_after_other_fields_and_tolerates_short_data() {
+        let max = u64::from(u32::MAX);
+        let mut extra = vec![0x55, 0x54, 0x01, 0x00, 0x03]; // an extended timestamp first
+        extra.extend(zip64(&[42]));
+        let mut r = record(max, max, 5, extra);
+        r.apply_zip64();
+        assert_eq!((r.size, r.compressed_size, r.header_offset), (42, max, 5));
+    }
+}