Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

10.8 KB
Raw Blame
package api

import (
	"encoding/json"
	"io"
	"net/http"
	"strings"
	"sync"
	"time"

	"github.com/rcourtman/pulse-go-rewrite/internal/agentcapabilities"
	"github.com/rcourtman/pulse-go-rewrite/internal/config"
	"github.com/rcourtman/pulse-go-rewrite/internal/mock"
	"github.com/rs/zerolog/log"
)

func (r *Router) withExternalAgentCapabilityActivity(capabilityName string, handler http.HandlerFunc) http.HandlerFunc {
	return func(w http.ResponseWriter, req *http.Request) {
		r.recordExternalAgentCapabilityActivity(req, capabilityName)
		if !externalAgentHistoryReadCapability(capabilityName) {
			handler(w, req)
			return
		}
		rw := &responseWriter{ResponseWriter: w, statusCode: http.StatusOK}
		handler(rw, req)
		if rw.StatusCode() < http.StatusBadRequest {
			r.recordExternalAgentHistoryReadDay(req, capabilityName)
		}
	}
}

// externalAgentHistoryReadCapability reports the requested history reads the
// event-record review counts: what changed, and how a resource's metrics moved.
func externalAgentHistoryReadCapability(capabilityName string) bool {
	switch strings.TrimSpace(capabilityName) {
	case agentcapabilities.ListRecentChangesCapabilityName, agentcapabilities.GetMetricHistoryCapabilityName:
		return true
	default:
		return false
	}
}

// externalAgentHistoryReadDays remembers the last UTC day each persistence
// recorded a history-read marker, so a busy agent costs one write per day
// rather than one per request. The persistence also dedupes, which covers
// restarts.
var externalAgentHistoryReadDays sync.Map

// recordExternalAgentHistoryReadDay writes the install-level history-read
// marker. It goes to the root persistence, which install telemetry reads,
// whichever organization the request served: the marker is a content-free
// day, not tenant data. Mock-mode reads are demo data, not adoption, and
// would otherwise outlive the switch back to live monitoring.
func (r *Router) recordExternalAgentHistoryReadDay(req *http.Request, capabilityName string) {
	if r == nil || req == nil || isFirstPartyBrowserRequest(req) || mock.IsMockEnabled() {
		return
	}
	_, requiredScope, ok := externalAgentCapabilityActivity(capabilityName)
	if !ok {
		return
	}
	now := time.Now().UTC()
	if !apiTokenCoversExternalAgentSurface(getAPITokenRecordFromRequest(req), now, requiredScope) {
		return
	}
	persistence := r.persistence
	if persistence == nil {
		return
	}
	day := now.Format(time.DateOnly)
	if last, seen := externalAgentHistoryReadDays.Load(persistence); seen && last == day {
		return
	}
	if err := persistence.RecordExternalAgentActivity(config.ExternalAgentActivityRecord{
		Timestamp: now,
		Surface:   externalAgentActivitySurface(req),
		Activity:  config.ExternalAgentActivityHistoryRead,
	}); err != nil {
		log.Debug().Err(err).Msg("Failed to record external agent history read")
		return
	}
	externalAgentHistoryReadDays.Store(persistence, day)
}

func (r *Router) recordExternalAgentCapabilityActivity(req *http.Request, capabilityName string) {
	activity, requiredScope, ok := externalAgentCapabilityActivity(capabilityName)
	if !ok {
		return
	}
	r.recordExternalAgentActivity(req, activity, requiredScope)
}

func externalAgentActivityForCapability(capabilityName string) (string, bool) {
	activity, _, ok := externalAgentCapabilityActivity(capabilityName)
	return activity, ok
}

