refactor so external servers can use Finger as a handler

Author: Maronato

README.md

@@ -1,14 +1,65 @@
 # Finger
 
-Webfinger server written in Go.
+Webfinger handler / standalone server written in Go.
 
 ## Features
 - 🍰  Easy YAML configuration
 - 🪶  Single 8MB binary / 0% idle CPU / 4MB idle RAM
 - ⚡️   Sub millisecond responses at 10,000 request per second
 - 🐳  10MB Docker image
 
-## Install
+## In your existing server
+
+To use Finger in your existing server, download the package as a dependency:
+
+```bash
+go get git.maronato.dev/maronato/finger@latest
+```
+
+Then, use it as a regular `http.Handler`:
+
+```go
+package main
+
+import (
+	"log"
+	"net/http"
+
+	"git.maronato.dev/maronato/finger/handler"
+	"git.maronato.dev/maronato/finger/webfingers"
+)
+
+func main() {
+  // Create the webfingers map that will be served by the handler
+  fingers, err := webfingers.NewWebFingers(
+    // Pass a map of your resources (Subject key followed by it's properties and links)
+    // the syntax is the same as the fingers.yml file (see below)
+    webfingers.Resources{
+      "user@example.com": {
+        "name": "Example User",
+      },
+    },
+    // Optionally, pass a map of URN aliases (see urns.yml for more)
+    // If nil is provided, no aliases will be used
+    webfingers.URNAliases{
+      "name": "http://schema.org/name",
+    },
+  )
+  if err != nil {
+    log.Fatal(err)
+  }
+
+  mux := http.NewServeMux()
+  // Then use the handler as a regular http.Handler
+  mux.Handle("/.well-known/webfinger", handler.WebfingerHandler(fingers))
+
+  log.Fatal(http.ListenAndServe("localhost:8080", mux))
+}
+```
+
+## As a standalone server
+
+If you don't have a server, Finger can also serve itself. You can install it via `go install` or use the Docker image.
 
 Via `go install`:
 

cmd/serve.go

@@ -6,9 +6,9 @@ import (
 	"os"
 
 	"git.maronato.dev/maronato/finger/internal/config"
+	"git.maronato.dev/maronato/finger/internal/fingerreader"
 	"git.maronato.dev/maronato/finger/internal/log"
 	"git.maronato.dev/maronato/finger/internal/server"
-	"git.maronato.dev/maronato/finger/internal/webfinger"
 	"github.com/peterbourgon/ff/v4"
 )
 
