feat(base-path): add subpath SPA mapping and cache-control support

Add a runtime --base-path/BASE_PATH option with normalization and default '/' to support serving SPAs behind URL prefixes (for example, /app).

Map prefixed request paths to the filesystem root while preserving root fallback behavior, SPA routing, compression, and traversal safety.

Update IgnoreCacheControlPaths matching to check both raw incoming paths and mapped internal paths under base-path deployments.

Add comprehensive tests for param normalization and app path mapping behavior, including /app canonical handling, asset lookup, traversal rejection, and outside-prefix fallback; touched package coverage is 100% for app and param.

Document the feature in README and deployment/config/development docs with mapping examples and cache-control guidance.

Author: mamchurovskyy

README.md

@@ -81,6 +81,17 @@ docker run --rm -p 8080:8080 \
   devforth/spa-to-http:latest
 ```
 
+### Subpath hosting (`/app`)
+
+```bash
+docker run --rm -p 8080:8080 \
+  -v $(pwd)/dist:/code \
+  devforth/spa-to-http:latest \
+  --base-path /app
+```
+
+This maps `/app/...` requests to the same build root (for example `/app/assets/main.js` -> `/code/assets/main.js`).
+
 ### Compose / reverse proxy setup
 
 For full Docker Compose and Traefik examples, see [`docs/deployment.md`](docs/deployment.md).
@@ -90,6 +101,7 @@ For full Docker Compose and Traefik examples, see [`docs/deployment.md`](docs/de
 - Zero-configuration Docker usage for SPA bundles
 - Optional Brotli/Gzip compression
 - Cache-control tuning (`--cache-max-age`, `--ignore-cache-control-paths`)
+- Subpath hosting with URL prefixes (`--base-path`)
 - SPA mode toggle (`--spa` / `SPA_MODE`)
 - In-memory file cache (`--cache`, `--cache-buffer`)
 - Optional request logging and basic auth

docs/configuration.md

@@ -14,6 +14,7 @@
 | BROTLI | `--brotli` | Enable Brotli compression for files above the threshold | `false` |
 | THRESHOLD | `--threshold <number>` | Threshold in bytes for gzip and Brotli | `1024` |
 | DIRECTORY | `-d <string>` or `--directory <string>` | Directory to serve | `.` |
+| BASE_PATH | `--base-path <string>` | URL prefix to mount the SPA under (normalized path prefix) | `/` |
 | CACHE_MAX_AGE | `--cache-max-age <number>` | Cache max-age in seconds; use `-1` to disable | `604800` |
 | IGNORE_CACHE_CONTROL_PATHS | `--ignore-cache-control-paths <string>` | Comma-separated paths to force `Cache-Control: no-store` | (empty) |
 | SPA_MODE | `--spa` or `--spa <bool>` | Serve `index.html` on missing paths (SPA routing) | `true` |
@@ -69,6 +70,46 @@ services:
     command: --ignore-cache-control-paths "/sw.js"
 ```
 
+## Base Path (Subpath Hosting)
+
+Use `--base-path` when your SPA is exposed behind a URL prefix (for example, `/app`) while files stay in the same build directory.
+
+### Normalization Rules
+
+- Empty value becomes `/`
+- Missing leading slash is added (`app` -> `/app`)
+- Trailing slash is removed (`/app/` -> `/app`)
+- Query strings and fragments are invalid (`/app?a=1`, `/app#x`)
+
+### Request Mapping
+
+With `--base-path /app` and `--directory /code`:
+
+- `/app` -> `/code/index.html`
+- `/app/` -> `/code/index.html`
+- `/app/assets/main.js` -> `/code/assets/main.js`
+- `/app/route1` -> SPA fallback to `/code/index.html` (when `--spa` is enabled)
+
+Requests outside the base path continue to follow normal root behavior:
+
+- `/assets/main.js` -> `/code/assets/main.js`
+
+### Interaction with `IGNORE_CACHE_CONTROL_PATHS`
+
+When `--base-path` is set, ignore paths are matched against both:
+
+1. Raw incoming request path (for example, `/app/sw.js`)
+2. Mapped internal path (for example, `/sw.js`)
+
+That means either style works:
+
+```yaml
+services:
+  spa:
+    image: devforth/spa-to-http:latest
+    command: --base-path /app --ignore-cache-control-paths "/sw.js,/app/sw.js"
+```
+
 ## See Also
 
 - [Getting Started](getting-started.md) — Install, build, and run

docs/deployment.md

