Add SPA fallback support and detailed project guidelines

- Introduced Single Page Application (SPA) fallback mode for 404 handling.
- Added a comprehensive `CLAUDE.md` guide with project architecture, configuration, and commands.

Author: cjimti

.gitignore

@@ -1,5 +1,7 @@
 .idea
+.claude
 dist
+asws
 
 # Binaries for programs and plugins
 *.exe

CLAUDE.md

@@ -0,0 +1,129 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+ASWS (A Static Web Server) is a lightweight, configurable static web server built with Go. It uses the Gin web framework and includes built-in Prometheus metrics support. The project is designed to be deployed as a Docker container, with multi-architecture support via GoReleaser.
+
+## Architecture
+
+### Single Binary Application
+- Main entry point: `cmd/asws.go`
+- Self-contained Go binary with no external dependencies
+- All configuration via environment variables or command-line flags
+- No test files present in the codebase
+
+### Core Components
+
+**Web Server (`cmd/asws.go`)**
+- Uses Gin web framework in release mode (or debug mode when DEBUG=true)
+- Structured logging via uber/zap with request logging middleware
+- Two-server architecture:
+  - Main server: Serves static content (configurable IP/port)
+  - Metrics server: Prometheus metrics endpoint (runs in goroutine on separate port)
+
+**Static File Serving**
+- Primary static path: Configurable via STATIC_PATH/STATIC_DIR (default: "/" serves from "./www")
+- Optional filesystem mode: Additional file browsing via FS_PATH/FS_DIR (default: "/files" from "./files")
+- Custom 404 handling: Can serve custom 404.html or redirect to a path
+
+**Metrics & Observability**
+- Prometheus metrics exposed on separate port (default: 2112)
+- Service info metrics include Go version, service version, and service name
+- Request logging integrated with zap logger
+
+## Common Commands
+
+### Development
+
+**Build the application:**
+```bash
+go build -o asws ./cmd/asws.go
+```
+
+**Run locally:**
+```bash
+go run ./cmd/asws.go -debug=true -port=8080
+```
+
+**Run with custom configuration:**
+```bash
+DEBUG=true PORT=8080 STATIC_DIR=./www go run ./cmd/asws.go
+```
+
+### Docker
+
+**Build Docker image:**
+```bash
+docker build -t asws:local .
+```
+
+**Run Docker container:**
+```bash
+docker run -e DEBUG=true -p 2701:80 -v "$(pwd)"/www:/www txn2/asws:latest
+```
+
+### Release Management
+
+**Test release locally (without publishing):**
+```bash
+goreleaser --skip-publish --rm-dist --skip-validate
+```
+
+**Create and publish release:**
+```bash
+GITHUB_TOKEN=$GITHUB_TOKEN goreleaser --rm-dist
+```
+
+## Configuration
+
+All configuration uses environment variables or command-line flags (flags override env vars). Key variables:
+
+- **IP/PORT**: Bind address and main server port (default: 127.0.0.1:8080)
+- **STATIC_DIR/STATIC_PATH**: Where and how to serve static files (default: ./www at /)
+- **FS_ENABLED/FS_DIR/FS_PATH**: Optional file browsing endpoint (default: disabled)
+- **NOT_FOUND_REDIRECT/NOT_FOUND_REDIRECT_PATH**: Redirect behavior for 404s (default: false)
+- **NOT_FOUND_FILE**: Custom 404 page (default: ./www/404.html)
+- **DEBUG**: Enable debug mode and verbose logging (default: false)
+- **METRICS/METRICS_PORT**: Prometheus metrics server (default: enabled on 2112)
+- **APP_NAME/APP_VERSION**: Application metadata for logging
+
+See `cmd/asws.go:20-35` for complete configuration reference with defaults.
+
+## Release Process
+
+GoReleaser handles multi-platform builds and Docker image creation:
+
+- **Platforms**: Linux and Darwin (macOS) for 386, amd64, arm, arm64
+- **Docker variants**:
+  - Scratch-based images (minimal size, multi-tag: latest, versioned, major version)
+  - Alpine-based images (with shell/debugging tools)
+- **Artifacts**: Binaries, checksums, deb/rpm/apk packages
+- **Version injection**: Version string injected at build time via ldflags (`-X main.Version={{.Version}}`)
+
+The build is configured in `goreleaser.yml`.
+
+## Directory Structure
+
+```
+cmd/           - Main application entry point
+www/           - Default static content directory
+files/         - Default file browsing directory (when FS_ENABLED=true)
+dockerfiles/   - Docker build configurations (scratch and alpine variants)
+```
+
+## Dependencies
+
+Core dependencies:
+- `github.com/gin-gonic/gin` - HTTP web framework
+- `github.com/gin-contrib/zap` - Zap logging middleware for Gin
+- `go.uber.org/zap` - Structured logging
+- `github.com/prometheus/client_golang` - Prometheus metrics
+
+## Notes
+
+- No automated tests exist in this codebase
+- The application is designed for container deployment with security considerations (runs as nobody user in Docker)
+- CGO is disabled for static binary compilation
+- Version information is injected at build time, not hardcoded

