Add optional hash-based directories for torrent payloads

[gl00ten]

Fixes:
#12842

Summary

This PR adds an opt-in option to give each torrent payload a deterministic top-level directory based on the torrent hash.

For example:

My Torrent [qb-1a2b3c4d5e6f]/

The goal is to prevent unrelated torrents with the same payload name from writing into the same directory.

Screenshots:

New option in settings:

New item in right click menu:

New style for directories. Guarantees uniqueness and sameness across sessions.

New option to preserve original name (for cross seeding) and what not:

Behaviour

When hash naming is enabled:

• New torrents receive a top-level directory with a short hash suffix.
• Single-file torrents are also placed inside their own hashed directory.
• The generated name is deterministic and remains the same when the torrent is restored.
• Users can preserve the original payload name for individual torrents when intentional path sharing or cross-seeding is required.

Existing torrents can be converted through the context-menu action.

If the target hashed directory already exists, qBittorrent warns the user that the entire directory will be permanently deleted and replaced. Nothing is deleted unless the user confirms.

The existing directory is not merged and no alternative names such as (1) are generated.

Motivation

Two torrents can have the same top-level payload name while containing different data. When both use the same save location, their files may overlap or overwrite one another.

Adding a deterministic hash suffix gives every torrent a unique and predictable payload directory while keeping the original name recognisable.

(personally, I got tired of IO errors on torrents with the same name)

Testing

I manually tested:

• Adding and downloading single-file torrents.
• Converting existing single-file torrents.
• Filename collisions involving single-file torrents.
• Filename collisions involving multi-file torrents.
• The warning shown when the target hashed directory already exists.
• Confirming the warning deletes and replaces the existing hashed directory.
• Cancelling the warning leaves the existing directory unchanged.

Unit tests were also added for the payload-name generation logic, including single-file, multi-file, rootless, Unicode, long-name and idempotence cases.

Edit:

This also fixes the magnet-versus-.torrent naming inconsistency. Magnet links may initially have only a display name and incomplete metadata, but once the metadata is available, qBittorrent uses the torrent’s canonical name and torrent ID to generate the payload path. As a result, adding the same torrent through a magnet link or a .torrent file should produce the same deterministic hashed folder name instead of creating different directories based on the magnet display name. The only unrelated edge case is duplicate detection between unresolved v1-only and v2-only magnets for the same hybrid torrent, since qBittorrent cannot know they refer to the same torrent until metadata is received.

[HanabishiRecca]

I like the idea, but don't really like the implementation.
It feels like to me it should be just another option for torrent content layout. So it would be something like

• Original
• Create subfolder
• Create unique subfolder
• Don't create subfolder

Also maybe just appending full hash but without the qb- prefix would be better?

[glassez]

It feels like to me it should be just another option for torrent content layout. So it would be something like

• Original
• Create subfolder
• Create unique subfolder
• Don't create subfolder

This idea has also crossed my mind.

[gl00ten]

@HanabishiRecca @glassez

Sure, I can move it into the existing content-layout dropdown.

The qb- was meant to show that qBittorrent added the suffix, but removing it would make the scheme easier for other clients to adopt.

My only concern with using the full hash is path length: v1 adds 40 characters and v2 up to 64, which may cause problems with long names, especially on Windows.

I think 12 hex characters is more than enough in practice, with roughly a 3.55e-15 (1 in trillions) collision probability. And then only for torrents with the same payload name.

I also tested it with cross-seeding, and it worked correctly:

#12842

[HanabishiRecca]

My only concern with using the full hash is path length: v1 adds 40 characters and v2 up to 64, which may cause problems with long names, especially on Windows.

qBittorrent enables long paths on Windows (allows up to 10k path length), so it shouldn't be a problem. The problem could be with the dir name itself though.

I think 12 hex characters is more than enough in practice

Maybe. But either way you need to ensure that the combined name is shorter than 255 chars/bytes depending on a platform, and truncate torrent names somehow if necessary.
As in

qBittorrent/src/base/utils/fs.cpp

Lines 243 to 246 in 3c2a58e

	#ifdef Q_OS_WIN
	// Windows restricts file names to 255 characters
	if (name.length() > 255)
	return false;

qBittorrent/src/base/utils/fs.cpp

Lines 255 to 258 in 3c2a58e

	#else
	// Non-Windows systems limit file name lengths to 255 bytes in UTF-8 encoding
	if (name.toUtf8().length() > 255)
	return false;

Or maybe keeping only hashes as names is also an option.

[stalkerok]

Related

• Avoid torrent root path collisions #24428