dctk

package module
v0.0.0-...-ece3ee3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 9, 2023 License: BSD-3-Clause Imports: 34 Imported by: 0

README

dctk

Test Lint CodeCov PkgGoDev

dctk implements the client part of the Direct Connect peer-to-peer system (ADC and NMDC protocols) in the Go programming language. It includes:

  • a library, that allows the creation of clients capable of interacting with hubs and other clients;
  • a series of command line utilities that make use of the library.

Direct Connect is semi-centralized peer-to-peer system in which peers connect to servers (hubs) and exchange textual messages and files. Files are indexed by computing their Tiger Tree Hash (TTH), provided by users through their file list, and searchable on a hub-basis. There exist two variants, one based on the traditional NMDC protocol (NeoModus Direct Connect) and the other based on the newer ADC protocol (Advanced Direct Connect).

This project is based on the go-dc project, that provides a base layer for building DC-related software.

Features:

  • ADC and NMDC transparent protocol support
  • Active and passive mode
  • Hub: connection with configurable try count, password authentication, keepalive, compression, encryption
  • Chat: bidirectional public and private chat
  • File search: by name or TTH, reply to requests
  • File download: by name or TTH, full or partial, on ram or disk, multiple in parallel, compression, encryption, configurable download slots, validation via TTH, client fingerprint validation
  • File upload: upload from personal share, asynchronous file indexing system, file list generation and serving, compression, encryption, configurable upload slots, tthl extension support, client fingerprint validation
  • Examples provided for every feature, comprehensive test suite, continuous integration

Note: this project uses the rolling release development model, as it is used in a production environment which requires the latest updates. The public API may suffer minor changes. The master branch is to be considered stable.

Table of contents

Library

Installation

Go ≥ 1.17 is required, and modules must be enabled (there must be a go.mod file in your project folder, that can be created with the command go mod init main). To install the library, it is enough to write its name in the import section of the source files that will use it. Go will take care of downloading the needed files:

import (
    "github.com/aler9/dctk"
)
Examples
API Documentation

https://pkg.go.dev/github.com/aler9/dctk#pkg-index

Testing

If you want to edit this library and test the results, you can you automated tests with:

make test

Command-line utilities

Installation

Go ≥ 1.17 is required. Download, compile and install the binaries with:

go get github.com/aler9/dctk/cmd/...
Usage
dc-tth [<flags>] <filepath>

Compute the Tiger Tree Hash (TTH) of a given file.

dc-search --hub=HUB --nick=NICK [<flags>] <query>

Search files and directories by name in a given hub.

dc-download --hub=HUB --nick=NICK --outdir=OUTDIR [<flags>] <user> <fpath>

Download a file or a directory from a user in a given hub.

dc-share --hub=HUB --nick=NICK [<flags>] <share>

Share a directory in a given hub.

Related projects

Hubs

Other clients

Other libraries

Standards

Documentation

Overview

Package dctk implements the client part of the Direct Connect peer-to-peer system (ADC and NMDC protocols) in the Go programming language. It allows the creation of clients that can interact with hubs and other clients, and can be used as backend to user interfaces or automatic bots.

Examples are available at https://github.com/aler9/dctk/tree/master/examples

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

