File Transfer

# By peer name (fire-and-forget - exits immediately)
shurli send photo.jpg home-server

# With live progress
shurli send photo.jpg home-server --follow

# With priority (jumps the queue)
shurli send photo.jpg home-server --priority

# Send a directory
shurli send ./folder home-server

# JSON output (for scripting)
shurli send photo.jpg home-server --json

shurli config set transfer.receive_mode ask

# Timed mode: open for 10 minutes then revert
shurli config set transfer.receive_mode timed --duration 10m

shurli config set transfer.receive_dir /path/to/your/dir

# View transfer inbox (pending + active)
shurli transfers

# Watch live (auto-refresh)
shurli transfers --watch

# View completed transfers
shurli transfers --history

# Accept a pending transfer
shurli accept <transfer-id>

# Accept only specific files (1-indexed)
shurli accept <transfer-id> --files 1,3,5

# Accept all except specific files
shurli accept <transfer-id> --exclude 2,4

# Accept with index ranges
shurli accept <transfer-id> --files 1-5,10,15-20

# Accept all pending
shurli accept --all

# Reject a pending transfer
shurli reject <transfer-id>

# View single transfer details (including file list)
shurli transfers <transfer-id>

# Cancel an outbound transfer
shurli cancel <transfer-id>

# Share a file with all authorized peers
shurli share add /path/to/file.pdf

# Share a directory (hidden files like .env, .git/ are excluded from downloads)
shurli share add /path/to/photos

# Share with a specific peer only
shurli share add /path/to/file.pdf --to home-server

# List your shares
shurli share list

# Remove a share
shurli share remove /path/to/file.pdf

# Browse a peer's shared files
shurli browse home-server

# Download a specific file from a peer's shares
shurli download home-server:shareID/document.pdf

# Download an entire shared directory
shurli download home-server:shareID

# Download a subdirectory
shurli download home-server:shareID/photos/2024

# List files in a shared directory (preview before downloading)
shurli download home-server:shareID --list

# Download only specific files from a shared directory (1-indexed)
shurli download home-server:shareID --files 1,3,10-20

# Download all except specific files
shurli download home-server:shareID --exclude 2,4

shurli download large-file.zip home-server --multi-peer --peers home-server,laptop

curl -X POST --unix-socket ~/.shurli/shurli.sock \
  http://localhost/v1/send \
  -H "Cookie: auth=$(cat ~/.shurli/.daemon-cookie)" \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/absolute/path/to/file.pdf", "peer": "home-server"}'

{
  "transfer_id": "xfer-a1b2c3d4e5f6"
}

curl --unix-socket ~/.shurli/shurli.sock \
  "http://localhost/v1/transfers/xfer-a1b2c3d4e5f6" \
  -H "Cookie: auth=$(cat ~/.shurli/.daemon-cookie)"

curl --unix-socket ~/.shurli/shurli.sock \
  http://localhost/v1/transfers \
  -H "Cookie: auth=$(cat ~/.shurli/.daemon-cookie)"

import "github.com/shurlinet/shurli/plugins/filetransfer"

type FileTransferPlugin struct {
    // unexported fields
}

func New() *FileTransferPlugin

type PluginConfig struct {
    ReceiveDir        string   `yaml:"receive_dir"`
    MaxFileSize       int64    `yaml:"max_file_size"`
    ReceiveMode       string   `yaml:"receive_mode"`
    TimedDuration     string   `yaml:"timed_duration"`
    Compress          *bool    `yaml:"compress"`
    Notify            string   `yaml:"notify"`
    NotifyCommand     string   `yaml:"notify_command"`
    LogPath           string   `yaml:"log_path"`
    MaxConcurrent     int      `yaml:"max_concurrent"`
    RateLimit         int      `yaml:"rate_limit"`
    BrowseRateLimit   int      `yaml:"browse_rate_limit"`
    QueueFile         string   `yaml:"queue_file"`
    MultiPeerEnabled  *bool    `yaml:"multi_peer_enabled"`
    MultiPeerMaxPeers int      `yaml:"multi_peer_max_peers"`
    MultiPeerMinSize  int64    `yaml:"multi_peer_min_size"`
    ErasureOverhead     *float64 `yaml:"erasure_overhead"`
    MaxInboundTransfers int      `yaml:"max_inbound_transfers"`
    MaxPerPeerTransfers int      `yaml:"max_per_peer_transfers"`
    GlobalRateLimit     int      `yaml:"global_rate_limit"`
    MaxQueuedPerPeer  int      `yaml:"max_queued_per_peer"`
    MinSpeedBytes     int      `yaml:"min_speed_bytes"`
    MinSpeedSeconds   int      `yaml:"min_speed_seconds"`
    MaxTempSize       int64    `yaml:"max_temp_size"`
    TempFileExpiry    string   `yaml:"temp_file_expiry"`
    BandwidthBudget   string   `yaml:"bandwidth_budget"`
    DefaultPersistent *bool    `yaml:"default_persistent"`
}

