mirror of
https://github.com/rwinkhart/libmutton.git
synced 2026-08-28 12:56:31 -04:00
Properly format function documentation comments
This commit is contained in:
+1
-3
@@ -2,12 +2,10 @@ package sync
|
||||
|
||||
import "github.com/rwinkhart/libmutton/core"
|
||||
|
||||
// define field separator constants
|
||||
const (
|
||||
FSSpace = "\u259d" // ▝ space/list separator
|
||||
FSPath = "\u259e" // ▞ path separator
|
||||
FSMisc = "\u259f" // ▟ misc. field separator (if \u259d is already used)
|
||||
)
|
||||
|
||||
// rootLength stores length of core.EntryRoot string
|
||||
var rootLength = len(core.EntryRoot)
|
||||
var rootLength = len(core.EntryRoot) // length of core.EntryRoot string
|
||||
|
||||
+20
-20
@@ -13,15 +13,15 @@ import (
|
||||
"golang.org/x/crypto/ssh/knownhosts"
|
||||
)
|
||||
|
||||
// global constants used only in this file
|
||||
// ANSI color constants used only in this file
|
||||
const (
|
||||
ansiDelete = "\033[38;5;1m"
|
||||
ansiDownload = "\033[38;5;2m"
|
||||
ansiUpload = "\033[38;5;4m"
|
||||
)
|
||||
|
||||
// GetSSHClient returns an SSH client connection to the server (also returns the remote EntryRoot as a string and the server's OS as a bool - IsWindows)
|
||||
// only supports key-based authentication (passphrases are supported for CLI-based implementations)
|
||||
// GetSSHClient returns an SSH client connection to the server (also returns the remote EntryRoot and an indicator of the server's OS).
|
||||
// Only supports key-based authentication (passphrases are supported for CLI-based implementations).
|
||||
func GetSSHClient(manualSync bool) (*ssh.Client, string, bool) {
|
||||
// get SSH config info, exit if not configured (displaying an error if the sync job was called manually)
|
||||
var sshUserConfig []string
|
||||
@@ -99,7 +99,7 @@ func GetSSHClient(manualSync bool) (*ssh.Client, string, bool) {
|
||||
return sshClient, entryRoot, isWindows
|
||||
}
|
||||
|
||||
// GetSSHOutput runs a command over SSH and returns the output as a string
|
||||
// GetSSHOutput runs a command over SSH and returns the output as a string.
|
||||
func GetSSHOutput(sshClient *ssh.Client, cmd, stdin string) string {
|
||||
// create a session
|
||||
sshSession, err := sshClient.NewSession()
|
||||
@@ -126,7 +126,7 @@ func GetSSHOutput(sshClient *ssh.Client, cmd, stdin string) string {
|
||||
return outputString
|
||||
}
|
||||
|
||||
// getRemoteDataFromClient returns a map of remote entries to their modification times, a list of remote folders, a list of queued deletions, and the current server+client times as UNIX timestamps
|
||||
// getRemoteDataFromClient returns a map of remote entries to their modification times, a list of remote folders, a list of queued deletions, and the current server&client times as UNIX timestamps.
|
||||
func getRemoteDataFromClient(sshClient *ssh.Client, manualSync bool) (map[string]int64, []string, []string, int64, int64) {
|
||||
// get remote output over SSH
|
||||
clientDeviceID, _ := os.ReadDir(core.ConfigDir + core.PathSeparator + "devices")
|
||||
@@ -171,7 +171,7 @@ func getRemoteDataFromClient(sshClient *ssh.Client, manualSync bool) (map[string
|
||||
return entryModMap, folders, deletions, serverTime, clientTime
|
||||
}
|
||||
|
||||
// getLocalData returns a map of local entries to their modification times
|
||||
// getLocalData returns a map of local entries to their modification times.
|
||||
func getLocalData() map[string]int64 {
|
||||
// get a list of all entries
|
||||
entries, _ := WalkEntryDir()
|
||||
@@ -189,7 +189,7 @@ func getLocalData() map[string]int64 {
|
||||
return entryModMap
|
||||
}
|
||||
|
||||
// targetLocationFormatSFTP formats the target location to match the remote server's entry directory and path separator
|
||||
// targetLocationFormatSFTP formats the target location to match the remote server's entry directory and path separator.
|
||||
func targetLocationFormatSFTP(targetName, serverEntryRoot string, serverIsWindows bool) string {
|
||||
if !serverIsWindows {
|
||||
return serverEntryRoot + targetName
|
||||
@@ -198,7 +198,7 @@ func targetLocationFormatSFTP(targetName, serverEntryRoot string, serverIsWindow
|
||||
}
|
||||
}
|
||||
|
||||
// sftpSync takes two slices of entries (one for downloads and one for uploads) and syncs them between the client and server using SFTP
|
||||
// sftpSync takes two slices of entries (one for downloads and one for uploads) and syncs them between the client and server using SFTP.
|
||||
func sftpSync(sshClient *ssh.Client, sshEntryRoot string, sshIsWindows bool, downloadList, uploadList []string) {
|
||||
// create an SFTP client from sshClient
|
||||
sftpClient, err := sftp.NewClient(sshClient)
|
||||
@@ -323,8 +323,8 @@ func sftpSync(sshClient *ssh.Client, sshEntryRoot string, sshIsWindows bool, dow
|
||||
}
|
||||
}
|
||||
|
||||
// syncLists determines which entries need to be downloaded and uploaded for synchronizations and calls sftpSync with this information
|
||||
// using maps means that syncing will be done in an arbitrary order, but it is a worthy tradeoff for speed and simplicity
|
||||
// syncLists determines which entries need to be downloaded and uploaded for synchronizations and calls sftpSync with this information.
|
||||
// Using maps means that syncing will be done in an arbitrary order, but it is a worthy tradeoff for speed and simplicity.
|
||||
func syncLists(sshClient *ssh.Client, sshEntryRoot string, sshIsWindows, timeSynced bool, localEntryModMap, remoteEntryModMap map[string]int64) {
|
||||
// initialize slices to store entries that need to be downloaded or uploaded
|
||||
var downloadList, uploadList []string
|
||||
@@ -367,7 +367,7 @@ func syncLists(sshClient *ssh.Client, sshEntryRoot string, sshIsWindows, timeSyn
|
||||
fmt.Println("Client is synchronized with server")
|
||||
}
|
||||
|
||||
// deletionSync removes entries from the client that have been deleted on the server (multi-client deletion)
|
||||
// deletionSync removes entries from the client that have been deleted on the server (multi-client deletion).
|
||||
func deletionSync(deletions []string) {
|
||||
var filesDeleted bool
|
||||
for _, deletion := range deletions {
|
||||
@@ -381,8 +381,8 @@ func deletionSync(deletions []string) {
|
||||
}
|
||||
}
|
||||
|
||||
// ShearRemoteFromClient removes the target file or directory from the local system and calls the server to remove it remotely and add it to the deletions list
|
||||
// can safely be called in offline mode, as well, so this is the intended interface for shearing (ShearLocal should only be used directly by the server binary)
|
||||
// ShearRemoteFromClient removes the target file or directory from the local system and calls the server to remove it remotely and add it to the deletions list.
|
||||
// It can safely be called in offline mode, as well, so this is the intended interface for shearing (ShearLocal should only be used directly by the server binary).
|
||||
func ShearRemoteFromClient(sshClient *ssh.Client, targetLocationIncomplete string) {
|
||||
deviceID := ShearLocal(targetLocationIncomplete, "") // remove the target from the local system and get the device ID of the client
|
||||
|
||||
@@ -394,8 +394,8 @@ func ShearRemoteFromClient(sshClient *ssh.Client, targetLocationIncomplete strin
|
||||
core.Exit(0) // sync is not required after shearing since the target has already been removed from the local system
|
||||
}
|
||||
|
||||
// RenameRemoteFromClient renames oldLocationIncomplete to newLocationIncomplete on the local system and calls the server to perform the rename remotely and add the old target to the deletions list
|
||||
// can safely be called in offline mode, as well, so this is the intended interface for renaming (RenameLocal should only be used directly by the server binary)
|
||||
// RenameRemoteFromClient renames oldLocationIncomplete to newLocationIncomplete on the local system and calls the server to perform the rename remotely and add the old target to the deletions list.
|
||||
// It can safely be called in offline mode, as well, so this is the intended interface for renaming (RenameLocal should only be used directly by the server binary).
|
||||
func RenameRemoteFromClient(sshClient *ssh.Client, oldLocationIncomplete, newLocationIncomplete string) {
|
||||
RenameLocal(oldLocationIncomplete, newLocationIncomplete, false) // move the target on the local system
|
||||
|
||||
@@ -411,8 +411,8 @@ func RenameRemoteFromClient(sshClient *ssh.Client, oldLocationIncomplete, newLoc
|
||||
core.Exit(0)
|
||||
}
|
||||
|
||||
// AddFolderRemoteFromClient creates a new entry-containing directory on the local system and calls the server to create the folder remotely
|
||||
// can safely be called in offline mode, as well, so this is the intended interface for adding folders (AddFolderLocal should only be used directly by the server binary)
|
||||
// AddFolderRemoteFromClient creates a new entry-containing directory on the local system and calls the server to create the folder remotely.
|
||||
// It can safely be called in offline mode, as well, so this is the intended interface for adding folders (AddFolderLocal should only be used directly by the server binary).
|
||||
func AddFolderRemoteFromClient(sshClient *ssh.Client, targetLocationIncomplete string) {
|
||||
AddFolderLocal(targetLocationIncomplete) // add the folder on the local system
|
||||
GetSSHOutput(sshClient, "libmuttonserver addfolder", strings.ReplaceAll(targetLocationIncomplete, core.PathSeparator, FSPath)) // call the server to create the folder remotely
|
||||
@@ -420,7 +420,7 @@ func AddFolderRemoteFromClient(sshClient *ssh.Client, targetLocationIncomplete s
|
||||
core.Exit(0)
|
||||
}
|
||||
|
||||
// folderSync creates folders on the client (from the given list of folder names)
|
||||
// folderSync creates folders on the client (from the given list of folder names).
|
||||
func folderSync(folders []string) {
|
||||
for _, folder := range folders {
|
||||
// store the full local path of the folder
|
||||
@@ -438,8 +438,8 @@ func folderSync(folders []string) {
|
||||
}
|
||||
}
|
||||
|
||||
// RunJob runs the SSH sync job
|
||||
// setting manualSync to true will throw errors if sync is not configured, as online mode is assumed
|
||||
// RunJob runs the SSH sync job.
|
||||
// Setting manualSync to true will throw errors if sync is not configured (online mode is assumed).
|
||||
func RunJob(manualSync bool) {
|
||||
// get SSH client to re-use throughout the sync process
|
||||
sshClient, sshEntryRoot, sshIsWindows := GetSSHClient(manualSync)
|
||||
|
||||
+10
-10
@@ -9,7 +9,7 @@ import (
|
||||
"github.com/rwinkhart/libmutton/core"
|
||||
)
|
||||
|
||||
// getModTimes returns a list of all entry modification times
|
||||
// getModTimes returns a list of all entry modification times.
|
||||
func getModTimes(entryList []string) []int64 {
|
||||
var modList []int64
|
||||
for _, file := range entryList {
|
||||
@@ -20,7 +20,7 @@ func getModTimes(entryList []string) []int64 {
|
||||
return modList
|
||||
}
|
||||
|
||||
// genDeviceIDList returns a pointer to a slice of all registered device IDs
|
||||
// genDeviceIDList returns a pointer to a slice of all registered device IDs.
|
||||
func genDeviceIDList() *[]fs.DirEntry {
|
||||
// create a slice of all registered devices
|
||||
deviceIDList, err := os.ReadDir(core.ConfigDir + core.PathSeparator + "devices")
|
||||
@@ -31,10 +31,10 @@ func genDeviceIDList() *[]fs.DirEntry {
|
||||
return &deviceIDList
|
||||
}
|
||||
|
||||
// ShearLocal removes the target file or directory from the local system
|
||||
// returns: deviceID (on client), for use in ShearRemoteFromClient
|
||||
// if the local system is a server, it will also add the target to the deletions list for all clients (except the requesting client)
|
||||
// this function should only be used directly by the server binary
|
||||
// ShearLocal removes the target file or directory from the local system.
|
||||
// Returns: deviceID (only on client; for use in ShearRemoteFromClient).
|
||||
// If the local system is a server, it will also add the target to the deletions list for all clients (except the requesting client).
|
||||
// This function should only be used directly by the server binary.
|
||||
func ShearLocal(targetLocationIncomplete, clientDeviceID string) string {
|
||||
// determine if running on a server
|
||||
var onServer bool
|
||||
@@ -77,8 +77,8 @@ func ShearLocal(targetLocationIncomplete, clientDeviceID string) string {
|
||||
// do not exit program, as this function is used as part of ShearRemoteFromClient
|
||||
}
|
||||
|
||||
// RenameLocal renames oldLocationIncomplete to newLocationIncomplete on the local system
|
||||
// this function should only be used directly by the server binary
|
||||
// RenameLocal renames oldLocationIncomplete to newLocationIncomplete on the local system.
|
||||
// This function should only be used directly by the server binary.
|
||||
func RenameLocal(oldLocationIncomplete, newLocationIncomplete string, verifyOldLocationExists bool) {
|
||||
// get full paths for both locations
|
||||
oldLocation := core.TargetLocationFormat(oldLocationIncomplete)
|
||||
@@ -104,8 +104,8 @@ func RenameLocal(oldLocationIncomplete, newLocationIncomplete string, verifyOldL
|
||||
// do not exit program, as this function is used as part of RenameRemoteFromClient
|
||||
}
|
||||
|
||||
// AddFolderLocal creates a new entry-containing directory on the local system
|
||||
// this function should only be used directly by the server binary
|
||||
// AddFolderLocal creates a new entry-containing directory on the local system.
|
||||
// This function should only be used directly by the server binary.
|
||||
func AddFolderLocal(targetLocationIncomplete string) {
|
||||
// get the full targetLocation path and create the target
|
||||
targetLocationComplete := core.TargetLocationFormat(targetLocationIncomplete)
|
||||
|
||||
+3
-3
@@ -11,8 +11,8 @@ import (
|
||||
"github.com/rwinkhart/libmutton/core"
|
||||
)
|
||||
|
||||
// WalkEntryDir walks the entry directory and returns lists of all files and directories found (two separate lists)
|
||||
// regardless of platform, all paths are stored with forward slashes (UNIX-style)
|
||||
// WalkEntryDir walks the entry directory and returns lists of all files and directories found (two separate lists).
|
||||
// Regardless of platform, all paths are stored with forward slashes (UNIX-style).
|
||||
func WalkEntryDir() ([]string, []string) {
|
||||
// define file/directory containing slices so that they may be accessed by the anonymous WalkDir function
|
||||
var fileList []string
|
||||
@@ -49,7 +49,7 @@ func WalkEntryDir() ([]string, []string) {
|
||||
return fileList, dirList
|
||||
}
|
||||
|
||||
// joinErrorWithEXE joins and returns the two strings it is provided (in error format) with the executable name inserted between them
|
||||
// joinErrorWithEXE is a utility function that joins and returns the two strings it is provided (in error format) with the executable name inserted between them.
|
||||
func joinErrorWithEXE(firstHalf, secondHalf string) string {
|
||||
return core.AnsiError + firstHalf + os.Args[0] + secondHalf + core.AnsiReset
|
||||
}
|
||||
|
||||
+3
-3
@@ -12,8 +12,8 @@ import (
|
||||
"github.com/rwinkhart/libmutton/core"
|
||||
)
|
||||
|
||||
// WalkEntryDir walks the entry directory and returns lists of all files and directories found (two separate lists)
|
||||
// regardless of platform, all paths are stored with forward slashes (UNIX-style)
|
||||
// WalkEntryDir walks the entry directory and returns lists of all files and directories found (two separate lists).
|
||||
// Regardless of platform, all paths are stored with forward slashes (UNIX-style).
|
||||
func WalkEntryDir() ([]string, []string) {
|
||||
// define file/directory containing slices so that they may be accessed by the anonymous WalkDir function
|
||||
var fileList []string
|
||||
@@ -50,7 +50,7 @@ func WalkEntryDir() ([]string, []string) {
|
||||
return fileList, dirList
|
||||
}
|
||||
|
||||
// joinErrorWithEXE joins and returns the two strings it is provided (in error format) with the executable name inserted between them
|
||||
// joinErrorWithEXE is a utility function that joins and returns the two strings it is provided (in error format) with the executable name inserted between them.
|
||||
func joinErrorWithEXE(firstHalf, secondHalf string) string {
|
||||
return core.AnsiError + firstHalf + os.Args[0][strings.LastIndex(os.Args[0], "\\")+1:] + secondHalf + core.AnsiReset
|
||||
}
|
||||
|
||||
+4
-4
@@ -11,10 +11,10 @@ import (
|
||||
"github.com/rwinkhart/libmutton/core"
|
||||
)
|
||||
|
||||
// DeviceIDGen generates a new client device ID and registers it with the server
|
||||
// device IDs are only needed for online synchronization
|
||||
// device IDs are guaranteed unique as the current UNIX time is appended to them
|
||||
// returns the remote EntryRoot and OS type (OS type is a bool: core.IsWindows)
|
||||
// DeviceIDGen generates a new client device ID and registers it with the server.
|
||||
// Device IDs are only needed for online synchronization.
|
||||
// Device IDs are guaranteed unique as the current UNIX time is appended to them.
|
||||
// Returns: the remote EntryRoot and OS type indicator.
|
||||
func DeviceIDGen() (string, string) {
|
||||
deviceIDPrefix, _ := os.Hostname()
|
||||
deviceIDSuffix := core.StringGen(rand.Intn(32)+48, true, 0.2, true) + "-" + strconv.FormatInt(time.Now().Unix(), 10)
|
||||
|
||||
+4
-3
@@ -2,15 +2,16 @@ package sync
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"golang.org/x/crypto/ssh/terminal"
|
||||
"os"
|
||||
|
||||
"golang.org/x/term"
|
||||
)
|
||||
|
||||
// inputKeyFilePassphrase prompts the user for a passphrase for an SSH key file
|
||||
// inputKeyFilePassphrase prompts the user for a passphrase for an SSH key file.
|
||||
// TODO support non-CLI implementations
|
||||
func inputKeyFilePassphrase() []byte {
|
||||
fmt.Print("\nEnter passphrase for your SSH keyfile: ")
|
||||
passphrase, _ := terminal.ReadPassword(int(os.Stdin.Fd()))
|
||||
passphrase, _ := term.ReadPassword(int(os.Stdin.Fd()))
|
||||
fmt.Println()
|
||||
return passphrase
|
||||
}
|
||||
|
||||
+3
-3
@@ -9,9 +9,9 @@ import (
|
||||
"github.com/rwinkhart/libmutton/core"
|
||||
)
|
||||
|
||||
// GetRemoteDataFromServer prints to stdout the remote entries, mod times, folders, and deletions
|
||||
// lists in output are separated by FSSpace
|
||||
// output is meant to be captured over SSH for interpretation by the client
|
||||
// GetRemoteDataFromServer prints to stdout the remote entries, mod times, folders, and deletions.
|
||||
// Lists in output are separated by FSSpace.
|
||||
// Output is meant to be captured over SSH for interpretation by the client.
|
||||
func GetRemoteDataFromServer(clientDeviceID string) {
|
||||
entryList, dirList := WalkEntryDir()
|
||||
modList := getModTimes(entryList)
|
||||
|
||||
Reference in New Issue
Block a user