README
¶
Ytl
Yggdrasil Transports Lib
Documentation
¶
Overview ¶
Package ytl provides top-level logic for working with Yggdrasil network transport connections.
Although the package provides access to low-level primitives, but most clients will need only the basic interface provided by the ConnManager, ProxyManager, DeduplicationManager, YggConn and YggListener types.
In the basic case, to get started, you need to create a ConnManager object.
manager := ytl.NewConnManager( context.Background(), // Or your context here nil, nil, nil, nil, )
If you want to use a specific private and public key pair, you need to pass your private key to the ConnManager constructor. If key is not passed, a new random key will be generated for each connection.
_, priv, _ := ed25519.GenerateKey(nil) manager := ytl.NewConnManager( context.Background(), priv, // Pass your ygg private key here nil, nil, nil, )
If you want to enable connetions deduplication ( aka restriction for more than one connection to each node), you need to pass DeduplicationManager object with those params to ConnManager constructor.
( See more info in DeduplicationManager type documentation. )
manager := ytl.NewConnManager( context.Background(), nil, nil, ytl.NewDeduplicationManager(true, nil), nil, )
If you want to allow only subset of nodes to strait connections, you need to pass slice of there public keys to ConnManager constructor.
pub1, _, _ := ed25519.GenerateKey(nil)
pub2, _, _ := ed25519.GenerateKey(nil)
pub3, _, _ := ed25519.GenerateKey(nil)
manager := ytl.NewConnManager(
context.Background(),
nil,
nil,
nil,
ytl.static.AllowList[]{
pub1,
pub2,
pub3,
},
)
If you want to proxify connections to certain hosts via socks proxy, you need to pass the ProxyManager object with the appropriate rules to the ConnManager constructor.
( See more info in ProxyManager type documentation. )
torProxy, _ := url.Parse("socks://localhost:9050")
i2pProxy, _ := url.Parse("socks://localhost:9060")
manager := ytl.NewConnManager(
context.Background(),
nil,
ytl.NewProxyManager(
nil, // Default proxy here or nil
[]ytl.ProxyMapping{
{
// Proxify rule for tor nodes
HostRegexp: *regexp.MustCompile(`\.onion$`),
Proxy: torProxy,
},
{
// Proxify rule for i2p nodes
HostRegexp: *regexp.MustCompile(`\.i2p$`),
Proxy: i2pProxy,
},
},
),
nil,
nil,
)
After you have created the ConnManager object, you can use it to open outgoing connections with the Connect method ( ConnectCtx and ConnectTimeout methods are also available ).
addr, _ := url.Parse("tcp://0.0.0.0:1337")
conn, err := manager.Connect(addr)
if err != nil { panic(err) }
Returned YggConn object has interface similar to net.Conn but with extra methods. So it can be used wherever net.Conn is used.
If you want to listen incoming connections you need to use ConnManager.Listen method
addr, _ := url.Parse("tcp://127.0.0.1:1337")
listener, err := manager.Listen(addr)
if err != nil { panic(err) }
for {
conn, err := listener.Accept()
if err != nil {
// Handle error
}
}
Index ¶
- func KeyFromOptionalKey(key ed25519.PrivateKey) ed25519.PrivateKey
- type ConnManager
- func (c *ConnManager) Connect(uri url.URL) (*YggConn, error)
- func (c *ConnManager) ConnectCtx(ctx context.Context, uri url.URL) (*YggConn, error)
- func (c *ConnManager) ConnectTimeout(uri url.URL, timeout time.Duration) (*YggConn, error)
- func (c *ConnManager) Listen(uri url.URL) (ygg YggListener, err error)
- type DeduplicationManager
- type ProxyManager
- type ProxyMapping
- type YggConn
- func (y *YggConn) Close() (err error)
- func (y *YggConn) GetPublicKey() (ed25519.PublicKey, error)
- func (y *YggConn) GetVer() (*static.ProtoVersion, error)
- func (y *YggConn) LocalAddr() net.Addr
- func (y *YggConn) Read(b []byte) (n int, err error)
- func (y *YggConn) RemoteAddr() net.Addr
- func (y *YggConn) SetDeadline(t time.Time) (err error)
- func (y *YggConn) SetReadDeadline(t time.Time) (err error)
- func (y *YggConn) SetWriteDeadline(t time.Time) (err error)
- func (y *YggConn) Write(b []byte) (n int, err error)
- type YggListener
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func KeyFromOptionalKey ¶
func KeyFromOptionalKey(key ed25519.PrivateKey) ed25519.PrivateKey
If key is not nil, retruns it as is. If key is nil, generate new random key.
Types ¶
type ConnManager ¶
type ConnManager struct {
// contains filtered or unexported fields
}
Incapsulate list of transport realisations and other lower level managers. Manage opening & auto-closing connections, keys, proxys & dedupliaction.
func NewConnManager ¶
func NewConnManager( ctx context.Context, key ed25519.PrivateKey, proxy *ProxyManager, dm *DeduplicationManager, allowList *static.AllowList, ) *ConnManager
Create new ConnManager with default transports list.
Key can be nill.
func NewConnManagerWithTransports ¶
func NewConnManagerWithTransports( ctx context.Context, key ed25519.PrivateKey, proxy *ProxyManager, dm *DeduplicationManager, allowList *static.AllowList, transports []static.Transport, ) *ConnManager
Create new ConnManager with custom transports list.
Key can be nill.
func (*ConnManager) Connect ¶
func (c *ConnManager) Connect(uri url.URL) (*YggConn, error)
Selects the appropriate transport implementation based on the uri scheme and opens the connection.
If ConnManager was constructed with non nil ProxyManager, it will be used to selection proxy based on uri host.
If ConnManager was constructed with non nil private key, it will pass to transport implementation. Otherwise new random key will be used for each call.
If ConnManager was constructed with non nil DeduplicationManager, it will be used to close duplicate connections on early stage.
func (*ConnManager) ConnectCtx ¶
Selects the appropriate transport implementation based on the uri scheme and opens the connection.
If ConnManager was constructed with non nil ProxyManager, it will be used to selection proxy based on uri host.
If ConnManager was constructed with non nil private key, it will pass to transport implementation. Otherwise new random key will be used for each call.
If ConnManager was constructed with non nil DeduplicationManager, it will be used to close duplicate connections on early stage.
It also accepts a context that allows you to cancel the process ahead of time.
func (*ConnManager) ConnectTimeout ¶
Selects the appropriate transport implementation based on the uri scheme and opens the connection.
If ConnManager was constructed with non nil ProxyManager, it will be used to selection proxy based on uri host.
If ConnManager was constructed with non nil private key, it will pass to transport implementation. Otherwise new random key will be used for each call.
If ConnManager was constructed with non nil DeduplicationManager, it will be used to close duplicate connections on early stage.
It also accepts a timeout param. After timeout expires, the connection process will be canceled.
func (*ConnManager) Listen ¶
func (c *ConnManager) Listen(uri url.URL) (ygg YggListener, err error)
Selects the appropriate transport implementation based on the uri scheme and create listener object that accpet incoming connections.
type DeduplicationManager ¶
type DeduplicationManager struct {
// contains filtered or unexported fields
}
Stores info about all active connections. Call callback if one of them need to be closed.
func NewDeduplicationManager ¶
func NewDeduplicationManager(secureMode bool, blockKey ed25519.PublicKey) *DeduplicationManager
If secureMode is disabled all new duplicated connections will closed immediately. Otherwise from group of duplicated connections will select one with higher SecurityLvl param, and other will be closed.
Any connection with blockKey will be closed anyway. This param may be used to prevent node connect to itself.
func (*DeduplicationManager) Check ¶
func (d *DeduplicationManager) Check(key ed25519.PublicKey, isSecure uint, closeMethod func()) func()
Accept public key of connected node, security lvl of connection and callback function that will be called when DeduplicationManager decied to close current connection.
Check if new connection is duplicate. If it is not, returns callback that this connection MUST call on close. If it is duplicate and if it must be closed returns nill.
type ProxyManager ¶
type ProxyManager struct {
// contains filtered or unexported fields
}
Stores ProxyMappings and match URLs to proxy
func NewProxyManager ¶
func NewProxyManager(defaultProxy *url.URL, mapping []ProxyMapping) ProxyManager
type ProxyMapping ¶
type ProxyMapping struct {
// RegExp for host matching
HostRegexp regexp.Regexp
// Proxy (may be nil)
Proxy *url.URL
}
ProxyMapping is a representation of the correspondence between hosts that fall under the regular expression and proxy that should be used to connect to these hosts.
type YggConn ¶
type YggConn struct {
// contains filtered or unexported fields
}
Wraper that represents connection with other yggdrasil node.
Incapsulate analysing handshake pkg and communicate with DeduplicationManager.
func ConnToYggConn ¶
func ConnToYggConn(conn net.Conn, transport_key ed25519.PublicKey, allow *static.AllowList, secureTranport uint, dm *DeduplicationManager) *YggConn
Wraps regular net connection to YggConn.
Accepts optinal transport key, list of allowded nodes, security lvl of connection and optional DeduplicationManager.
If connection has key different transport key or has key that does not contatain in allow list or duplicates oter connection with the same node, it will be closed. Otherwise, it will be available as a normal connection.
func (*YggConn) GetPublicKey ¶
Returns public key of of connected node if handshake pkg was successfully received and parsed.
func (*YggConn) GetVer ¶
func (y *YggConn) GetVer() (*static.ProtoVersion, error)
Returns version of yggdrasil protocol using for this connection if handshake pkg was successfully received and parsed.
func (*YggConn) RemoteAddr ¶
type YggListener ¶
type YggListener struct {
// contains filtered or unexported fields
}
Allows accepting incoming connections
func (*YggListener) Accept ¶
func (y *YggListener) Accept() (ygg YggConn, err error)
Accept waits for and returns the next connection to the listener.
func (*YggListener) Addr ¶
func (y *YggListener) Addr() net.Addr
Addr returns the listener's network address.
func (*YggListener) Close ¶
func (y *YggListener) Close() error
Close closes the listener. Any blocked Accept operations will be unblocked and return errors.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package debugstuff implements mock structs & functions using in unit tests in whole project
|
Package debugstuff implements mock structs & functions using in unit tests in whole project |
|
Package static implements interfaces, types and constants used in the rest of the project modules.
|
Package static implements interfaces, types and constants used in the rest of the project modules. |
|
Package transports contatin implementations of [static.Transport] interface
|
Package transports contatin implementations of [static.Transport] interface |