const (
    TransferProtocol  = "/shurli/file-transfer/2.0.0"
    BrowseProtocol    = "/shurli/file-browse/1.0.0"
    DownloadProtocol  = "/shurli/file-download/1.0.0"
    MultiPeerProtocol = "/shurli/file-multi-peer/1.0.0"
    CancelProtocol    = "/shurli/transfer-cancel/1.0.0"
)

func RegisterCancelHandler(h host.Host, ts *TransferService)

func UnregisterCancelHandler(h host.Host)

const (
    RejectReasonNone  byte = 0x00 // no reason disclosed
    RejectReasonSpace byte = 0x01 // insufficient disk space
    RejectReasonBusy  byte = 0x02 // receiver busy
    RejectReasonSize  byte = 0x03 // file too large
)

type ReceiveMode string

const (
    ReceiveModeOff      ReceiveMode = "off"      // reject all
    ReceiveModeContacts ReceiveMode = "contacts"  // auto-accept from authorized peers (default)
    ReceiveModeAsk      ReceiveMode = "ask"       // queue for manual approval
    ReceiveModeOpen     ReceiveMode = "open"      // accept from any authorized peer
    ReceiveModeTimed    ReceiveMode = "timed"     // temporarily open, reverts after duration
)

type TransferPriority int

const (
    PriorityLow    TransferPriority = 0
    PriorityNormal TransferPriority = 1
    PriorityHigh   TransferPriority = 2
)

type TransferConfig struct {
    ReceiveDir        string              // directory for received files
    MaxSize           int64               // max file size (0 = unlimited)
    ReceiveMode       ReceiveMode         // default: contacts
    Compress          bool                // enable zstd compression (default: true)
    ErasureOverhead   float64             // RS parity overhead (0.10 = 10%, 0 = disabled)
    LogPath           string              // transfer event log path (empty = disabled)
    Notify            string              // "none" (default), "desktop", "command"
    NotifyCommand     string              // command template for "command" mode
    MaxConcurrent     int                 // max concurrent outbound transfers (default: 5)
    MultiPeerEnabled  bool                // enable multi-peer downloads (default: true)
    MultiPeerMaxPeers int                 // max peers for multi-peer (default: 4)
    MultiPeerMinSize  int64               // min file size for multi-peer (default: 10 MB)
    RateLimit         int                 // max requests per peer per minute (default: 600)
    GlobalRateLimit   int                 // max total inbound requests per minute (default: 600)
    MaxQueuedPerPeer  int                 // max pending+active per peer (default: 10)
    MinSpeedBytes     int                 // min transfer speed bytes/sec (default: 1024)
    MinSpeedSeconds   int                 // speed check window seconds (default: 30)
    MaxTempSize       int64               // max total .tmp size (default: 1GB)
    TempFileExpiry    time.Duration       // auto-expire old .tmp files (default: 1h)
    BandwidthBudget   int64               // max bytes per peer per hour (default: 100MB)
    PeerBudgetFunc    func(string) int64  // per-peer budget override (-1=unlimited, 0=global)
    FailureBackoffThreshold int           // fails to trigger block (default: 3)
    FailureBackoffWindow    time.Duration // failure counting window (default: 5m)
    FailureBackoffBlock     time.Duration // block duration (default: 60s)
    QueueFile         string              // persisted queue path (empty = disabled)
    QueueHMACKey      []byte              // 32-byte HMAC key for queue integrity
    GrantChecker      sdk.RelayGrantChecker // relay grant checker for budget/time checks
    ConnsToPeer       func(peer.ID) []network.Conn // returns connections to a peer
    HasVerifiedLANConn func(peer.ID) bool // true if peer has live mDNS-verified LAN connection
}

