add file handler api

Author: davidnewhall

pkg/api/api.go

@@ -0,0 +1,41 @@
+// Package api provides an HTTP API for listing, fetching, and deleting files
+// written by the UDP ingest path. All operations are scoped to output_path.
+package api
+
+import (
+	"net/http"
+	"path/filepath"
+
+	"github.com/gorilla/mux"
+)
+
+// API handles HTTP routes for the file management API.
+type API struct {
+	outputPath string
+	password   string
+}
+
+// New returns an API instance rooted at outputPath.
+// password is compared against the X-Api-Key request header; an empty string disables auth.
+func New(outputPath, password string) *API {
+	return &API{
+		outputPath: filepath.Clean(outputPath),
+		password:   password,
+	}
+}
+
+// Register mounts all API routes onto smuthe server muxx and is intended to be passed as the
+// register callback to httpserver.New.
+func (a *API) Register(smx *http.ServeMux) {
+	router := mux.NewRouter()
+	apiRouter := router.PathPrefix("/api").Subrouter()
+	apiRouter.Use(a.authenticate)
+
+	apiRouter.HandleFunc("/list/{path:.+}", a.listHandler).Methods(http.MethodGet)
+	apiRouter.HandleFunc("/file/{path:.+}", a.fileHandler).Methods(http.MethodGet)
+	apiRouter.HandleFunc("/all", a.deleteAllHandler).Methods(http.MethodDelete)
+	apiRouter.HandleFunc("/{path:.+}", a.deleteHandler).Methods(http.MethodDelete)
+
+	smx.Handle("/api/", router)
+	smx.Handle("/api", router)
+}

pkg/api/handlers.go

