proto

package
v0.3.5 Latest Latest
Warning

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

 Go to latest Published: Mar 31, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package proto provides protocol buffer type adapters for the plugin system.

This package contains helpers for working with the protobuf definitions from the finfocus-spec repository, enabling type conversions between internal Go types and gRPC message types.

Index

Constants

View Source 
const (
	ErrCodePluginError     = "PLUGIN_ERROR"
	ErrCodeValidationError = "VALIDATION_ERROR"
	ErrCodeTimeoutError    = "TIMEOUT_ERROR"
	ErrCodeNoCostData      = "NO_COST_DATA"
)

Error code constants for StructuredError. These mirror the constants in engine/types.go for use at the proto/adapter layer.

Variables

View Source 
var ErrEstimateCostNotSupported = errors.New(
	"EstimateCost RPC not yet implemented in finfocus-spec v0.5.6",
)

ErrEstimateCostNotSupported indicates the EstimateCost RPC is not yet implemented.

View Source 
var ErrPropertiesMultiResource = errors.New(
	"properties cannot be used with multiple ResourceIDs: each resource requires its own properties",
)

ErrPropertiesMultiResource indicates Properties cannot be used with multiple ResourceIDs because each resource requires its own cloud ID, ARN, and tag mappings.

Functions

func ActionTypeLabel 

func ActionTypeLabel(at pbc.RecommendationActionType) string

ActionTypeLabel returns the human-readable label for a RecommendationActionType. For unknown/future enum values, it returns "Unknown (N)" where N is the integer value.

func ActionTypeLabelFromString 

func ActionTypeLabelFromString(actionType string) string

ActionTypeLabelFromString returns the human-readable label for an action type string. For unknown types, it returns the input string unchanged. This is useful for converting stored/serialized action type strings to display labels.

func DismissalReasonFromProtoName added in v0.3.0 

func DismissalReasonFromProtoName(protoName string) string

DismissalReasonFromProtoName converts a proto enum name (e.g., "BUSINESS_CONSTRAINT") to a CLI flag value (e.g., "business-constraint"). This is used when reading stored dismissal reasons from the local state file.

func DismissalReasonLabel added in v0.3.0 

func DismissalReasonLabel(reason pbc.DismissalReason) string

DismissalReasonLabel returns the human-readable label for a DismissalReason. For unknown/future enum values, it returns "Unknown (N)" where N is the integer value.

func MatchesActionType 

func MatchesActionType(recType string, types []pbc.RecommendationActionType) bool

MatchesActionType checks if a recommendation's action type matches any of the given types. The rec parameter should have a Type field containing the action type string. Matching is case-insensitive.

func ParseActionType 

func ParseActionType(s string) (pbc.RecommendationActionType, error)

ParseActionType parses a string into a RecommendationActionType enum value. Matching is case-insensitive and whitespace is trimmed. Returns an error for unknown type names, listing all valid options. UNSPECIFIED is not allowed as a filter value.

func ParseActionTypeFilter 

func ParseActionTypeFilter(filter string) ([]pbc.RecommendationActionType, error)

ParseActionTypeFilter parses a comma-separated list of action types. Each type is validated and converted to a RecommendationActionType enum value. Returns an error if any type is invalid or if the input is empty.

func ParseDismissalReason added in v0.3.0 

func ParseDismissalReason(s string) (pbc.DismissalReason, error)

ParseDismissalReason parses a CLI flag value into a DismissalReason enum value. Matching is case-insensitive and whitespace is trimmed. Returns an error for unknown reason values, listing all valid options.

func ValidActionTypes 

func ValidActionTypes() []string

ValidActionTypes returns a list of valid action type short names for filter expressions. UNSPECIFIED is excluded as it's not a valid filter value.

func ValidDismissalReasons added in v0.3.0 

func ValidDismissalReasons() []string

ValidDismissalReasons returns a sorted list of valid CLI flag values for dismissal reasons. UNSPECIFIED is excluded as it's not a valid user-selectable reason.