func NewTransferService(cfg TransferConfig, metrics *sdk.Metrics, events *sdk.EventBus) (*TransferService, error)

type TransferService struct {
    // unexported fields
}

func (ts *TransferService) SendFile(s network.Stream, filePath string, opts ...SendOptions) (*TransferProgress, error)

func (ts *TransferService) SendDirectory(ctx context.Context, dirPath string, openStream func() (network.Stream, error), opts SendOptions) ([]*TransferProgress, error)

func (ts *TransferService) SubmitSend(filePath, peerID string, priority TransferPriority, openStream streamOpener, opts SendOptions) (*TransferProgress, error)

func (ts *TransferService) HandleInbound() sdk.StreamHandler

func (ts *TransferService) ReceiveFrom(s network.Stream, remotePath, destDir string, sel ...*FileSelection) (*TransferProgress, error)

func (ts *TransferService) ProbeRootHash(openStream func() (network.Stream, error), remotePath string) ([32]byte, error)

func RequestList(s network.Stream, remotePath string) ([]fileEntry, int64, error)

func (ts *TransferService) GetTransfer(id string) (*TransferProgress, bool)
func (ts *TransferService) ListTransfers() []TransferSnapshot
func (ts *TransferService) CancelTransfer(id string) error
func (ts *TransferService) CleanTempFiles() (int, int64)
func (ts *TransferService) Close() error

func (ts *TransferService) SetReceiveMode(mode ReceiveMode)
func (ts *TransferService) SetTimedMode(duration time.Duration) error
func (ts *TransferService) TimedModeRemaining() time.Duration
func (ts *TransferService) GetReceiveMode() ReceiveMode
func (ts *TransferService) SetReceiveDir(dir string)
func (ts *TransferService) SetCompress(enabled bool)
func (ts *TransferService) SetMaxSize(maxBytes int64)
func (ts *TransferService) SetNotifyMode(mode string)
func (ts *TransferService) SetNotifyCommand(cmd string)
func (ts *TransferService) ReceiveDir() string

type MultiPeerStreamOpener func(peerID peer.ID) (network.Stream, error)

func (ts *TransferService) MultiPeerEnabled() bool
func (ts *TransferService) MultiPeerMaxPeers() int
func (ts *TransferService) MultiPeerMinSize() int64
func (ts *TransferService) HandleMultiPeerRequest() sdk.StreamHandler
func (ts *TransferService) DownloadMultiPeer(ctx context.Context, rootHash [32]byte, peers []peer.ID, openStream MultiPeerStreamOpener, destDir string) (*TransferProgress, error)

func (ts *TransferService) RegisterHash(rootHash [32]byte, localPath string)
func (ts *TransferService) LookupHash(rootHash [32]byte) (string, bool)

func (ts *TransferService) LogPath() string
func (ts *TransferService) FlushQueue()
func (ts *TransferService) RequeuePersisted(streamFactory func(peerID string) func() (network.Stream, error))

func (ts *TransferService) ListPending() []PendingTransfer
func (ts *TransferService) AcceptTransfer(id, dest string, acceptedFiles []int) error
func (ts *TransferService) RejectTransfer(id string, reason byte) error

type TransferProgress struct {
    ID              string       `json:"id"`
    Filename        string       `json:"filename"`
    Size            int64        `json:"size"`
    Transferred     int64        `json:"transferred"`
    ChunksTotal     int          `json:"chunks_total"`
    ChunksDone      int          `json:"chunks_done"`
    Compressed      bool         `json:"compressed"`
    CompressedSize  int64        `json:"compressed_size,omitempty"`
    ErasureParity   int          `json:"erasure_parity,omitempty"`
    ErasureOverhead float64      `json:"erasure_overhead,omitempty"`
    StreamProgress  []StreamInfo `json:"stream_progress,omitempty"`
    PeerID          string       `json:"peer_id"`
    Direction       string       `json:"direction"`
    Status          string       `json:"status"`
    StartTime       time.Time    `json:"start_time"`
    Done            bool         `json:"done"`
    Error           string       `json:"error,omitempty"`
}

