ModelRouter/internal/lua/plugin_http_handler_test.go

package lua

// Plugin-registered HTTP endpoints.
//
// Three properties have to hold, and none of them is visible from the plugin's
// own point of view:
//
//  1. Auth and roles are enforced by the GATEWAY. A plugin that forgets to
//     declare roles gets admin-only, not open — the failure mode of "public by
//     omission" is an internet-scannable endpoint inside the gateway process.
//  2. A handler error is a value, never a panic. The pcall guard is the same one
//     the hooks use, for the same reason.
//  3. The plugin cannot steer the gateway's own response framing: a nonsense
//     status becomes a 500, and Content-Length / hop-by-hop headers are dropped.
//
// These tests drive the declaration layer and the response writer directly; the
// router-level dispatch is covered in the gateway package.

import (
	"net/http"
	"net/http/httptest"
	"testing"
)

const httpPlugin = `
local P = {}
P.name = "api"
P.version = "1.0.0"
P.exports = {}
P.http = {
  {
    path = "health",
    handler = "health",
    roles = { "admin" },
    description = "liveness",
  },
  {
    path = "echo/:what",
    method = "POST",
    handler = "echo",
    roles = { "admin", "user" },
  },
}
function P.health(req)
  return { status = 200, json = { ok = true, role = req.role, key = req.key } }
end
function P.echo(req)
  return { status = 201, json = { what = req.params.what, body = req.body } }
end
return P
`

func TestPluginRegistersHTTPHandlers(t *testing.T) {
	dir := t.TempDir()
	ps := NewPlugins(NewVM(dir), dir)
	if err := ps.LoadSource("api", httpPlugin); err != nil {
		t.Fatal(err)
	}
	hs := ps.HTTPHandlers()
	if len(hs) != 2 {
		t.Fatalf("expected 2 registered endpoints, got %d: %+v", len(hs), hs)
	}
	for _, h := range hs {
		if h.Plugin != "api" {
			t.Errorf("handler %q has no owner; the dispatcher could not route it", h.Path)
		}
		if h.Method == "" {
			t.Errorf("handler %q has no method; the gateway would answer 405 forever", h.Path)
		}
	}
}

func TestHandlerRoleRules(t *testing.T) {
	// A handler with no roles and no public opt-out is ADMIN-ONLY. This is the
	// decision the whole feature turns on: "I forgot to declare roles" must not
	// mean "anyone on the internet".
	open := HTTPHandler{Path: "x", Handler: "h"}
	if open.allows("user", "") {
		t.Error("an undeclared handler must default to admin-only")
	}
	if !open.allows("admin", "") {
		t.Error("an undeclared handler must still serve admin")
	}
	// The explicit opt-out is how a plugin says "this one really is public".
	pub := HTTPHandler{Path: "x", Handler: "h", Public: true}
	if !pub.allows("user", "") || !pub.allows("", "") {
		t.Error("public=true must admit any role")
	}
	// Declared roles.
	scoped := HTTPHandler{Path: "x", Roles: []string{"admin", "user"}}
	if !scoped.allows("user", "homeagent") || !scoped.allows("admin", "admin") {
		t.Error("a listed role must be admitted")
	}
	if (HTTPHandler{Path: "x", Roles: []string{"admin"}}).allows("user", "homeagent") {
		t.Error("an unlisted role must be refused")
	}
}

// Naming keys is how the operator grants one collaborator access without opening
// the endpoint to every user key. Two properties matter and neither is obvious:
// a named key wins even when the role rule would have refused it, and the named
// list REPLACES the role rule rather than adding to it.
func TestHandlerKeyRules(t *testing.T) {
	h := HTTPHandler{Path: "x", Roles: []string{"admin"}, Keys: []string{"homeagent"}}
	if !h.allows("user", "homeagent") {
		t.Error("a named key must be admitted even though its role is not listed")
	}
	// The replacement semantics: listing one key must NOT also admit every user
	// key through the role rule, which is what an OR would have done.
	if h.allows("user", "club") {
		t.Error("naming keys must replace the role rule, not add to it")
	}
	if h.allows("user", "") {
		t.Error("an unnamed key must not match a named-key allowlist")
	}
	// Admin is always admitted, so a typo in the list never locks the operator
	// out of the endpoint they are trying to tighten.
	if !h.allows("admin", "admin") {
		t.Error("admin must always reach an endpoint")
	}
	// Name matching is case-insensitive; a config written by hand varies.
	if !(HTTPHandler{Path: "x", Keys: []string{"HomeAgent"}}).allows("user", "homeagent") {
		t.Error("key names should match case-insensitively")
	}
}

