ResolveSpec/proxy.md

Plan: Proxy endpoint support for pkg/webserver2 static serving

Status: quickproxy package implemented in ResolveSpec. GoCore-side wiring (config field, webserver2/proxy.go, server.go route ordering) is a separate repo, not present here, and remains unimplemented.

Goal

pkg/webserver2 (via WithStaticFS) currently serves static files from WebResDir (/res) and WebStaticDir (/), using ResolveSpec's pkg/server/staticweb package, with an HTML fallback for SPA routing.

We're adding a proxy layer: requests are tried against a configured proxy target first; if the proxy can't resolve them (unreachable, or upstream returns 404), they fall back to the existing static file handling.

Decisions (from Q&A with user)

1. Config shape: a list of prefix rules (like nginx location blocks), where one rule may use prefix / to act as a catch-all passthrough. So a single config list covers both "proxy just /api" and "proxy everything not otherwise matched" use cases.
2. Package placement: new package in the ResolveSpec repo (/mnt/vault/ResolveSpec, published as github.com/bitechdev/ResolveSpec), named quickproxy, living alongside pkg/server/staticweb at pkg/server/quickproxy. GoCore's pkg/webserver2 will consume it the same way it consumes staticweb today (wire it up in static.go), after bumping the ResolveSpec dependency version — mirroring the existing fix(resolve-spec): update ResolveSpec to vX.Y.Z commit pattern already used in this repo's history.
3. Fallback trigger: fall back to static files both when the upstream is unreachable (dial/connect error, timeout) and when the upstream responds with 404. Any other upstream response (2xx, other 4xx, 5xx) is passed through to the client as-is.
4. Method scope: proxying applies to all HTTP methods, not just GET (unlike today's static routes, which are GET-only).

New package: github.com/bitechdev/ResolveSpec/pkg/server/quickproxy

Repo location: /mnt/vault/ResolveSpec/pkg/server/quickproxy

Types

package quickproxy

// Rule maps a URL prefix to an upstream target.
// A Rule with URLPrefix "/" acts as a catch-all passthrough.
type Rule struct {
    URLPrefix string // e.g. "/api", "/"
    Target    string // upstream base URL, e.g. "http://localhost:3000"
}

// Service holds the compiled set of rules and does longest-prefix matching.
type Service struct { ... }

func NewService(rules []Rule) (*Service, error)

Matching & fallback behavior

• Longest-prefix match against configured rules, same convention as staticweb's mount points.
• Implemented with net/http/httputil.ReverseProxy per matched rule (director rewrites scheme/host/path, adds X-Forwarded-Host / X-Forwarded-For).
• 404 detection without buffering the body: use ReverseProxy.ModifyResponse to inspect resp.StatusCode as soon as headers arrive from upstream, before the body is streamed to the client. If it's 404, return a sentinel error from ModifyResponse — this causes ReverseProxy to invoke ErrorHandler instead of writing anything to the client, so we never commit a partial/wrong response.
• Connection failure detection: ReverseProxy.ErrorHandler catches both the sentinel 404 error and real transport errors (dial failure, timeout, connection reset).
• In both cases, ErrorHandler invokes a caller-supplied fallback http.Handler (the existing static file service) instead of writing an error response. Because nothing has been written to the ResponseWriter yet in either failure path, the fallback handler can write a normal response (status, headers, body) as if the proxy had never been tried.
• Any other status code (including other 4xx/5xx) streams straight through to the client — no masking of real upstream errors.

Handler API

// Handler returns an http.Handler that tries the configured proxy rules
// first (longest-prefix match), and calls fallback when no rule matches,
// the upstream is unreachable, or the upstream returns 404.
func (s *Service) Handler(fallback http.Handler) http.Handler

This mirrors the shape of staticweb.StaticFileService.Handler() so it composes the same way in pkg/webserver2.

Config changes (GoCore)

pkg/cfg/settings-model.go — add a new field to Settings, following the existing flat-JSON convention used by WebStaticDir/WebResDir:

type ProxyRule struct {
    URLPrefix string `json:"urlprefix"`
    Target    string `json:"target"`
}

// in Settings:
WebProxyRules []ProxyRule `json:"webproxyrules"`

Wiring changes (GoCore, pkg/webserver2)

New file pkg/webserver2/proxy.go (parallel to static.go), e.g.:

func (r *Router) WithProxyFS(corestate cfg.State) *Router {
    if len(corestate.Cfg.WebProxyRules) == 0 {
        return r
    }
    rules := make([]quickproxy.Rule, 0, len(corestate.Cfg.WebProxyRules))
    for _, pr := range corestate.Cfg.WebProxyRules {
        rules = append(rules, quickproxy.Rule{URLPrefix: pr.URLPrefix, Target: pr.Target})
    }
    service, err := quickproxy.NewService(rules)
    if err != nil {
        logger.Error("could not configure proxy service %v", err)
        return r
    }
    r.proxyService = service // stored for static.go to consume as fallback target
    return r
}

Integration point with existing static routing — needs care

This is the trickiest part of the wiring, flagged here rather than decided, since it affects route registration order in server.go:

• For a proxy rule prefix that doesn't overlap with the static mounts (e.g. /api), we can register new routes directly: r.Handle(method, "/api/*path", quickproxy handler) for all methods, with no fallback (there's no static content at /api anyway).
• For the catch-all / proxy rule, it directly overlaps the existing WebStaticDir mount at /. Rather than registering a second competing route, WithStaticFS's existing GET handler for /*path needs to become proxyService.Handler(staticAuth(service.Handler())) — i.e. the proxy wraps the static handler as its fallback, instead of the two being separate router registrations. This means WithProxyFS needs to run before WithStaticFS (or the two need to be merged into one method), and server.go's call chain (WithStaticFS(corestate)) needs adjusting accordingly.
• Non-GET methods on the catch-all / rule have no static fallback to offer (static routes are GET-only today) — they'd just proxy or 404.