type Client struct {

	// OnInitialized is called just after client initialization, before connecting to the hub
	OnInitialized func()
	// OnShareIndexed is called every time the share indexer has finished indexing the client share
	OnShareIndexed func()
	// OnHubConnected is called when the connection between client and hub has been established
	OnHubConnected func()
	// OnHubError is called when a critical error happens
	OnHubError func(err error)
	// OnHubInfo is called when an information about the hub is received
	OnHubInfo func(field HubField, value string)
	// OnHubTLS is called when a TLS connection with a hub is established
	OnHubTLS func(st tls.ConnectionState)
	// OnHubProto is called when a protocol for the hub is selected
	OnHubProto func(proto string)
	// OnPeerConnected is called when a peer connects to the hub
	OnPeerConnected func(p *Peer)
	// OnPeerUpdated is called when a peer has just updated its informations
	OnPeerUpdated func(p *Peer)
	// OnPeerDisconnected is called when a peer disconnects from the hub
	OnPeerDisconnected func(p *Peer)
	// OnMessagePublic is called when someone writes in the hub public chat.
	// When using ADC, it is also called when the hub sends a message.
	OnMessagePublic func(p *Peer, content string)
	// OnMessagePrivate is called when a private message has been received
	OnMessagePrivate func(p *Peer, content string)
	// OnSearchResult is called when a search result has been received
	OnSearchResult func(r *SearchResult)
	// OnDownloadSuccessful is called when a given download has finished
	OnDownloadSuccessful func(d *Download)
	// OnDownloadError is called when a given download has failed
	OnDownloadError func(d *Download)
	// contains filtered or unexported fields
}

Client represents a local client.

func NewClient 

func NewClient(conf ClientConf) (*Client, error)

NewClient is used to initialize a client. See ClientConf for the available options.

func (*Client) Close 

func (c *Client) Close() error

Close every open connection and stop the client.

func (*Client) Conf 

func (c *Client) Conf() ClientConf

Conf returns the configuration passed during client initialization.

func (*Client) DownloadCount 

func (c *Client) DownloadCount() int

DownloadCount returns the number of remaining downloads, queued or active.

func (*Client) DownloadFLDirectory 

func (c *Client) DownloadFLDirectory(peer *Peer, dir *FileListDirectory, savePath string) error

DownloadFLDirectory starts downloading recursively all the files inside a file list directory.

func (*Client) DownloadFLFile 

func (c *Client) DownloadFLFile(peer *Peer, file *FileListFile, savePath string) (*Download, error)

DownloadFLFile starts downloading a file given a file list entry.

func (*Client) DownloadFile 

func (c *Client) DownloadFile(conf DownloadConf) (*Download, error)

DownloadFile starts downloading a file by its Tiger Tree Hash (TTH). See DownloadConf for the options.

func (*Client) DownloadFileList 

func (c *Client) DownloadFileList(peer *Peer, savePath string) (*Download, error)

DownloadFileList starts downloading the file list of a given peer.

func (*Client) HubConnect 

func (c *Client) HubConnect()

HubConnect starts the connection to the hub. It must be called only when HubManualConnect is true.

func (*Client) MessagePrivate 

func (c *Client) MessagePrivate(dest *Peer, content string)

MessagePrivate sends a private message to a specific peer connected to the hub.

func (*Client) MessagePublic 

func (c *Client) MessagePublic(content string)

MessagePublic publishes a message in the hub public chat.

func (*Client) Peers 

func (c *Client) Peers() map[string]*Peer

Peers returns a map containing all the peers connected to current hub.

func (*Client) Run 

func (c *Client) Run()

Run starts the client and waits until the client has been terminated.

func (*Client) Safe 

func (c *Client) Safe(cb func())

Safe is used to safely execute code outside the client context. It must be used when interacting with the client outside the callbacks (i.e. inside a parallel goroutine).

func (*Client) Search 

func (c *Client) Search(conf SearchConf) error

Search starts a file search asynchronously. See SearchConf for the available options.

func (*Client) ShareAdd 

func (c *Client) ShareAdd(alias string, dpath string)

ShareAdd adds a given directory (dpath) to the client share, with the given alias, and starts indexing its subdirectories and files. if a directory with the same alias was added previously, it is replaced with the new one. OnShareIndexed is called when the indexing is finished.

func (*Client) ShareDel 

func (c *Client) ShareDel(alias string)

ShareDel removes a directory with the given alias from the client share, and starts reindexing the current share.

type ClientConf 