func (p *TransferProgress) Snapshot() TransferSnapshot
func (p *TransferProgress) Sent() int64

PendingFiles []PendingFileInfo `json:"pending_files,omitempty"`

type StreamInfo struct {
    ChunksDone int   `json:"chunks_done"`
    BytesDone  int64 `json:"bytes_done"`
}

type PendingTransfer struct {
    ID       string    `json:"id"`
    Filename string    `json:"filename"`
    Size     int64     `json:"size"`
    PeerID   string    `json:"peer_id"`
    Time     time.Time `json:"time"`

    // unexported: files []fileEntry, hasErasure bool, decision chan
}

type FileSelection struct {
    Include []int // accept ONLY these file indices (0-indexed)
    Exclude []int // accept all EXCEPT these file indices (0-indexed)
}

func (s *FileSelection) resolve(fileCount int) ([]int, error)

type SendOptions struct {
    NoCompress           bool         // disable compression for this transfer
    Streams              int          // parallel stream count (0 = adaptive default based on transport)
    StreamOpener         streamOpener // opens additional streams for parallel transfer
    RelativeName         string       // override manifest filename (for directory transfer)
    RateLimitBytesPerSec int64        // per-transfer send rate limit (0 = use service default)
    SkipHidden           bool         // skip dot-prefixed files/dirs in directory walks (#41)
    OnComplete           func()       // called when send goroutine exits (serving concurrency tracking)
}

type ShareRegistry struct {
    // unexported fields
}

func NewShareRegistry() *ShareRegistry

func LoadShareRegistry(path string) (*ShareRegistry, error)

func (r *ShareRegistry) SetPersistPath(path string)
func (r *ShareRegistry) SetHMACKey(key []byte)
func (r *ShareRegistry) SetBrowseRateLimit(maxPerMin int)

func (r *ShareRegistry) Share(path string, peers []peer.ID, persistent bool) error
func (r *ShareRegistry) Unshare(path string) error
func (r *ShareRegistry) DenyPeer(path string, peerID peer.ID) error
func (r *ShareRegistry) ListShares(forPeer *peer.ID) []*ShareEntry
func (r *ShareRegistry) LookupShare(path string) (*ShareEntry, bool)
func (r *ShareRegistry) LookupShareByID(shareID string, peerID peer.ID) (*ShareEntry, bool)
func (r *ShareRegistry) IsPathShared(path string, peerID peer.ID) bool
func (r *ShareRegistry) SavePersistent(path string) error

func (r *ShareRegistry) BrowseForPeer(peerID peer.ID) []BrowseEntry
func (r *ShareRegistry) HandleBrowse() sdk.StreamHandler
func (r *ShareRegistry) HandleDownload(ts *TransferService) sdk.StreamHandler

type ShareEntry struct {
    ID         string           `json:"id"`
    Path       string           `json:"path"`
    Name       string           `json:"name"`
    Peers      map[peer.ID]bool `json:"-"`
    PeerIDs    []string         `json:"peers"`
    Persistent bool             `json:"persistent"`
    SharedAt   time.Time        `json:"shared_at"`
    IsDir      bool             `json:"is_dir"`
}

type BrowseEntry struct {
    Name    string `json:"name"`
    Path    string `json:"path"`
    ShareID string `json:"share_id"`
    Size    int64  `json:"size"`
    IsDir   bool   `json:"is_dir"`
    ModTime int64  `json:"mod_time"`
}

type BrowseResult struct {
    Entries []BrowseEntry `json:"entries"`
    Error   string        `json:"error,omitempty"`
}

type HashProbeResult struct {
    RootHash   [32]byte
    TotalSize  int64
    ChunkCount uint32
}

func BrowsePeer(s network.Stream, subPath string) (*BrowseResult, error)
func RequestDownload(s network.Stream, remotePath string) (io.Reader, error)
func RequestProbe(s network.Stream, remotePath string) (*HashProbeResult, error)