// The stored override replaces whatever the plugin declared — this is the admin
// editing access without touching a .lua that an upgrade would overwrite.
func TestEndpointAccessOverrideReplacesDeclaration(t *testing.T) {
	dir := t.TempDir()
	ps := NewPlugins(NewVM(dir), dir)
	if err := ps.LoadSource("api", httpPlugin); err != nil {
		t.Fatal(err)
	}
	// health is declared admin-only; widen it to one named key.
	if err := ps.SetEndpointAccess("api", "health", "@homeagent"); err != nil {
		t.Fatal(err)
	}
	var found *HTTPHandler
	for _, h := range ps.HTTPHandlers() {
		if h.Path == "health" {
			hh := h
			found = &hh
		}
	}
	if found == nil {
		t.Fatal("health endpoint disappeared after an access override")
	}
	if len(found.Roles) != 0 {
		t.Errorf("the declared roles should be replaced, got %v", found.Roles)
	}
	if len(found.Keys) != 1 || found.Keys[0] != "homeagent" {
		t.Errorf("override keys = %v, want [homeagent]", found.Keys)
	}
	if !found.allows("user", "homeagent") || found.allows("user", "club") {
		t.Error("the override is not in force")
	}
	// Clearing restores the plugin's own declaration.
	if err := ps.SetEndpointAccess("api", "health", ""); err != nil {
		t.Fatal(err)
	}
	for _, h := range ps.HTTPHandlers() {
		if h.Path == "health" {
			if len(h.Keys) != 0 {
				t.Errorf("clearing the override should restore the declaration, got %v", h.Keys)
			}
			return
		}
	}
	t.Error("health endpoint vanished")
}

func TestSetEndpointAccessRejectsUnknownTarget(t *testing.T) {
	dir := t.TempDir()
	ps := NewPlugins(NewVM(dir), dir)
	if err := ps.LoadSource("api", httpPlugin); err != nil {
		t.Fatal(err)
	}
	if err := ps.SetEndpointAccess("api", "nope", "@homeagent"); err == nil {
		t.Error("setting access on a path the plugin does not expose must fail loudly")
	}
	if err := ps.SetEndpointAccess("nosuchplugin", "health", "@homeagent"); err == nil {
		t.Error("setting access for an unknown plugin must fail loudly")
	}
}

// A stored allowlist naming a key that does not exist refuses every caller while
// looking perfectly configured. ValidateAccessSpec exists to catch that at write
// time instead.
func TestValidateAccessSpec(t *testing.T) {
	SetKeyNameLookup(func() []string { return []string{"homeagent", "club"} })
	t.Cleanup(func() { SetKeyNameLookup(nil) })

	for _, ok := range []string{"admin", "user", "public", "@homeagent",
		"admin,@homeagent,@club", " admin , @club "} {
		if err := (&Plugins{}).ValidateAccessSpec(ok); err != nil {
			t.Errorf("spec %q should be accepted: %v", ok, err)
		}
	}
	for _, bad := range []string{"@nosuchkey", "superuser", "@", "admin,@typo_key"} {
		if err := (&Plugins{}).ValidateAccessSpec(bad); err == nil {
			t.Errorf("spec %q must be refused: it is neither a role nor a configured key", bad)
		}
	}
	if err := (&Plugins{}).ValidateAccessSpec(""); err != nil {
		t.Errorf("an empty spec clears the override and must be accepted: %v", err)
	}
}

func TestHandlerPathValidationRejectsEscapes(t *testing.T) {
	// ":name" with empty segments around it is legal — the trims below reduce it
	// to ":name". What must be refused is an empty PARAM NAME, which cannot be
	// captured into request.params.
	for _, bad := range []string{"", "  ", "a/../b", "a//b", "wild*card", "q?x", "/:/"} {
		if err := validateHandlerPath(bad); err == nil {
			t.Errorf("path %q must be rejected: it can escape the mount or make the "+
				"route table ambiguous", bad)
		}
	}
	for _, ok := range []string{"health", "a/b", "echo/:what", "v1/things/:id", "/:name/"} {
		if err := validateHandlerPath(ok); err != nil {
			t.Errorf("path %q should be accepted: %v", ok, err)
		}
	}
}