@@ -0,0 +1,200 @@
+package api
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/gorilla/mux"
+)
+
+// Entry describes a file or directory returned by the list endpoint.
+type Entry struct {
+	Path    string    `json:"path"`
+	Size    int64     `json:"size"`
+	IsDir   bool      `json:"isDir"`
+	ModTime time.Time `json:"modTime"`
+}
+
+// DeleteResult describes the outcome of a delete request.
+type DeleteResult struct {
+	Deleted int      `json:"deleted"`
+	Paths   []string `json:"paths"`
+}
+
+// listHandler handles GET /api/list/{path}.
+// It returns the contents of all directories matching the (possibly glob) path.
+// A final /* is always appended so the response contains entries rather than
+// the matched directories themselves — clients should omit the trailing wildcard.
+func (a *API) listHandler(resp http.ResponseWriter, r *http.Request) {
+	rawPath := mux.Vars(r)["path"]
+
+	pattern, err := a.safePath(rawPath)
+	if err != nil {
+		writeError(resp, http.StatusBadRequest, err.Error())
+		return
+	}
+
+	// Append /* to list contents of each matched directory.
+	pattern = filepath.Join(pattern, "*")
+
+	matches, err := a.globSafe(pattern)
+	if err != nil {
+		writeError(resp, http.StatusInternalServerError, err.Error())
+		return
+	}
+
+	entries := make([]Entry, 0, len(matches))
+
+	for _, match := range matches {
+		info, statErr := os.Lstat(match)
+		if statErr != nil {
+			continue
+		}
+
+		relPath := strings.TrimPrefix(match, a.outputPath+string(filepath.Separator))
+		entries = append(entries, Entry{
+			Path:    relPath,
+			Size:    info.Size(),
+			IsDir:   info.IsDir(),
+			ModTime: info.ModTime().UTC(),
+		})
+	}
+
+	writeJSON(resp, http.StatusOK, entries)
+}
+
+// fileHandler handles GET /api/file/{path} and streams the file contents.
+// Wildcards are not permitted; use /api/list/ first to find file paths.
+func (a *API) fileHandler(resp http.ResponseWriter, req *http.Request) {
+	rawPath := mux.Vars(req)["path"]
+
+	filePath, err := a.safePath(rawPath)
+	if err != nil {
+		writeError(resp, http.StatusBadRequest, err.Error())
+		return
+	}
+
+	if strings.ContainsRune(filePath, '*') {
+		writeError(resp, http.StatusBadRequest, "wildcards not allowed for file fetch; use /api/list/ first")
+		return
+	}
+
+	info, err := os.Stat(filePath)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			writeError(resp, http.StatusNotFound, "not found: "+filePath)
+		} else {
+			writeError(resp, http.StatusInternalServerError, "stat: "+err.Error())
+		}
+
+		return
+	}
+
+	if info.IsDir() {
+		writeError(resp, http.StatusBadRequest, "path is a directory; use /api/list/")
+		return
+	}
+
+	fileHandle, err := os.Open(filePath) //nolint:gosec // path validated against outputPath
+	if err != nil {
+		writeError(resp, http.StatusInternalServerError, "opening file: "+err.Error())
+		return
+	}
+	defer fileHandle.Close()
+
+	http.ServeContent(resp, req, info.Name(), info.ModTime(), fileHandle)
+}
+
+// deleteHandler handles DELETE /api/{path} and removes all files or directories
+// matching the path. The path may contain * wildcards in any segment.
+func (a *API) deleteHandler(resp http.ResponseWriter, r *http.Request) {
+	rawPath := mux.Vars(r)["path"]
+
+	pattern, err := a.safePath(rawPath)
+	if err != nil {
+		writeError(resp, http.StatusBadRequest, err.Error())
+		return
+	}
+
+	matches, err := a.resolveForDelete(pattern)
+	if err != nil {
+		writeError(resp, http.StatusInternalServerError, err.Error())
+		return
+	}
+
+	deleted := make([]string, 0, len(matches))
+
+	for _, match := range matches {
+		err = os.RemoveAll(match)
+		if err == nil {
+			deleted = append(deleted, strings.TrimPrefix(match, a.outputPath+string(filepath.Separator)))
+		}
+	}
+
+	writeJSON(resp, http.StatusOK, DeleteResult{Deleted: len(deleted), Paths: deleted})
+}
+
+// resolveForDelete returns the filesystem paths to act on for the given pattern.
+// When the pattern contains no wildcard it returns the pattern if it exists.
+func (a *API) resolveForDelete(pattern string) ([]string, error) {
+	if !strings.ContainsRune(pattern, '*') {
+		_, statErr := os.Stat(pattern)
+
+		if errors.Is(statErr, os.ErrNotExist) {
+			return nil, nil
+		}
+
+		if statErr != nil {
+			return nil, fmt.Errorf("stat: %w", statErr)
+		}
+
+		return []string{pattern}, nil
+	}
+
+	return a.globSafe(pattern)
+}
+
+// deleteAllHandler handles DELETE /api/all and removes every entry directly
+// inside outputPath, including directories.
+func (a *API) deleteAllHandler(resp http.ResponseWriter, _ *http.Request) {
+	entries, err := os.ReadDir(a.outputPath)
+	if err != nil && !errors.Is(err, os.ErrNotExist) {
+		writeError(resp, http.StatusInternalServerError, "reading output path: "+err.Error())
+		return
+	}
+
+	var count int
+
+	for _, entry := range entries {
+		removeErr := os.RemoveAll(filepath.Join(a.outputPath, entry.Name()))
+		if removeErr == nil {
+			count++
+		}
+	}
+
+	writeJSON(resp, http.StatusOK, map[string]int{"deleted": count})
+}
+
+// writeJSON writes data as a JSON response body with the given status code.
+func writeJSON(resp http.ResponseWriter, status int, data any) {
+	body, err := json.Marshal(data)
+	if err != nil {
+		http.Error(resp, `{"error":"internal server error"}`, http.StatusInternalServerError)
+		return
+	}
+
+	resp.Header().Set("Content-Type", "application/json")
+	resp.WriteHeader(status)
+	_, _ = resp.Write(body)
+}
+
+// writeError writes a JSON error response.
+func writeError(resp http.ResponseWriter, status int, msg string) {
+	writeJSON(resp, status, map[string]string{"error": msg})
+}