type ClientConf struct {
	// verbosity of the library
	LogLevel log.Level

	// turns on passive mode: it is not necessary anymore to open TCPPort, UDPPort
	// and TLSPort but functionalities are limited
	IsPassive bool
	// (optional) an explicit ip, instead of the one obtained automatically
	IP string
	// these are the 3 ports needed for active mode. They must be accessible from the
	// internet, so any router/firewall in between must be configured
	TCPPort uint
	UDPPort uint
	TLSPort uint

	// the maximum number of file to download in parallel. When this number is
	// exceeded, the other downloads are queued and started when a slot becomes available
	DownloadMaxParallel uint
	// the maximum number of file to upload in parallel
	UploadMaxParallel uint

	// set the policy regarding encryption with other peers. See EncryptionMode for options
	PeerEncryptionMode EncryptionMode

	// The hub url in the format protocol://address:port
	// supported protocols are adc, adcs, nmdc and nmdcs
	HubURL string
	// how many times attempting a connection with hub before giving up
	HubConnTries uint
	// if turned on, connection to hub is not automatic and HubConnect() must be
	// called manually
	HubManualConnect bool

	// the nickname to use in the hub and with other peers
	Nick string
	// the password associated with the nick, if requested by the hub
	Password string
	// the private ID of the user (ADC only)
	PID atypes.PID
	// an email, optional
	Email string
	// a description, optional
	Description string
	// the maximum upload speed in bytes/sec. It is not really applied, but is sent to the hub
	UploadMaxSpeed uint
	// these are used to identify the software. By default they mimic DC++
	ClientString  string
	ClientVersion string
	PkValue       string
	ListGenerator string

	// options useful only for debugging purposes
	HubDisableCompression  bool
	PeerDisableCompression bool
	HubDisableKeepAlive    bool
}

ClientConf allows to configure a client.

type Download 

type Download struct {
	// contains filtered or unexported fields
}

Download represents an in-progress file download.

func (*Download) Close 

func (d *Download) Close()

Close stops the download. OnDownloadError and OnDownloadSuccessful are not called.

func (*Download) Conf 

func (d *Download) Conf() DownloadConf

Conf returns the configuration passed at download initialization.

func (*Download) Content 

func (d *Download) Content() []byte

Content returns the downloaded file content ONLY if SavePath is not used, otherwise file content is saved directly on disk.

type DownloadConf 

type DownloadConf struct {
	// the peer from which downloading
	Peer *Peer
	// the TTH of the file to download
	TTH tiger.Hash
	// the starting point of the file part to download, in bytes
	Start uint64
	// the length of the file part. Leave zero to download the entire file
	Length int64
	// if filled, the file is saved on the desired path on disk, otherwise it is kept on RAM
	SavePath string
	// after download, do not attempt to validate the file through its TTH
	SkipValidation bool
	// contains filtered or unexported fields
}

DownloadConf allows to configure a download.

type EncryptionMode 

type EncryptionMode int

EncryptionMode contains the options regarding encryption. 

const (
	// PreferEncryption uses encryption when the two peers both support it
	PreferEncryption EncryptionMode = iota
	// DisableEncryption disables competely encryption
	DisableEncryption
	// ForceEncryption forces encryption and block interaction with peers that
	// do not support encrypton
	ForceEncryption
)

type FileList 

type FileList struct {
	XMLName   xml.Name             `xml:"FileListing"`
	Version   string               `xml:"Version,attr"`
	CID       string               `xml:"CID,attr"`
	Base      string               `xml:"Base,attr"`
	Generator string               `xml:"Generator,attr"`
	Dirs      []*FileListDirectory `xml:"Directory"`
}

FileList is a user file list, containing directories and files.

func FileListParse 

func FileListParse(in []byte) (*FileList, error)

FileListParse parses a given user file list in XML format into a FileList struct.

func (*FileList) Export 

func (fl *FileList) Export() ([]byte, error)

Export transform the FileList struct into a user file list in the XML format.

func (*FileList) GetDirectory 

func (fl *FileList) GetDirectory(dpath string) (*FileListDirectory, error)

GetDirectory returns the directory in the file list corresponding to the given path.

func (*FileList) GetFile 

func (fl *FileList) GetFile(fpath string) (*FileListFile, error)

GetFile returns the file in the file list corresponding to the given path.

