exchange

type AutoExchangeResult struct {
	Mode      string
	Completed []ExchangeOutcome
	Pending   []ExchangeOutcome
	Failed    []ExchangeOutcome
	Skipped   []SkippedRecommendation
}

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

type EC2ExchangeAPI interface {
	GetReservedInstancesExchangeQuote(ctx context.Context, params *ec2.GetReservedInstancesExchangeQuoteInput, optFns ...func(*ec2.Options)) (*ec2.GetReservedInstancesExchangeQuoteOutput, error)
	AcceptReservedInstancesExchangeQuote(ctx context.Context, params *ec2.AcceptReservedInstancesExchangeQuoteInput, optFns ...func(*ec2.Options)) (*ec2.AcceptReservedInstancesExchangeQuoteOutput, error)
}

type ExchangeClientInterface interface {
	GetQuote(ctx context.Context, req ExchangeQuoteRequest) (*ExchangeQuoteSummary, error)
	Execute(ctx context.Context, req ExchangeExecuteRequest) (string, *ExchangeQuoteSummary, error)
}

type ExchangeExecuteRequest struct {
	Region          string
	ExpectedAccount string // optional safety check
	ReservedIDs     []string

	// Targets is the preferred path for multi-target exchanges. When
	// non-empty, TargetOfferingID / TargetCount are ignored.
	Targets []TargetConfig

	// Legacy single-target alias. Prefer Targets for new code.
	TargetOfferingID string
	TargetCount      int32

	// Guardrail: require PaymentDue <= MaxPaymentDueUSD to execute.
	// AWS returns a single aggregated PaymentDue across all targets,
	// so for multi-target requests this guardrail naturally becomes a
	// total cap rather than a per-target cap.
	// If nil, execution is refused.
	MaxPaymentDueUSD *big.Rat
}

type ExchangeOutcome struct {
	RecordID           string
	ApprovalToken      string
	SourceRIID         string
	SourceInstanceType string
	TargetInstanceType string
	TargetOfferingID   string
	TargetCount        int32
	PaymentDue         string
	ExchangeID         string
	UtilizationPct     float64
	Error              string
	// OutcomeUnknown is true when the accept response was lost, so the exchange
	// may have executed. It must be reconciled before any retry. The outcome
	// stays in AutoExchangeResult.Failed (readers of Failed still see it) and
	// halts the run (no further exchanges are attempted).
	OutcomeUnknown bool
	// Simulated is true when RunAutoExchangeParams.DryRun was set. The outcome
	// was analyzed and quoted but no record was saved and no exchange was executed.
	Simulated bool
}

type ExchangeQuoteRequest struct {
	Region          string
	ExpectedAccount string // optional safety check
	ReservedIDs     []string

	// Targets is the preferred path for multi-target exchanges. When
	// non-empty, TargetOfferingID / TargetCount are ignored.
	Targets []TargetConfig

	// TargetOfferingID + TargetCount are the legacy single-target
	// fields, retained so pre-existing callers (HTTP handlers, sanity
	// tests, serialized PurchasePlans) don't need a flag-day change.
	// New code should populate Targets instead.
	TargetOfferingID string
	TargetCount      int32

	// DryRun here uses the AWS API DryRun parameter (permission check).
	// The quote call itself never performs an exchange.
	DryRun bool
}

type ExchangeQuoteSummary struct {
	IsValidExchange         bool
	ValidationFailureReason string
	CurrencyCode            string

	PaymentDueRaw    string   // as returned by AWS (string)
	PaymentDueUSD    *big.Rat `json:"-"`                         // internal use only, not serializable
	PaymentDueUSDStr string   `json:"payment_due_usd,omitempty"` // parsed decimal for JSON consumers

	OutputReservedInstancesExp string // formatted date string (YYYY-MM-DD), empty if not set

	// Rollups (strings in AWS response)
	SourceHourlyPriceRaw      string
	SourceRemainingUpfrontRaw string
	SourceRemainingTotalRaw   string
	TargetHourlyPriceRaw      string
	TargetRemainingUpfrontRaw string
	TargetRemainingTotalRaw   string
}