pkg/api/middleware.go

@@ -0,0 +1,16 @@
+package api
+
+import "net/http"
+
+// authenticate validates the X-Api-Key header against the configured password.
+// When password is empty, all requests are allowed through.
+func (a *API) authenticate(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(resp http.ResponseWriter, req *http.Request) {
+		if a.password != "" && req.Header.Get("X-Api-Key") != a.password {
+			writeError(resp, http.StatusUnauthorized, "invalid or missing X-Api-Key")
+			return
+		}
+
+		next.ServeHTTP(resp, req)
+	})
+}

pkg/api/paths.go

@@ -0,0 +1,72 @@
+package api
+
+import (
+	"errors"
+	"fmt"
+	"path/filepath"
+	"slices"
+	"strings"
+)
+
+// Sentinel errors returned by path validation.
+var (
+	errPathTraversal = errors.New("path traversal not allowed")
+	errPathEscapes   = errors.New("path escapes output directory")
+)
+
+// safePath joins rawPath with outputPath and validates that the result stays
+// within outputPath. For glob paths (containing *), the static prefix before
+// the first wildcard is validated.
+func (a *API) safePath(rawPath string) (string, error) {
+	// Strip leading slashes so filepath.Join does not treat rawPath as absolute.
+	rawPath = strings.TrimLeft(rawPath, "/")
+
+	if slices.Contains(strings.Split(rawPath, "/"), "..") {
+		return "", errPathTraversal
+	}
+
+	joined := filepath.Join(a.outputPath, rawPath)
+	prefix, _, hasWildcard := strings.Cut(joined, "*")
+
+	if !hasWildcard {
+		clean := filepath.Clean(joined)
+
+		if !a.isUnder(clean) {
+			return "", errPathEscapes
+		}
+
+		return clean, nil
+	}
+
+	// For glob paths, verify the static prefix before the first wildcard.
+	if !a.isUnder(filepath.Clean(prefix)) {
+		return "", errPathEscapes
+	}
+
+	return joined, nil
+}
+
+// isUnder reports whether path equals outputPath or is directly beneath it.
+func (a *API) isUnder(path string) bool {
+	return path == a.outputPath ||
+		strings.HasPrefix(path, a.outputPath+string(filepath.Separator))
+}
+
+// globSafe expands pattern with filepath.Glob and returns only results that
+// are confirmed to be under outputPath.
+func (a *API) globSafe(pattern string) ([]string, error) {
+	matches, err := filepath.Glob(pattern)
+	if err != nil {
+		return nil, fmt.Errorf("glob pattern: %w", err)
+	}
+
+	result := make([]string, 0, len(matches))
+
+	for _, match := range matches {
+		if a.isUnder(filepath.Clean(match)) {
+			result = append(result, match)
+		}
+	}
+
+	return result, nil
+}

pkg/fog/start.go

@@ -9,6 +9,7 @@ import (
 	"sync"
 	"time"
 
+	"github.com/Notifiarr/fogwillow/pkg/api"
 	"github.com/Notifiarr/fogwillow/pkg/buf"
 	"github.com/Notifiarr/fogwillow/pkg/httpserver"
 	"github.com/Notifiarr/fogwillow/pkg/metrics"
@@ -102,7 +103,8 @@ func (c *Config) Start() error {
 		go c.packetListener(idx)
 	}
 
-	c.httpSrv = httpserver.New(c.HTTPServer, nil)
+	fogAPI := api.New(c.OutputPath, c.Password)
+	c.httpSrv = httpserver.New(c.HTTPServer, fogAPI.Register)
 
 	err = c.httpSrv.ListenAndServe()
 	if err != nil {