@@ -25,21 +25,21 @@ func newServerCmd(cfg *config.Config) *ff.Command {
 			ctx = log.WithLogger(ctx, l)
 
 			// Read the webfinger files
-			r := webfinger.NewFingerReader()
+			r := fingerreader.NewFingerReader()
 			err := r.ReadFiles(cfg)
 			if err != nil {
 				return fmt.Errorf("error reading finger files: %w", err)
 			}
 
-			webfingers, err := r.ReadFingerFile(ctx)
+			fingers, err := r.ReadFingerFile(ctx)
 			if err != nil {
 				return fmt.Errorf("error parsing finger files: %w", err)
 			}
 
-			l.Info(fmt.Sprintf("Loaded %d webfingers", len(webfingers)))
+			l.Info(fmt.Sprintf("Loaded %d webfingers", len(fingers)))
 
 			// Start the server
-			if err := server.StartServer(ctx, cfg, webfingers); err != nil {
+			if err := server.StartServer(ctx, cfg, fingers); err != nil {
 				return fmt.Errorf("error running server: %w", err)
 			}
 

internal/server/webfinger.go renamed to handler/handler.go

@@ -1,22 +1,16 @@
-package server
+package handler
 
 import (
 	"encoding/json"
 	"net/http"
 
-	"git.maronato.dev/maronato/finger/internal/config"
-	"git.maronato.dev/maronato/finger/internal/log"
-	"git.maronato.dev/maronato/finger/internal/webfinger"
+	"git.maronato.dev/maronato/finger/webfingers"
 )
 
-func WebfingerHandler(_ *config.Config, webfingers webfinger.WebFingers) http.Handler {
+func WebfingerHandler(fingers webfingers.WebFingers) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		ctx := r.Context()
-		l := log.FromContext(ctx)
-
 		// Only handle GET requests
 		if r.Method != http.MethodGet {
-			l.Debug("Method not allowed")
 			http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
 
 			return
@@ -28,16 +22,14 @@ func WebfingerHandler(_ *config.Config, webfingers webfinger.WebFingers) http.Ha
 		// Get the resource
 		resource := q.Get("resource")
 		if resource == "" {
-			l.Debug("No resource provided")
 			http.Error(w, "No resource provided", http.StatusBadRequest)
 
 			return
 		}
 
 		// Get and validate resource
-		finger, ok := webfingers[resource]
+		finger, ok := fingers[resource]
 		if !ok {
-			l.Debug("Resource not found")
 			http.Error(w, "Resource not found", http.StatusNotFound)
 
 			return
@@ -48,12 +40,9 @@ func WebfingerHandler(_ *config.Config, webfingers webfinger.WebFingers) http.Ha
 
 		// Write the response
 		if err := json.NewEncoder(w).Encode(finger); err != nil {
-			l.Debug("Error encoding json")
 			http.Error(w, "Error encoding json", http.StatusInternalServerError)
 
 			return
 		}
-
-		l.Debug("Webfinger request successful")
 	})
 }

internal/server/webfinger_test.go renamed to handler/handler_test.go

@@ -1,4 +1,4 @@
-package server_test
+package handler_test
 
 import (
 	"context"
@@ -10,19 +10,19 @@ import (
 	"strings"
 	"testing"
 
+	"git.maronato.dev/maronato/finger/handler"
 	"git.maronato.dev/maronato/finger/internal/config"
 	"git.maronato.dev/maronato/finger/internal/log"
-	"git.maronato.dev/maronato/finger/internal/server"
-	"git.maronato.dev/maronato/finger/internal/webfinger"
+	"git.maronato.dev/maronato/finger/webfingers"
 )
 
 func TestWebfingerHandler(t *testing.T) {
 	t.Parallel()
 
-	webfingers := webfinger.WebFingers{
+	fingers := webfingers.WebFingers{
 		"acct:user@example.com": {
 			Subject: "acct:user@example.com",
-			Links: []webfinger.Link{
+			Links: []webfingers.Link{
 				{
 					Rel:  "http://webfinger.net/rel/profile-page",
 					Href: "https://example.com/user",
@@ -104,7 +104,7 @@ func TestWebfingerHandler(t *testing.T) {
 			w := httptest.NewRecorder()
 
 			// Create a new handler
-			h := server.WebfingerHandler(cfg, webfingers)
+			h := handler.WebfingerHandler(fingers)
 
 			// Serve the request
 			h.ServeHTTP(w, r)
@@ -121,8 +121,8 @@ func TestWebfingerHandler(t *testing.T) {
 					t.Errorf("expected content type %s, got %s", "application/jrd+json", w.Header().Get("Content-Type"))
 				}
 
-				fingerWant := webfingers[tc.resource]
-				fingerGot := &webfinger.WebFinger{}
+				fingerWant := fingers[tc.resource]
+				fingerGot := &webfingers.WebFinger{}
 
 				// Decode the response body
 				if err := json.NewDecoder(w.Body).Decode(fingerGot); err != nil {
@@ -147,3 +147,30 @@ func TestWebfingerHandler(t *testing.T) {
 		})
 	}
 }
+
+func BenchmarkWebfingerHandler(b *testing.B) {
+	fingers, err := webfingers.NewWebFingers(
+		webfingers.Resources{
+			"user@example.com": {
+				"prop1": "value1",
+			},
+		},
+		nil,
+	)
+	if err != nil {
+		b.Fatal(err)
+	}
+
+	h := handler.WebfingerHandler(fingers)
+	r := httptest.NewRequest(http.MethodGet, "/.well-known/webfinger?resource=acct:user@example.com", http.NoBody)
+
+	for i := 0; i < b.N; i++ {
+		w := httptest.NewRecorder()
+
+		h.ServeHTTP(w, r)
+
+		if w.Code != http.StatusOK {
+			b.Errorf("expected status code %d, got %d", http.StatusOK, w.Code)
+		}
+	}
+}

internal/fingerreader/fingerreader.go

@@ -0,0 +1,89 @@
+package fingerreader
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"net/url"
+	"os"
+
+	"git.maronato.dev/maronato/finger/internal/config"
+	"git.maronato.dev/maronato/finger/internal/log"
+	"git.maronato.dev/maronato/finger/webfingers"
+	"gopkg.in/yaml.v3"
+)
+
+type FingerReader struct {
+	URNSFile    []byte
+	FingersFile []byte
+}
+
+func NewFingerReader() *FingerReader {
+	return &FingerReader{}
+}
+
+func (f *FingerReader) ReadFiles(cfg *config.Config) error {
+	// Read URNs file
+	file, err := os.ReadFile(cfg.URNPath)
+	if err != nil {
+		// If the file does not exist and the path is the default, set the URNs to an empty map
+		if os.IsNotExist(err) && cfg.URNPath == config.DefaultURNPath {
+			f.URNSFile = []byte("")
+		} else {
+			return fmt.Errorf("error opening URNs file: %w", err)
+		}
+	}
+
+	f.URNSFile = file
+
+	// Read fingers file
+	file, err = os.ReadFile(cfg.FingerPath)
+	if err != nil {
+		// If the file does not exist and the path is the default, set the fingers to an empty map
+		if os.IsNotExist(err) && cfg.FingerPath == config.DefaultFingerPath {
+			f.FingersFile = []byte("")
+		} else {
+			return fmt.Errorf("error opening fingers file: %w", err)
+		}
+	}
+
+	f.FingersFile = file
+
+	return nil
+}
+
+func (f *FingerReader) ReadFingerFile(ctx context.Context) (webfingers.WebFingers, error) {
+	l := log.FromContext(ctx)
+
+	urnAliases := make(webfingers.URNAliases)
+	resources := make(webfingers.Resources)
+
+	// Parse the URNs file
+	if err := yaml.Unmarshal(f.URNSFile, &urnAliases); err != nil {
+		return nil, fmt.Errorf("error unmarshalling URNs file: %w", err)
+	}
+
+	// The URNs file must be a map of strings to valid URLs
+	for _, v := range urnAliases {
+		if _, err := url.ParseRequestURI(v); err != nil {
+			return nil, fmt.Errorf("error parsing URN URIs: %w", err)
+		}
+	}
+
+	l.Debug("URNs file parsed successfully", slog.Int("number", len(urnAliases)), slog.Any("data", urnAliases))
+
+	// Parse the fingers file
+	if err := yaml.Unmarshal(f.FingersFile, &resources); err != nil {
+		return nil, fmt.Errorf("error unmarshalling fingers file: %w", err)
+	}
+
+	l.Debug("Fingers file parsed successfully", slog.Int("number", len(resources)), slog.Any("data", resources))
+
+	// Parse raw data
+	fingers, err := webfingers.NewWebFingers(resources, urnAliases)
+	if err != nil {
+		return nil, fmt.Errorf("error parsing raw fingers: %w", err)
+	}
+
+	return fingers, nil
+}