Types

type ActualCostResult 

type ActualCostResult struct {
	Currency       string
	TotalCost      float64
	CostBreakdown  map[string]float64
	Sustainability map[string]SustainabilityMetric
	ExpiresAt      *time.Time
}

ActualCostResult represents the calculated actual cost data retrieved from cloud providers. It includes the total cost and detailed breakdowns by service or resource.

type CostDelta added in v0.3.0 

type CostDelta struct {
	// Property is the name of the property that was changed
	Property string `json:"property"`

	// OriginalValue is the value before the change
	OriginalValue string `json:"originalValue"`

	// NewValue is the value after the change
	NewValue string `json:"newValue"`

	// CostChange is the monthly cost difference
	// Positive = increase, negative = savings
	CostChange float64 `json:"costChange"`
}

CostDelta represents the cost impact of a single property change.

type CostResult 

type CostResult struct {
	Currency        string
	MonthlyCost     float64
	HourlyCost      float64
	Notes           string
	CostBreakdown   map[string]float64
	Sustainability  map[string]SustainabilityMetric
	StructuredError *StructuredError `json:"structuredError,omitempty"`
	ExpiresAt       *time.Time
}

CostResult represents the calculated cost information for a single resource. It includes monthly and hourly costs, currency, and detailed cost breakdowns.

type CostResultWithErrors 

type CostResultWithErrors struct {
	Results []*CostResult
	Errors  []ErrorDetail
}

CostResultWithErrors wraps results and any errors encountered during cost calculation.

func GetActualCostWithErrors 

func GetActualCostWithErrors(
	ctx context.Context,
	client CostSourceClient,
	pluginName string,
	req *GetActualCostRequest,
) *CostResultWithErrors

GetActualCostWithErrors validates the request, then for each ResourceID it resolves cloud identifiers and tags (including optional SKU and region enrichment when Provider is set), validates the plugin-facing request, and invokes the client's GetActualCost. For each resource it appends either the plugin's cost results or a placeholder CostResult and records any per-resource validation or plugin errors in the returned ErrorDetail slice.

Parameters:

  • ctx: request context for cancellation and timeouts.
  • client: the CostSourceClient used to call plugin GetActualCost.
  • pluginName: human-readable name of the plugin (used in ErrorDetail entries).
  • req: parameters for the actual cost query; must include ResourceIDs and time range.

Returns: 

A *CostResultWithErrors containing Results for each resource (actual or placeholder)
and any per-resource ErrorDetail entries. If the request is invalid (for example,
Properties are provided with multiple ResourceIDs) the returned CostResultWithErrors
will contain the validation error and no per-resource processing will be performed.

func GetProjectedCostWithErrors 

func GetProjectedCostWithErrors(
	ctx context.Context,
	client CostSourceClient,
	pluginName string,
	resources []*ResourceDescriptor,
) *CostResultWithErrors

GetProjectedCostWithErrors queries projected costs for each resource and aggregates successful results

  • Errors: a slice of ErrorDetail with per-resource failure information and timestamps.

func (*CostResultWithErrors) ErrorSummary 

func (c *CostResultWithErrors) ErrorSummary() string

ErrorSummary returns a human-readable summary of errors. Truncates the output after 5 errors to keep it readable.

func (*CostResultWithErrors) HasErrors 

func (c *CostResultWithErrors) HasErrors() bool

HasErrors returns true if any errors were encountered during cost calculation.

type CostSourceClient 

