output

package
v0.0.68 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 9, 2025 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package output provides fleet-scale output filtering and truncation for MCP tool responses.

When operating across a fleet of clusters, queries can return massive amounts of data that overwhelm LLM context windows (typically 128K-200K tokens). This package implements intelligent output filtering, truncation, and summarization to maintain usable response sizes.

Key Features

Response Truncation: Limits the number of resources returned per query with clear warning messages when truncation occurs. Configurable per-query limits with absolute maximums.

Field Exclusion (Slim Output): Automatically removes verbose fields that rarely help AI agents, such as managedFields, last-applied-configuration annotations, and timestamps.

Secret Masking: Never returns secret data in responses - all secret values are replaced with "***REDACTED***" to prevent accidental exposure.

Summary Mode: For large queries, offers summary counts by status and cluster instead of raw data, dramatically reducing response size while maintaining usefulness.

Configuration

Output behavior is controlled via Config: 

cfg := output.DefaultConfig()
cfg.MaxItems = 50     // Limit items per response
cfg.SlimOutput = true // Enable field exclusion
cfg.MaskSecrets = true // Redact secret data

Security Considerations

This package implements several security controls:

  • Secret masking prevents credential leakage
  • Response size limits prevent DoS via context exhaustion
  • Configurable limits allow operators to tune for their environment

Usage Example 

// Apply all transformations to a response
processor := output.NewProcessor(cfg)
result, warnings := processor.Process(items)

// Or use individual functions
slimmed := output.SlimResource(obj)
masked := output.MaskSecrets(obj)
truncated, warning := output.TruncateResponse(items, 100)

Index

Constants

View Source 
const (
	// DefaultMaxItems is the default maximum number of resources returned per query.
	DefaultMaxItems = 100

	// DefaultMaxClusters is the default maximum number of clusters in fleet-wide queries.
	DefaultMaxClusters = 20

	// DefaultMaxResponseBytes is the default hard limit on response size (512KB).
	DefaultMaxResponseBytes = 512 * 1024

	// AbsoluteMaxItems is the absolute maximum items that can be requested.
	// This prevents DoS via unbounded result sets even when users request higher limits.
	AbsoluteMaxItems = 1000

	// AbsoluteMaxClusters is the absolute maximum clusters for fleet operations.
	AbsoluteMaxClusters = 100

	// AbsoluteMaxResponseBytes is the absolute maximum response size (2MB).
	AbsoluteMaxResponseBytes = 2 * 1024 * 1024
)

Default limits for output processing. These are tuned for typical LLM context windows and API response sizes.

View Source 
const RedactedValue = "***REDACTED***"

RedactedValue is the placeholder used for masked secret data.

Variables

This section is empty.

Functions

func AppendWarningsToResult 

func AppendWarningsToResult(result map[string]interface{}, warnings []TruncationWarning) map[string]interface{}

AppendWarningsToResult appends truncation warnings to a JSON result. The warnings are added to a "warnings" field if any exist.

func ContainsSensitiveData 

func ContainsSensitiveData(obj map[string]interface{}) bool

ContainsSensitiveData checks if a resource might contain sensitive data. This includes Secrets, ConfigMaps with certain names, and ServiceAccounts.

func DefaultExcludedFields 

func DefaultExcludedFields() []string

DefaultExcludedFields returns the default list of fields to exclude in slim mode. These are verbose fields that typically don't help AI agents understand resources.

func EffectiveClusterLimit 

func EffectiveClusterLimit(requestLimit, configLimit int) int

EffectiveClusterLimit calculates the effective cluster limit.

func EffectiveLimit 

func EffectiveLimit(requestLimit, configLimit int) int

EffectiveLimit calculates the effective limit considering request and config limits. It applies absolute bounds to prevent DoS attacks.

func EstimateFieldSize 

func EstimateFieldSize(obj map[string]interface{}, path string) int64

EstimateFieldSize estimates the JSON size reduction from removing a field. This is useful for logging and metrics.

func FormatResultWithMetadata 

func FormatResultWithMetadata(items interface{}, metadata ProcessingMetadata, warnings []TruncationWarning) map[string]interface{}

