README
¶
torrent/fs
Package torrentfs exposes a torrent client as a read-only filesystem.
It is FUSE-library-agnostic: the core types (TorrentFS, Backend,
Unmounter) and helpers live here; concrete FUSE backends are in separate
modules:
| Repo | FUSE library |
|---|---|
| anacrolix/og-torrentfs | anacrolix/fuse — supports macFUSE and fuse-t on macOS, fusermount on Linux |
| anacrolix/hanwen-torrentfs | hanwen/go-fuse/v2 — uses macFUSE socket protocol on macOS (incompatible with fuse-t) |
Changing this package
- Interface changes (
Backend,Unmounter, or any exported type/function used by backends): update both backend repos and verify their CI passes. - Helper changes (
traverse.go,fileread.go): check both backends still compile and their tests pass. - Test suite changes (
tfstest/): both backends import and runtfstest.RunTestSuite; update them if theMountFuncsignature orRunTestSuiteAPI changes. - go.mod / dependency changes: backends pin a specific commit of this
module via a pseudo-version (no
replacedirectives). After merging, update therequireline in each backend'sgo.modto the new commit hash.
Documentation
¶
Overview ¶
Package torrentfs exposes a torrent client as a read-only filesystem.
It is FUSE-library-agnostic: the core types (TorrentFS, Backend, Unmounter) and helpers live here; concrete FUSE backends are in separate modules:
- github.com/anacrolix/og-torrentfs – uses github.com/anacrolix/fuse
- github.com/anacrolix/hanwen-torrentfs – uses github.com/hanwen/go-fuse/v2
Filesystem traversal ¶
traverse.go provides the directory-listing and lookup helpers used by every backend:
- RootEntries / RootLookup – enumerate/find top-level torrent entries
- DirEntries / DirLookup – enumerate/find entries inside a torrent directory
File reading ¶
fileread.go provides ReadFile, which reads a range of bytes from a torrent file. It blocks until data is available, the context is cancelled, or Destroy is called on the TorrentFS.
Testing ¶
The tfstest sub-package contains a shared integration test suite (RunTestSuite) that any backend can run against its MountFunc.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrDestroyed = errors.New("torrentfs: filesystem destroyed")
ErrDestroyed is returned by ReadFile when the filesystem has been destroyed.
Functions ¶
func ReadFile ¶
func ReadFile(ctx context.Context, tfs *TorrentFS, f *torrent.File, dest []byte, off int64) (int, error)
ReadFile reads len(dest) bytes at offset off from torrent file f. It blocks until data is available, the context is cancelled, or the filesystem is destroyed. It returns (n, ErrDestroyed) if the filesystem is destroyed, (n, ctx.Err()) if the context is cancelled, or (n, nil) on success.
Types ¶
type Backend ¶
Backend is implemented by FUSE library integrations (e.g. hanwen-torrentfs, og-torrentfs). It mounts a TorrentFS at a directory and returns an Unmounter.
type DirEntry ¶
DirEntry describes a single filesystem entry returned by a directory listing.
func DirEntries ¶
DirEntries returns directory entries for a sub-directory at path within t.
func RootEntries ¶
RootEntries returns directory entries for the root of tfs.
type TorrentFS ¶
TorrentFS is the shared state for a torrent-backed filesystem. It holds no FUSE-library-specific code; mount it via a Backend.
func (*TorrentFS) Destroy ¶
func (tfs *TorrentFS) Destroy()
Destroy signals all blocked reads to abort and marks the FS as destroyed.
func (*TorrentFS) Destroyed ¶
func (tfs *TorrentFS) Destroyed() <-chan struct{}
Destroyed returns a channel that is closed when Destroy is called.
func (*TorrentFS) TrackBlockedRead ¶
func (tfs *TorrentFS) TrackBlockedRead() (done func())
TrackBlockedRead is called by backend read implementations when they block waiting for torrent data. The returned func must be called when the read completes or is cancelled.
type TorrentLookup ¶
type TorrentLookup struct {
IsDir bool
Torrent *torrent.Torrent
File *torrent.File // nil when IsDir is true
Path string // full path within the torrent
}
TorrentLookup is the result of a successful lookup in a torrent filesystem.
func DirLookup ¶
func DirLookup(t *torrent.Torrent, path, name string) (TorrentLookup, bool)
DirLookup looks up name in the sub-directory at path within torrent t.
func RootLookup ¶
func RootLookup(tfs *TorrentFS, name string) (TorrentLookup, bool)
RootLookup looks up name in the root of tfs.
Source Files
Directories