README
¶
qcon
qcon is a Go library implementing the Synology QuickConnect protocol.
What is QuickConnect?
QuickConnect is a service provided by Synology that allows one to access a registered Synology NAS device using a globally unique QuickConnect ID. QuickConnect will examine all known routes to the device and connect through the best available means in the following order:
- local access via LAN
- remote access to device connected directly to internet
- remote access via proxy (eg. router with port-forwarding enabled)
- relay host connected to device via an encrypted tunnel
QuickConnect will only use routes that it has tested for connectivity.
QuickConnect prevents the user from having to manually determine which method is best for accessing their device.
Installation
go get github.com/jamesbo13/quickconnect
Usage
Most use cases can be handled by the Resolve() function:
import (
"context"
"github.com/jamesbo13/qcon"
)
...
ctx := context.Background()
id := "your-quick-connect-id"
// Resolve will return list of all working routes to device
// expressed as URL strings. The most preferred route will
// be listed first.
urls, err := qcon.Resolve(ctx, id)
if err != nil {
// handle error
}
// use synoURL for accessing Synology device APIs
synoURL := urls[0]
...
More control over the library behavior can be achieved by using a custom Client:
import (
"context"
"crypto/tls"
"net/http"
"github.com/jamesbo13/qcon"
)
...
ctx := context.Background()
id := "your-quick-connect-id"
// Set up a custom http.Transport and Client to control
// individual timeouts and provide server name for TLS cert checks
tr := &http.Transport{
Dial: (&net.Dialer{
Timeout: 5 * time.Second, // Timeout for TCP connection
}).Dial,
TLSHandshakeTimeout: 5 * time.Second, // Timeout for TLS handshake
TLSClientConfig: &tls.Config{
ServerName: "synology.mydomain.com", // Use this name for certificate checks
}, // useful when connecting to IP addresses rather than hostnames
}
c := &qcon.Client{
Client: &http.Client{
Timeout: 10 * time.Second, // Timeout for HTTP responses from server
Transport: tr,
},
Timeout: 20 * time.Second, // Timeout waiting for connectivity checks
}
// Resolve will return list of all working routes to device
// expressed as URL strings. The most preferred route will
// be listed first.
urls, err := c.Resolve(ctx, id)
if err != nil {
// handle error
}
// use synoURL for accessing Synology device APIs
synoURL := urls[0]
...
Timeouts and Cancellation
The standard Resolve() function (and Client.Resolve() method) imposes a
default 2 second timeout for its connectivity checks to the URLs it is
testing. Any route that does not respond within the two second timeout will
not be considered for connection.
Resolve() and other methods all take the standard context.Context parameter.
This can be used to cancel any calls to the library from another goroutine.
See the original Go blog post on context
for more details.
License
Documentation
¶
Overview ¶
Package qcon implements the QuickConnect protocol for accessing Synology NAS devices over the best available connection using a globally unique identifier. The returned URLs will vary depending on the client network relative to the Synology - for example, if on the same LAN local URLs will be returned, otherwise URLs using remote address (or even a Synology created tunnel) will be returned.
For most cases, all that is necessary is to pass the QuickConnect ID to the Resolve() function which will return a prioritized list of URLs:
// Create context ctx := context.Background() // Fetch list of URLs urls, err := qcon.Resolve(ctx, id) // Provided no error returned, the first URL in the returned slice // will be the most desired available connection. This can then // be used to access the Synology API
More control can be obtained by creating a Client with custom settings (including modifying the default http.Client).
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrTimeout error = errors.New("operation timed out") ErrCancelled error = errors.New("operation cancelled") ErrInvalidID error = errors.New("invalid server ID") ErrCannotAccess error = errors.New("cannot access any URLs") ErrParse error = errors.New("response parse error") ErrPingFailure error = errors.New("ping response failure") ErrUnknownCommand error = errors.New("unknown command") ErrUnknownServerType error = errors.New("unknown server type") )
var DefaultClient = &Client{}
DefaultClient is the default Client used by Resolve.
Functions ¶
Types ¶
type Client ¶
type Client struct {
Client *http.Client
Timeout time.Duration
// contains filtered or unexported fields
}
Client provides HTTP(S) connectivity to the central QuickConnect server and is also used for testing connectivity to returned URLs.
Client allows setting of non-default timeout and http.Client options for increased control over method behavior. Timeout is separate from any timeout settings inherited from http.Client and refers to the time Resolve() and UpdateState() will wait for responses during connectivity tests.
func (Client) GetInfo ¶
GetInfo returns information for given QuickConnect ID retrieved from the global QuickConnect server. This information includes the set of all Records associated with this ID (see struct Info).
func (Client) Ping ¶
Ping attempts a ping-pong request to the given URL and returns an MD5 hash of the ServerID from the response for use in verification.
Source Files