From dcec9f7485595ba79512329c103872522f6cb2cf Mon Sep 17 00:00:00 2001
From: Abhinav Gupta <mail@abhinavg.net>
Date: Fri, 28 Apr 2023 05:33:20 -0700
Subject: config: Rename Package to PackageConfig, add docs (#84)

Renames the Package struct to PackageConfig
to make it clear that it is a configuration struct.

This differentiation will help disconnect
the configuration-level representation
from the runtime representation of this information.

This patch also adds documentation to the config package
that was previously missing.
---
 config.go       | 51 ++++++++++++++++++++++++++++++++++++++++-----------
 config_test.go  |  6 +++---
 handler.go      |  2 +-
 handler_test.go |  2 +-
 4 files changed, 45 insertions(+), 16 deletions(-)

diff --git a/config.go b/config.go
index 95dad7a..4d60a36 100644
--- a/config.go
+++ b/config.go
@@ -12,22 +12,51 @@ const (
 	_defaultBranch      = "master"
 )
 
-// Config represents the structure of the yaml file
+// Config defines the configuration for a Sally server.
 type Config struct {
-	URL      string             `yaml:"url"`
-	Packages map[string]Package `yaml:"packages"`
-	Godoc    struct {
-		Host string `yaml:"host"`
-	} `yaml:"godoc"`
+	// URL is the base URL for all vanity imports.
+	URL string `yaml:"url"` // required
+
+	// Packages is a map of package name to package details.
+	Packages map[string]PackageConfig `yaml:"packages"`
+
+	// Godoc specifies where to redirect to for documentation.
+	Godoc GodocConfig `yaml:"godoc"`
+}
+
+// GodocConfig is the configuration for the documentation server.
+type GodocConfig struct {
+	// Host is the hostname of the documentation server.
+	//
+	// Defaults to pkg.go.dev.
+	Host string `yaml:"host"`
 }
 
-// Package details the options available for each repo
-type Package struct {
-	Repo   string `yaml:"repo"`
+// PackageConfig is the configuration for a single Go module
+// that is served by Sally.
+type PackageConfig struct {
+	// Repo is the URL to the Git repository for the module
+	// without the https:// prefix.
+	// This URL must serve the Git HTTPS protocol.
+	//
+	// For example, "github.com/uber-go/sally".
+	Repo string `yaml:"repo"` // required
+
+	// Branch is the default branch for the repository
+	// when no version is specified.
+	//
+	// Defaults to master.
 	Branch string `yaml:"branch"`
-	URL    string `yaml:"url"`
+	// NB: This is no longer necessary.
+	// https://github.com/uber-go/sally/issues/83
+
+	// URL is the base URL of the vanity import for this module.
+	//
+	// Defaults to the URL specified in the top-level config.
+	URL string `yaml:"url"`
 
-	Desc string `yaml:"description"` // plain text only
+	// Desc is a plain text description of this module.
+	Desc string `yaml:"description"`
 }
 
 // Parse takes a path to a yaml file and produces a parsed Config
diff --git a/config_test.go b/config_test.go
index e4146b1..6587295 100644
--- a/config_test.go
+++ b/config_test.go
@@ -29,7 +29,7 @@ packages:
 	pkg, ok := config.Packages["grpc"]
 	assert.True(t, ok)
 
-	assert.Equal(t, pkg, Package{Repo: "github.com/grpc/grpc-go", Branch: "main"})
+	assert.Equal(t, pkg, PackageConfig{Repo: "github.com/grpc/grpc-go", Branch: "main"})
 }
 
 func TestParseDefaultBranch(t *testing.T) {
@@ -48,7 +48,7 @@ packages:
 
 	pkg, ok := config.Packages["grpc"]
 	assert.True(t, ok)
-	assert.Equal(t, pkg, Package{Repo: "github.com/grpc/grpc-go", Branch: "master"})
+	assert.Equal(t, pkg, PackageConfig{Repo: "github.com/grpc/grpc-go", Branch: "master"})
 }
 
 func TestParsePackageLevelURL(t *testing.T) {
@@ -102,7 +102,7 @@ packages:
 
 			pkg, ok := config.Packages["grpc"]
 			assert.True(t, ok)
-			assert.Equal(t, Package{Repo: "github.com/grpc/grpc-go", Branch: "master"}, pkg)
+			assert.Equal(t, PackageConfig{Repo: "github.com/grpc/grpc-go", Branch: "master"}, pkg)
 		})
 	}
 }
diff --git a/handler.go b/handler.go
index bbefd30..08c3e4b 100644
--- a/handler.go
+++ b/handler.go
@@ -54,8 +54,8 @@ func (h *indexHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 }
 
 type packageHandler struct {
+	pkg     PackageConfig
 	pkgName string
-	pkg     Package
 	config  *Config
 }
 
diff --git a/handler_test.go b/handler_test.go
index b1d5d2e..9cb84ff 100644
--- a/handler_test.go
+++ b/handler_test.go
@@ -131,7 +131,7 @@ func TestPostRejected(t *testing.T) {
 
 	h := CreateHandler(&Config{
 		URL: "go.uberalt.org",
-		Packages: map[string]Package{
+		Packages: map[string]PackageConfig{
 			"zap": {
 				Repo: "github.com/uber-go/zap",
 			},
-- 
cgit v1.2.3