@@ -33,9 +33,34 @@ services:
 
 - Use `--port` if you run the container on a non-default port.
 - Enable compression (`--brotli` or `--gzip`) when serving large static bundles.
+- Use `--base-path` when the SPA is mounted under a subpath (for example, `/app`) behind your proxy.
 - For fixed asset paths (for example, a service worker), use `--ignore-cache-control-paths` to avoid CDN caching issues.
 - Add rate limiting at the reverse proxy (Traefik, Nginx, Cloudflare) to mitigate brute-force attempts.
 
+## Subpath Deployment (`--base-path`)
+
+When your reverse proxy exposes the app at a subpath such as `/app`, configure:
+
+```yaml
+services:
+  spa:
+    image: devforth/spa-to-http:latest
+    command: --base-path /app
+```
+
+Behavior:
+- `/app` and `/app/` serve `index.html`
+- `/app/assets/...` maps to assets from the same dist root
+- SPA routes under `/app/...` fall back to `index.html` (with `--spa=true`)
+
+### `--ignore-cache-control-paths` with `--base-path`
+
+Ignore paths are matched against both:
+- Raw incoming path (for example, `/app/sw.js`)
+- Internal mapped path (for example, `/sw.js`)
+
+So either notation works in deployment config.
+
 ## See Also
 
 - [Configuration](configuration.md) — Environment variables and CLI flags

docs/development.md

@@ -40,7 +40,8 @@ go run . \
   --logger \
   --log-pretty \
   --cache-max-age 3600 \