func TestHandlerMethodValidation(t *testing.T) {
	if m, err := normalizeHandlerMethod(""); err != nil || m != http.MethodGet {
		t.Errorf("an empty method should default to GET, got %q %v", m, err)
	}
	if _, err := normalizeHandlerMethod("TRACE"); err == nil {
		t.Error("TRACE must be refused")
	}
	if m, err := normalizeHandlerMethod("post"); err != nil || m != http.MethodPost {
		t.Errorf("method should normalise to upper case, got %q %v", m, err)
	}
}

func TestInvokeHandlerReturnsStructuredData(t *testing.T) {
	dir := t.TempDir()
	ps := NewPlugins(NewVM(dir), dir)
	if err := ps.LoadSource("api", httpPlugin); err != nil {
		t.Fatal(err)
	}
	resp, err := ps.InvokeHandler("api", "health", &HandlerRequest{
		Method: http.MethodGet, Path: "health", Role: "admin", Key: "sk-test",
	})
	if err != nil {
		t.Fatalf("invoke: %v", err)
	}
	if resp.Status != 200 {
		t.Errorf("status = %d, want 200", resp.Status)
	}
	j, ok := resp.JSON.(map[string]interface{})
	if !ok {
		t.Fatalf("json = %T, want a table (the handler's nested value must survive)", resp.JSON)
	}
	if j["ok"] != true || j["role"] != "admin" {
		t.Errorf("handler data crossed wrong: %v", j)
	}
}

func TestInvokeHandlerParamsAndBodyReachLua(t *testing.T) {
	dir := t.TempDir()
	ps := NewPlugins(NewVM(dir), dir)
	if err := ps.LoadSource("api", httpPlugin); err != nil {
		t.Fatal(err)
	}
	resp, err := ps.InvokeHandler("api", "echo", &HandlerRequest{
		Method: http.MethodPost, Path: "echo/thing",
		Params: map[string]string{"what": "thing"},
		Body:   `{"n":1}`, Role: "user",
	})
	if err != nil {
		t.Fatalf("invoke: %v", err)
	}
	j, _ := resp.JSON.(map[string]interface{})
	if resp.Status != 201 {
		t.Errorf("status = %d, want 201 (the handler chose it)", resp.Status)
	}
	if j["what"] != "thing" {
		t.Errorf("path param did not reach the handler: %v", j)
	}
	if j["body"] != `{"n":1}` {
		t.Errorf("body did not reach the handler: %v", j)
	}
}

// A handler that raises must produce an error, never a process abort — the same
// SIGSEGV class of bug the hook guard exists for.
func TestInvokeHandlerErrorIsValueNotPanic(t *testing.T) {
	dir := t.TempDir()
	ps := NewPlugins(NewVM(dir), dir)
	const boom = `
local P = {}
P.name = "boom"
P.version = "1.0.0"
P.exports = {}
P.http = { { path = "blow", handler = "blow", roles = { "admin" } } }
function P.blow(req)
  error("handler exploded")
end
return P
`
	if err := ps.LoadSource("boom", boom); err != nil {
		t.Fatal(err)
	}
	if _, err := ps.InvokeHandler("boom", "blow", &HandlerRequest{Role: "admin"}); err == nil {
		t.Fatal("a raising handler must surface as an error")
	}
}