FormatResultWithMetadata formats a result map with processing metadata.

func FromRuntimeObjects 

func FromRuntimeObjects(objects []runtime.Object) ([]map[string]interface{}, error)

FromRuntimeObjects converts a slice of runtime.Object to maps for processing.

func IsSecretResource 

func IsSecretResource(obj map[string]interface{}) bool

IsSecretResource checks if a resource is a Kubernetes Secret.

func IsSensitiveSecretType 

func IsSensitiveSecretType(secretType string) bool

IsSensitiveSecretType checks if a secret type contains sensitive data. Returns true for types that should always have their data masked.

func MaskSecretSummary 

func MaskSecretSummary(secret map[string]interface{}) map[string]interface{}

MaskSecretSummary creates a summary of a Secret without exposing data. Useful for listing secrets with basic info but no sensitive content.

func MaskSecrets 

func MaskSecrets(obj map[string]interface{}) map[string]interface{}

MaskSecrets replaces secret data with redacted placeholders. This prevents accidental exposure of sensitive data in tool responses.

func MaskSecretsInList 

func MaskSecretsInList(objects []map[string]interface{}) []map[string]interface{}

MaskSecretsInList masks secrets in a list of resources.

func ProcessSingleRuntimeObject 

func ProcessSingleRuntimeObject(processor *Processor, obj runtime.Object) (runtime.Object, error)

ProcessSingleRuntimeObject applies output processing to a single runtime.Object.

func QuickProcessSingle 

func QuickProcessSingle(item map[string]interface{}) map[string]interface{}

QuickProcessSingle is a convenience function for processing a single item.

func ShouldUseSummary 

func ShouldUseSummary(itemCount, threshold int) bool

ShouldUseSummary determines if summary mode should be suggested. Returns true if the result set is large enough to benefit from summarization.

func SlimResource 

func SlimResource(obj map[string]interface{}, excludedFields []string) map[string]interface{}

SlimResource removes verbose fields from a resource map. This reduces response size by removing fields that rarely help AI agents.

func SlimResources 

func SlimResources(objects []map[string]interface{}, excludedFields []string) []map[string]interface{}

SlimResources applies SlimResource to a slice of resources.

func ToRuntimeObjects 

func ToRuntimeObjects(maps []map[string]interface{}) []runtime.Object

ToRuntimeObjects converts a slice of maps back to runtime.Objects. Note: This returns unstructured objects, not typed objects.

Types

type Config 

type Config struct {
	// MaxItems limits the number of resources returned per query.
	// Default: 100, Absolute max: 1000
	MaxItems int `json:"maxItems" yaml:"maxItems"`

	// MaxClusters limits clusters in fleet-wide queries.
	// Default: 20, Absolute max: 100
	MaxClusters int `json:"maxClusters" yaml:"maxClusters"`

	// MaxResponseBytes is a hard limit on response size in bytes.
	// Default: 512KB, Absolute max: 2MB
	MaxResponseBytes int `json:"maxResponseBytes" yaml:"maxResponseBytes"`

	// SlimOutput enables removal of verbose fields that rarely help AI agents.
	// Default: true
	SlimOutput bool `json:"slimOutput" yaml:"slimOutput"`

	// MaskSecrets replaces secret data with "***REDACTED***".
	// Default: true (security critical - should rarely be disabled)
	MaskSecrets bool `json:"maskSecrets" yaml:"maskSecrets"`

	// SummaryThreshold is the item count above which summary mode is suggested.
	// Default: 500
	SummaryThreshold int `json:"summaryThreshold" yaml:"summaryThreshold"`

	// ExcludedFields lists JSON paths of fields to exclude in slim mode.
	// Default: common verbose fields (managedFields, last-applied-configuration, etc.)
	ExcludedFields []string `json:"excludedFields,omitempty" yaml:"excludedFields,omitempty"`
}

Config holds configuration for output processing. All limits have sensible defaults that can be overridden via Helm values.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns a Config with sensible defaults for fleet-scale operations.

func (*Config) Clone 

func (c *Config) Clone() *Config

