/ 
Net-BitTorrent-v2.0.0
River stage zero No dependents
⭐ Starred 13 GitHub stars
/ Net::BitTorrent::Storage::File

NAME

Net::BitTorrent::Storage::File - Individual File Handler with Merkle Tree Support

SYNOPSIS

use Net::BitTorrent::Storage::File;

my $file = Net::BitTorrent::Storage::File->new(
    path        => 'downloads/ubuntu.iso',
    size        => 2147483648,
    pieces_root => $sha256_merkle_root
);

# Read/Write
$file->write( 0, $data );
my $chunk = $file->read( 0, 16384 );

# Verify
my $valid = $file->verify_block( 0, $data );

DESCRIPTION

This class manages a single file on disk, handling sparse file allocation, Merkle tree verification (BEP 52), and raw I/O.

In BitTorrent v2 (BEP 52), every file has its own Merkle tree. This class manages the mapping of block indices to Merkle tree leaves, ensuring that every 16KiB chunk written to disk is cryptographically verified against the swarm's trusted pieces root.

METHODS

new( %params )

Creates a new File handler object.

my $file = Net::BitTorrent::Storage::File->new(
    path => $path,
    size => $size
);

Expected parameters:

path

The file system path to the file.

size

The expected size of the file in bytes.

pieces_root - optional

The 32-byte binary SHA-256 Merkle root of the file.

piece_size - optional

The BitTorrent piece size for this file.

verify_block( $index, $data )

Verifies a 16KiB block against the file's Merkle root.

my $valid = $file->verify_block( 0, $data );

Calculates the SHA-256 hash of $data and inserts it into the file's internal Merkle tree at block index $index. Returns true if the updated tree root matches the expected pieces_root.

Expected parameters:

$index

The zero-based block index within the file.

$data

The 16KiB block of data.

verify_block_audit( $index, $data, $audit_path )

Verifies a block using an audit path (branch nodes).

my $valid = $file->verify_block_audit( 0, $data, $audit );

Verifies a block using a provided audit path (a list of sibling hashes). This allows verifying data even if the rest of the Merkle tree has not been populated yet.

Expected parameters:

$index

The block index.

$data

The block data.

$audit_path

An array reference of hashes representing the branch nodes.

verify_piece_v2( $index, $data, $expected_hash )

Verifies a full BitTorrent v2 piece.

my $valid = $file->verify_piece_v2( 0, $data, $hash );

Expected parameters:

$index

The piece index within the file.

$data

The full piece data.

$expected_hash

The 32-byte binary SHA-256 hash from the piece layer.

read( $offset, $length )

Reads data from the file.

my $data = $file->read( 0, 16384 );

Reads $length bytes from the file starting at $offset. Returns the binary data or undef if the file does not exist.

Expected parameters:

$offset

The byte offset.

$length

The number of bytes to read.

write( $offset, $data )

Writes data to the file.

$file->write( 0, $data );

Writes the binary string $data to the file at $offset. Automatically creates the file and any parent directories if they are missing.

Expected parameters:

$offset

The byte offset.

$data

The data string to write.

dump_state( )

Exports the file's Merkle tree state.

my $state = $file->dump_state();

load_state( $state )

Restores the Merkle tree state.

$file->load_state( $state );

Expected parameters:

$state

The state hash reference.

path( )

Returns the Path::Tiny object for the file.

size( )

Returns the file size in bytes.

pieces_root( )

Returns the 32-byte Merkle root.

piece_size( )

Returns the configured piece size.

merkle( )

Returns the Digest::Merkle::SHA256 object.

AUTHOR

Sanko Robinson <sanko@cpan.org>

COPYRIGHT

Copyright (C) 2008-2026 by Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.