// The plugin does not get to decide how the gateway frames its response.
func TestHandlerResponseFramingIsKernelOwned(t *testing.T) {
	cases := []struct {
		name string
		in   *HandlerResponse
		want int
	}{
		{"status 0 becomes 200", &HandlerResponse{Status: 0, Body: "x"}, 200},
		{"status 9999 becomes 500", &HandlerResponse{Status: 9999, Body: "x"}, 500},
		{"status -1 becomes 500", &HandlerResponse{Status: -1, Body: "x"}, 500},
		{"explicit 404 is kept", &HandlerResponse{Status: 404, Body: "x"}, 404},
	}
	for _, c := range cases {
		w := httptest.NewRecorder()
		writeHTTPHandlerResponse(w, c.in)
		if w.Code != c.want {
			t.Errorf("%s: status = %d, want %d", c.name, w.Code, c.want)
		}
	}

	// A handler must not be able to desync the gateway's own framing.
	w := httptest.NewRecorder()
	writeHTTPHandlerResponse(w, &HandlerResponse{
		Status: 200, Body: "hello",
		Headers: map[string]string{
			"Content-Length":    "99999",
			"Connection":        "close",
			"Transfer-Encoding": "chunked",
			"X-Custom":          "kept",
		},
	})
	if got := w.Header().Get("Content-Length"); got != "" {
		t.Errorf("a plugin set Content-Length (%s); the body length is the kernel's", got)
	}
	if got := w.Header().Get("X-Custom"); got != "kept" {
		t.Errorf("a normal header should survive, got %q", got)
	}
}

// A malformed declaration must not take the whole plugin down.
func TestBadHTTPRouteDoesNotBreakPluginLoad(t *testing.T) {
	dir := t.TempDir()
	ps := NewPlugins(NewVM(dir), dir)
	const mixed = `
local P = {}
P.name = "mixed"
P.version = "1.0.0"
P.exports = {}
P.state = { seen = true }
P.ui = { page = { page_id = "m", title = "M", mount = "<div/>" } }
P.http = {
  { path = "../escape", handler = "h", roles = { "admin" } },
  { path = "fine",      handler = "h", roles = { "admin" } },
}
function P.h(req) return { status = 200, body = "ok" } end
return P
`
	if err := ps.LoadSource("mixed", mixed); err != nil {
		t.Fatalf("a bad route must not fail the plugin load: %v", err)
	}
	// The good route survives; the bad one is simply absent.
	hs := ps.HTTPHandlers()
	if len(hs) != 1 || hs[0].Path != "fine" {
		t.Fatalf("expected only the valid route, got %+v", hs)
	}
	// And the plugin's own page/state still work.
	if ps.State("mixed") == nil {
		t.Error("the plugin's state was lost because of a bad route")
	}
}

func TestParseHandlerResponseShapes(t *testing.T) {
	if _, err := parseHandlerResponse("just a string"); err == nil {
		t.Error("a non-table return must be an error, not an empty 200")
	}
	if _, err := parseHandlerResponse(map[string]interface{}{}); err == nil {
		t.Error("an empty table should say so rather than returning a blank 200")
	}
	r, err := parseHandlerResponse(map[string]interface{}{
		"status": float64(204), "headers": map[string]interface{}{"X-A": "b"},
	})
	if err != nil {
		t.Fatal(err)
	}
	if r.Status != 204 || r.Headers["X-A"] != "b" {
		t.Errorf("decoded %+v", r)
	}
}

// TestEndpointAccessReportsPerEndpointOverride guards the reporting side of the
// override store.
//
// SetEndpointAccess already keyed overrides by plugin#path, but endpointAccess
// read the plugin-level key. After an operator saved a restriction on ONE
// endpoint, /api/plugins kept reporting the plugin's DECLARED roles, so the
// plugin page drew the pre-change value and a later save from that screen
// reverted the restriction. Authorization kept working — only the display and
// the round trip through the UI were broken, which is why it went unnoticed.
func TestEndpointAccessReportsPerEndpointOverride(t *testing.T) {
	dir := t.TempDir()
	ps := NewPlugins(NewVM(dir), dir)
	if err := ps.LoadSource("api", httpPlugin); err != nil {
		t.Fatal(err)
	}
	// httpPlugin registers "health" and "echo/:what".
	if err := ps.SetEndpointAccess("api", "health", "user"); err != nil {
		t.Fatalf("SetEndpointAccess: %v", err)
	}
	got := map[string][]string{}
	for _, e := range ps.EndpointAccess() {
		got[e.Path] = e.OverrideRoles
	}
	if len(got["health"]) != 1 || got["health"][0] != "user" {
		t.Errorf("health override not reported to the UI: %+v", got["health"])
	}
	if len(got["echo/:what"]) != 0 {
		t.Errorf("echo inherited an override it never had: %+v", got["echo/:what"])
	}
}