type CostSourceClient interface {
	Name(ctx context.Context, in *Empty, opts ...grpc.CallOption) (*NameResponse, error)
	GetProjectedCost(
		ctx context.Context,
		in *GetProjectedCostRequest,
		opts ...grpc.CallOption,
	) (*GetProjectedCostResponse, error)
	GetActualCost(
		ctx context.Context,
		in *GetActualCostRequest,
		opts ...grpc.CallOption,
	) (*GetActualCostResponse, error)
	GetRecommendations(
		ctx context.Context,
		in *GetRecommendationsRequest,
		opts ...grpc.CallOption,
	) (*GetRecommendationsResponse, error)
	GetPluginInfo(
		ctx context.Context,
		in *Empty,
		opts ...grpc.CallOption,
	) (*pbc.GetPluginInfoResponse, error)
	GetBudgets(
		ctx context.Context,
		in *pbc.GetBudgetsRequest,
		opts ...grpc.CallOption,
	) (*pbc.GetBudgetsResponse, error)
	DryRun(
		ctx context.Context,
		in *pbc.DryRunRequest,
		opts ...grpc.CallOption,
	) (*pbc.DryRunResponse, error)
	DismissRecommendation(
		ctx context.Context,
		in *DismissRecommendationRequest,
		opts ...grpc.CallOption,
	) (*DismissRecommendationResponse, error)
	Supports(
		ctx context.Context,
		in *pbc.SupportsRequest,
		opts ...grpc.CallOption,
	) (*pbc.SupportsResponse, error)
}

CostSourceClient wraps the generated gRPC client from finfocus-spec.

func NewCostSourceClient 

func NewCostSourceClient(conn *grpc.ClientConn) CostSourceClient

NewCostSourceClient creates a new cost source client using the real proto client.

type DismissRecommendationRequest added in v0.3.0 

type DismissRecommendationRequest struct {
	// RecommendationID is the unique identifier of the recommendation to dismiss.
	RecommendationID string

	// Reason is the DismissalReason proto enum value.
	Reason pbc.DismissalReason

	// CustomReason is the free-text explanation (required when Reason is OTHER).
	CustomReason string

	// ExpiresAt is the snooze expiry; nil means permanent dismissal.
	ExpiresAt *time.Time

	// DismissedBy identifies the user who dismissed the recommendation.
	DismissedBy string
}

DismissRecommendationRequest contains parameters for dismissing a recommendation via plugin RPC.

type DismissRecommendationResponse added in v0.3.0 

type DismissRecommendationResponse struct {
	// Success indicates whether the plugin accepted the dismissal.
	Success bool

	// Message is the plugin's response message.
	Message string

	// DismissedAt is when the plugin recorded the dismissal.
	DismissedAt time.Time

	// ExpiresAt is the snooze expiry echoed back from the plugin.
	ExpiresAt *time.Time

	// RecommendationID echoes back the dismissed recommendation's ID.
	RecommendationID string
}

DismissRecommendationResponse contains the result of a dismiss RPC call.

type Empty 

type Empty struct{}

Empty represents an empty request/response for compatibility with existing engine code.

type ErrorDetail 

type ErrorDetail struct {
	ResourceType string
	ResourceID   string
	PluginName   string
	Error        error
	Timestamp    time.Time
}

ErrorDetail captures information about a failed resource cost calculation.

type EstimateCostRequest added in v0.3.0 

type EstimateCostRequest struct {
	// Resource is the base resource descriptor
	Resource *ResourceDescriptor `json:"resource,omitempty"`

	// PropertyOverrides are the changes to evaluate
	PropertyOverrides map[string]string `json:"propertyOverrides,omitempty"`

	// UsageProfile optionally provides context (dev, prod, etc.)
	UsageProfile string `json:"usageProfile,omitempty"`
}

EstimateCostRequest represents the internal request for what-if cost estimation.

func BuildEstimateCostRequest added in v0.3.0 

func BuildEstimateCostRequest(
	_ *ResourceDescriptor,
	_ map[string]string,
) (*EstimateCostRequest, error)

BuildEstimateCostRequest constructs an EstimateCostRequest proto message.

This is the adapter layer function that converts engine-level types to proto-level types for gRPC communication with plugins.

Parameters:

  • resource: The ResourceDescriptor to estimate costs for
  • overrides: Property overrides to apply for the modified calculation

