From 3b51af4708317a060a77b59cbeb1ec132e6a0538 Mon Sep 17 00:00:00 2001 From: Christian Rocha Date: Thu, 9 Dec 2021 15:11:19 -0500 Subject: [PATCH] Add some missing godocs --- cmd/soft/main.go | 7 ++++++- config/config.go | 3 ++- internal/config/config.go | 5 +++++ internal/config/git.go | 6 ++++++ internal/git/git.go | 12 ++++++++++++ internal/tui/style/style.go | 2 ++ server/server.go | 3 +++ 7 files changed, 36 insertions(+), 2 deletions(-) diff --git a/cmd/soft/main.go b/cmd/soft/main.go index a25e5618a..f7ea656fe 100644 --- a/cmd/soft/main.go +++ b/cmd/soft/main.go @@ -11,7 +11,12 @@ import ( ) var ( - Version = "" + // Version contains the application version number. It's set via ldflags + // when building. + Version = "" + + // CommitSHA contains the SHA of the commit that this application was built + // against. It's set via lgflags when building. CommitSHA = "" version = flag.Bool("version", false, "display version") diff --git a/config/config.go b/config/config.go index 897bd014d..0a28e783f 100644 --- a/config/config.go +++ b/config/config.go @@ -13,7 +13,7 @@ type Callbacks interface { Fetch(repo string) } -// Config is the configuration for the soft-serve. +// Config is the configuration for Soft Serve. type Config struct { Host string `env:"SOFT_SERVE_HOST" default:""` Port int `env:"SOFT_SERVE_PORT" default:"23231"` @@ -34,6 +34,7 @@ func DefaultConfig() *Config { return scfg.WithCallbacks(nil) } +// WithCallbacks applies the given Callbacks to the configuration. func (cfg *Config) WithCallbacks(c Callbacks) *Config { cfg.Callbacks = c return cfg diff --git a/internal/config/config.go b/internal/config/config.go index 21a22b33d..c43e0a424 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -16,6 +16,7 @@ import ( "github.com/go-git/go-git/v5/plumbing/object" ) +// Config is the Soft Serve configuration. type Config struct { Name string `yaml:"name"` Host string `yaml:"host"` @@ -28,6 +29,7 @@ type Config struct { Cfg *config.Config } +// User contains user-level configuration for a repository. type User struct { Name string `yaml:"name"` Admin bool `yaml:"admin"` @@ -35,6 +37,7 @@ type User struct { CollabRepos []string `yaml:"collab-repos"` } +// Repo contains repository configuration information. type Repo struct { Name string `yaml:"name"` Repo string `yaml:"repo"` @@ -42,6 +45,7 @@ type Repo struct { Private bool `yaml:"private"` } +// NewConfig creates a new internal Config struct. func NewConfig(cfg *config.Config) (*Config, error) { var anonAccess string var yamlUsers string @@ -84,6 +88,7 @@ func NewConfig(cfg *config.Config) (*Config, error) { return c, nil } +// Reload reloads the configuration. func (cfg *Config) Reload() error { err := cfg.Source.LoadRepos() if err != nil { diff --git a/internal/config/git.go b/internal/config/git.go index b1a46e173..063a098d3 100644 --- a/internal/config/git.go +++ b/internal/config/git.go @@ -8,6 +8,7 @@ import ( "github.com/gliderlabs/ssh" ) +// Push registers Git push functionality for the given repo and key. func (cfg *Config) Push(repo string, pk ssh.PublicKey) { err := cfg.Reload() if err != nil { @@ -18,20 +19,25 @@ func (cfg *Config) Push(repo string, pk ssh.PublicKey) { } } +// Fetch registers Git fetch functionality for the given repo and key. func (cfg *Config) Fetch(repo string, pk ssh.PublicKey) { if cfg.Cfg.Callbacks != nil { cfg.Cfg.Callbacks.Fetch(repo) } } +// AuthRepo grants repo authorization to the given key. func (cfg *Config) AuthRepo(repo string, pk ssh.PublicKey) gm.AccessLevel { return cfg.accessForKey(repo, pk) } +// PasswordHandler returns whether or not password access is allowed. func (cfg *Config) PasswordHandler(ctx ssh.Context, password string) bool { return (cfg.AnonAccess != "no-access") && cfg.AllowKeyless } +// PublicKeyHandler returns whether or not the given public key may access the +// repo. func (cfg *Config) PublicKeyHandler(ctx ssh.Context, pk ssh.PublicKey) bool { return cfg.accessForKey("", pk) != gm.NoAccess } diff --git a/internal/git/git.go b/internal/git/git.go index 66a7c7bcc..936cf080c 100644 --- a/internal/git/git.go +++ b/internal/git/git.go @@ -16,8 +16,10 @@ import ( "github.com/go-git/go-git/v5/storage/memory" ) +// ErrMissingRepo indicates that the requested repository could not be found. var ErrMissingRepo = errors.New("missing repo") +// Repo represents a Git repository. type Repo struct { Name string Repository *git.Repository @@ -25,11 +27,13 @@ type Repo struct { LastUpdated *time.Time } +// RepoCommit contains metadata for a Git commit. type RepoCommit struct { Name string Commit *object.Commit } +// CommitLog is a series of Git commits. type CommitLog []RepoCommit func (cl CommitLog) Len() int { return len(cl) } @@ -38,6 +42,7 @@ func (cl CommitLog) Less(i, j int) bool { return cl[i].Commit.Author.When.After(cl[j].Commit.Author.When) } +// RepoSource is a reference to an on-disk repositories. type RepoSource struct { Path string mtx sync.Mutex @@ -45,6 +50,7 @@ type RepoSource struct { commits CommitLog } +// NewRepoSource creates a new RepoSource. func NewRepoSource(repoPath string) *RepoSource { err := os.MkdirAll(repoPath, os.ModeDir|os.FileMode(0700)) if err != nil { @@ -54,12 +60,14 @@ func NewRepoSource(repoPath string) *RepoSource { return rs } +// AllRepos returns all repositories for the given RepoSource. func (rs *RepoSource) AllRepos() []*Repo { rs.mtx.Lock() defer rs.mtx.Unlock() return rs.repos } +// GetRepo returns a repository by name. func (rs *RepoSource) GetRepo(name string) (*Repo, error) { rs.mtx.Lock() defer rs.mtx.Unlock() @@ -71,6 +79,7 @@ func (rs *RepoSource) GetRepo(name string) (*Repo, error) { return nil, ErrMissingRepo } +// InitRepo initializes a new Git repository. func (rs *RepoSource) InitRepo(name string, bare bool) (*Repo, error) { rs.mtx.Lock() defer rs.mtx.Unlock() @@ -97,6 +106,7 @@ func (rs *RepoSource) InitRepo(name string, bare bool) (*Repo, error) { return r, nil } +// GetCommits returns commits for the repository. func (rs *RepoSource) GetCommits(limit int) []RepoCommit { rs.mtx.Lock() defer rs.mtx.Unlock() @@ -106,6 +116,7 @@ func (rs *RepoSource) GetCommits(limit int) []RepoCommit { return rs.commits[:limit] } +// LoadRepos opens Git repositories. func (rs *RepoSource) LoadRepos() error { rs.mtx.Lock() defer rs.mtx.Unlock() @@ -158,6 +169,7 @@ func (rs *RepoSource) loadRepo(name string, rg *git.Repository) (*Repo, error) { return r, nil } +// LatestFile returns the latest file at the specified path in the repository. func (r *Repo) LatestFile(path string) (string, error) { lg, err := r.Repository.Log(&git.LogOptions{}) if err != nil { diff --git a/internal/tui/style/style.go b/internal/tui/style/style.go index 9377fb0e3..ec09bd832 100644 --- a/internal/tui/style/style.go +++ b/internal/tui/style/style.go @@ -7,6 +7,7 @@ import ( // XXX: For now, this is in its own package so that it can be shared between // different packages without incurring an illegal import cycle. +// Styles defines styles for the TUI. type Styles struct { ActiveBorderColor lipgloss.Color InactiveBorderColor lipgloss.Color @@ -39,6 +40,7 @@ type Styles struct { ErrorBody lipgloss.Style } +// DefaultStyles returns default styles for the TUI. func DefaultStyles() *Styles { s := new(Styles) diff --git a/server/server.go b/server/server.go index 684a6048f..e7ab0cf23 100644 --- a/server/server.go +++ b/server/server.go @@ -15,6 +15,7 @@ import ( "github.com/gliderlabs/ssh" ) +// Server is the Soft Serve server. type Server struct { SSHServer *ssh.Server Config *config.Config @@ -53,10 +54,12 @@ func NewServer(cfg *config.Config) *Server { } } +// Reload reloads the server configuration. func (srv *Server) Reload() error { return srv.config.Reload() } +// Start starts the SSH server. func (srv *Server) Start() error { return srv.SSHServer.ListenAndServe() }