| 1 | // SPDX-License-Identifier: GPL-3.0-or-later |
| 2 | |
| 3 | package funcapi |
| 4 | |
| 5 | // MethodConfig describes a function method provided by a module. |
| 6 | type MethodConfig struct { |
| 7 | ID string // Method ID (e.g., "top-queries") |
| 8 | // FIXME: funcctl currently honors aliases only for module/static methods. |
| 9 | // Job method registration still publishes only the canonical module:method name. |
| 10 | Aliases []string // Additional function names to register for this method |
| 11 | Name string // Display name (e.g., "Top Queries") |
| 12 | UpdateEvery int // Default UI refresh interval |
| 13 | Help string // Description for UI |
| 14 | RequireCloud bool // Indicates whether the method requires cloud connection |
| 15 | ResponseType string // Response schema type; empty defaults to "table" when dispatched |
| 16 | // FIXME: AgentWide currently removes __job from the public API, but funcctl still |
| 17 | // dispatches through the first running job for the module instead of a true |
| 18 | // agent-level execution path. |
| 19 | AgentWide bool // Method is agent-wide (does not require __job selector) |
| 20 | RequiredParams []ParamConfig // Required parameters for this method (including __sort if used) |
| 21 | // FIXME: Presentation is intentionally untyped here, while the shared UI schema |
| 22 | // currently defines only topology-specific presentation payloads. |
| 23 | presentation any |
| 24 | } |
| 25 | |
| 26 | // WithPresentation returns an updated copy with optional presentation metadata attached. |
| 27 | // This uses builder-style value semantics so it can be chained from composite literals. |
| 28 | func (cfg MethodConfig) WithPresentation(v any) MethodConfig { |
| 29 | cfg.presentation = v |
| 30 | return cfg |
| 31 | } |
| 32 | |
| 33 | // Presentation returns optional presentation metadata for the method info response. |
| 34 | func (cfg MethodConfig) Presentation() any { |
| 35 | return cfg.presentation |
| 36 | } |
| 37 | |
| 38 | // FunctionResponse is the response from a module's HandleMethod. |
| 39 | type FunctionResponse struct { |
| 40 | Status int // HTTP-like status code (200, 400, 403, 500, 503) |
| 41 | Message string // Error message (if Status != 200) |
| 42 | Help string // Help text for this response |
| 43 | ResponseType string // Override response schema type (defaults to MethodConfig.ResponseType) |
| 44 | Columns map[string]any // Column definitions for the table |
| 45 | Data any // Row data: [][]any (array of arrays, ordered by column index) |
| 46 | DefaultSortColumn string // Default sort column ID |
| 47 | |
| 48 | // Optional dynamic required params (override MethodConfig.RequiredParams) |
| 49 | RequiredParams []ParamConfig |
| 50 | |
| 51 | // Chart configuration for visualization (embedded for JSON compatibility) |
| 52 | ChartingConfig |
| 53 | } |
| 54 | |
| 55 | // ChartingConfig groups chart visualization settings. |
| 56 | // Embedded in FunctionResponse - JSON fields are promoted to top level. |
| 57 | type ChartingConfig struct { |
| 58 | Charts map[string]ChartConfig // Chart definitions (chartID -> config) |
| 59 | DefaultCharts DefaultCharts // Default charts to display |
| 60 | GroupBy map[string]GroupByConfig // Group-by options (groupByID -> config) |
| 61 | } |
| 62 | |
| 63 | // DefaultChart represents a chart with its grouping. |
| 64 | type DefaultChart struct { |
| 65 | Chart string // Chart ID to display |
| 66 | GroupBy string // Column to group by |
| 67 | } |
| 68 | |
| 69 | // DefaultCharts is a list of default charts. |
| 70 | type DefaultCharts []DefaultChart |
| 71 | |
| 72 | // Build converts DefaultCharts to [][]string for JSON response. |
| 73 | // Output format: [["chartID", "groupByID"], ...] |
| 74 | func (dc DefaultCharts) Build() [][]string { |
| 75 | if len(dc) == 0 { |
| 76 | return nil |
| 77 | } |
| 78 | result := make([][]string, len(dc)) |
| 79 | for i, c := range dc { |
| 80 | result[i] = []string{c.Chart, c.GroupBy} |
| 81 | } |
| 82 | return result |
| 83 | } |
| 84 | |
| 85 | // ChartConfig defines a chart for visualization. |
| 86 | type ChartConfig struct { |
| 87 | Name string `json:"name"` |
| 88 | Type string `json:"type"` // "stacked-bar", "line", etc. |
| 89 | Columns []string `json:"columns"` // Column IDs to include in chart |
| 90 | } |
| 91 | |
| 92 | // GroupByConfig defines a grouping option for function responses. |
| 93 | type GroupByConfig struct { |
| 94 | Name string `json:"name"` |
| 95 | Columns []string `json:"columns"` // Columns to group by |
| 96 | } |