Returns:

  • *EstimateCostRequest: The internal request (nil when RPC not implemented)
  • error: ErrEstimateCostNotSupported until the RPC is implemented

type EstimateCostResponse added in v0.3.0 

type EstimateCostResponse struct {
	// Baseline is the cost with original properties
	Baseline *CostResult `json:"baseline,omitempty"`

	// Modified is the cost with property overrides applied
	Modified *CostResult `json:"modified,omitempty"`

	// Deltas contains per-property cost impact breakdown
	Deltas []*CostDelta `json:"deltas,omitempty"`
}

EstimateCostResponse contains the results of a cost estimation.

type FieldMapping 

type FieldMapping struct {
	FieldName    string             `json:"fieldName"              yaml:"fieldName"`
	Status       FieldMappingStatus `json:"status"                 yaml:"status"`
	Condition    string             `json:"condition,omitempty"    yaml:"condition,omitempty"`
	ExpectedType string             `json:"expectedType,omitempty" yaml:"expectedType,omitempty"`
}

FieldMapping describes how a Pulumi resource property maps to pricing inputs.

type FieldMappingStatus 

type FieldMappingStatus string

FieldMappingStatus represents the support status of a resource field in the plugin. 

const (
	// StatusSupported indicates the field is fully supported and mapped.
	StatusSupported FieldMappingStatus = "SUPPORTED"
	// StatusUnsupported indicates the field is known but not supported for cost estimation.
	StatusUnsupported FieldMappingStatus = "UNSUPPORTED"
	// StatusConditional indicates the field is supported only under certain conditions.
	StatusConditional FieldMappingStatus = "CONDITIONAL"
	// StatusDynamic indicates the field's support is determined at runtime.
	StatusDynamic FieldMappingStatus = "DYNAMIC"
)

func (FieldMappingStatus) String added in v0.2.1 

func (s FieldMappingStatus) String() string

String returns the string representation of the FieldMappingStatus. It implements the fmt.Stringer interface for human-readable output in logs and debug.

type GetActualCostRequest 

type GetActualCostRequest struct {
	ResourceIDs []string
	StartTime   int64
	EndTime     int64
	// Properties carries resource context (cloud IDs, ARN, tags) from state.
	// Used by the adapter to populate proto fields (ResourceId, Arn, Tags).
	Properties map[string]interface{}
	// Provider is the cloud provider identifier (e.g., "aws", "azure", "gcp").
	// When set, the adapter resolves SKU and region from Properties and injects
	// them into the tags sent to the plugin, enabling plugins like aws-public
	// to price resources by instance type / volume type.
	Provider string
	// ResourceType is the Pulumi type token (e.g., "aws:eks/cluster:Cluster").
	// Used by resolveSKUAndRegion as a fallback for well-known SKU resolution
	// when property-based extraction returns empty.
	ResourceType string
}

GetActualCostRequest contains parameters for querying historical actual costs. It includes resource IDs and a time range for cost data retrieval.

type GetActualCostResponse 

type GetActualCostResponse struct {
	Results []*ActualCostResult
}

GetActualCostResponse contains the results of actual cost queries.

type GetProjectedCostRequest 

type GetProjectedCostRequest struct {
	Resources []*ResourceDescriptor
}

GetProjectedCostRequest contains resources for which projected costs should be calculated.

type GetProjectedCostResponse 

type GetProjectedCostResponse struct {
	Results []*CostResult
}

GetProjectedCostResponse contains the results of projected cost calculations.

type GetRecommendationsRequest 

type GetRecommendationsRequest struct {
	// TargetResources specifies the resources to analyze for recommendations.
	// When empty, plugins return recommendations for all resources in scope.
	TargetResources []*ResourceDescriptor

	// ProjectionPeriod specifies the time period for savings projection.
	// Valid values: "daily", "monthly" (default), "annual".
	ProjectionPeriod string

	// PageSize is the maximum number of recommendations to return (default: 50, max: 1000).
	PageSize int32

	// PageToken is the continuation token from a previous response.
	PageToken string

	// ExcludedRecommendationIDs contains IDs of recommendations to exclude from results.
	ExcludedRecommendationIDs []string
}