type ExchangeRecord struct {
	ID                 string
	AccountID          string
	ExchangeID         string
	Region             string
	SourceRIIDs        []string
	SourceInstanceType string
	SourceCount        int
	TargetOfferingID   string
	TargetInstanceType string
	TargetCount        int
	PaymentDue         string
	Status             string
	ApprovalToken      string
	Error              string
	Mode               string
	// LadderRunID links this exchange record to the ladder run that created it.
	// Nil for standalone ri_exchange_reshape task records.
	// The database column ri_exchange_history.ladder_run_id was added in
	// migration 000080 and is the authoritative source for origin scoping.
	LadderRunID *string
	CreatedAt   time.Time
	UpdatedAt   time.Time
	CompletedAt *time.Time
	ExpiresAt   *time.Time
}

type LookupOfferingFunc func(ctx context.Context, p LookupOfferingParams) (string, error)

type LookupOfferingParams struct {
	InstanceType       string
	ProductDescription string
	Tenancy            string
	Scope              string
	AvailabilityZone   string
	Duration           int64
}

type Mode string

type OfferingOption struct {
	InstanceType         string  `json:"instance_type"`
	OfferingID           string  `json:"offering_id"`
	EffectiveMonthlyCost float64 `json:"effective_monthly_cost"`
	// NormalizationFactor is the AWS normalization factor for the
	// offering's instance size — needed by the local
	// passesDollarUnitsCheck pre-filter that gates which cross-family
	// alternatives surface in the UI. Zero on missing means the
	// alternative cannot be safely compared and the pre-filter
	// excludes it.
	NormalizationFactor float64 `json:"normalization_factor,omitempty"`
	// CurrencyCode is the ISO-4217 currency the EffectiveMonthlyCost is
	// denominated in (typically "USD"). The pre-filter requires source
	// and target currencies to match; empty on either side falls back to
	// "skip the currency guard" so today's USD-only fixtures stay green.
	CurrencyCode string `json:"currency_code,omitempty"`
	// TermSeconds is the offering's commitment term in seconds
	// (31_536_000 for 1y, 94_608_000 for 3y) — same unit as
	// RIInfo.TermSeconds and the AWS SDK's ReservedInstance.Duration.
	// AnalyzeReshapingWithRecs rejects term-mismatched alternatives
	// before building AlternativeTargets so a 3y RI never surfaces as
	// an alternative to a 1y source commitment (and vice versa). Zero
	// on either side falls back to "skip the term guard" for callers
	// or fixtures that don't populate it.
	TermSeconds int64 `json:"term_seconds,omitempty"`
	// SavingsAbs is the absolute monthly savings (in CurrencyCode) that
	// AWS Cost Explorer reported for this recommendation. Used by
	// compositeScore to estimate savings % and derive a confidence
	// signal. Zero means "not supplied" — the score component is omitted
	// rather than coerced to 0 (which would falsely rank this offering
	// last on the savings axis).
	SavingsAbs *float64 `json:"savings_abs,omitempty"`
	// RecommendationCount is the number of instances AWS Cost Explorer
	// included in the recommendation. Used together with SavingsAbs to
	// derive a confidence signal (large fleet + large savings = high
	// confidence). Zero means "not supplied"; the confidence signal is
	// skipped rather than treated as a 0-instance fleet.
	RecommendationCount int `json:"recommendation_count,omitempty"`
}

type PurchaseRecLookup func(ctx context.Context, region, currencyCode string) ([]OfferingOption, error)

type RIExchangeConfig struct {
	Mode                     string
	UtilizationThreshold     float64
	MaxPaymentPerExchangeUSD float64
	MaxPaymentDailyUSD       float64
	LookbackDays             int
}

type RIExchangeStore interface {
	SaveRIExchangeRecord(ctx context.Context, record *ExchangeRecord) error
	// CancelAllPendingExchanges cancels every pending record regardless of origin.
	// Kept for interface compatibility; RunAutoExchange now calls
	// CancelPendingExchangesByOrigin instead to avoid cross-origin contamination.
	CancelAllPendingExchanges(ctx context.Context) (int64, error)
	// CancelPendingExchangesByOrigin cancels only pending records whose origin
	// matches:
	//   - common.ExchangeOriginStandalone: cancels WHERE ladder_run_id IS NULL
	//   - common.ExchangeOriginLadder:     cancels WHERE ladder_run_id IS NOT NULL
	// This prevents the standalone task from wiping out ladder-linked pending
	// reshapes and vice versa. Implementations must validate the origin and
	// fail loud on an unknown value (money path).
	CancelPendingExchangesByOrigin(ctx context.Context, origin common.ExchangeOrigin) (int64, error)
	GetStaleProcessingExchanges(ctx context.Context, olderThan time.Duration) ([]ExchangeRecord, error)
	GetRIExchangeDailySpend(ctx context.Context, date time.Time) (string, error)
	CompleteRIExchange(ctx context.Context, id string, exchangeID string) error
	// ReserveRIExchange atomically checks daily spend and saves a processing
	// record with the returned execution ceiling. It sets record.ID.
	ReserveRIExchange(ctx context.Context, record *ExchangeRecord, dailyCapUSD, perExchangeCapUSD string) (string, error)
	CompleteRIExchangeWithPayment(ctx context.Context, id, exchangeID, acceptedPaymentDue string) error
	FailRIExchange(ctx context.Context, id string, errorMsg string) error
}