README.md

@@ -8,11 +8,24 @@ The following example exposes port 2701 on your local machine and forwards all t
 docker run -e DEBUG=true -p 2701:80 -v "$(pwd)"/www:/www txn2/asws:v1.6.1
 ```
 
+## SPA (Single Page Application) Mode
+
+For modern React, Vue, or Angular applications with client-side routing, enable SPA fallback mode:
+
+```bash
+docker run -e SPA_FALLBACK=true -p 8080:80 -v "$(pwd)"/dist:/www txn2/asws:latest
+```
+
+This mode serves `index.html` with a 200 status code for any non-file request, allowing client-side routers to handle routing.
+
+**Note:** SPA_FALLBACK takes precedence over NOT_FOUND_REDIRECT and NOT_FOUND_FILE.
+
 ## Environment Variable Defaults
 
 - PORT="80"
 - STATIC_DIR="./www"
 - STATIC_PATH="./www"
+- SPA_FALLBACK="false"
 - FS_ENABLED="no"
 - FS_DIR="./files"
 - FS_PATH="/files"

cmd/asws.go

@@ -24,6 +24,7 @@ var (
 	notFoundRedirectEnv     = getEnv("NOT_FOUND_REDIRECT", "false")
 	notFoundRedirectPathEnv = getEnv("NOT_FOUND_REDIRECT_PATH", "/")
 	notFoundFileEnv         = getEnv("NOT_FOUND_FILE", "./www/404.html")
+	spaFallbackEnv          = getEnv("SPA_FALLBACK", "false")
 	fsEnabledEnv            = getEnv("FS_ENABLED", "false")
 	fsDirEnv                = getEnv("FS_DIR", "./files")
 	fsPathEnv               = getEnv("FS_PATH", "/files")
@@ -47,6 +48,7 @@ func main() {
 		notFoundRedirect     = flag.String("notFoundRedirect", notFoundRedirectEnv, "redirect on not found?")
 		notFoundRedirectPath = flag.String("notFoundRedirectPath", notFoundRedirectPathEnv, "not found redirect path")
 		notFoundFile         = flag.String("notFoundFile", notFoundFileEnv, "not found file to serve")
+		spaFallback          = flag.String("spaFallback", spaFallbackEnv, "SPA fallback mode (serve index.html on 404)")
 		fsEnabled            = flag.String("fsEnabled", fsEnabledEnv, "filesystem enabled")
 		fsDir                = flag.String("fsDir", fsDirEnv, "filesystem directory")
 		fsPath               = flag.String("fsPath", fsPathEnv, "filesystem path")
@@ -102,12 +104,35 @@ func main() {
 	r.Static(*staticPath, *staticDir)
 
 	r.NoRoute(func(c *gin.Context) {
+		// SPA fallback mode - serve index.html with 200 status for non-file requests
+		if *spaFallback == "true" {
+			indexPath := *staticDir + "/index.html"
+			content, err := os.ReadFile(indexPath)
+			if err != nil {
+				logger.Error("SPA index.html not found", zap.String("file", indexPath))
+				c.String(http.StatusNotFound, http.StatusText(http.StatusNotFound))
+				return
+			}
+
+			c.Writer.WriteHeader(http.StatusOK) // Important: 200 not 404
+			c.Writer.Header().Set("Content-Type", "text/html; charset=utf-8")
+			_, err = c.Writer.Write(content)
+			if err != nil {
+				logger.Error("SPA write error", zap.Error(err))
+				c.String(http.StatusInternalServerError, http.StatusText(http.StatusInternalServerError))
+				return
+			}
+			return
+		}
+
+		// Redirect mode (existing functionality)
 		if *notFoundRedirect == "true" {
 			c.Redirect(http.StatusTemporaryRedirect, *notFoundRedirectPath)
 			c.Abort()
 			return
 		}
 
+		// Custom 404 file mode (existing functionality)
 		content, err := os.ReadFile(*notFoundFile)
 		if err != nil {
 			logger.Error("404 content not found", zap.String("file", *notFoundFile))

go.mod

@@ -1,49 +1,53 @@
 module github.com/txn2/asws
 
-go 1.21
-toolchain go1.24.1
+go 1.24.7
 
 require (
-	github.com/gin-contrib/zap v0.1.0
-	github.com/gin-gonic/gin v1.9.1
-	github.com/prometheus/client_golang v1.16.0
-	go.uber.org/zap v1.25.0
+	github.com/gin-contrib/zap v1.1.5
+	github.com/gin-gonic/gin v1.11.0
+	github.com/prometheus/client_golang v1.23.2
+	go.uber.org/zap v1.27.0
 )
 
 require (
 	github.com/beorn7/perks v1.0.1 // indirect
-	github.com/bytedance/sonic v1.10.0 // indirect
-	github.com/cespare/xxhash/v2 v2.2.0 // indirect
-	github.com/chenzhuoyu/base64x v0.0.0-20230717121745-296ad89f973d // indirect
-	github.com/chenzhuoyu/iasm v0.9.0 // indirect
-	github.com/gabriel-vasile/mimetype v1.4.2 // indirect
-	github.com/gin-contrib/sse v0.1.0 // indirect
+	github.com/bytedance/gopkg v0.1.3 // indirect
+	github.com/bytedance/sonic v1.14.2 // indirect
+	github.com/bytedance/sonic/loader v0.4.0 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/cloudwego/base64x v0.1.6 // indirect
+	github.com/gabriel-vasile/mimetype v1.4.11 // indirect
+	github.com/gin-contrib/sse v1.1.0 // indirect
 	github.com/go-playground/locales v0.14.1 // indirect
 	github.com/go-playground/universal-translator v0.18.1 // indirect
-	github.com/go-playground/validator/v10 v10.15.1 // indirect
-	github.com/goccy/go-json v0.10.2 // indirect
-	github.com/golang/protobuf v1.5.3 // indirect
+	github.com/go-playground/validator/v10 v10.28.0 // indirect
+	github.com/goccy/go-json v0.10.5 // indirect
+	github.com/goccy/go-yaml v1.18.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
-	github.com/klauspost/cpuid/v2 v2.2.5 // indirect
-	github.com/leodido/go-urn v1.2.4 // indirect
-	github.com/mattn/go-isatty v0.0.19 // indirect
-	github.com/matttproud/golang_protobuf_extensions v1.0.4 // indirect
+	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
+	github.com/leodido/go-urn v1.4.0 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
-	github.com/pelletier/go-toml/v2 v2.0.9 // indirect
-	github.com/prometheus/client_model v0.4.0 // indirect
-	github.com/prometheus/common v0.44.0 // indirect
-	github.com/prometheus/procfs v0.11.1 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+	github.com/prometheus/client_model v0.6.2 // indirect
+	github.com/prometheus/common v0.66.1 // indirect
+	github.com/prometheus/procfs v0.16.1 // indirect
+	github.com/quic-go/qpack v0.5.1 // indirect
+	github.com/quic-go/quic-go v0.55.0 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
-	github.com/ugorji/go/codec v1.2.11 // indirect
-	go.opentelemetry.io/otel v1.16.0 // indirect
-	go.opentelemetry.io/otel/trace v1.16.0 // indirect
+	github.com/ugorji/go/codec v1.3.1 // indirect
+	go.uber.org/mock v0.6.0 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
-	golang.org/x/arch v0.4.0 // indirect
-	golang.org/x/crypto v0.36.0 // indirect
-	golang.org/x/net v0.38.0 // indirect
-	golang.org/x/sys v0.31.0 // indirect
-	golang.org/x/text v0.23.0 // indirect
-	google.golang.org/protobuf v1.33.0 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
+	go.yaml.in/yaml/v2 v2.4.2 // indirect
+	golang.org/x/arch v0.22.0 // indirect
+	golang.org/x/crypto v0.43.0 // indirect
+	golang.org/x/mod v0.29.0 // indirect
+	golang.org/x/net v0.46.0 // indirect
+	golang.org/x/sync v0.17.0 // indirect
+	golang.org/x/sys v0.37.0 // indirect
+	golang.org/x/text v0.30.0 // indirect
+	golang.org/x/tools v0.38.0 // indirect
+	google.golang.org/protobuf v1.36.10 // indirect
 )