ingest/loadtest: expand loadtest functionality to handle multiple ledger bundles

[cjonas9]

PR Checklist

PR Structure

• This PR has reasonably narrow scope (if not, break it down into smaller PRs).
• This PR avoids mixing refactoring changes with feature changes (split into two PRs
  otherwise).
• This PR's title starts with name of package that is most changed in the PR, ex.
  services/friendbot, or all or doc if the changes are broad or impact many
  packages.

Thoroughness

• This PR adds tests for the most critical parts of the new functionality or fixes.
• I've updated any docs (developer docs, .md
  files, etc... affected by this change). Take a look in the docs folder for a given service,
  like this one.

Release planning

• I've reviewed the changes in this PR and if I consider them worthwhile for being mentioned on release notes then I have updated the relevant CHANGELOG.md within the component folder structure. For example, if I changed horizon, then I updated (services/horizon/CHANGELOG.md. I add a new line item describing the change and reference to this PR. If I don't update a CHANGELOG, I acknowledge this PR's change may not be mentioned in future release notes.
• I've decided if this PR requires a new major/minor version according to
  semver, or if it's mainly a patch change. The PR is targeted at the next
  release branch if it's not a patch change.

What

Extends ingest/loadtest's LedgerBackend functionality to replay synthetic ledgers from multiple ledger bundle files and to cap how many ledgers are replayed per file, and bundle verification by ensuring.

The following API changes were made to LedgerBackendConfig:

• LedgersFilePath string -> LedgersFilePaths []string: bundles are replayed in order, sequence-rebased onto the requested range as before. When multiple ledger bundles are provided, it's verified that they all share the same network passphrase.
• MaxLedgersPerFile uint32 (new field, optional): caps the number of ledgers replayed from each file (0 = no cap; a value above a file's size simply replays the whole file). It's a per-file ceiling applied independently and it's never an error.
  Note that the breaking caused by these changes is resolved in stellar-rpc/741 and stellar-horizon/185

The following exported helper is new:

• CountLedgersPerFile(paths, perFileLimit) ([]FileLedgerCount, error): returns the post-cap ledger count for each bundle. It shares the exact reader + cap logic PrepareRange uses, so callers can compute the replay length/the per-bundle bounds and be guaranteed the numbers match what the backend will serve without re-deriving them from generation configs or the bundles + passed parameters.

Why

This PR intends to shift work into the callee rather than delegating it to callers. Within stellar-rpc/#741 (which is the primary use of this SDK package), it's necessary to read multiple ledger bundle files. Doing so creates a great deal of overhead: one must keep track of which apply-load config file was used to generate the bundle and couple it to the bundle, or inspect the bundle file's contents before ingestion, in order to have the metadata required to run + verify the ingested ledgers. Additionally, allowing users to cap the number of ingested ledgers fell on the caller.

Known limitations

N/A

[Copilot]

Pull request overview

This PR extends ingest/loadtest’s LedgerBackend to support replaying synthetic ledgers from multiple zstd-compressed ledger bundle files (in order) with an optional per-file replay cap, and adds an exported helper to compute per-bundle replay lengths using the same cap/reader logic as PrepareRange.

Changes:

• Replace LedgersFilePath with LedgersFilePaths []string and add MaxLedgersPerFile uint32 to cap replay per bundle.
• Introduce a multi-file ledgerReader, plus CountLedgersPerFile / FileLedgerCount helper APIs used by PrepareRange.
• Add unit tests for counting/capping and ledger merge behavior; fix an incorrect MustV2() reference in a V1 error path.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
ingest/loadtest/ledger_backend.go	Adds multi-file synthetic ledger streaming with per-file caps and exposes per-file counting helper; adjusts PrepareRange to use the new reader.
ingest/loadtest/ledger_backend_test.go	Adds tests for counting/capping, empty reader behavior, and merge behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.