type TransferQueue struct {
    // unexported fields
}

func NewTransferQueue(maxActive int) *TransferQueue
func (q *TransferQueue) Enqueue(filePath, peerID, direction string, priority TransferPriority) (string, error)
func (q *TransferQueue) Dequeue() *QueuedTransfer
func (q *TransferQueue) Complete(id string)
func (q *TransferQueue) Requeue(id, filePath, peerID, direction string, priority TransferPriority)
func (q *TransferQueue) Cancel(id string) bool
func (q *TransferQueue) Pending() []*QueuedTransfer
func (q *TransferQueue) ActiveCount() int

type QueuedTransfer struct {
    ID        string           `json:"id"`
    FilePath  string           `json:"file_path"`
    PeerID    string           `json:"peer_id"`
    Priority  TransferPriority `json:"priority"`
    Direction string           `json:"direction"`
    QueuedAt  time.Time        `json:"queued_at"`
}

type DirectoryTransfer struct {
    RootDir   string
    Files     []dirFileEntry
    TotalSize int64
}

func WalkDirectory(dirPath string) (*DirectoryTransfer, error)
func (d *DirectoryTransfer) RegularFiles() []dirFileEntry

type TransferEvent struct {
    Timestamp     time.Time `json:"timestamp"`
    EventType     string    `json:"event_type"`
    Direction     string    `json:"direction"`
    PeerID        string    `json:"peer_id"`
    FileName      string    `json:"file_name"`
    FileSize      int64     `json:"file_size,omitempty"`
    BytesDone     int64     `json:"bytes_done,omitempty"`
    Error         string    `json:"error,omitempty"`
    Duration      string    `json:"duration,omitempty"`
    AcceptedFiles int       `json:"accepted_files,omitempty"` // selective rejection: accepted file count
    TotalFiles    int       `json:"total_files,omitempty"`    // selective rejection: total file count
}

const (
    EventLogRequestReceived   = "request_received"
    EventLogAccepted          = "accepted"
    EventLogRejected          = "rejected"
    EventLogStarted           = "started"
    EventLogProgress25        = "progress_25"
    EventLogProgress50        = "progress_50"
    EventLogProgress75        = "progress_75"
    EventLogCompleted         = "completed"
    EventLogFailed            = "failed"
    EventLogResumed           = "resumed"
    EventLogCancelled         = "cancelled"
    EventLogSpamBlocked       = "spam_blocked"
    EventLogDiskSpaceRejected = "disk_space_rejected"
    EventLogMultiPeerRejected = "multi_peer_rejected"
    EventLogPathFailover      = "path_failover"
)

type TransferLogger struct {
    // unexported fields
}

func NewTransferLogger(path string) (*TransferLogger, error)
func (l *TransferLogger) Log(event TransferEvent)
func (l *TransferLogger) Close() error
func ReadTransferEvents(path string, max int) ([]TransferEvent, error)

type TransferNotifier struct {
    // unexported fields
}

func NewTransferNotifier(mode, command string) *TransferNotifier
func (n *TransferNotifier) SetMode(mode string)
func (n *TransferNotifier) SetCommand(cmd string)
func (n *TransferNotifier) Notify(from, fileName string, fileSize int64) error

type Chunk struct {
    Data   []byte
    Hash   [32]byte
    Offset int64
}

func ChunkTarget(fileSize int64) (minSize, avgSize, maxSize int)

func ChunkReader(r io.Reader, fileSize int64, cb func(Chunk) error) error

func RejectReasonString(reason byte) string

func SanitizeDisplayName(name string) string

type SendRequest struct {
    Path       string `json:"path"`
    Peer       string `json:"peer"`
    NoCompress bool   `json:"no_compress"`
    Streams    int    `json:"streams"`
    Priority   string `json:"priority"`
    RateLimit  string `json:"rate_limit"` // send rate limit e.g. "100M" (empty = service default)
}

type SendResponse struct {
    TransferID string `json:"transfer_id"`
    Filename   string `json:"filename"`
    Size       int64  `json:"size"`
    PeerID     string `json:"peer_id"`
}