-  --threshold 2048
+  --threshold 2048 \
+  --base-path /app
 ```
 
 ## Configure via Environment Variables

src/app/app.go

@@ -261,8 +261,24 @@ func (app *App) GetFilePath(urlPath string) (string, bool) {
 	return requestedPath, true
 }
 
+func (app *App) mapRequestPath(urlPath string) string {
+	basePath := app.params.BasePath
+	if basePath == "" || basePath == "/" {
+		return urlPath
+	}
+	if urlPath == basePath || urlPath == basePath+"/" {
+		return "/"
+	}
+	basePathWithSlash := basePath + "/"
+	if strings.HasPrefix(urlPath, basePathWithSlash) {
+		return strings.TrimPrefix(urlPath, basePath)
+	}
+	return urlPath
+}
+
 func (app *App) HandlerFuncNew(w http.ResponseWriter, r *http.Request) {
-	requestedPath, valid := app.GetFilePath(r.URL.Path)
+	mappedRequestPath := app.mapRequestPath(r.URL.Path)
+	requestedPath, valid := app.GetFilePath(mappedRequestPath)
 
 	if !valid {
 		w.WriteHeader(http.StatusNotFound)
@@ -283,7 +299,9 @@ func (app *App) HandlerFuncNew(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	if slices.Contains(app.params.IgnoreCacheControlPaths, r.URL.Path) || path.Ext(responseItem.Name) == ".html" {
+	if slices.Contains(app.params.IgnoreCacheControlPaths, r.URL.Path) ||
+		slices.Contains(app.params.IgnoreCacheControlPaths, mappedRequestPath) ||
+		path.Ext(responseItem.Name) == ".html" {
 		w.Header().Set("Cache-Control", "no-store")
 	} else {
 		w.Header().Set("Cache-Control", fmt.Sprintf("max-age=%d", app.params.CacheControlMaxAge))

src/app/app_internal_test.go

@@ -5,6 +5,7 @@ import (
 	"io"
 	"io/fs"
 	"net/http"
+	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"testing"
@@ -242,3 +243,162 @@ func TestGetOrCreateResponseItemDirWithCompressionNotFound(t *testing.T) {
 		t.Fatalf("expected status %d, got %d", http.StatusNotFound, code)
 	}
 }
+
+func TestMapRequestPath(t *testing.T) {
+	params := param.Params{
+		Directory: ".",
+		BasePath:  "/app",
+	}
+	app := NewApp(&params)
+
+	tests := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{name: "base path exact", in: "/app", want: "/"},
+		{name: "base path with trailing slash", in: "/app/", want: "/"},
+		{name: "asset under base path", in: "/app/assets/main.js", want: "/assets/main.js"},
+		{name: "outside prefix fallback", in: "/assets/main.js", want: "/assets/main.js"},
+		{name: "prefix-like but not matching", in: "/application/main.js", want: "/application/main.js"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := app.mapRequestPath(tt.in)
+			if got != tt.want {
+				t.Fatalf("expected %q, got %q", tt.want, got)
+			}
+		})
+	}
+}
+
+func TestMapRequestPathRootBasePathNoop(t *testing.T) {
+	params := param.Params{
+		Directory: ".",
+		BasePath:  "/",
+	}
+	app := NewApp(&params)
+
+	got := app.mapRequestPath("/app/assets/main.js")
+	if got != "/app/assets/main.js" {
+		t.Fatalf("expected path unchanged, got %q", got)
+	}
+}
+
+func TestMapRequestPathEmptyBasePathNoop(t *testing.T) {
+	params := param.Params{
+		Directory: ".",
+		BasePath:  "",
+	}
+	app := NewApp(&params)
+
+	got := app.mapRequestPath("/app/assets/main.js")
+	if got != "/app/assets/main.js" {
+		t.Fatalf("expected path unchanged, got %q", got)
+	}
+}
+
+func TestHandlerFuncNewBasePathCanonicalIndex(t *testing.T) {
+	dir := t.TempDir()
+	indexPath := filepath.Join(dir, "index.html")
+	if err := os.WriteFile(indexPath, []byte("index"), 0600); err != nil {
+		t.Fatalf("failed to write index: %v", err)
+	}
+
+	params := param.Params{
+		Directory: dir,
+		BasePath:  "/app",
+		SpaMode:   true,
+	}
+	app := NewApp(&params)
+
+	for _, reqPath := range []string{"/app", "/app/"} {
+		req := httptest.NewRequest("GET", reqPath, nil)
+		rec := httptest.NewRecorder()
+		app.HandlerFuncNew(rec, req)
+
+		if rec.Code != http.StatusOK {
+			t.Fatalf("expected status 200 for %s, got %d", reqPath, rec.Code)
+		}
+		if rec.Body.String() != "index" {
+			t.Fatalf("expected index body for %s, got %q", reqPath, rec.Body.String())
+		}
+	}
+}
+
+func TestHandlerFuncNewBasePathAssetMappingAndIgnoreCacheControl(t *testing.T) {
+	dir := t.TempDir()
+	assetPath := filepath.Join(dir, "asset.bin")
+	if err := os.WriteFile(assetPath, []byte("asset"), 0600); err != nil {
+		t.Fatalf("failed to write asset: %v", err)
+	}
+
+	params := param.Params{
+		Directory:               dir,
+		BasePath:                "/app",
+		SpaMode:                 true,
+		IgnoreCacheControlPaths: []string{"/asset.bin"},
+		CacheControlMaxAge:      3600,
+	}
+	app := NewApp(&params)
+
+	req := httptest.NewRequest("GET", "/app/asset.bin", nil)
+	rec := httptest.NewRecorder()
+	app.HandlerFuncNew(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", rec.Code)
+	}
+	if rec.Header().Get("Cache-Control") != "no-store" {
+		t.Fatalf("expected no-store cache control, got %s", rec.Header().Get("Cache-Control"))
+	}
+	if rec.Body.String() != "asset" {
+		t.Fatalf("expected asset body, got %q", rec.Body.String())
+	}
+}
+
+func TestHandlerFuncNewBasePathTraversalRejected(t *testing.T) {
+	dir := t.TempDir()
+	params := param.Params{
+		Directory: dir,
+		BasePath:  "/app",
+		SpaMode:   true,
+	}
+	app := NewApp(&params)
+
+	req := httptest.NewRequest("GET", "/app/../secret.txt", nil)
+	rec := httptest.NewRecorder()
+	app.HandlerFuncNew(rec, req)
+
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", rec.Code)
+	}
+}
+
+func TestHandlerFuncNewBasePathOutsidePrefixFallsBackToRoot(t *testing.T) {
+	dir := t.TempDir()
+	assetPath := filepath.Join(dir, "asset.bin")
+	if err := os.WriteFile(assetPath, []byte("asset"), 0600); err != nil {
+		t.Fatalf("failed to write asset: %v", err)
+	}
+
+	params := param.Params{
+		Directory:          dir,
+		BasePath:           "/app",
+		SpaMode:            true,
+		CacheControlMaxAge: 3600,
+	}
+	app := NewApp(&params)
+
+	req := httptest.NewRequest("GET", "/asset.bin", nil)
+	rec := httptest.NewRecorder()
+	app.HandlerFuncNew(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", rec.Code)
+	}
+	if rec.Body.String() != "asset" {
+		t.Fatalf("expected asset body, got %q", rec.Body.String())
+	}
+}