type RIInfo struct {
	ID                  string
	InstanceType        string
	InstanceCount       int32
	OfferingClass       string  // must be "convertible" — standard RIs cannot be exchanged
	NormalizationFactor float64 // AWS normalization factor for the instance size
	// MonthlyCost is the effective per-instance per-month price (amortized
	// upfront + recurring charges, AWS-canonical 730 hours per month).
	// Used by the local passesDollarUnitsCheck pre-filter that gates
	// cross-family alternatives. Zero when the caller didn't compute it
	// (e.g. older callers that only need primary-target analysis); the
	// pre-filter treats zero as "skip the check" so existing behavior
	// is preserved.
	MonthlyCost float64
	// CurrencyCode is the ISO-4217 currency the prices are denominated
	// in (typically "USD"). Used by the cross-family check to refuse
	// comparisons across currencies. Empty matches the same "skip"
	// semantics as MonthlyCost == 0.
	CurrencyCode string
	// TermSeconds is the RI commitment term in seconds (31_536_000 for
	// 1y, 94_608_000 for 3y) — the same unit the AWS SDK uses on the
	// ReservedInstance.Duration field and the unit ec2.ConvertibleRI.Duration
	// already carries. Used by the cross-family alternatives pass to
	// reject term-mismatched offerings (e.g. surfacing a 3y RI as an
	// alternative to a 1y commitment is wrong because the customer's
	// existing exchange anchor is the 1y term). Zero means "unknown" —
	// the term filter is skipped for that rec to preserve today's
	// behavior for older callers that don't populate it.
	TermSeconds int64
}

type RIMetadataInfo struct {
	ProductDescription string
	InstanceTenancy    string
	Scope              string
	AvailabilityZone   string
	Duration           int64
}

type ReshapeRecommendation struct {
	SourceRIID          string           `json:"source_ri_id"`
	SourceInstanceType  string           `json:"source_instance_type"`
	SourceCount         int32            `json:"source_count"`
	TargetInstanceType  string           `json:"target_instance_type"`
	TargetCount         int32            `json:"target_count"`
	AlternativeTargets  []OfferingOption `json:"alternative_targets,omitempty"`
	UtilizationPercent  float64          `json:"utilization_percent"`
	NormalizedUsed      float64          `json:"normalized_used"`
	NormalizedPurchased float64          `json:"normalized_purchased"`
	Reason              string           `json:"reason"`
}

type RunAutoExchangeParams struct {
	Store          RIExchangeStore
	ExchangeClient ExchangeClientInterface
	LookupOffering LookupOfferingFunc
	RIs            []RIInfo
	Utilization    []UtilizationInfo
	Config         RIExchangeConfig
	AccountID      string
	Region         string
	DashboardURL   string

	// RIMetadata maps RI ID to its metadata (product description, tenancy, scope, duration).
	RIMetadata map[string]RIMetadataInfo

	// LadderRunID links all exchange records created by this run to the ladder
	// run that originated them. Nil for the standalone ri_exchange_reshape task.
	// When set, RunAutoExchange calls CancelPendingExchangesByOrigin with
	// ladderScoped=true (cancels only ladder-linked pendings). When nil, it
	// cancels only standalone (ladder_run_id IS NULL) pendings.
	LadderRunID *string

	// DryRun skips all state mutations (cancellations, record saves, exchange
	// executions). Outcomes are returned with Simulated=true. No store write
	// is performed; mock.AssertExpectations will catch any accidental mutation
	// call in tests (fail-loud gate).
	DryRun bool
}

type SkippedRecommendation struct {
	SourceRIID         string
	SourceInstanceType string
	Reason             string
}

type TargetConfig struct {
	OfferingID string
	Count      int32
}

type UtilizationInfo struct {
	RIID               string
	UtilizationPercent float64 // 0.0–100.0
}