Clone creates a deep copy of the configuration.

func (*Config) Validate 

func (c *Config) Validate() *Config

Validate validates the configuration and applies absolute limits. It returns a validated copy with any out-of-range values capped.

type CountEntry 

type CountEntry struct {
	Key   string `json:"key"`
	Count int    `json:"count"`
}

CountEntry represents a key-count pair.

func TopCounts 

func TopCounts(counts map[string]int, n int) []CountEntry

TopCounts returns the top N entries from a count map.

type ProcessingMetadata 

type ProcessingMetadata struct {
	// ProcessedAt is when processing occurred
	ProcessedAt time.Time `json:"processedAt"`

	// OriginalCount is the item count before processing
	OriginalCount int `json:"originalCount"`

	// FinalCount is the item count after processing
	FinalCount int `json:"finalCount"`

	// Truncated indicates if truncation occurred
	Truncated bool `json:"truncated"`

	// SlimApplied indicates if slim output was applied
	SlimApplied bool `json:"slimApplied"`

	// SecretsMasked indicates if secrets were masked
	SecretsMasked bool `json:"secretsMasked"`

	// BytesReduced is the estimated bytes saved by processing
	BytesReduced int64 `json:"bytesReduced,omitempty"`
}

ProcessingMetadata contains metadata about the processing operation.

type ProcessingResult 

type ProcessingResult struct {
	// Items contains the processed items
	Items []map[string]interface{} `json:"items"`

	// Warnings contains any warnings generated during processing
	Warnings []TruncationWarning `json:"warnings,omitempty"`

	// Metadata contains additional processing metadata
	Metadata ProcessingMetadata `json:"metadata"`
}

ProcessingResult contains the result of output processing.

func ProcessRuntimeObjects 

func ProcessRuntimeObjects(processor *Processor, objects []runtime.Object) ([]runtime.Object, *ProcessingResult, error)

ProcessRuntimeObjects applies output processing to runtime.Objects. This is a convenience function for handlers that work with runtime.Object slices.

func ProcessRuntimeObjectsWithLimit 

func ProcessRuntimeObjectsWithLimit(processor *Processor, objects []runtime.Object, limit int) ([]runtime.Object, *ProcessingResult, error)

ProcessRuntimeObjectsWithLimit applies output processing with a custom limit.

func QuickProcess 

func QuickProcess(items []map[string]interface{}) *ProcessingResult

QuickProcess is a convenience function for processing with default config.

type ProcessingStats 

type ProcessingStats struct {
	// ItemsProcessed is the number of items processed
	ItemsProcessed int `json:"itemsProcessed"`

	// ItemsTruncated is the number of items removed by truncation
	ItemsTruncated int `json:"itemsTruncated"`

	// SecretsRedacted is the number of secrets that had data redacted
	SecretsRedacted int `json:"secretsRedacted"`

	// FieldsRemoved is the estimated count of fields removed by slim mode
	FieldsRemoved int `json:"fieldsRemoved"`

	// BytesSaved is the estimated bytes saved by processing
	BytesSaved int64 `json:"bytesSaved"`

	// ProcessingTimeMs is the processing duration in milliseconds
	ProcessingTimeMs int64 `json:"processingTimeMs"`
}

ProcessingStats contains statistics about output processing.

type Processor 

type Processor struct {
	// contains filtered or unexported fields
}

Processor applies output transformations based on configuration.

func NewProcessor 

func NewProcessor(config *Config) *Processor

NewProcessor creates a new output processor with the given configuration.

func (*Processor) Config 

func (p *Processor) Config() *Config

Config returns the processor's configuration.

func (*Processor) GenerateSummary 

func (p *Processor) GenerateSummary(items []map[string]interface{}, opts *SummaryOptions) *ResourceSummary

GenerateSummary creates a summary for large result sets.

func (*Processor) Process 

func (p *Processor) Process(items []map[string]interface{}) *ProcessingResult

Process applies all configured transformations to a list of resources. It returns the processed items and a result containing metadata and warnings.

func (*Processor) ProcessSingle 

func (p *Processor) ProcessSingle(item map[string]interface{}) map[string]interface{}

