Refactored internals more

.air.toml

@@ -0,0 +1,52 @@
+root = "."
+testdata_dir = "testdata"
+tmp_dir = "tmp"
+
+[build]
+  args_bin = []
+  bin = "./tmp/main"
+  cmd = "go build -o ./tmp/main cmd/ratchetd/main.go"
+  delay = 1000
+  exclude_dir = ["assets", "tmp", "vendor", "testdata"]
+  exclude_file = []
+  exclude_regex = ["_test.go"]
+  exclude_unchanged = false
+  follow_symlink = false
+  full_bin = ""
+  include_dir = []
+  include_ext = ["go", "tpl", "tmpl", "html", "go.tmpl"]
+  include_file = []
+  kill_delay = "0s"
+  log = "build-errors.log"
+  poll = false
+  poll_interval = 0
+  post_cmd = []
+  pre_cmd = []
+  rerun = false
+  rerun_delay = 500
+  send_interrupt = false
+  stop_on_error = false
+
+[color]
+  app = ""
+  build = "yellow"
+  main = "magenta"
+  runner = "green"
+  watcher = "cyan"
+
+[log]
+  main_only = false
+  silent = false
+  time = false
+
+[misc]
+  clean_on_exit = false
+
+[proxy]
+  app_port = 0
+  enabled = false
+  proxy_port = 0
+
+[screen]
+  clear_on_rebuild = false
+  keep_scroll = true

.gitignore

@@ -21,3 +21,4 @@
 # Go workspace file
 go.work
 
+tmp/

README.md

@@ -3,6 +3,8 @@
 An example web application in Golang.
 
 