type FileListDirectory 

type FileListDirectory struct {
	Name  string               `xml:"Name,attr"`
	Files []*FileListFile      `xml:"File"`
	Dirs  []*FileListDirectory `xml:"Directory"`
}

FileListDirectory is part of a user file list and represents a shared drectory.

type FileListFile 

type FileListFile struct {
	Name string     `xml:"Name,attr"`
	Size uint64     `xml:"Size,attr"`
	TTH  tiger.Hash `xml:"TTH,attr"`
}

FileListFile is part of a user file list and represents a shared file.

type HubField 

type HubField string

HubField is the key of a hub information field. 

const (
	HubName        HubField = ("name")
	HubTopic       HubField = ("topic")
	HubSoftware    HubField = ("software")
	HubVersion     HubField = ("version")
	HubDescription HubField = ("description")
)

HubField standard keys.

type Peer 

type Peer struct {
	// peer nickname
	Nick string
	// peer description (if provided)
	Description string
	// peer email (if provided)
	Email string
	// whether peer is a bot
	IsBot bool
	// whether peer is a operator
	IsOperator bool
	// client used by peer (in NMDC this could be hidden)
	Client string
	// version of client (in NMDC this could be hidden)
	Version string
	// overall size of files shared by peer
	ShareSize uint64
	// whether peer is in passive mode (in NMDC this could be hidden)
	IsPassive bool
	// peer ip (if provided by both peer and hub)
	IP string
	// contains filtered or unexported fields
}

Peer represents a remote client connected to a Hub.

type SearchConf 

type SearchConf struct {
	// the search type, defaults to SearchAny. See SearchType for all the available options
	Type SearchType
	// the minimum size of the searched file (if type is SearchAny or SearchTTH)
	MinSize uint64
	// the maximum size of the searched file (if type is SearchAny or SearchTTH)
	MaxSize uint64
	// part of a file name (if type is SearchAny), part of a directory name
	// (if type is SearchAny or SearchDirectory)
	Query string
	// file TTH (if type is SearchTTH)
	TTH tiger.Hash
}

SearchConf allows to configure a search request.

type SearchResult 

type SearchResult struct {
	// whether the search result was received in passive or active mode
	IsActive bool
	// the peer sending the result
	Peer *Peer
	// path of a file or directory matching a search request
	Path string
	// whether the result is a directory
	IsDir bool
	// size (file only in NMDC, both files and directories in ADC)
	Size uint64
	// TTH (file only)
	TTH *tiger.Hash
	// the available upload slots of the peer
	SlotAvail uint
}

SearchResult contains a single result received after a search request.

type SearchType 

type SearchType int

SearchType contains the search type. 

const (
	// SearchAny searches for a file or directory by name
	SearchAny SearchType = iota
	// SearchDirectory searches for a directory by name
	SearchDirectory
	// SearchTTH searches for a file by TTH
	SearchTTH
)

Source Files

View all Source files

Directories

Path Synopsis
cmd
dc-download
dc-download command.
 dc-download command.
dc-search
dc-search command.
 dc-search command.
dc-share
dc-share command.
 dc-share command.
dc-tth
dc-tth command.
 dc-tth command.
examples
chat-private
chat-public
connection-active
connection-passive
download-all-lists
download-directory-from-list
download-file
download-file-from-list
download-file-from-search
download-file-on-disk
download-list
download-streaming
magnet
search
share
pkg
log
Package log provides a logger.
 Package log provides a logger.
protoadc
Package protoadc provides an ADC connection implementation.
 Package protoadc provides an ADC connection implementation.
protocommon
Package protocommon contains shared elements between ADC and NMDC connections.
 Package protocommon contains shared elements between ADC and NMDC connections.
protonmdc
Package protonmdc provides a NMDC connection implementation.
 Package protonmdc provides a NMDC connection implementation.
tiger
Package tiger provides the Tiger hash.
 Package tiger provides the Tiger hash.
test-manual
client
manual client.
 manual client.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.