ProcessSingle applies transformations to a single resource.

func (*Processor) ProcessWithLimit 

func (p *Processor) ProcessWithLimit(items []map[string]interface{}, limit int) *ProcessingResult

ProcessWithLimit applies transformations with a custom limit. Useful when the limit is specified per-request.

func (*Processor) ProcessWithStats 

func (p *Processor) ProcessWithStats(items []map[string]interface{}) (*ProcessingResult, *ProcessingStats)

ProcessWithStats applies transformations and returns detailed statistics. This is useful for observability and debugging.

func (*Processor) ShouldSuggestSummary 

func (p *Processor) ShouldSuggestSummary(itemCount int) bool

ShouldSuggestSummary returns true if the item count exceeds the summary threshold.

type ResourceSummary 

type ResourceSummary struct {
	// Total is the total number of resources
	Total int `json:"total"`

	// ByStatus shows counts grouped by status (e.g., Running, Pending, Failed)
	ByStatus map[string]int `json:"byStatus,omitempty"`

	// ByCluster shows counts grouped by cluster name
	ByCluster map[string]int `json:"byCluster,omitempty"`

	// ByNamespace shows counts grouped by namespace
	ByNamespace map[string]int `json:"byNamespace,omitempty"`

	// ByKind shows counts grouped by resource kind
	ByKind map[string]int `json:"byKind,omitempty"`

	// Sample contains the first few resource names for context
	Sample []string `json:"sample,omitempty"`

	// HasMore indicates if there are more items not shown in sample
	HasMore bool `json:"hasMore,omitempty"`
}

ResourceSummary provides aggregated counts for large query results. This dramatically reduces response size while maintaining usefulness.

func GenerateFleetSummary 

func GenerateFleetSummary(objects []map[string]interface{}, clusterField string) *ResourceSummary

GenerateFleetSummary creates a summary optimized for fleet-wide queries.

func GenerateSummary 

func GenerateSummary(objects []map[string]interface{}, opts *SummaryOptions) *ResourceSummary

GenerateSummary creates a summary from a list of resources.

type SummaryOptions 

type SummaryOptions struct {
	// MaxSampleSize limits the number of sample names included
	MaxSampleSize int

	// IncludeByStatus groups by status field
	IncludeByStatus bool

	// IncludeByCluster groups by cluster (for multi-cluster results)
	IncludeByCluster bool

	// IncludeByNamespace groups by namespace
	IncludeByNamespace bool

	// IncludeByKind groups by resource kind
	IncludeByKind bool

	// ClusterField is the field path for cluster name (default: metadata.annotations.cluster)
	ClusterField string
}

SummaryOptions configures summary generation.

func DefaultSummaryOptions 

func DefaultSummaryOptions() *SummaryOptions

DefaultSummaryOptions returns sensible defaults for summary generation.

type TruncationWarning 

type TruncationWarning struct {
	// Shown is the number of items returned
	Shown int `json:"shown"`

	// Total is the total number of items before truncation
	Total int `json:"total"`

	// Message is a human-readable warning message
	Message string `json:"message"`

	// SuggestSummary indicates if summary mode is recommended
	SuggestSummary bool `json:"suggestSummary,omitempty"`

	// SuggestFilters suggests filter options to reduce results
	SuggestFilters []string `json:"suggestFilters,omitempty"`
}

TruncationWarning contains information about response truncation.

func TruncateClusters 

func TruncateClusters[T any](clusters []T, maxClusters int) ([]T, *TruncationWarning)

TruncateClusters truncates a slice of clusters for fleet-wide operations. Returns the truncated slice and a warning if truncation occurred.

func TruncateGeneric 

func TruncateGeneric[T any](items []T, maxItems int) ([]T, *TruncationWarning)

TruncateGeneric truncates a generic slice of items. This is useful for typed slices that need to be truncated.

func TruncateResponse 

func TruncateResponse(items []map[string]interface{}, maxItems int) ([]map[string]interface{}, *TruncationWarning)

TruncateResponse truncates a slice of items to the configured maximum. Returns the truncated slice and a warning if truncation occurred.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.