func externalAgentCapabilityActivity(capabilityName string) (string, string, bool) {
	capabilityName = strings.TrimSpace(capabilityName)
	if capabilityName == "" {
		return "", "", false
	}
	capability, ok := agentcapabilities.FindCapability(agentcapabilities.CanonicalManifest().Capabilities, capabilityName)
	if !ok {
		return "", "", false
	}
	var activity string
	switch strings.TrimSpace(capabilityName) {
	case agentcapabilities.ResourceContextCapabilityName,
		agentcapabilities.ListResourceCapabilitiesCapabilityName,
		agentcapabilities.GetMetricHistoryCapabilityName:
		activity = config.ExternalAgentActivityResourceContext
	case agentcapabilities.FleetContextCapabilityName,
		agentcapabilities.ListRecentChangesCapabilityName:
		activity = config.ExternalAgentActivityFleetContext
	case agentcapabilities.OperationsLoopStatusCapabilityName:
		activity = config.ExternalAgentActivityFleetContext
	case agentcapabilities.EventSubscriptionCapabilityName:
		activity = config.ExternalAgentActivityEventStream
	case agentcapabilities.ListNodesCapabilityName,
		agentcapabilities.AddNodeCapabilityName,
		agentcapabilities.UpdateNodeCapabilityName,
		agentcapabilities.RemoveNodeCapabilityName,
		agentcapabilities.TestNodeCredentialsCapabilityName,
		agentcapabilities.TestNodeConnectionCapabilityName,
		agentcapabilities.RefreshNodeClusterMembershipCapabilityName,
		agentcapabilities.DiscoverLANCapabilityName:
		activity = config.ExternalAgentActivityProvisioning
	case agentcapabilities.GetOperatorStateCapabilityName,
		agentcapabilities.SetOperatorStateCapabilityName,
		agentcapabilities.ClearOperatorStateCapabilityName:
		activity = config.ExternalAgentActivityOperatorState
	case agentcapabilities.ListFindingsCapabilityName:
		activity = config.ExternalAgentActivityFindingList
	case agentcapabilities.AcknowledgeFindingCapabilityName,
		agentcapabilities.SnoozeFindingCapabilityName,
		agentcapabilities.DismissFindingCapabilityName,
		agentcapabilities.ResolveFindingCapabilityName:
		activity = config.ExternalAgentActivityFindingDecision
	case agentcapabilities.PlanActionCapabilityName:
		activity = config.ExternalAgentActivityActionPlan
	case agentcapabilities.DecideActionCapabilityName:
		activity = config.ExternalAgentActivityActionDecision
	case agentcapabilities.ExecuteActionCapabilityName:
		activity = config.ExternalAgentActivityActionExecute
	default:
		return "", "", false
	}
	requiredScope := strings.TrimSpace(capability.Scope)
	if requiredScope == "" {
		return "", "", false
	}
	return activity, requiredScope, true
}

func (r *Router) recordExternalAgentActivity(req *http.Request, activity string, requiredScopes ...string) {
	if r == nil || req == nil || strings.TrimSpace(activity) == "" {
		return
	}
	if isFirstPartyBrowserRequest(req) {
		return
	}
	token := getAPITokenRecordFromRequest(req)
	if !apiTokenCoversExternalAgentSurface(token, time.Now().UTC(), requiredScopes...) {
		return
	}
	persistence := r.persistenceForOrg(req.Context())
	if persistence == nil {
		return
	}
	if err := persistence.RecordExternalAgentActivity(config.ExternalAgentActivityRecord{
		Timestamp: time.Now().UTC(),
		Surface:   externalAgentActivitySurface(req),
		Activity:  activity,
	}); err != nil {
		log.Debug().Err(err).Str("activity", activity).Msg("Failed to record external agent activity")
	}
}

type agentWorkflowPromptActivityRequest struct {
	Name string `json:"name"`
}

// HandleAgentWorkflowPromptActivity records content-free workflow starter
// usage from agent adapters that render prompts locally, such as pulse-mcp.
func (r *Router) HandleAgentWorkflowPromptActivity(w http.ResponseWriter, req *http.Request) {
	if req.Method != http.MethodPost {
		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
		return
	}

	var payload agentWorkflowPromptActivityRequest
	dec := json.NewDecoder(http.MaxBytesReader(w, req.Body, 4096))
	if err := dec.Decode(&payload); err != nil {
		http.Error(w, "Invalid request", http.StatusBadRequest)
		return
	}
	var discard json.RawMessage
	if err := dec.Decode(&discard); err != io.EOF {
		http.Error(w, "Invalid request", http.StatusBadRequest)
		return
	}

	promptName := strings.TrimSpace(payload.Name)
	if !canonicalWorkflowPromptDeclared(promptName) {
		http.Error(w, "Unknown workflow prompt", http.StatusBadRequest)
		return
	}

	r.recordWorkflowPromptActivity(req, workflowPromptActivitySurface(req), promptName)
	w.WriteHeader(http.StatusNoContent)
}

