Skip to main content

grit_lib/bundle/
core.rs

1//! Git bundle format ([gitformat-bundle](https://git-scm.com/docs/gitformat-bundle)).
2//!
3//! Bundles combine a text header (signature, optional v3 capabilities, prerequisite
4//! commits, ref tips) with a thin packfile. This module reads and writes that format,
5//! verifies prerequisite connectivity against a local repository, and ingests the pack
6//! without updating refs (callers apply [`BundleHeader::refs`] themselves).
7
8use crate::error::ObjectError;
9use std::collections::{HashMap, HashSet, VecDeque};
10use std::fs::File;
11use std::io::{BufRead, Read, Seek, Write};
12use std::path::{Path, PathBuf};
13
14use thiserror::Error;
15
16use crate::commit_pretty::message_subject;
17use crate::connectivity::bundle_prerequisites_connected_to_refs;
18use crate::error::{Error, Result};
19use crate::index_pack::{ingest_received_pack_path_with_progress, IngestPackOptions};
20use crate::objects::{parse_commit, HashAlgo, ObjectId, ObjectKind};
21use crate::odb::Odb;
22use crate::pack_objects::PackStats;
23use crate::progress::{NullProgress, ProgressPhase, ProgressSink, ProgressUnit};
24use crate::repo::Repository;
25use crate::rev_list::{
26    FilterObjectKind, MissingAction, ObjectFilter, RevListOptions, RevListResult,
27};
28use crate::transfer::{build_pack_from_send_list, reachable_closure, PackBuildOptions};
29
30const V2_SIGNATURE: &str = "# v2 git bundle\n";
31const V3_SIGNATURE: &str = "# v3 git bundle\n";
32
33/// Supported on-disk bundle header versions.
34#[derive(Debug, Clone, Copy, PartialEq, Eq)]
35pub enum BundleVersion {
36    /// Legacy header (SHA-1 repositories without filter capabilities).
37    V2,
38    /// Capabilities for object format and partial-clone filter.
39    V3,
40}
41
42/// Wire filter specification carried in v3 `@filter=` capabilities.
43#[derive(Debug, Clone, PartialEq, Eq)]
44pub struct FilterSpec(ObjectFilter);
45
46impl FilterSpec {
47    /// Parse a filter capability value (same grammar as `--filter=` on fetch).
48    ///
49    /// # Errors
50    ///
51    /// Returns [`BundleError::InvalidFilter`] when the spec is invalid.
52    pub fn parse(spec: &str) -> std::result::Result<Self, BundleError> {
53        Ok(Self(ObjectFilter::parse(spec)?))
54    }
55
56    /// Borrow the parsed filter.
57    #[must_use]
58    pub fn as_filter(&self) -> &ObjectFilter {
59        &self.0
60    }
61
62    /// Serialize for an `@filter=` capability line (percent-encoding when needed).
63    #[must_use]
64    pub fn to_capability_value(&self) -> String {
65        filter_to_capability_value(&self.0)
66    }
67}
68
69/// Parsed bundle header (everything before the `PACK` stream).
70#[derive(Debug, Clone, PartialEq, Eq)]
71pub struct BundleHeader {
72    /// Header version (`2` or `3`).
73    pub version: BundleVersion,
74    /// Object hash used in the pack and OID lines.
75    pub object_format: HashAlgo,
76    /// Partial-clone filter advertised by the bundle (v3 only).
77    pub filter: Option<FilterSpec>,
78    /// Prerequisite commits that must already exist (`-oid` lines).
79    pub prerequisites: Vec<(ObjectId, Option<String>)>,
80    /// Ref tips included in the pack (`oid refname` lines).
81    pub refs: Vec<(String, ObjectId)>,
82}
83
84/// A single ref entry returned from [`Bundle::unbundle`].
85#[derive(Debug, Clone, PartialEq, Eq)]
86pub struct UnbundledRef {
87    /// Full ref name (e.g. `refs/heads/main`).
88    pub name: String,
89    /// Tip object id.
90    pub oid: ObjectId,
91}
92
93/// Result of ingesting a bundle's embedded pack into a repository.
94#[derive(Debug, Clone, PartialEq, Eq)]
95pub struct UnbundleOutcome {
96    /// Ref tips from the bundle header (refs are not updated on disk by unbundle).
97    pub refs: Vec<UnbundledRef>,
98    /// Objects and bytes installed from the bundle pack.
99    pub transfer: crate::transfer::TransferStats,
100    /// Object ids indexed from the installed pack.
101    pub pack_object_ids: HashSet<ObjectId>,
102}
103
104/// Outcome of [`Bundle::verify`].
105#[derive(Debug, Clone, Default, PartialEq, Eq)]
106pub struct BundleVerifyReport {
107    /// Prerequisites missing from the object database.
108    pub missing_prerequisites: Vec<(ObjectId, Option<String>)>,
109    /// Prerequisites exist as objects but their exclusive history is incomplete in the ODB (not
110    /// ref-reachable and not a fully readable dangling graph).
111    pub prerequisites_not_connected: bool,
112}
113
114impl BundleVerifyReport {
115    /// Whether verification succeeded with no issues.
116    #[must_use]
117    pub fn is_ok(&self) -> bool {
118        self.missing_prerequisites.is_empty() && !self.prerequisites_not_connected
119    }
120
121    /// Convert validation failures into a [`BundleError`].
122    ///
123    /// Returns `Ok(())` when [`Self::is_ok`].
124    ///
125    /// # Errors
126    ///
127    /// Returns missing prerequisites, or [`BundleError::PrerequisitesNotConnected`].
128    pub fn into_result(self) -> std::result::Result<(), BundleError> {
129        if !self.missing_prerequisites.is_empty() {
130            return Err(BundleError::MissingPrerequisites {
131                commits: self.missing_prerequisites,
132            });
133        }
134        if self.prerequisites_not_connected {
135            return Err(BundleError::PrerequisitesNotConnected);
136        }
137        Ok(())
138    }
139}
140
141/// Bundle read/write/verify failures.
142#[non_exhaustive]
143#[derive(Debug, Error, Clone, PartialEq, Eq)]
144pub enum BundleError {
145    /// The file does not begin with a v2/v3 bundle signature.
146    #[error("not a v2 or v3 git bundle")]
147    BadSignature,
148    /// Only versions 2 and 3 are supported.
149    #[error("unsupported bundle version")]
150    UnsupportedVersion,
151    /// A v3 `@` capability was not recognized.
152    #[error("unknown bundle capability: {capability}")]
153    UnsupportedCapability {
154        /// The capability as written in the header.
155        capability: String,
156    },
157    /// A header line could not be parsed.
158    #[error("malformed bundle header: {line}")]
159    MalformedLine {
160        /// The header line as written.
161        line: String,
162    },
163    /// Header object format disagrees with the repository.
164    #[error("bundle object format {bundle_name} does not match repository {repo_name}")]
165    ObjectFormatMismatch {
166        /// Format recorded in the bundle header.
167        bundle_name: &'static str,
168        /// Format configured for the open repository.
169        repo_name: &'static str,
170    },
171    /// One or more prerequisite commits are absent from the ODB.
172    #[error("repository lacks these prerequisite commits: {}", format_missing_prerequisite_commits(.commits))]
173    MissingPrerequisites {
174        /// Required commits from the bundle header (oid and optional subject).
175        commits: Vec<(ObjectId, Option<String>)>,
176    },
177    /// Prerequisite objects exist locally but are not ref-reachable and their exclusive history is
178    /// missing commits, trees, or blobs.
179    #[error("prerequisite commits are not connected to local refs")]
180    PrerequisitesNotConnected,
181    /// No ref tips were listed in the header.
182    #[error("bundle contains no refs")]
183    EmptyRefs,
184    /// The pack stream did not start where expected.
185    #[error("bundle pack stream missing or invalid")]
186    MissingPack,
187    /// Underlying I/O failure.
188    #[error("{detail}")]
189    Io {
190        /// What failed, with the path when known.
191        detail: String,
192    },
193    /// A named object id is missing from the ODB.
194    #[error("object not found: {name}")]
195    ObjectNotFound {
196        /// Object id (hex) that was looked up.
197        name: String,
198    },
199    /// A v3 `@filter=` capability is not a filter Git accepts.
200    #[error(transparent)]
201    InvalidFilter(#[from] crate::rev_list::ObjectFilterError),
202    /// Bundle creation was given no revision to include and was not asked for every ref.
203    #[error("at least one revision is required")]
204    NoRevisions,
205    /// The operation was cancelled before the bundle finished unpacking.
206    #[error("operation cancelled")]
207    Cancelled,
208}
209
210impl From<std::io::Error> for BundleError {
211    fn from(e: std::io::Error) -> Self {
212        Self::Io {
213            detail: e.to_string(),
214        }
215    }
216}
217
218fn io_open_path(path: &Path, source: std::io::Error) -> BundleError {
219    BundleError::Io {
220        detail: format!("could not open '{}': {source}", path.display()),
221    }
222}
223
224fn format_missing_prerequisite_commits(commits: &[(ObjectId, Option<String>)]) -> String {
225    commits
226        .iter()
227        .map(|(oid, _)| oid.to_hex())
228        .collect::<Vec<_>>()
229        .join(" ")
230}
231
232impl BundleError {
233    /// Whether the bundle operation was cancelled.
234    #[must_use]
235    pub fn is_cancelled(&self) -> bool {
236        matches!(self, Self::Cancelled)
237    }
238}
239
240/// Input for [`write_bundle`].
241#[derive(Debug, Clone, Default)]
242pub struct BundleSpec {
243    /// Tips to include (`oid` + ref name for the header).
244    pub include: Vec<(ObjectId, String)>,
245    /// Commits treated as already present (incremental bundles).
246    pub exclude: Vec<ObjectId>,
247    /// Optional partial-clone filter (forces v3).
248    pub filter: Option<FilterSpec>,
249}
250
251/// One ref tip that would appear in a bundle header.
252#[derive(Debug, Clone, PartialEq, Eq)]
253pub struct BundleRefEntry {
254    /// Full ref name (for example `refs/heads/main`).
255    pub name: String,
256    /// Tip object id.
257    pub oid: ObjectId,
258}
259
260/// One prerequisite commit line (`-oid`) for an incremental bundle.
261#[derive(Debug, Clone, PartialEq, Eq)]
262pub struct BundlePrerequisite {
263    /// Required commit oid.
264    pub oid: ObjectId,
265    /// Optional subject from the commit message.
266    pub subject: Option<String>,
267}
268
269/// Planned bundle contents without writing a file.
270#[derive(Debug, Clone, PartialEq, Eq)]
271pub struct BundleCreatePlan {
272    /// Ref tips that would be listed in the header.
273    pub refs: Vec<BundleRefEntry>,
274    /// Prerequisite commits the recipient must already have.
275    pub prerequisites: Vec<BundlePrerequisite>,
276    /// Object count encoded in the pack stream.
277    pub object_count: u32,
278}
279
280/// One ref movement that would occur when applying bundle header tips locally.
281#[derive(Debug, Clone, PartialEq, Eq)]
282pub struct BundleRefUpdatePlan {
283    /// Ref to update.
284    pub name: String,
285    /// Current tip when the ref exists locally.
286    pub old_oid: Option<ObjectId>,
287    /// Tip from the bundle header.
288    pub new_oid: ObjectId,
289}
290
291/// Planned unbundle work: verification outcome and ref updates without ingesting the pack.
292#[derive(Debug, Clone, PartialEq, Eq)]
293pub struct BundleUnbundlePlan {
294    /// Verification against the open repository.
295    pub verify: BundleVerifyReport,
296    /// Ref updates implied by the bundle header (refs are not written during unbundle).
297    pub ref_updates: Vec<BundleRefUpdatePlan>,
298    /// Object count in the embedded pack.
299    pub object_count: u32,
300}
301
302/// An opened bundle file on disk.
303#[derive(Debug, Clone)]
304pub struct Bundle {
305    path: PathBuf,
306    header: BundleHeader,
307    pack_offset: u64,
308}
309
310impl Bundle {
311    /// Open `path` and parse the header, leaving the pack at `pack_offset`.
312    ///
313    /// # Errors
314    ///
315    /// Returns [`BundleError`] when the signature or header lines are invalid.
316    pub fn open(path: impl AsRef<Path>) -> std::result::Result<Self, BundleError> {
317        let path = path.as_ref().to_path_buf();
318        let (header, pack_offset) = read_header_from_file(&path)?;
319        Ok(Self {
320            path,
321            header,
322            pack_offset,
323        })
324    }
325
326    /// Parsed header.
327    #[must_use]
328    pub fn header(&self) -> &BundleHeader {
329        &self.header
330    }
331
332    /// Path passed to [`Self::open`].
333    #[must_use]
334    pub fn path(&self) -> &Path {
335        &self.path
336    }
337
338    /// Object count from the embedded pack header.
339    ///
340    /// # Errors
341    ///
342    /// Returns [`BundleError::MissingPack`] when the pack stream is absent or truncated.
343    pub fn pack_object_count(&self) -> std::result::Result<u32, BundleError> {
344        bundle_pack_object_count(self)
345    }
346
347    /// Byte offset in [`Self::path`] where the `PACK` stream begins.
348    #[must_use]
349    pub fn pack_byte_offset(&self) -> u64 {
350        self.pack_offset
351    }
352
353    /// Check prerequisites against `repo` and ref connectivity.
354    ///
355    /// # Errors
356    ///
357    /// Returns [`BundleError::ObjectFormatMismatch`] when hash algorithms disagree.
358    pub fn verify(
359        &self,
360        repo: &Repository,
361    ) -> std::result::Result<BundleVerifyReport, BundleError> {
362        let repo_algo = repo.odb().hash_algo();
363        if self.header.object_format != repo_algo {
364            return Err(BundleError::ObjectFormatMismatch {
365                bundle_name: self.header.object_format.name(),
366                repo_name: repo_algo.name(),
367            });
368        }
369        let mut report = BundleVerifyReport::default();
370        for (oid, subject) in &self.header.prerequisites {
371            if repo.odb().read(oid).is_err() {
372                report.missing_prerequisites.push((*oid, subject.clone()));
373            }
374        }
375        if report.missing_prerequisites.is_empty() {
376            let prereq_oids: Vec<ObjectId> =
377                self.header.prerequisites.iter().map(|(o, _)| *o).collect();
378            let connected =
379                bundle_prerequisites_connected_to_refs(repo, &prereq_oids).map_err(|e| {
380                    BundleError::Io {
381                        detail: e.to_string(),
382                    }
383                })?;
384            report.prerequisites_not_connected = !connected;
385        }
386        Ok(report)
387    }
388
389    /// Stream the embedded pack into `repo`'s ODB (does not update refs), reporting receive
390    /// and index-pack progress through `progress` and stopping when `cancel` fires.
391    ///
392    /// With a files-backed primary the pack is installed under `objects/pack/`. With a
393    /// custom [`RepositoryOptions::with_object_store`](crate::environment::RepositoryOptions::with_object_store) store the pack is
394    /// read straight from the bundle file and every object is written into that store;
395    /// no temporary file is created. A filtered (v3 `filter`) bundle is then not marked
396    /// as a promisor pack, since there is no pack to mark.
397    ///
398    /// Pack integrity is checked while building the pack index (object hashes and the
399    /// pack trailer); there is no second full read of the pack after indexing.
400    ///
401    /// Refuses to ingest the pack when [`Self::verify`] reports missing prerequisites or
402    /// disconnected prerequisite history (same checks as
403    /// [`RepositoryBundles::fetch`](crate::repo_handles::RepositoryBundles::fetch)).
404    ///
405    /// # Errors
406    ///
407    /// Returns [`BundleError`], [`BundleError::Cancelled`], or ingest failures wrapped as
408    /// [`BundleError::Io`].
409    pub fn unbundle(
410        &self,
411        repo: &Repository,
412        progress: &mut dyn ProgressSink,
413        cancel: &crate::progress::CancelToken,
414    ) -> std::result::Result<UnbundleOutcome, BundleError> {
415        crate::progress::poll_cancel(progress, cancel).map_err(bundle_ingest_error)?;
416        if self.header.object_format != repo.odb().hash_algo() {
417            return Err(BundleError::ObjectFormatMismatch {
418                bundle_name: self.header.object_format.name(),
419                repo_name: repo.odb().hash_algo().name(),
420            });
421        }
422        self.verify(repo)?.into_result()?;
423        let ingested = if repo.odb().uses_files_primary() {
424            self.install_pack(repo, progress, cancel)?
425        } else {
426            let mut input = File::open(&self.path)?;
427            Seek::seek(&mut input, std::io::SeekFrom::Start(self.pack_offset))?;
428            let mut reader = std::io::BufReader::with_capacity(1 << 20, input);
429            crate::unpack_objects::ingest_pack_into_odb(
430                &mut reader,
431                repo.odb(),
432                &crate::unpack_objects::UnpackOptions::default(),
433                Some(progress),
434                Some(cancel),
435            )
436            .map(crate::index_pack::IngestedPack::from)
437            .map_err(bundle_ingest_error)?
438        };
439        if let (Some(_), Some(pack_path)) = (&self.header.filter, &ingested.pack_path) {
440            std::fs::write(pack_path.with_extension("promisor"), b"").map_err(|e| {
441                BundleError::Io {
442                    detail: e.to_string(),
443                }
444            })?;
445            repo.odb().invalidate_packs();
446        }
447        let transfer = crate::transfer::TransferStats::from_ingested_pack(&ingested);
448        let refs = self
449            .header
450            .refs
451            .iter()
452            .map(|(name, oid)| UnbundledRef {
453                name: name.clone(),
454                oid: *oid,
455            })
456            .collect();
457        Ok(UnbundleOutcome {
458            refs,
459            transfer,
460            pack_object_ids: ingested.object_ids,
461        })
462    }
463
464    /// Copy the embedded pack under `objects/pack/` and install it there.
465    fn install_pack(
466        &self,
467        repo: &Repository,
468        progress: &mut dyn ProgressSink,
469        cancel: &crate::progress::CancelToken,
470    ) -> std::result::Result<crate::index_pack::IngestedPack, BundleError> {
471        let pack_bytes = std::fs::metadata(&self.path)
472            .map(|m| m.len().saturating_sub(self.pack_offset))
473            .unwrap_or(0);
474        progress.start_with_unit(
475            ProgressPhase::ReceivingObjects,
476            ProgressUnit::Bytes,
477            Some(pack_bytes),
478        );
479        let pack_dir = repo.odb().objects_dir().join("pack");
480        std::fs::create_dir_all(&pack_dir).map_err(BundleError::from)?;
481        let tmp = tempfile::NamedTempFile::new_in(&pack_dir).map_err(|e| BundleError::Io {
482            detail: e.to_string(),
483        })?;
484        {
485            let mut input = File::open(&self.path)?;
486            Seek::seek(&mut input, std::io::SeekFrom::Start(self.pack_offset))
487                .map_err(BundleError::from)?;
488            let mut output = std::io::BufWriter::new(tmp.as_file());
489            let mut copied = 0u64;
490            let mut buf = [0u8; 64 * 1024];
491            loop {
492                crate::progress::poll_cancel(progress, cancel).map_err(bundle_ingest_error)?;
493                let n = input.read(&mut buf).map_err(BundleError::from)?;
494                if n == 0 {
495                    break;
496                }
497                output.write_all(&buf[..n]).map_err(BundleError::from)?;
498                copied = copied.saturating_add(n as u64);
499                progress.set(copied);
500            }
501            output.flush().map_err(BundleError::from)?;
502        }
503        progress.finish();
504        crate::progress::poll_cancel(progress, cancel).map_err(bundle_ingest_error)?;
505        let opts = IngestPackOptions {
506            fix_thin: true,
507            // Indexing hashes every object and the trailer is checked while
508            // installing, so a second full read of the pack proves nothing.
509            skip_post_index_verify: true,
510            ..Default::default()
511        };
512        ingest_received_pack_path_with_progress(
513            tmp.path().to_path_buf(),
514            repo.odb(),
515            &opts,
516            Some(progress),
517            Some(cancel),
518        )
519        .map_err(bundle_ingest_error)
520    }
521}
522
523fn bundle_ingest_error(e: Error) -> BundleError {
524    match e {
525        Error::Cancelled => BundleError::Cancelled,
526        other => BundleError::Io {
527            detail: other.to_string(),
528        },
529    }
530}
531
532/// Parse a bundle header from `reader`, leaving the cursor at the first `PACK` byte.
533///
534/// # Errors
535///
536/// Returns [`BundleError`] when the signature or header is invalid.
537pub fn read_header(reader: &mut dyn BufRead) -> std::result::Result<BundleHeader, BundleError> {
538    let header = read_header_lines(reader)?;
539    ensure_pack_magic(reader)?;
540    Ok(header)
541}
542
543/// Parse the signature, capability, prerequisite and ref lines up to and including the
544/// blank line that ends the header, without inspecting the pack that follows.
545fn read_header_lines(reader: &mut dyn BufRead) -> std::result::Result<BundleHeader, BundleError> {
546    let signature = read_line(reader)?;
547    let version = match signature.as_str() {
548        s if s == V2_SIGNATURE.trim_end() => BundleVersion::V2,
549        s if s == V3_SIGNATURE.trim_end() => BundleVersion::V3,
550        _ => return Err(BundleError::BadSignature),
551    };
552
553    let mut object_format = HashAlgo::Sha1;
554    let mut filter = None;
555    let mut prerequisites = Vec::new();
556    let mut refs = Vec::new();
557
558    loop {
559        let line = read_line(reader)?;
560        if line.is_empty() {
561            break;
562        }
563        if version == BundleVersion::V3 && line.starts_with('@') {
564            parse_capability(&line[1..], &mut object_format, &mut filter)?;
565            continue;
566        }
567        let (is_prereq, rest) = if let Some(stripped) = line.strip_prefix('-') {
568            (true, stripped)
569        } else {
570            (false, line.as_str())
571        };
572        let (oid, tail) = parse_oid_field(rest, object_format)?;
573        if is_prereq {
574            let subject = tail
575                .map(str::trim)
576                .filter(|s| !s.is_empty())
577                .map(str::to_owned);
578            prerequisites.push((oid, subject));
579        } else {
580            let refname = tail.ok_or_else(|| BundleError::MalformedLine {
581                line: "ref line missing ref name".to_owned(),
582            })?;
583            let refname = refname.trim();
584            if refname.is_empty() {
585                return Err(BundleError::MalformedLine {
586                    line: "ref line missing ref name".to_owned(),
587                });
588            }
589            refs.push((refname.to_owned(), oid));
590        }
591    }
592
593    Ok(BundleHeader {
594        version,
595        object_format,
596        filter,
597        prerequisites,
598        refs,
599    })
600}
601
602/// Buffer size for streaming the header; most headers fit in one read, and the pack that
603/// follows (often far larger than the header) is never pulled into memory.
604const HEADER_READ_BUF: usize = 64 * 1024;
605
606fn read_header_from_file(path: &Path) -> std::result::Result<(BundleHeader, u64), BundleError> {
607    let file = File::open(path).map_err(|e| io_open_path(path, e))?;
608    let mut reader = std::io::BufReader::with_capacity(HEADER_READ_BUF, file);
609    let header = read_header_lines(&mut reader)?;
610    let mut pack_offset = reader.stream_position().map_err(BundleError::from)?;
611    let mut magic = [0u8; 4];
612    loop {
613        read_exact_or_missing_pack(&mut reader, &mut magic[..1])?;
614        if magic[0] != b'\n' && magic[0] != b'\r' {
615            break;
616        }
617        pack_offset += 1;
618    }
619    read_exact_or_missing_pack(&mut reader, &mut magic[1..])?;
620    if &magic != b"PACK" {
621        return Err(BundleError::MissingPack);
622    }
623    Ok((header, pack_offset))
624}
625
626fn read_exact_or_missing_pack(
627    reader: &mut dyn std::io::Read,
628    buf: &mut [u8],
629) -> std::result::Result<(), BundleError> {
630    reader.read_exact(buf).map_err(|e| match e.kind() {
631        std::io::ErrorKind::UnexpectedEof => BundleError::MissingPack,
632        _ => BundleError::from(e),
633    })
634}
635
636fn ensure_pack_magic(reader: &mut dyn BufRead) -> std::result::Result<(), BundleError> {
637    loop {
638        let buf = reader.fill_buf().map_err(BundleError::from)?;
639        if buf.is_empty() {
640            return Err(BundleError::MissingPack);
641        }
642        if buf.starts_with(b"PACK") {
643            return Ok(());
644        }
645        if buf[0] == b'\n' || buf[0] == b'\r' {
646            reader.consume(1);
647            continue;
648        }
649        return Err(BundleError::MissingPack);
650    }
651}
652
653/// Plan a bundle for `spec` without writing a file.
654///
655/// # Errors
656///
657/// Returns [`BundleError::EmptyRefs`] when `spec.include` is empty, or pack generation failures.
658pub(crate) fn plan_bundle_create(
659    repo: &Repository,
660    spec: &BundleSpec,
661) -> std::result::Result<BundleCreatePlan, BundleError> {
662    if spec.include.is_empty() {
663        return Err(BundleError::EmptyRefs);
664    }
665    let header = bundle_header_parts(repo, spec)?;
666    let object_count = write_bundle_pack(repo, spec, &mut std::io::sink())?.object_count;
667    Ok(BundleCreatePlan {
668        refs: header
669            .refs
670            .into_iter()
671            .map(|(oid, name)| BundleRefEntry { name, oid })
672            .collect(),
673        prerequisites: header
674            .prerequisites
675            .into_iter()
676            .map(|(oid, subject)| BundlePrerequisite { oid, subject })
677            .collect(),
678        object_count,
679    })
680}
681
682/// Plan unbundle verification and ref updates without ingesting the pack or writing refs.
683///
684/// # Errors
685///
686/// Returns [`BundleError`] when the bundle cannot be read or verified.
687pub(crate) fn plan_bundle_unbundle(
688    bundle: &Bundle,
689    repo: &Repository,
690) -> std::result::Result<BundleUnbundlePlan, BundleError> {
691    let verify = bundle.verify(repo)?;
692    let ref_updates = planned_ref_updates_from_header(repo, &bundle.header().refs);
693    let object_count = bundle_pack_object_count(bundle)?;
694    Ok(BundleUnbundlePlan {
695        verify,
696        ref_updates,
697        object_count,
698    })
699}
700
701fn bundle_pack_object_count(bundle: &Bundle) -> std::result::Result<u32, BundleError> {
702    let mut input = File::open(&bundle.path).map_err(BundleError::from)?;
703    Seek::seek(&mut input, std::io::SeekFrom::Start(bundle.pack_offset))
704        .map_err(BundleError::from)?;
705    let mut header = [0u8; 12];
706    read_exact_or_missing_pack(&mut input, &mut header)?;
707    Ok(crate::receive_pack::pack_object_count(&header).unwrap_or(0))
708}
709
710fn planned_ref_updates_from_header(
711    repo: &Repository,
712    refs: &[(String, ObjectId)],
713) -> Vec<BundleRefUpdatePlan> {
714    let git_dir = repo.git_dir();
715    let mut updates = Vec::new();
716    for (name, new_oid) in refs {
717        if name.ends_with("^{}") {
718            continue;
719        }
720        let old_oid = crate::refs::resolve_ref(git_dir, name).ok();
721        if old_oid.as_ref() == Some(new_oid) {
722            continue;
723        }
724        updates.push(BundleRefUpdatePlan {
725            name: name.clone(),
726            old_oid,
727            new_oid: *new_oid,
728        });
729    }
730    updates
731}
732
733struct BundleHeaderParts {
734    prerequisites: Vec<(ObjectId, Option<String>)>,
735    refs: Vec<(ObjectId, String)>,
736}
737
738fn bundle_header_parts(
739    repo: &Repository,
740    spec: &BundleSpec,
741) -> std::result::Result<BundleHeaderParts, BundleError> {
742    let include_oids: Vec<ObjectId> = spec.include.iter().map(|(o, _)| *o).collect();
743    let prerequisites = prerequisite_commits(repo.odb(), &include_oids, &spec.exclude)?;
744    Ok(BundleHeaderParts {
745        prerequisites,
746        refs: spec.include.clone(),
747    })
748}
749
750/// Stream the bundle's pack to `out` and return its statistics.
751///
752/// Uses the same settings as serving a fetch ([`PackBuildOptions::for_serve`]): deltas
753/// and whole objects already in local packs are copied, and only blobs not already
754/// stored as deltas enter the delta search, so memory stays bounded by the pack index
755/// instead of the inflated object size. Bundles with prerequisites are thin.
756fn map_pack_error(e: Error) -> BundleError {
757    match e {
758        Error::Cancelled => BundleError::Cancelled,
759        Error::Object(ObjectError::NotFound { name: id }) => {
760            BundleError::ObjectNotFound { name: id }
761        }
762        other => BundleError::Io {
763            detail: other.to_string(),
764        },
765    }
766}
767
768fn write_bundle_pack(
769    repo: &Repository,
770    spec: &BundleSpec,
771    out: &mut dyn Write,
772) -> std::result::Result<PackStats, BundleError> {
773    write_bundle_pack_with_cancel(
774        repo,
775        spec,
776        out,
777        &mut NullProgress,
778        &crate::progress::CancelToken::never(),
779    )
780}
781
782fn write_bundle_pack_with_cancel(
783    repo: &Repository,
784    spec: &BundleSpec,
785    out: &mut dyn Write,
786    progress: &mut dyn ProgressSink,
787    cancel: &crate::progress::CancelToken,
788) -> std::result::Result<PackStats, BundleError> {
789    let stop = crate::progress::CancelSignal::new(cancel);
790    let io_err = map_pack_error;
791    let include_oids: Vec<ObjectId> = spec.include.iter().map(|(o, _)| *o).collect();
792    let mut haves: Vec<ObjectId> = spec
793        .exclude
794        .iter()
795        .map(|oid| peel_to_commit(repo.odb(), *oid))
796        .collect::<Result<Vec<_>>>()
797        .map_err(io_err)?;
798    haves.sort();
799    haves.dedup();
800    let cfg = repo.config().snapshot().ok();
801    let pack_opts = PackBuildOptions {
802        thin: !haves.is_empty(),
803        ..PackBuildOptions::for_serve(cfg.as_deref())
804    };
805    let no_shallow = HashSet::new();
806    let Some(filter) = spec.filter.as_ref() else {
807        let stats = crate::pack_objects::write_upload_pack_stream_with_cancel(
808            repo,
809            &include_oids,
810            &haves,
811            &no_shallow,
812            &no_shallow,
813            None,
814            &[],
815            &pack_opts,
816            progress,
817            out,
818            &stop,
819        )
820        .map_err(io_err)?;
821        return Ok(stats);
822    };
823    // A filtered bundle is what `pack-objects --filter` sends, the same selection a
824    // filtered fetch gets, so it streams with the same bounded walk instead of listing
825    // the excluded side's whole closure in memory. A partial clone lacks the blobs it
826    // was promised, which that walk does not skip, so it keeps the listing below.
827    let promisor = cfg
828        .as_deref()
829        .is_some_and(crate::promisor::repo_treats_promisor_packs);
830    if !promisor {
831        return crate::pack_objects::write_upload_pack_stream_with_cancel(
832            repo,
833            &include_oids,
834            &haves,
835            &no_shallow,
836            &no_shallow,
837            Some(filter.as_filter()),
838            &[],
839            &pack_opts,
840            progress,
841            out,
842            &stop,
843        )
844        .map_err(io_err);
845    }
846    stop.poll().map_err(map_pack_error)?;
847    let have_closure = reachable_closure(repo.odb(), &haves, &HashSet::new(), true, &no_shallow)
848        .map_err(io_err)?;
849    stop.poll().map_err(map_pack_error)?;
850    let send = filtered_pack_objects(
851        repo,
852        &include_oids,
853        &spec.exclude,
854        filter.as_filter(),
855        &have_closure,
856    )
857    .map_err(io_err)?;
858    stop.poll().map_err(map_pack_error)?;
859    let pack = build_pack_from_send_list(
860        repo.odb(),
861        &send,
862        &have_closure,
863        &pack_opts,
864        &HashMap::new(),
865    )
866    .map_err(io_err)?;
867    stop.poll().map_err(map_pack_error)?;
868    out.write_all(&pack).map_err(BundleError::from)?;
869    progress.finish();
870    Ok(PackStats {
871        object_count: crate::receive_pack::pack_object_count(&pack).unwrap_or(0),
872        pack_bytes: pack.len() as u64,
873        ..PackStats::default()
874    })
875}
876
877/// Write a bundle to `out` from `repo` using `spec`, reporting pack progress through
878/// `progress` and stopping pack generation when `cancel` is set.
879///
880/// The header is written first, then the pack is streamed straight into `out`; the
881/// pack is never held in memory as a whole (filtered bundles excepted). Deltas and
882/// whole objects already stored in local packs are copied verbatim rather than
883/// recomputed, and bundles with prerequisites are thin (deltas may name a
884/// prerequisite-reachable base the recipient already holds). Pass a buffered writer:
885/// the pack is emitted in many small writes.
886///
887/// # Errors
888///
889/// Returns [`BundleError::EmptyRefs`] when `spec.include` is empty, [`BundleError::Cancelled`]
890/// when `cancel` fires, or I/O / pack errors.
891pub(crate) fn write_bundle(
892    repo: &Repository,
893    spec: &BundleSpec,
894    out: &mut dyn Write,
895    progress: &mut dyn ProgressSink,
896    cancel: &crate::progress::CancelToken,
897) -> std::result::Result<(), BundleError> {
898    if spec.include.is_empty() {
899        return Err(BundleError::EmptyRefs);
900    }
901    crate::progress::poll_cancel(progress, cancel).map_err(map_pack_error)?;
902    let header = bundle_header_parts(repo, spec)?;
903    write_header(
904        out,
905        repo.odb().hash_algo(),
906        spec.filter.as_ref(),
907        &header.prerequisites,
908        &header.refs,
909    )?;
910
911    write_bundle_pack_with_cancel(repo, spec, out, progress, cancel)?;
912    Ok(())
913}
914
915/// Write a bundle header: the signature, the capabilities a non-SHA-1 bundle
916/// needs, one `-<oid> <subject>` line per prerequisite, one `<oid> <ref>` line
917/// per tip, and the blank line the pack follows.
918///
919/// For callers that already have a pack for those tips (such as a push), so a
920/// bundle is this header followed by the pack bytes.
921///
922/// # Errors
923///
924/// [`BundleError::Io`] when writing fails.
925pub fn write_bundle_header(
926    out: &mut dyn Write,
927    algo: HashAlgo,
928    prerequisites: &[(ObjectId, Option<String>)],
929    refs: &[(ObjectId, String)],
930) -> std::result::Result<(), BundleError> {
931    write_header(out, algo, None, prerequisites, refs)
932}
933
934fn write_header(
935    out: &mut dyn Write,
936    algo: HashAlgo,
937    filter: Option<&FilterSpec>,
938    prerequisites: &[(ObjectId, Option<String>)],
939    refs: &[(ObjectId, String)],
940) -> std::result::Result<(), BundleError> {
941    let version = if algo != HashAlgo::Sha1 || filter.is_some() {
942        BundleVersion::V3
943    } else {
944        BundleVersion::V2
945    };
946    write_signature(out, version)?;
947    if version == BundleVersion::V3 {
948        write_capability_object_format(out, algo)?;
949        if let Some(filter) = filter {
950            write_capability_filter(out, filter)?;
951        }
952    }
953    for (oid, subject) in prerequisites {
954        write!(out, "-{} ", oid.to_hex()).map_err(|e| BundleError::Io {
955            detail: e.to_string(),
956        })?;
957        if let Some(s) = subject {
958            write!(out, "{s}").map_err(|e| BundleError::Io {
959                detail: e.to_string(),
960            })?;
961        }
962        writeln!(out).map_err(|e| BundleError::Io {
963            detail: e.to_string(),
964        })?;
965    }
966    for (oid, name) in refs {
967        writeln!(out, "{} {name}", oid.to_hex()).map_err(|e| BundleError::Io {
968            detail: e.to_string(),
969        })?;
970    }
971    writeln!(out).map_err(|e| BundleError::Io {
972        detail: e.to_string(),
973    })
974}
975
976fn write_signature(
977    out: &mut dyn Write,
978    version: BundleVersion,
979) -> std::result::Result<(), BundleError> {
980    let sig = match version {
981        BundleVersion::V2 => V2_SIGNATURE,
982        BundleVersion::V3 => V3_SIGNATURE,
983    };
984    out.write_all(sig.as_bytes()).map_err(|e| BundleError::Io {
985        detail: e.to_string(),
986    })
987}
988
989fn write_capability_object_format(
990    out: &mut dyn Write,
991    algo: HashAlgo,
992) -> std::result::Result<(), BundleError> {
993    writeln!(out, "@object-format={}", algo.name()).map_err(|e| BundleError::Io {
994        detail: e.to_string(),
995    })
996}
997
998fn write_capability_filter(
999    out: &mut dyn Write,
1000    filter: &FilterSpec,
1001) -> std::result::Result<(), BundleError> {
1002    writeln!(out, "@filter={}", filter.to_capability_value()).map_err(|e| BundleError::Io {
1003        detail: e.to_string(),
1004    })
1005}
1006
1007fn parse_capability(
1008    cap: &str,
1009    object_format: &mut HashAlgo,
1010    filter: &mut Option<FilterSpec>,
1011) -> std::result::Result<(), BundleError> {
1012    if let Some(name) = cap.strip_prefix("object-format=") {
1013        *object_format = HashAlgo::from_name(name).ok_or_else(|| BundleError::MalformedLine {
1014            line: format!("unknown object format: {name}"),
1015        })?;
1016        return Ok(());
1017    }
1018    if let Some(spec) = cap.strip_prefix("filter=") {
1019        *filter = Some(FilterSpec::parse(spec)?);
1020        return Ok(());
1021    }
1022    Err(BundleError::UnsupportedCapability {
1023        capability: cap.to_owned(),
1024    })
1025}
1026
1027fn read_line(reader: &mut dyn BufRead) -> std::result::Result<String, BundleError> {
1028    let mut line = String::new();
1029    let n = reader.read_line(&mut line).map_err(BundleError::from)?;
1030    if n == 0 {
1031        return Err(BundleError::MalformedLine {
1032            line: "unexpected end of header".to_owned(),
1033        });
1034    }
1035    if line.ends_with('\n') {
1036        line.pop();
1037        if line.ends_with('\r') {
1038            line.pop();
1039        }
1040    }
1041    Ok(line)
1042}
1043
1044fn parse_oid_field(
1045    line: &str,
1046    algo: HashAlgo,
1047) -> std::result::Result<(ObjectId, Option<&str>), BundleError> {
1048    let hex_len = algo.hex_len();
1049    if line.len() < hex_len {
1050        return Err(BundleError::MalformedLine {
1051            line: "short object id".to_owned(),
1052        });
1053    }
1054    let (hex, tail) = line.split_at(hex_len);
1055    if !hex.chars().all(|c| c.is_ascii_hexdigit()) {
1056        return Err(BundleError::MalformedLine {
1057            line: "invalid object id".to_owned(),
1058        });
1059    }
1060    let oid = ObjectId::from_hex(hex).map_err(|_| BundleError::MalformedLine {
1061        line: "invalid object id".to_owned(),
1062    })?;
1063    if hex.len() != algo.hex_len() {
1064        return Err(BundleError::MalformedLine {
1065            line: "object id length mismatch".to_owned(),
1066        });
1067    }
1068    let tail = match tail.chars().next() {
1069        None => None,
1070        Some(c) if c.is_whitespace() => Some(tail.trim_start()),
1071        Some(_) => {
1072            return Err(BundleError::MalformedLine {
1073                line: "garbage after object id".to_owned(),
1074            })
1075        }
1076    };
1077    Ok((oid, tail))
1078}
1079
1080fn peel_to_commit(odb: &Odb, oid: ObjectId) -> Result<ObjectId> {
1081    match odb.peel_tags(oid)? {
1082        (commit, ObjectKind::Commit) => Ok(commit),
1083        (other, _) => Err(Error::Object(ObjectError::Corrupt {
1084            detail: format!("object {other} is not commit or tag"),
1085        })),
1086    }
1087}
1088
1089fn commit_parent_set(odb: &Odb, commit: ObjectId) -> Result<Vec<ObjectId>> {
1090    let obj = odb.read(&commit)?;
1091    let commit = parse_commit(&obj.data)?;
1092    Ok(commit.parents)
1093}
1094
1095/// Commits the bundle's pack is cut at: excluded commits that are parents of a
1096/// commit the bundle carries (`rev-list --boundary`), each with its subject.
1097///
1098/// The excluded side is walked only as far as the included history meets it (the
1099/// same date-ordered walk that bounds the pack, see
1100/// [`crate::pack_object_select::uninteresting_commits_to_boundary`]), so a bundle
1101/// of one new commit reads a handful of commits instead of the whole history.
1102fn prerequisite_commits(
1103    odb: &Odb,
1104    includes: &[ObjectId],
1105    excludes: &[ObjectId],
1106) -> std::result::Result<Vec<(ObjectId, Option<String>)>, BundleError> {
1107    if excludes.is_empty() {
1108        return Ok(Vec::new());
1109    }
1110    let io = |e: Error| BundleError::Io {
1111        detail: e.to_string(),
1112    };
1113    let exclude_tips = excludes
1114        .iter()
1115        .map(|&oid| peel_to_commit(odb, oid))
1116        .collect::<Result<Vec<_>>>()
1117        .map_err(io)?;
1118    let include_tips = includes
1119        .iter()
1120        .map(|&oid| peel_to_commit(odb, oid))
1121        .collect::<Result<Vec<_>>>()
1122        .map_err(io)?;
1123    // Only as far as the included history meets the excluded side, not the excluded
1124    // tips' whole history.
1125    let uninteresting = crate::pack_object_select::uninteresting_commits_to_boundary(
1126        odb,
1127        &include_tips,
1128        &exclude_tips,
1129    )
1130    .map_err(io)?;
1131    let mut prerequisites = Vec::new();
1132    let mut seen_prereq = HashSet::new();
1133    let mut walk_seen = HashSet::new();
1134    let mut q: VecDeque<ObjectId> = VecDeque::new();
1135    for c in include_tips {
1136        if !uninteresting.contains(&c) && walk_seen.insert(c) {
1137            q.push_back(c);
1138        }
1139    }
1140    while let Some(c) = q.pop_front() {
1141        let parents = commit_parent_set(odb, c).map_err(io)?;
1142        for p in parents {
1143            if uninteresting.contains(&p) {
1144                if seen_prereq.insert(p) {
1145                    let subject = commit_subject(odb, p).map_err(io)?;
1146                    prerequisites.push((p, subject));
1147                }
1148            } else if walk_seen.insert(p) {
1149                q.push_back(p);
1150            }
1151        }
1152    }
1153    Ok(prerequisites)
1154}
1155
1156fn commit_subject(odb: &Odb, commit: ObjectId) -> Result<Option<String>> {
1157    let obj = odb.read(&commit)?;
1158    let parsed = parse_commit(&obj.data)?;
1159    let subj = message_subject(&parsed.message);
1160    if subj.is_empty() {
1161        Ok(None)
1162    } else {
1163        Ok(Some(subj))
1164    }
1165}
1166
1167fn filter_to_capability_value(filter: &ObjectFilter) -> String {
1168    match filter {
1169        ObjectFilter::BlobNone => "blob:none".to_owned(),
1170        ObjectFilter::BlobLimit(n) => format!("blob:limit={n}"),
1171        ObjectFilter::TreeDepth(d) => format!("tree:{d}"),
1172        ObjectFilter::SparseOid(s) => format!("sparse:oid={s}"),
1173        ObjectFilter::ObjectType(k) => format!("object:type={}", filter_object_kind_name(*k)),
1174        ObjectFilter::Combine(parts) => {
1175            let encoded: Vec<String> = parts
1176                .iter()
1177                .map(|p| {
1178                    crate::rev_list::url_encode_object_filter_subspec(&filter_to_capability_value(
1179                        p,
1180                    ))
1181                })
1182                .collect();
1183            format!("combine:{}", encoded.join("+"))
1184        }
1185    }
1186}
1187
1188fn filter_object_kind_name(kind: FilterObjectKind) -> &'static str {
1189    match kind {
1190        FilterObjectKind::Blob => "blob",
1191        FilterObjectKind::Tree => "tree",
1192        FilterObjectKind::Commit => "commit",
1193        FilterObjectKind::Tag => "tag",
1194    }
1195}
1196
1197/// Object list for a filtered bundle pack (`rev-list --objects --filter`).
1198fn filtered_pack_objects(
1199    repo: &Repository,
1200    include: &[ObjectId],
1201    exclude: &[ObjectId],
1202    filter: &ObjectFilter,
1203    have_closure: &HashSet<ObjectId>,
1204) -> Result<Vec<ObjectId>> {
1205    let positive: Vec<String> = include.iter().map(ObjectId::to_hex).collect();
1206    // `rev_list` takes the excluded tips bare: they are already the negative side.
1207    let negative: Vec<String> = exclude.iter().map(ObjectId::to_hex).collect();
1208    let options = RevListOptions {
1209        objects: true,
1210        no_object_names: true,
1211        quiet: true,
1212        filter: Some(filter.clone()),
1213        missing_action: MissingAction::Error,
1214        ..Default::default()
1215    };
1216    let walk = crate::rev_list::rev_list(repo, &positive, &negative, &options)?;
1217    Ok(collect_filtered_send_list(&walk, have_closure))
1218}
1219
1220fn collect_filtered_send_list(
1221    walk: &RevListResult,
1222    have_closure: &HashSet<ObjectId>,
1223) -> Vec<ObjectId> {
1224    let mut send = Vec::new();
1225    let mut seen = HashSet::new();
1226    let mut push = |oid: ObjectId| {
1227        if have_closure.contains(&oid) {
1228            return;
1229        }
1230        if seen.insert(oid) {
1231            send.push(oid);
1232        }
1233    };
1234    for oid in &walk.commits {
1235        push(*oid);
1236    }
1237    for (oid, _) in &walk.objects {
1238        push(*oid);
1239    }
1240    for tag_oid in walk.tip_annotated_tag_by_commit.values().flatten() {
1241        push(*tag_oid);
1242    }
1243    send
1244}
1245
1246#[cfg(test)]
1247mod tests {
1248    use super::*;
1249    use std::io::Cursor;
1250
1251    #[test]
1252    fn parse_v2_header_and_refs() {
1253        let oid = "a".repeat(40);
1254        let data = format!("# v2 git bundle\n{oid} refs/heads/main\n\nPACK");
1255        let mut cur = Cursor::new(data.into_bytes());
1256        let header = read_header(&mut cur).expect("header");
1257        assert_eq!(header.version, BundleVersion::V2);
1258        assert_eq!(header.object_format, HashAlgo::Sha1);
1259        assert_eq!(header.prerequisites.len(), 0);
1260        assert_eq!(header.refs.len(), 1);
1261        assert_eq!(header.refs[0].0, "refs/heads/main");
1262    }
1263
1264    #[test]
1265    fn bad_signature_yields_error() {
1266        let mut cur = Cursor::new(b"# v4 git bundle\n\nPACK");
1267        let err = read_header(&mut cur).unwrap_err();
1268        assert_eq!(err, BundleError::BadSignature);
1269    }
1270
1271    #[test]
1272    fn unknown_capability() {
1273        let mut cur = Cursor::new(b"# v3 git bundle\n@unknown=yes\n\nPACK");
1274        let err = read_header(&mut cur).unwrap_err();
1275        assert!(matches!(err, BundleError::UnsupportedCapability { .. }));
1276    }
1277
1278    #[test]
1279    fn truncated_ref_line() {
1280        let oid = "a".repeat(40);
1281        let data = format!("# v2 git bundle\n{oid}\n\nPACK");
1282        let mut cur = Cursor::new(data.into_bytes());
1283        let err = read_header(&mut cur).unwrap_err();
1284        assert!(matches!(err, BundleError::MalformedLine { .. }));
1285    }
1286
1287    #[test]
1288    fn filter_spec_roundtrip_blob_none() {
1289        let f = FilterSpec::parse("blob:none").expect("parse");
1290        assert_eq!(f.to_capability_value(), "blob:none");
1291    }
1292
1293    #[test]
1294    fn verify_report_missing_prerequisite_error() {
1295        let oid = ObjectId::from_hex(&"b".repeat(40)).expect("oid");
1296        let report = BundleVerifyReport {
1297            missing_prerequisites: vec![(oid, Some("subj".to_owned()))],
1298            prerequisites_not_connected: false,
1299        };
1300        let err = report.into_result().unwrap_err();
1301        assert!(matches!(err, BundleError::MissingPrerequisites { .. }));
1302    }
1303
1304    fn write_bundle_file(bytes: &[u8]) -> tempfile::NamedTempFile {
1305        let mut file = tempfile::NamedTempFile::new().expect("tempfile");
1306        file.write_all(bytes).expect("write bundle");
1307        file.flush().expect("flush bundle");
1308        file
1309    }
1310
1311    #[test]
1312    fn open_reports_pack_offset_after_header() {
1313        let oid = "a".repeat(40);
1314        let header = format!("# v2 git bundle\n{oid} refs/heads/main\n\n");
1315        let mut data = header.clone().into_bytes();
1316        data.extend_from_slice(b"PACK\0\0\0\x02\0\0\0\0");
1317        let file = write_bundle_file(&data);
1318        let bundle = Bundle::open(file.path()).expect("open");
1319        assert_eq!(bundle.pack_byte_offset(), header.len() as u64);
1320        assert_eq!(bundle.header().refs.len(), 1);
1321    }
1322
1323    #[test]
1324    fn open_skips_blank_lines_before_pack() {
1325        let oid = "a".repeat(40);
1326        let header = format!("# v2 git bundle\n{oid} HEAD\n\n\r\n\n");
1327        let mut data = header.clone().into_bytes();
1328        data.extend_from_slice(b"PACK");
1329        let file = write_bundle_file(&data);
1330        let bundle = Bundle::open(file.path()).expect("open");
1331        assert_eq!(bundle.pack_byte_offset(), header.len() as u64);
1332    }
1333
1334    #[test]
1335    fn open_handles_pack_magic_across_read_buffer_boundary() {
1336        let oid = "c".repeat(40);
1337        let signature = "# v2 git bundle\n";
1338        let ref_line = |i: usize| format!("{oid} refs/tags/t{i:06}\n");
1339        let line_len = ref_line(0).len();
1340        // Grow the header until the blank terminator lands two bytes before the first
1341        // buffer refill, so "PACK" straddles the boundary.
1342        let mut refs = 0usize;
1343        while signature.len() + (refs + 1) * line_len + 1 + 2 <= HEADER_READ_BUF {
1344            refs += 1;
1345        }
1346        let mut header = String::from(signature);
1347        for i in 0..refs {
1348            header.push_str(&ref_line(i));
1349        }
1350        header.push('\n');
1351        let pad = HEADER_READ_BUF - 2 - header.len();
1352        let mut data = header.clone().into_bytes();
1353        data.extend(std::iter::repeat_n(b'\n', pad));
1354        data.extend_from_slice(b"PACK\0\0\0\x02");
1355        assert_eq!(&data[HEADER_READ_BUF - 2..HEADER_READ_BUF + 2], b"PACK");
1356        let file = write_bundle_file(&data);
1357        let bundle = Bundle::open(file.path()).expect("open");
1358        assert_eq!(bundle.header().refs.len(), refs);
1359        assert_eq!(bundle.pack_byte_offset(), (HEADER_READ_BUF - 2) as u64);
1360    }
1361
1362    #[test]
1363    fn open_missing_file_names_path() {
1364        let path = std::path::Path::new("/no/such/bundle/path.bundle");
1365        let err = Bundle::open(path).unwrap_err();
1366        let msg = err.to_string();
1367        assert!(
1368            msg.contains("could not open") && msg.contains("path.bundle"),
1369            "{msg}"
1370        );
1371    }
1372
1373    #[test]
1374    fn open_without_pack_is_missing_pack() {
1375        let oid = "a".repeat(40);
1376        let truncated = format!("# v2 git bundle\n{oid} HEAD\n\n");
1377        let file = write_bundle_file(truncated.as_bytes());
1378        assert_eq!(
1379            Bundle::open(file.path()).unwrap_err(),
1380            BundleError::MissingPack
1381        );
1382
1383        let short = format!("# v2 git bundle\n{oid} HEAD\n\nPA");
1384        let file = write_bundle_file(short.as_bytes());
1385        assert_eq!(
1386            Bundle::open(file.path()).unwrap_err(),
1387            BundleError::MissingPack
1388        );
1389
1390        let garbage = format!("# v2 git bundle\n{oid} HEAD\n\nJUNK");
1391        let file = write_bundle_file(garbage.as_bytes());
1392        assert_eq!(
1393            Bundle::open(file.path()).unwrap_err(),
1394            BundleError::MissingPack
1395        );
1396    }
1397}