type TransferAcceptRequest struct {
    Dest    string `json:"dest,omitempty"`    // override receive directory
    Files   []int  `json:"files,omitempty"`   // 0-indexed: accept ONLY these files (nil = all)
    Exclude []int  `json:"exclude,omitempty"` // 0-indexed: accept all EXCEPT these (nil = none)
}

type TransferRejectRequest struct {
    Reason string `json:"reason,omitempty"`
}

type PendingTransferInfo struct {
    ID         string            `json:"id"`
    Filename   string            `json:"filename"`
    Size       int64             `json:"size"`
    PeerID     string            `json:"peer_id"`
    Time       string            `json:"time"`
    FileCount  int               `json:"file_count"`            // total files in transfer
    Files      []PendingFileInfo `json:"files,omitempty"`       // per-file info for selective rejection
    HasErasure bool              `json:"has_erasure,omitempty"` // sender uses erasure coding (gates selective rejection)
}

type PendingFileInfo struct {
    Index int    `json:"index"` // 0-indexed position in file table
    Path  string `json:"path"`  // relative path (sanitized)
    Size  int64  `json:"size"`  // file size in bytes
}

type ShareRequest struct {
    Path       string   `json:"path"`
    Peers      []string `json:"peers,omitempty"`
    Persistent *bool    `json:"persistent,omitempty"`
}

type UnshareRequest struct {
    Path string `json:"path"`
}

type ShareDenyRequest struct {
    Path string `json:"path"` // shared path
    Peer string `json:"peer"` // peer name or ID to remove
}

type ShareInfo struct {
    Path       string   `json:"path"`
    Peers      []string `json:"peers,omitempty"`
    Persistent bool     `json:"persistent"`
    IsDir      bool     `json:"is_dir"`
    SharedAt   string   `json:"shared_at"`
}

type BrowseRequest struct {
    Peer    string `json:"peer"`
    SubPath string `json:"sub_path,omitempty"`
}

type BrowseResponse struct {
    Entries []BrowseEntry `json:"entries"`
    Error   string        `json:"error,omitempty"`
}

type DownloadRequest struct {
    Peer       string   `json:"peer"`
    RemotePath string   `json:"remote_path"`
    LocalDest  string   `json:"local_dest"`
    MultiPeer  bool     `json:"multi_peer,omitempty"`
    ExtraPeers []string `json:"extra_peers,omitempty"`
    Files      []int    `json:"files,omitempty"`   // 0-indexed: download ONLY these files
    Exclude    []int    `json:"exclude,omitempty"` // 0-indexed: download all EXCEPT these
    List       bool     `json:"list,omitempty"`    // list files without downloading (#41)
}

type DownloadResponse struct {
    TransferID string `json:"transfer_id"`
    FileName   string `json:"filename"`
    FileSize   int64  `json:"file_size"`
    PeersUsed  int    `json:"peers_used,omitempty"` // multi-peer peer count
}

type ListFilesResponse struct {
    Files     []ListFileEntry `json:"files"`
    TotalSize int64           `json:"total_size"`
}

type ListFileEntry struct {
    Index int    `json:"index"` // 1-indexed
    Path  string `json:"path"`
    Size  int64  `json:"size"`
}

const (
    maxFilenameLen         = 4096     // max filename length in bytes
    maxFileSize            = 1 << 40  // 1 TB max single file
    maxChunkCount          = 1 << 20  // 1M chunks max per transfer
    maxManifestSize        = 40 << 20 // 40 MB max manifest wire size
    maxChunkWireSize       = 4 << 20  // 4 MB max single chunk on wire
    maxDecompressedChunk   = 8 << 20  // 8 MB max decompressed chunk
    maxFileCount           = 65535    // max files per transfer (uint16 wire format)
    maxConcurrentTransfers = 10       // global inbound transfer limit
    maxPerPeerTransfers    = 3        // per-peer inbound limit
    maxTrackedTransfers    = 10000    // max tracked transfer entries
    maxGlobalServing       = 10       // global download-serving goroutine limit (#41)
    maxPerPeerServing      = 3        // per-peer download-serving limit (#41)
)