func canonicalWorkflowPromptDeclared(promptName string) bool {
	promptName = strings.TrimSpace(promptName)
	if promptName == "" {
		return false
	}
	for _, prompt := range agentcapabilities.ManifestPulseWorkflowPrompts(agentcapabilities.CanonicalManifest()) {
		if strings.TrimSpace(prompt.Name) == promptName {
			return true
		}
	}
	return false
}

func (r *Router) recordWorkflowPromptActivity(req *http.Request, surface, promptName string) {
	if r == nil || req == nil || strings.TrimSpace(promptName) == "" {
		return
	}
	token := getAPITokenRecordFromRequest(req)
	if !apiTokenCoversExternalAgentSurface(token, time.Now().UTC(), config.ScopeMonitoringRead) {
		return
	}
	persistence := r.persistenceForOrg(req.Context())
	if persistence == nil {
		return
	}
	if err := persistence.RecordWorkflowPromptActivity(config.WorkflowPromptActivityRecord{
		Timestamp:  time.Now().UTC(),
		Surface:    surface,
		PromptName: promptName,
	}); err != nil {
		log.Debug().Err(err).Str("prompt_name", promptName).Msg("Failed to record workflow prompt activity")
	}
}

func workflowPromptActivitySurface(req *http.Request) string {
	if req == nil {
		return config.WorkflowPromptActivitySurfaceAgentAPI
	}
	switch strings.TrimSpace(req.Header.Get(agentcapabilities.AgentSurfaceHeader)) {
	case agentcapabilities.AgentSurfacePulseMCP:
		return config.WorkflowPromptActivitySurfacePulseMCP
	default:
		return config.WorkflowPromptActivitySurfaceAgentAPI
	}
}

func externalAgentActivitySurface(req *http.Request) string {
	if req == nil {
		return config.ExternalAgentActivitySurfaceAgentAPI
	}
	switch strings.TrimSpace(req.Header.Get(agentcapabilities.AgentSurfaceHeader)) {
	case agentcapabilities.AgentSurfacePulseMCP:
		return config.ExternalAgentActivitySurfacePulseMCP
	default:
		return config.ExternalAgentActivitySurfaceAgentAPI
	}
}

// isFirstPartyBrowserRequest reports whether the request came from a page
// Pulse itself served. The setup wizard leaves the browser authenticated with
// the wildcard admin token, and kiosk links authenticate with ?token=, so the
// Pulse UI's own node and finding fetches would otherwise count as external
// agent use. Browsers set Sec-Fetch-Site and page scripts cannot override it;
// scripts, MCP adapters and dashboards on another origin never send
// same-origin.
func isFirstPartyBrowserRequest(req *http.Request) bool {
	return strings.EqualFold(strings.TrimSpace(req.Header.Get("Sec-Fetch-Site")), "same-origin")
}

func apiTokenCoversExternalAgentSurface(token *config.APITokenRecord, now time.Time, requiredScopes ...string) bool {
	if token == nil {
		return false
	}
	if token.ExpiresAt != nil && now.After(token.ExpiresAt.UTC()) {
		return false
	}
	if len(requiredScopes) == 0 {
		requiredScopes = agentcapabilities.CanonicalManifest().RequiredScopes
	}
	if len(requiredScopes) == 0 {
		return false
	}
	token = cloneAPITokenRecord(token)
	for _, scope := range requiredScopes {
		scope = strings.TrimSpace(scope)
		if scope == "" {
			return false
		}
		if !token.HasScope(scope) {
			return false
		}
	}
	return true
}

func cloneAPITokenRecord(token *config.APITokenRecord) *config.APITokenRecord {
	if token == nil {
		return nil
	}
	clone := token.Clone()
	return &clone
}