Release flow

Since quickproxy lives in the separate ResolveSpec module:

1. Implement + test in /mnt/vault/ResolveSpec.
2. Tag/publish a new ResolveSpec version.
3. Bump github.com/bitechdev/ResolveSpec in GoCore's go.mod (go get github.com/bitechdev/ResolveSpec@vX.Y.Z), same as the recent fix(resolve-spec): update ResolveSpec to v1.1.46 commit.
4. Land the GoCore-side wiring (cfg field, proxy.go, server.go call order change) in the same or a follow-up commit.

Resolved decisions (quickproxy implementation)

• Timeouts: a single global default (quickproxy.DefaultTimeout, 10s), overridable via quickproxy.WithTimeout(d) passed to NewService. It bounds dial + response-header wait only; response body streaming is unbounded, so it won't cut off long downloads or upgraded connections.
• Auth middleware: out of scope for quickproxy. Whether/how staticAuth wraps proxied requests is entirely GoCore's call at the wiring layer, not something this package decides.
• Path rewriting: no prefix stripping — the full incoming path/query is forwarded unchanged to the target host (matches nginx proxy_pass without a trailing slash). Only scheme/host are rewritten, and X-Forwarded-Host is set from the original Host header.

Open questions / not yet decided

• WebSocket upgrade proxying (needed if any proxied target does live reload / HMR, e.g. a frontend dev server) — plain ReverseProxy handles this automatically via its Transport, should confirm it's not disabled.
• Whether request bodies need special handling for large uploads proxied to non-GET targets (streaming vs. buffering — ReverseProxy streams by default, should be fine, but worth confirming with the intended proxy targets).

Testing plan

• quickproxy package: unit tests in ResolveSpec covering longest-prefix matching, 404-triggers-fallback, connection-error-triggers-fallback, pass-through of non-404 error codes, all-methods support.
• pkg/webserver2: integration test standing up a fake upstream (httptest.Server) plus a temp static dir, verifying the proxy-then-static-fallback order end to end.