go comments

Author: aspage2

mpd-web-proxy/events.go

@@ -19,11 +19,15 @@ const (
 	EventTypeMPD
 )
 
-func startChannelListener(mpd net.Conn) chan string {
+// The MPD Idler uses the MPD idle command to receive
+// notifications when the state has changed on the MPD
+// server. It relays what has changed on the returned
+// channel.
+func startMPDIdler(mpd net.Conn) chan string {
 	eventC := make(chan string)
 	go func() {
-		slog.Debug("start channel listener")
-		defer slog.Debug("end channel listener")
+		slog.Debug("start MPD Idler")
+		defer slog.Debug("end MPD Idler")
 		defer close(eventC)
 		sc := bufio.NewScanner(mpd)
 		// MPD Header
@@ -56,11 +60,19 @@ func startChannelListener(mpd net.Conn) chan string {
 	return eventC
 }
 
+// An Event is any asynchronous event 
+// that should be sent to a listening client.
 type Event struct {
 	Type EventType
 	Data string
 }
 
+// getEvents starts a goroutine which emits events
+// to send to the client. Events include:
+//   - any string sent on the provided string channel is sent as an MPDEvent
+//   - the emitter produces a "ping" event that clients can use as a heartbeat.
+// The emitter exits and closes the returned channel when the given context
+// is cancelled.
 func getEvents(ts chan string, ctx context.Context) chan Event {
 	ret := make(chan Event)
 	ticker := time.NewTicker(5 * time.Second)

mpd-web-proxy/main.go

@@ -95,6 +95,13 @@ func WriteBadRequest(rw http.ResponseWriter, msg string) {
 	fmt.Fprintf(rw, "ACK: %s\n", msg)
 }
 
+// Use server-sent events (SSE) to notify the client in
+// real time when the MPD server state has changed. Internally,
+// uses the mpd "idle" command and sends idle values as event
+// data to the client.
+//
+// Additionally, the endpoint will deliver "ping" events on
+// a set interval as a sort of heartbeat.
 func MpdEvents(rw http.ResponseWriter, req *http.Request) {
 	slog.Info(fmt.Sprintf("%s %s", req.RemoteAddr, req.URL))
 	defer slog.Info(fmt.Sprintf("%s %s CLIENT EXIT", req.RemoteAddr, req.URL))
@@ -113,7 +120,7 @@ func MpdEvents(rw http.ResponseWriter, req *http.Request) {
 
 	mpd := Must(net.Dial("tcp", MpdAuthority))
 	defer mpd.Close()
-	events := startChannelListener(mpd)
+	events := startMPDIdler(mpd)
 	for ev := range getEvents(events, req.Context()) {
 		var eventPayload string
 		switch ev.Type {
@@ -134,6 +141,8 @@ func MpdEvents(rw http.ResponseWriter, req *http.Request) {
 	}
 }
 
+// MpdCommand is an endpoint which sends the client query
+// to MPD and returns the MPD response in the HTTP body.
 func MpdCommand(rw http.ResponseWriter, req *http.Request) {
 	qs, ok := req.URL.Query()["q"]
 	if !ok {
@@ -145,6 +154,7 @@ func MpdCommand(rw http.ResponseWriter, req *http.Request) {
 	rw.Write(data)
 }
 
+// Returns the verson of the MPD server being used.
 func MpdVersion(rw http.ResponseWriter, req *http.Request) {
 	conn := Must(net.Dial("tcp", MpdAuthority))
 	defer conn.Close()
@@ -173,6 +183,8 @@ func chooseAFile(sc *bufio.Scanner) (string, error) {
 	return "", sc.Err()
 }
 
+// The AlbumArt endpoint searches in the album directory
+// or the ID3 tags in one of the track files for the album.
 func AlbumArt(rw http.ResponseWriter, req *http.Request) {
 	conn := Must(net.Dial("tcp", MpdAuthority))
 	defer conn.Close()
@@ -206,6 +218,7 @@ func AlbumArt(rw http.ResponseWriter, req *http.Request) {
 	io.Copy(rw, bytes.NewReader(data))
 }
 
+// Build the server.
 func httpServer(s *Server) {
 	var nonEventMux http.ServeMux
 	nonEventMux.HandleFunc("/go/version", func(w http.ResponseWriter, r *http.Request) {
@@ -222,6 +235,7 @@ func httpServer(s *Server) {
 	http.ListenAndServe(BindAddr, nil)
 }
 
+// Panic on any error.
 func Must[T any](t T, err error) T {
 	if err != nil {
 		panic(err)

mpd-web-proxy/mpd.go

@@ -11,6 +11,9 @@ import (
 	"strings"
 )
 
+// MpdQuery connects and queries the MPD server
+// with the given command. Returns the response body
+// or any connection error.
 func MpdQuery(cmd string) ([]byte, error) {
 	mpd, err := net.Dial("tcp", MpdAuthority)
 	if err != nil {
@@ -20,6 +23,7 @@ func MpdQuery(cmd string) ([]byte, error) {
 	return mpdQuery(cmd, mpd)
 }
 
+// A cancellable MPD Query.
 func MpdQueryContext(cmd string, ctx context.Context) ([]byte, error) {
 	mpd, err := net.Dial("tcp", MpdAuthority)
 	if err != nil {
@@ -33,6 +37,8 @@ func MpdQueryContext(cmd string, ctx context.Context) ([]byte, error) {
 	return mpdQuery(cmd, mpd)
 }
 
+// mpdQuery reads and parses a response stream
+// to verify that the response is valid.
 func mpdQuery(cmd string, mpd io.ReadWriter) ([]byte, error) {
 	scanner := bufio.NewScanner(mpd)
 	if !scanner.Scan() {