GetRecommendationsRequest contains parameters for retrieving cost optimization recommendations. It supports filtering by target resources, pagination, and exclusion of dismissed recommendations.

type GetRecommendationsResponse 

type GetRecommendationsResponse struct {
	// Recommendations is the list of cost optimization recommendations.
	Recommendations []*Recommendation

	// NextPageToken is the token for retrieving the next page (empty if last page).
	NextPageToken string
}

GetRecommendationsResponse contains the recommendations and summary from a GetRecommendations call.

type NameResponse 

type NameResponse struct {
	Name string
}

NameResponse contains the plugin name returned by the Name RPC call.

func (*NameResponse) GetName 

func (n *NameResponse) GetName() string

GetName returns the plugin name from the response.

type PluginMetadata 

type PluginMetadata struct {
	Name               string            `json:"name"                         yaml:"name"`
	Version            string            `json:"version"                      yaml:"version"`
	SpecVersion        string            `json:"specVersion"                  yaml:"specVersion"`
	SupportedProviders []string          `json:"supportedProviders,omitempty" yaml:"supportedProviders,omitempty"`
	Metadata           map[string]string `json:"metadata,omitempty"           yaml:"metadata,omitempty"`
	Capabilities       []string          `json:"capabilities,omitempty"       yaml:"capabilities,omitempty"`
}

PluginMetadata contains information about a plugin's version and capabilities.

type Recommendation 

type Recommendation struct {
	// ID is a unique identifier for this recommendation.
	ID string

	// Category classifies the type of recommendation (e.g., "COST", "PERFORMANCE").
	Category string

	// ActionType specifies what action is recommended (e.g., "RIGHTSIZE", "TERMINATE").
	ActionType string

	// Description is a human-readable summary of the recommendation.
	Description string

	// ResourceID identifies the affected resource.
	ResourceID string

	// Source identifies the data source (e.g., "aws", "kubecost", "azure-advisor").
	Source string

	// Impact contains the financial impact assessment.
	Impact *RecommendationImpact

	// Metadata contains additional provider-specific information.
	Metadata map[string]string

	// Reasoning carries plugin-provided warnings and caveats mapped from
	// proto Recommendation.Reasoning (field 14). These explain prerequisites
	// or risks associated with implementing the recommendation.
	Reasoning []string
}

Recommendation represents a single cost optimization recommendation from a plugin. This is the internal representation that maps to the protobuf Recommendation message.

type RecommendationImpact 

type RecommendationImpact struct {
	// EstimatedSavings is the estimated cost savings.
	EstimatedSavings float64

	// Currency is the ISO 4217 currency code.
	Currency string

	// CurrentCost is the current cost of the resource.
	CurrentCost float64

	// ProjectedCost is the projected cost after implementing the recommendation.
	ProjectedCost float64

	// SavingsPercentage is the savings as a percentage.
	SavingsPercentage float64
}

RecommendationImpact describes the financial impact of implementing a recommendation.

type ResourceDescriptor 

type ResourceDescriptor struct {
	// ID is a client-generated identifier for request/response correlation.
	// Plugins copy this to recommendation ResourceID for proper matching.
	ID         string
	Type       string
	Provider   string
	Properties map[string]string
}

ResourceDescriptor describes a cloud resource for cost calculation requests. It contains the resource type, provider, and properties needed for pricing lookups.

type StructuredError added in v0.3.0 

type StructuredError struct {
	Code         string `json:"code"`
	Message      string `json:"message"`
	ResourceType string `json:"resourceType"`
}

StructuredError is a machine-readable error representation that accompanies CostResult entries produced by error paths (validation, plugin, timeout).

type SustainabilityMetric 

type SustainabilityMetric struct {
	Value float64
	Unit  string
}

SustainabilityMetric represents a single sustainability impact measurement.

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.