+https://lets-go.alexedwards.net/sample/02.09-serving-static-files.html
+
 ## Project Structure
 
 Loosely inspired by the organization of [WTFDial](https://github.com/benbjohnson/wtf?tab=readme-ov-file#project-structure), 
@@ -39,3 +41,47 @@ You can build `ratchet` locally by cloning the respository, then run
 
 The `ratchetd` cmd binary uses Oauth so you will need to create a new Oauth App. The vlaue of the authorization callback must be the hostname and IP at which clients can access the `ratchetd` server.
 
+## Additional Resources
+
+- [Content Range Requests](https://web.archive.org/web/20230918195519/https://benramsey.com/blog/2008/05/206-partial-content-and-range-requests/)
+- [HTTP 204 and 205 Status Codes](https://web.archive.org/web/20230918193536/https://benramsey.com/blog/2008/05/http-status-204-no-content-and-205-reset-content/)
+- [How to Disable FileServer Directory Listings](https://www.alexedwards.net/blog/disable-http-fileserver-directory-listings)
+- [Understand Mutexs in Go](https://www.alexedwards.net/blog/understanding-mutexes)
+- [Structured Logging in Go with log/slog](https://pkg.go.dev/log/slog)
+- [Exit Codes with special meaning](https://tldp.org/LDP/abs/html/exitcodes.html)
+- [Organizing Database Access in Go](https://www.alexedwards.net/blog/organising-database-access)
+
+### Go http.FileServer
+
+Supports If-Modified-Since and Last-Modified headers
+```
+curl -i -H "If-Modified-Since: 
+Thu, 04 May 2017 13:07:52 GMT" http://localhost:5001/static/img/logo.png
+HTTP/1.1 304 Not Modified
+Last-Modified: Thu, 04 May 2017 13:07:52 GMT
+Date: Sun, 12 Jan 2025 14:26:06 GMT
+```
+
+Supports Range Requests and 206 Partial Content responses.
+```
+curl -i -H "Range: bytes=100-199" --output - http://localhost:5001/static/img/logo.png
+HTTP/1.1 206 Partial Content
+Accept-Ranges: bytes
+Content-Length: 100
+Content-Range: bytes 100-199/1075
+Content-Type: image/png
+Last-Modified: Thu, 04 May 2017 13:07:52 GMT
+Date: Sun, 12 Jan 2025 14:18:32 GMT
+```
+
+- The `Content-Type` is automatically set from the file extension using the `mime.TypeByExtension()` function. You can add your own custom extensions and content types using the `mime.AddExtensionType()` function if necessary.
+
+- Sometimes you might want to serve a single file from within a handler. For this there’s the `http.ServeFile()` function, which you can use like so:
+
+```go
+func downloadHandler(w http.ResponseWriter, r *http.Request) {
+    http.ServeFile(w, r, "./ui/static/file.zip")
+}
+```
+
+Warning: http.ServeFile() does not automatically sanitize the file path. If you’re constructing a file path from untrusted user input, to avoid directory traversal attacks you must sanitize the input with filepath.Clean() before using it. 

cmd/ratchetd/main.go

@@ -1,21 +1,48 @@
 package main
 
 import (
+	"flag"
 	"fmt"
+	"log/slog"
+	"net/http"
 	"os"
-	"strings"
 
-	"git.runcible.io/learning/ratchet"
+	"git.runcible.io/learning/ratchet/internal/logging"
+	"git.runcible.io/learning/ratchet/internal/server"
+	// "git.runcible.io/learning/ratchet"
+	// ratchethttp "git.runcible.io/learning/ratchet/internal"
 )
 
-var (
+// var (
-	version string
+// 	version string
-	commit  string
+// 	commit  string
-)
+// )
 
 func main() {
+	// CONFIGURATION
+	// Parse command line options
+	addr := flag.String("addr", "0.0.0.0", "HTTP network address")
+	port := flag.String("port", "5001", "HTTP port")
+	logLevel := flag.String("logging", "INFO", "Logging Level. Valid values [INFO, DEBUG, WARN, ERROR].")
+	// must call parse or all values will be the defaults
+	flag.Parse()
+
+	// DEPENDENCY INJECTION FOR HANDLERS
+	// Setup Logging
+	logger := logging.InitLogging(*logLevel)
+
 	// Propagate build information to root package to share globally
-	ratchet.Version = strings.TrimPrefix(version, "")
+	// ratchet.Version = strings.TrimPrefix(version, "")
-	ratchet.Commit = commit
+	// ratchet.Commit = commit
-	fmt.Fprintf(os.Stdout, "Version: %s\nCommit: %s\n", ratchet.Version, ratchet.Commit)
+	server := server.NewRatchetServer(logger)
+
+	// START SERVING REQUESTS
+	slog.Debug("Herp dirp!")
+	slog.Info(fmt.Sprintf("Listening on http://%s:%s", *addr, *port))
+	//log.Fatal(http.ListenAndServe(fmt.Sprintf("%s:%s", *addr, *port), server))
+	// there is no log.Fatal equivalent. This is an approximation of the behavior
+	err := http.ListenAndServe(fmt.Sprintf("%s:%s", *addr, *port), server)
+	slog.Error(err.Error())
+	os.Exit(1)
+
 }

internal/apperror/apperror.go

@@ -1,4 +1,4 @@
-package ratchet
+package apperror
 
 import (
 	"errors"

internal/apperror/apperror_test.go

@@ -1,4 +1,4 @@
-package ratchet
+package apperror
 
 import (
 	"errors"

internal/domain/user/user.go

@@ -1,8 +1,10 @@
-package ratchet
+package user
 
 import (
 	"context"
 	"time"
+
+	"git.runcible.io/learning/ratchet/internal/apperror"
 )
 
 type User struct {
@@ -27,7 +29,7 @@ type User struct {
 
 func (u *User) Validate() error {
 	if u.Name == "" {
-		return Errorf(EINVALID, "User name required.")
+		return apperror.Errorf(apperror.EINVALID, "User name required.")
 	}
 	return nil
 }

internal/domain/user/user_test.go

@@ -1,11 +1,15 @@
-package ratchet
+package user
 
-import "testing"
+import (
+	"testing"
+
+	"git.runcible.io/learning/ratchet/internal/apperror"
+)
 
 func TestUserValidation(t *testing.T) {
 	t.Run("user should return invalid", func(t *testing.T) {
 		u := &User{}
-		if ErrorCode(u.Validate()) != EINVALID {
+		if apperror.ErrorCode(u.Validate()) != apperror.EINVALID {
 			t.Errorf("User validation should have failed but passed instead.")
 		}
 	})

internal/logging/logging.go

@@ -0,0 +1,36 @@
+package logging
+
+import (
+	"log/slog"
+	"os"
+	"strings"
+)
+
+func parseLogLevel(levelStr string) slog.Level {
+	switch strings.ToUpper(levelStr) {
+	case "DEBUG":
+		return slog.LevelDebug
+	case "INFO":
+		return slog.LevelInfo
+	case "WARN":
+		return slog.LevelWarn
+	case "ERROR":
+		return slog.LevelError
+	default:
+		return slog.LevelInfo // Default level
+	}
+}
+
+// InitLogggin initializes global structured logging for the entire application
+func InitLogging(level string) *slog.Logger {
+	// Use os.Stderr
+	//
+	// Stderr is used for diagnostics and logging. Stdout is used for program
+	// output. Stderr also have greater likely hood of being seen if a programs
+	// output is being redirected.
+	parsedLogLevel := parseLogLevel(level)
+	loggerHandler := slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{Level: parsedLogLevel, AddSource: true})
+	logger := slog.New(loggerHandler)
+	slog.SetDefault(logger)
+	return logger
+}

internal/server/base_server.go

@@ -0,0 +1,115 @@
+package server
+
+import (
+	"fmt"
+	"html/template"
+	"log/slog"
+	"net/http"
+	"strconv"
+
+	"git.runcible.io/learning/ratchet/internal/domain/user"
+)
+
+type RatchetServer struct {
+	http.Handler
+
+	logger *slog.Logger
+	//Services used by HTTP routes
+	UserService user.UserService
+}
+
+func NewRatchetServer(logger *slog.Logger) *RatchetServer {
+	rs := new(RatchetServer)
+	rs.logger = logger
+	// TODO implement middleware that disables directory listings
+	fileServer := http.FileServer(http.Dir("./ui/static/"))
+	router := http.NewServeMux()
+
+	// Subtree pattern for static assets
+	router.Handle("GET /static/", http.StripPrefix("/static/", fileServer))
+
+	// /{$} is used to prevent subtree path patterns from acting like a wildcard
+	// resulting in this route requiring an exact match on "/" only
+	// You can only include one HTTP method in a route pattern if you choose
+	// GET will match GET & HEAD http request methods
+	router.HandleFunc("GET /{$}", rs.home)
+	router.HandleFunc("GET /snippet/view/{id}", rs.snippetView)
+	router.HandleFunc("GET /snippet/create", rs.snippetCreate)
+
+	// FYI The http.HandlerFunc() adapter works by automatically adding a ServeHTTP() method to
+	// the passed function
+	router.HandleFunc("POST /snippet/create", rs.snippetCreatePost)
+
+	// Mux Router implements the Handler interface. AKA it has a ServeHTTP receiver.
+	rs.Handler = router
+	return rs
+}
+
+func (rs *RatchetServer) home(w http.ResponseWriter, r *http.Request) {
+	// TODO middleware should be able to print out these lines for all routes
+	rs.logger.Info("request received", "method", "GET", "path", "/")
+
+	w.Header().Add("Server", "Go")
+
+	// Initialize a slice containing the paths to the two files. It's important
+	// to note that the file containing our base template must be the *first*
+	// file in the slice.
+	files := []string{
+		"./ui/html/base.go.tmpl",
+		"./ui/html/partials/nav.go.tmpl",
+		"./ui/html/pages/home.go.tmpl",
+	}
+
+	// read template file into template set.
+	ts, err := template.ParseFiles(files...)
+	if err != nil {
+		rs.serverError(w, r, err)
+		return
+	}
+	// Write template content to response body
+	err = ts.ExecuteTemplate(w, "base", nil)
+	if err != nil {
+		// This is the older more verbose way of doing what RatchetServer.serverError does
+		// rs.logger.Error(err.Error())
+		// http.Error(w, "Internal Server Error", http.StatusInternalServerError)
+		rs.serverError(w, r, err)
+	}
+}
+
+func (rs *RatchetServer) snippetView(w http.ResponseWriter, r *http.Request) {
+
+	id, err := strconv.Atoi(r.PathValue("id"))
+	if err != nil || id < 1 {
+		// http.NotFound(w, r)
+		rs.clientError(w, http.StatusNotFound)
+		return
+	}
+
+	// Set a new cache-control header. If an existing "Cache-Control" header exists
+	// it will be overwritten.
+	w.Header().Set("Cache-Control", "public, max-age=31536000")
+
+	// msg := fmt.Sprintf("Snippet %d...", id)
+
+	// w.Write([]byte(msg))
+
+	// we can rely on the Write() interface to use a differnent
+	// function to write out our response
+
+	fmt.Fprintf(w, "Snippet %d...", id)
+}
+
+// snippetCreate handles display of the form used to create snippets
+func (rs *RatchetServer) snippetCreate(w http.ResponseWriter, r *http.Request) {
+	w.Write([]byte("Displaying snippetCreate form..."))
+}
+
+// snippetCreate handles display of the form used to create snippets
+func (rs *RatchetServer) snippetCreatePost(w http.ResponseWriter, r *http.Request) {
+	// example of a custom header. Must be done before calling WriteHeader
+	// or they will fail to take effect.
+	w.Header().Add("Server", "Dirp")
+	w.WriteHeader(http.StatusCreated)
+
+	w.Write([]byte("Created snippet..."))
+}

internal/server/helpers.go

@@ -0,0 +1,29 @@
+package server
+
+import (
+	"net/http"
+	"runtime/debug"
+)
+
+// serverError helper writes a log entry at Error level (including the request
+// method and URI as attributes), then sends a generic 500 Internal Server Error
+// response to the user.
+func (rs *RatchetServer) serverError(w http.ResponseWriter, r *http.Request, err error) {
+	var (
+		method = r.Method
+		uri    = r.URL.RequestURI()
+		// Use debug.Stack() to get the stack trace. This returns a byte slice, which
+		// we need to convert to a string so that it's readable in the log entry.
+		trace = string(debug.Stack())
+	)
+
+	rs.logger.Error(err.Error(), "method", method, "uri", uri, "trace", trace)
+	http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
+}
+
+// clientError helper sends a specific status code and corresponding description
+// to the user. We'll use this later in the book to send responses like 400 "Bad
+// Request" when there's a problem with the request that the user sent
+func (rs *RatchetServer) clientError(w http.ResponseWriter, status int) {
+	http.Error(w, http.StatusText(status), status)
+}

ui/html/base.go.tmpl

@@ -0,0 +1,24 @@
+{{define "base" -}}
+<!doctype html>
+<html lang='en'>
+    <head>
+        <meta charset='utf-8'>
+        <title>{{template "title" .}}</title>
+        <link rel='stylesheet' href='/static/css/main.css'>
+        <link rel='shortcut icon' href='/static/img/favicon.ico' type='image/x-icon'>
+        <!-- Also link to some fonts hosted by Google -->
+        <link rel='stylesheet' href='https://fonts.googleapis.com/css?family=Ubuntu+Mono:400,700'>
+    </head>
+    <body>
+        <header>
+            <h1><a href='/'>Ratchet</a></h1>
+        </header>
+        {{template "nav" .}}
+        <main>
+            {{template "main" .}}
+        </main>
+        <footer>Powered by <a href='https://golang.org/'>Go</a></footer>
+        <script src='/static/js/main.js' type='text/javascript'></script>
+    </body>
+</html>
+{{end}}

ui/html/pages/home.go.tmpl

@@ -0,0 +1,6 @@
+{{define "title"}}Home{{end}}
+
+{{define "main" -}}
+            <h2>Latest Snippets</h2>
+            <p>There's nothing to see yet!</p>
+{{- end -}}

ui/html/partials/nav.go.tmpl

@@ -0,0 +1,5 @@
+{{define "nav" -}}
+        <nav>
+            <a href='/'>Home</a>
+        </nav>
+{{- end}}

ui/static/css/main.css

@@ -0,0 +1,313 @@
+* {
+    box-sizing: border-box;
+    margin: 0;
+    padding: 0;
+    font-size: 18px;
+    font-family: "Ubuntu Mono", monospace;
+}
+
+html, body {
+    height: 100%;
+}
+
+body {
+    line-height: 1.5;
+    background-color: #F1F3F6;
+    color: #34495E;
+    overflow-y: scroll;
+}
+
+header, nav, main, footer {
+    padding: 2px calc((100% - 800px) / 2) 0;
+}
+
+main {
+    margin-top: 54px;
+    margin-bottom: 54px;
+    min-height: calc(100vh - 345px);
+    overflow: auto;
+}
+
+h1 a {
+    font-size: 36px;
+    font-weight: bold;
+    background-image: url("/static/img/logo.png");
+    background-repeat: no-repeat;
+    background-position: 0px 0px;
+    height: 36px;
+    padding-left: 50px;
+    position: relative;
+}
+
+h1 a:hover {
+    text-decoration: none;
+    color: #34495E;
+}
+
+h2 {
+    font-size: 22px;
+    margin-bottom: 36px;
+    position: relative;
+    top: -9px;
+}
+
+a {
+    color: #62CB31;
+    text-decoration: none;
+}
+
+a:hover {
+    color: #4EB722;
+    text-decoration: underline;
+}
+
+textarea, input:not([type="submit"]) {
+    font-size: 18px;
+    font-family: "Ubuntu Mono", monospace;
+}
+
+header {
+    background-image: -webkit-linear-gradient(left, #34495e, #34495e 25%, #9b59b6 25%, #9b59b6 35%, #3498db 35%, #3498db 45%, #62cb31 45%, #62cb31 55%, #ffb606 55%, #ffb606 65%, #e67e22 65%, #e67e22 75%, #e74c3c 85%, #e74c3c 85%, #c0392b 85%, #c0392b 100%);
+    background-image: -moz-linear-gradient(left, #34495e, #34495e 25%, #9b59b6 25%, #9b59b6 35%, #3498db 35%, #3498db 45%, #62cb31 45%, #62cb31 55%, #ffb606 55%, #ffb606 65%, #e67e22 65%, #e67e22 75%, #e74c3c 85%, #e74c3c 85%, #c0392b 85%, #c0392b 100%);
+    background-image: -ms-linear-gradient(left, #34495e, #34495e 25%, #9b59b6 25%, #9b59b6 35%, #3498db 35%, #3498db 45%, #62cb31 45%, #62cb31 55%, #ffb606 55%, #ffb606 65%, #e67e22 65%, #e67e22 75%, #e74c3c 85%, #e74c3c 85%, #c0392b 85%, #c0392b 100%);
+    background-image: linear-gradient(to right, #34495e, #34495e 25%, #9b59b6 25%, #9b59b6 35%, #3498db 35%, #3498db 45%, #62cb31 45%, #62cb31 55%, #ffb606 55%, #ffb606 65%, #e67e22 65%, #e67e22 75%, #e74c3c 85%, #e74c3c 85%, #c0392b 85%, #c0392b 100%);
+    background-size: 100% 6px;
+    background-repeat: no-repeat;
+    border-bottom: 1px solid #E4E5E7;
+    overflow: auto;
+    padding-top: 33px;
+    padding-bottom: 27px;
+    text-align: center;
+}
+
+header a {
+    color: #34495E;
+    text-decoration: none;
+}
+
+nav {
+    border-bottom: 1px solid #E4E5E7;
+    padding-top: 17px;
+    padding-bottom: 15px;
+    background: #F7F9FA;
+    height: 60px;
+    color: #6A6C6F;
+}
+
+nav a {
+    margin-right: 1.5em;
+    display: inline-block;
+}
+
+nav form {
+    display: inline-block;
+    margin-left: 1.5em;
+}
+
+nav div {
+    width: 50%;
+    float: left;
+}
+
+nav div:last-child {
+    text-align: right;
+}
+
+nav div:last-child a {
+    margin-left: 1.5em;
+    margin-right: 0;
+}
+
+nav a.live {
+    color: #34495E;
+    cursor: default;
+}
+
+nav a.live:hover {
+    text-decoration: none;
+}
+
+nav a.live:after {
+    content: '';
+    display: block;
+    position: relative;
+    left: calc(50% - 7px);
+    top: 9px;
+    width: 14px;
+    height: 14px;
+    background: #F7F9FA;
+    border-left: 1px solid #E4E5E7;
+    border-bottom: 1px solid #E4E5E7;
+    -moz-transform: rotate(45deg);
+    -webkit-transform: rotate(-45deg);
+}
+
+a.button, input[type="submit"] {
+    background-color: #62CB31;
+    border-radius: 3px;
+    color: #FFFFFF;
+    padding: 18px 27px;
+    border: none;
+    display: inline-block;
+    margin-top: 18px;
+    font-weight: 700;
+}
+
+a.button:hover, input[type="submit"]:hover {
+    background-color: #4EB722;
+    color: #FFFFFF;
+    cursor: pointer;
+    text-decoration: none;
+}
+
+form div {
+    margin-bottom: 18px;
+}
+
+form div:last-child {
+    border-top: 1px dashed #E4E5E7;
+}
+
+form input[type="radio"] {
+    margin-left: 18px;
+}
+
+form input[type="text"], form input[type="password"], form input[type="email"] {
+    padding: 0.75em 18px;
+    width: 100%;
+}
+
+form input[type=text], form input[type="password"], form input[type="email"], textarea {
+    color: #6A6C6F;
+    background: #FFFFFF;
+    border: 1px solid #E4E5E7;
+    border-radius: 3px;
+}
+
+form label {
+    display: inline-block;
+    margin-bottom: 9px;
+}
+
+.error {
+    color: #C0392B;
+    font-weight: bold;
+    display: block;
+}
+
+.error + textarea, .error + input {
+    border-color: #C0392B !important;
+    border-width: 2px !important;
+}
+
+textarea {
+    padding: 18px;
+    width: 100%;
+    height: 266px;
+}
+
+button {
+    background: none;
+    padding: 0;
+    border: none;
+    color: #62CB31;
+    text-decoration: none;
+}
+
+button:hover {
+    color: #4EB722;
+    text-decoration: underline;
+    cursor: pointer;
+}
+
+.snippet {
+    background-color: #FFFFFF;
+    border: 1px solid #E4E5E7;
+    border-radius: 3px;
+}
+
+.snippet pre {
+    padding: 18px;
+    border-top: 1px solid #E4E5E7;
+    border-bottom: 1px solid #E4E5E7;
+}
+
+.snippet .metadata {
+    background-color: #F7F9FA;
+    color: #6A6C6F;
+    padding: 0.75em 18px;
+    overflow: auto;
+}
+
+.snippet .metadata span {
+    float: right;
+}
+
+.snippet .metadata strong {
+    color: #34495E;
+}
+
+.snippet .metadata time {
+    display: inline-block;
+}
+
+.snippet .metadata time:first-child {
+    float: left;
+}
+
+.snippet .metadata time:last-child {
+    float: right;
+}
+
+div.flash {
+    color: #FFFFFF;
+    font-weight: bold;
+    background-color: #34495E;
+    padding: 18px;
+    margin-bottom: 36px;
+    text-align: center;
+}
+
+div.error {
+    color: #FFFFFF;
+    background-color: #C0392B;
+    padding: 18px;
+    margin-bottom: 36px;
+    font-weight: bold;
+    text-align: center;
+}
+
+table {
+    background: white;
+    border: 1px solid #E4E5E7;
+    border-collapse: collapse;
+    width: 100%;
+}
+
+td, th {
+    text-align: left;
+    padding: 9px 18px;
+}
+
+th:last-child, td:last-child {
+    text-align: right;
+    color: #6A6C6F;
+}
+
+tr {
+    border-bottom: 1px solid #E4E5E7;
+}
+
+tr:nth-child(2n) {
+    background-color: #F7F9FA;
+}
+
+footer {
+    border-top: 1px solid #E4E5E7;
+    padding-top: 17px;
+    padding-bottom: 15px;
+    background: #F7F9FA;
+    height: 60px;
+    color: #6A6C6F;
+    text-align: center;
+}

ui/static/js/main.js

@@ -0,0 +1,8 @@
+var navLinks = document.querySelectorAll("nav a");
+for (var i = 0; i < navLinks.length; i++) {
+	var link = navLinks[i]
+	if (link.getAttribute('href') == window.location.pathname) {
+		link.classList.add("live");
+		break;
+	}
+}