api

Documentation

Overview

Copyright 2022 The VolSync authors.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

Copyright 2022 The VolSync authors.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

Copyright 2022 The VolSync authors.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

Copyright 2022 The VolSync authors.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

Index

• Constants
• func CreateSyncthingTestServer(state *Syncthing, serverAPIKey string) *httptest.Server
• type APIConfig
  • func (api APIConfig) TLSClient() *http.Client
• type ConnectionStats
• type DialStatus
• type Syncthing
  • func (s *Syncthing) GetDeviceFromID(id string) (*config.DeviceConfiguration, bool)
  • func (s *Syncthing) MyID() string
  • func (s *Syncthing) ShareFoldersWithDevices(devices []config.DeviceConfiguration)
• type SyncthingConnection
  • func NewConnection(cfg APIConfig, logger logr.Logger) SyncthingConnection
• type SystemConnections
• type SystemStatus
• type TotalStats

Constants

const (
	SystemStatusEndpoint      = "/rest/system/status"
	SystemConnectionsEndpoint = "/rest/system/connections"
	ConfigEndpoint            = "/rest/config"
)

Defines endpoints for the Syncthing API

Functions

func CreateSyncthingTestServer

func CreateSyncthingTestServer(state *Syncthing, serverAPIKey string) *httptest.Server

CreateSyncthingTestServer Returns a test server that mimics the Syncthing API by exposing the endpoints for config, system status, and system connections. The server also accepts an API Key, which is used for authenticating between the client and server.

The accepted arguments are pointers so that the state can be changed externally and the server will be updated accordingly. nolint:funlen

Types

type APIConfig

type APIConfig struct {
	APIURL string `json:"apiURL"`
	APIKey string `json:"apiKey"`
	// don't marshal this field
	TLSConfig *tls.Config
	Client    *http.Client
}

APIConfig Describes the necessary elements needed to configure a client with the Syncthing API, included the credentials, URL, TLS Certs. This requires nolint:revive because the package it's in is called "api," and it's meant to be used in an interface which already contains `Config` meaning a different thing. nolint:revive

func (APIConfig) TLSClient

func (api APIConfig) TLSClient() *http.Client

TLSClient Returns a TLS Client used by the API Config. If the client field is nil, then a new TLS Client is built using either the custom TLS Config set or a default tlsConfig with version 1.2

type ConnectionStats

type ConnectionStats struct {
	TotalStats
	Connected     bool   `json:"connected"`
	Paused        bool   `json:"paused"`
	At            string `json:"at"`
	StartedAt     string `json:"startedAt"`
	ClientVersion string `json:"clientVersion"`
	Address       string `json:"address"`
	Type          string `json:"type"`
}

ConnectionStats Details statistics about this Syncthing connection.

type DialStatus

type DialStatus struct {
	When  string  `json:"when"`
	Error *string `json:"error"`
	OK    bool    `json:"ok"`
}

DialStatus Provides us with information as to whether or not we are able to dial a given device, when the last time we dialed was, and what the error is, if any.

type Syncthing

type Syncthing struct {
	Configuration     config.Configuration
	SystemConnections SystemConnections
	SystemStatus      SystemStatus
}

Syncthing Defines a Syncthing API object which contains a subset of the information exposed through Syncthing's API. Namely, this struct exposes the configuration, system status, and connections contained by the given object.

func (*Syncthing) GetDeviceFromID

func (s *Syncthing) GetDeviceFromID(id string) (*config.DeviceConfiguration, bool)

GetDeviceFromID Returns a pointer to the device with the given ID, along with a boolean indicating whether the device was found.

func (*Syncthing) MyID

func (s *Syncthing) MyID() string

MyID Is a convenience method which returns the current Syncthing device's ID.

func (*Syncthing) ShareFoldersWithDevices

func (s *Syncthing) ShareFoldersWithDevices(devices []config.DeviceConfiguration)

ShareFoldersWithDevices Will set all of the given devices to be shared with the currently tracked folders.

This method does not currently take into account any encryption password set on the folder by the device.

type SyncthingConnection

type SyncthingConnection interface {
	// API Functions, these are meant to define communication with the Syncthing API.
	Fetch() (*Syncthing, error)
	PublishConfig(config.Configuration) error
}

func NewConnection

func NewConnection(cfg APIConfig, logger logr.Logger) SyncthingConnection

NewConnection accepts an APIConfig object and a logger and creates a SyncthingConnection object in return.

type SystemConnections

type SystemConnections struct {
	Total       TotalStats                 `json:"total"`
	Connections map[string]ConnectionStats `json:"connections"`
}

SystemConnections Describes the devices which are connected to the Syncthing device, in addition to statistics about the total traffic to and from this node.

type SystemStatus

type SystemStatus struct {
	Alloc                   int                                        `json:"alloc"`
	ConnectionServiceStatus map[string]connections.ListenerStatusEntry `json:"connectionServiceStatus"`
	CPUPercent              int                                        `json:"cpuPercent"`
	Goroutines              int                                        `json:"goroutines"`
	GUIAddressOverridden    bool                                       `json:"guiAddressOverridden"`
	GUIAddressUsed          string                                     `json:"guiAddressUsed"`
	LastDialStatus          map[string]DialStatus                      `json:"lastDialStatus"`
	MyID                    string                                     `json:"myID"`
}

SystemStatus Details information about the running Syncthing system, including the device ID, CPU usage, allocated memory, number of goroutines, when it started, and so on and so forth.

type TotalStats

type TotalStats struct {
	At            string `json:"at"`
	InBytesTotal  int    `json:"inBytesTotal"`
	OutBytesTotal int    `json:"outBytesTotal"`
}

TotalStats Describes the total traffic to/from a given Syncthing node.