Documentation
¶
Index ¶
- Variables
- type AgentAvailabilityResult
- type AgentConfigTemplateService
- type AgentHeartbeatData
- type AgentHeartbeatInput
- type AgentSelectionMode
- type AgentSelector
- type AgentService
- func (s *AgentService) ActivateAgent(ctx context.Context, tenantID, agentID string, auditCtx *auditapp.AuditContext) (*agentdom.Agent, error)
- func (s *AgentService) AuthenticateByAPIKey(ctx context.Context, apiKey string) (*agentdom.Agent, error)
- func (s *AgentService) ClaimJob(ctx context.Context, agentID shared.ID) error
- func (s *AgentService) CreateAgent(ctx context.Context, input CreateAgentInput) (*CreateAgentOutput, error)
- func (s *AgentService) DeleteAgent(ctx context.Context, tenantID, agentID string, auditCtx *auditapp.AuditContext) error
- func (s *AgentService) DisableAgent(ctx context.Context, tenantID, agentID, reason string, ...) (*agentdom.Agent, error)
- func (s *AgentService) FindAvailableAgents(ctx context.Context, tenantID shared.ID, capabilities []string, tool string) ([]*agentdom.Agent, error)
- func (s *AgentService) FindAvailableWithCapacity(ctx context.Context, tenantID shared.ID, capabilities []string, tool string) ([]*agentdom.Agent, error)
- func (s *AgentService) GetAgent(ctx context.Context, tenantID, agentID string) (*agentdom.Agent, error)
- func (s *AgentService) GetAvailableCapabilitiesForTenant(ctx context.Context, tenantID shared.ID) (*TenantAvailableCapabilitiesOutput, error)
- func (s *AgentService) GetPlatformStats(ctx context.Context, tenantID shared.ID) (*PlatformStatsOutput, error)
- func (s *AgentService) GetTenantAgentStats(ctx context.Context, tenantID string) (*agentdom.TenantAgentStats, error)
- func (s *AgentService) HasCapability(ctx context.Context, tenantID shared.ID, capability string) (bool, error)
- func (s *AgentService) Heartbeat(ctx context.Context, input AgentHeartbeatInput) error
- func (s *AgentService) IncrementStats(ctx context.Context, agentID shared.ID, findings, scans, errors int64) error
- func (s *AgentService) ListAgents(ctx context.Context, input ListAgentsInput) (pagination.Result[*agentdom.Agent], error)
- func (s *AgentService) RegenerateAPIKey(ctx context.Context, tenantID, agentID string, auditCtx *auditapp.AuditContext) (string, error)
- func (s *AgentService) ReleaseJob(ctx context.Context, agentID shared.ID) error
- func (s *AgentService) RevokeAgent(ctx context.Context, tenantID, agentID, reason string, ...) (*agentdom.Agent, error)
- func (s *AgentService) SetPepper(pepper string)
- func (s *AgentService) UpdateAgent(ctx context.Context, input UpdateAgentInput) (*agentdom.Agent, error)
- func (s *AgentService) UpdateHeartbeat(ctx context.Context, agentID shared.ID, data AgentHeartbeatData) error
- type AgentTemplateData
- type CreateAgentInput
- type CreateAgentOutput
- type ListAgentsInput
- type PlatformStatsOutput
- type PlatformTierStats
- type RenderedTemplates
- type SelectAgentRequest
- type SelectAgentResult
- type TenantAvailableCapabilitiesOutput
- type UpdateAgentInput
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNoAgentAvailable is returned when no suitable agent is found. ErrNoAgentAvailable = errors.New("no suitable agent available") )
Functions ¶
This section is empty.
Types ¶
type AgentAvailabilityResult ¶
AgentAvailabilityResult represents agent availability status.
type AgentConfigTemplateService ¶
type AgentConfigTemplateService struct {
// contains filtered or unexported fields
}
AgentConfigTemplateService renders agent configuration templates (yaml, env, docker, cli) from filesystem-loaded templates.
Templates live in <templates_dir>/{yaml,env,docker,cli}.tmpl and use Go text/template syntax. Operators can edit the .tmpl files in place without rebuilding the API or frontend — changes are picked up on restart, or live if Reload() is called.
The service caches parsed templates after first load. Call Reload() to pick up file changes without restart.
func NewAgentConfigTemplateService ¶
func NewAgentConfigTemplateService(templatesDir string, log *logger.Logger) *AgentConfigTemplateService
NewAgentConfigTemplateService loads templates from the given directory. If the directory doesn't exist or any template fails to parse, the service falls back to built-in defaults so the API never fails to start.
func (*AgentConfigTemplateService) Reload ¶
func (s *AgentConfigTemplateService) Reload() error
Reload re-reads all template files from disk. Safe to call at runtime.
func (*AgentConfigTemplateService) Render ¶
func (s *AgentConfigTemplateService) Render(data AgentTemplateData) (*RenderedTemplates, error)
Render renders all four template formats with the given agent data. Returns user-friendly content (no internal errors leaked).
type AgentHeartbeatData ¶
type AgentHeartbeatData struct {
Version string
Hostname string
CPUPercent float64
MemoryPercent float64
CurrentJobs int
Region string
}
AgentHeartbeatData represents the data received from agent heartbeat.
type AgentHeartbeatInput ¶
type AgentHeartbeatInput struct {
AgentID shared.ID
Status string
Message string
Version string
Hostname string
IPAddress string
}
AgentHeartbeatInput represents the input for agent heartbeat.
type AgentSelectionMode ¶
type AgentSelectionMode string
AgentSelectionMode defines which agents to consider.
const ( // SelectTenantOnly only considers tenant's own agents. SelectTenantOnly AgentSelectionMode = "tenant_only" // SelectAny selects from any available agent. SelectAny AgentSelectionMode = "any" )
type AgentSelector ¶
type AgentSelector struct {
// contains filtered or unexported fields
}
AgentSelector handles intelligent agent selection for job execution.
func NewAgentSelector ¶
func NewAgentSelector( agentRepo agentdom.Repository, commandRepo command.Repository, agentState *redis.AgentStateStore, log *logger.Logger, ) *AgentSelector
NewAgentSelector creates a new AgentSelector.
func (*AgentSelector) CheckAgentAvailability ¶
func (s *AgentSelector) CheckAgentAvailability(ctx context.Context, tenantID shared.ID, toolName string, tenantOnly bool) *AgentAvailabilityResult
CheckAgentAvailability checks if any agent is available for the given scan configuration. This should be called before creating a scan to ensure execution is possible.
func (*AgentSelector) SelectAgent ¶
func (s *AgentSelector) SelectAgent(ctx context.Context, req SelectAgentRequest) (*SelectAgentResult, error)
SelectAgent selects the best agent for a job based on the selection mode.
type AgentService ¶
type AgentService struct {
// contains filtered or unexported fields
}
AgentService handles agent-related business operations.
func NewAgentService ¶
func NewAgentService(repo agentdom.Repository, auditService *auditapp.AuditService, log *logger.Logger) *AgentService
NewAgentService creates a new AgentService.
func (*AgentService) ActivateAgent ¶
func (s *AgentService) ActivateAgent(ctx context.Context, tenantID, agentID string, auditCtx *auditapp.AuditContext) (*agentdom.Agent, error)
ActivateAgent activates an agent (admin action).
func (*AgentService) AuthenticateByAPIKey ¶
func (s *AgentService) AuthenticateByAPIKey(ctx context.Context, apiKey string) (*agentdom.Agent, error)
AuthenticateByAPIKey authenticates an agent by API key. Authentication is based on admin-controlled Status field only: - Active: allowed to authenticate - Disabled: admin has disabled the agent - Revoked: access permanently revoked The Health field (unknown/online/offline/error) is for monitoring only.
func (*AgentService) CreateAgent ¶
func (s *AgentService) CreateAgent(ctx context.Context, input CreateAgentInput) (*CreateAgentOutput, error)
CreateAgent creates a new agent and generates an API key.
func (*AgentService) DeleteAgent ¶
func (s *AgentService) DeleteAgent(ctx context.Context, tenantID, agentID string, auditCtx *auditapp.AuditContext) error
DeleteAgent deletes an agent.
func (*AgentService) DisableAgent ¶
func (s *AgentService) DisableAgent(ctx context.Context, tenantID, agentID, reason string, auditCtx *auditapp.AuditContext) (*agentdom.Agent, error)
DisableAgent disables an agent (admin action).
func (*AgentService) FindAvailableAgents ¶
func (s *AgentService) FindAvailableAgents(ctx context.Context, tenantID shared.ID, capabilities []string, tool string) ([]*agentdom.Agent, error)
FindAvailableAgents finds agents that can handle a task.
func (*AgentService) FindAvailableWithCapacity ¶
func (s *AgentService) FindAvailableWithCapacity(ctx context.Context, tenantID shared.ID, capabilities []string, tool string) ([]*agentdom.Agent, error)
FindAvailableWithCapacity finds agents with available job capacity for load balancing.
func (*AgentService) GetAgent ¶
func (s *AgentService) GetAgent(ctx context.Context, tenantID, agentID string) (*agentdom.Agent, error)
GetAgent retrieves an agent by ID.
func (*AgentService) GetAvailableCapabilitiesForTenant ¶
func (s *AgentService) GetAvailableCapabilitiesForTenant(ctx context.Context, tenantID shared.ID) (*TenantAvailableCapabilitiesOutput, error)
GetAvailableCapabilitiesForTenant returns all capabilities available to a tenant. This aggregates capabilities from the tenant's own agents (if status=active and health=online).
func (*AgentService) GetPlatformStats ¶
func (s *AgentService) GetPlatformStats(ctx context.Context, tenantID shared.ID) (*PlatformStatsOutput, error)
GetPlatformStats returns aggregate statistics for platform agents accessible to the tenant.
func (*AgentService) GetTenantAgentStats ¶
func (s *AgentService) GetTenantAgentStats(ctx context.Context, tenantID string) (*agentdom.TenantAgentStats, error)
GetTenantAgentStats returns aggregate statistics for the tenant's agents. Computed via SQL aggregation in a single round-trip — replaces the previous client-side .filter().length pattern that only saw the current page of results.
func (*AgentService) HasCapability ¶
func (s *AgentService) HasCapability(ctx context.Context, tenantID shared.ID, capability string) (bool, error)
HasCapability checks if a tenant has access to a specific capability.
func (*AgentService) Heartbeat ¶
func (s *AgentService) Heartbeat(ctx context.Context, input AgentHeartbeatInput) error
Heartbeat updates agent status from heartbeat.
func (*AgentService) IncrementStats ¶
func (s *AgentService) IncrementStats(ctx context.Context, agentID shared.ID, findings, scans, errors int64) error
IncrementStats increments agent statistics.
func (*AgentService) ListAgents ¶
func (s *AgentService) ListAgents(ctx context.Context, input ListAgentsInput) (pagination.Result[*agentdom.Agent], error)
ListAgents lists agents with filters.
func (*AgentService) RegenerateAPIKey ¶
func (s *AgentService) RegenerateAPIKey(ctx context.Context, tenantID, agentID string, auditCtx *auditapp.AuditContext) (string, error)
RegenerateAPIKey generates a new API key for an agent.
func (*AgentService) ReleaseJob ¶
ReleaseJob releases a job slot on an agent.
func (*AgentService) RevokeAgent ¶
func (s *AgentService) RevokeAgent(ctx context.Context, tenantID, agentID, reason string, auditCtx *auditapp.AuditContext) (*agentdom.Agent, error)
RevokeAgent permanently revokes an agent's access (admin action).
func (*AgentService) SetPepper ¶
func (s *AgentService) SetPepper(pepper string)
SetPepper configures the HMAC pepper used by the API-key hash. Empty string disables peppering (backward-compat with pre-existing SHA-256 hashes). Should be called once at boot before the service handles any traffic.
func (*AgentService) UpdateAgent ¶
func (s *AgentService) UpdateAgent(ctx context.Context, input UpdateAgentInput) (*agentdom.Agent, error)
UpdateAgent updates an agent.
func (*AgentService) UpdateHeartbeat ¶
func (s *AgentService) UpdateHeartbeat(ctx context.Context, agentID shared.ID, data AgentHeartbeatData) error
UpdateHeartbeat updates agent metrics from heartbeat.
type AgentTemplateData ¶
type AgentTemplateData struct {
Agent *agentdom.Agent
APIKey string // May be empty if not freshly created/regenerated
BaseURL string // Public API URL agents should connect to
GeneratedAt string // RFC3339 timestamp
}
AgentTemplateData is the data passed to every agent config template.
type CreateAgentInput ¶
type CreateAgentInput struct {
TenantID string `json:"tenant_id" validate:"required,uuid"`
Name string `json:"name" validate:"required,min=1,max=255"`
Type string `json:"type" validate:"required,oneof=runner worker collector sensor"`
Description string `json:"description" validate:"max=1000"`
Capabilities []string `json:"capabilities" validate:"max=20,dive,max=50"`
Tools []string `json:"tools" validate:"max=20,dive,max=50"`
ExecutionMode string `json:"execution_mode" validate:"omitempty,oneof=standalone daemon"`
MaxConcurrentJobs int `json:"max_concurrent_jobs" validate:"omitempty,min=1,max=100"`
// Audit context (optional, for audit logging)
AuditContext *auditapp.AuditContext `json:"-"`
}
CreateAgentInput represents the input for creating an agent.
type CreateAgentOutput ¶
type CreateAgentOutput struct {
Agent *agentdom.Agent `json:"agent"`
APIKey string `json:"api_key"` // Only returned on creation
}
CreateAgentOutput represents the output after creating an agent.
type ListAgentsInput ¶
type ListAgentsInput struct {
TenantID string `json:"tenant_id" validate:"required,uuid"`
Type string `json:"type" validate:"omitempty,oneof=runner worker collector sensor"`
Status string `json:"status" validate:"omitempty,oneof=active disabled revoked"` // Admin-controlled
Health string `json:"health" validate:"omitempty,oneof=unknown online offline error"` // Automatic
ExecutionMode string `json:"execution_mode" validate:"omitempty,oneof=standalone daemon"`
Capabilities []string `json:"capabilities"`
Tools []string `json:"tools"`
Search string `json:"search" validate:"max=255"`
HasCapacity *bool `json:"has_capacity"` // Filter by agents with available capacity
Page int `json:"page"`
PerPage int `json:"per_page"`
}
ListAgentsInput represents the input for listing agents.
type PlatformStatsOutput ¶
type PlatformStatsOutput struct {
Enabled bool
MaxTier string
AccessibleTiers []string
MaxConcurrent int
MaxQueued int
CurrentActive int
CurrentQueued int
AvailableSlots int
TierStats map[string]PlatformTierStats
}
PlatformStatsOutput represents the output for platform stats.
type PlatformTierStats ¶
type PlatformTierStats struct {
TotalAgents int
OnlineAgents int
OfflineAgents int
TotalCapacity int
CurrentLoad int
AvailableSlots int
}
PlatformTierStats represents statistics for a single platform agent tier.
type RenderedTemplates ¶
type RenderedTemplates struct {
YAML string `json:"yaml"`
Env string `json:"env"`
Docker string `json:"docker"`
CLI string `json:"cli"`
}
RenderedTemplates is the output of rendering all templates for one agent.
type SelectAgentRequest ¶
type SelectAgentRequest struct {
TenantID shared.ID
Capabilities []string
Tool string
Region string // Preferred region
Mode AgentSelectionMode
AllowQueue bool // If true, return queue info instead of error when no agent available
}
SelectAgentRequest represents a request to select an agent for a job.
type SelectAgentResult ¶
SelectAgentResult represents the result of agent selection.
type TenantAvailableCapabilitiesOutput ¶
type TenantAvailableCapabilitiesOutput struct {
Capabilities []string `json:"capabilities"` // Unique capability names available to tenant
TotalAgents int `json:"total_agents"` // Total number of online agents
}
TenantAvailableCapabilitiesOutput represents the output for available capabilities.
type UpdateAgentInput ¶
type UpdateAgentInput struct {
TenantID string `json:"tenant_id" validate:"required,uuid"`
AgentID string `json:"agent_id" validate:"required,uuid"`
Name string `json:"name" validate:"omitempty,min=1,max=255"`
Description string `json:"description" validate:"max=1000"`
Capabilities []string `json:"capabilities" validate:"max=20,dive,max=50"`
Tools []string `json:"tools" validate:"max=20,dive,max=50"`
Status string `json:"status" validate:"omitempty,oneof=active disabled revoked"` // Admin-controlled
MaxConcurrentJobs *int `json:"max_concurrent_jobs" validate:"omitempty,min=1,max=100"`
// Audit context (optional, for audit logging)
AuditContext *auditapp.AuditContext `json:"-"`
}
UpdateAgentInput represents the input for updating an agent.