archera

package
v0.0.0-...-8caed39 Latest Latest
Warning

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

 Go to latest Published: Oct 18, 2026 License: OSL-3.0 Imports: 20 Imported by: 0

Documentation

Overview

Package archera wires the explicit Archera comparison (pkg/insurance) into the server. The surface is off unless all three settings are present, and the API key is resolved lazily on the first explicit request.

Index

Constants

View Source 
const (
	EnvOrgID     = "ARCHERA_ORG_ID"
	EnvPlanID    = "ARCHERA_PLAN_ID"
	EnvKeySecret = "ARCHERA_API_KEY_SECRET" // #nosec G101 -- setting name, not a credential value
)

Setting names, shared with the CLI and MCP consumers.

Variables

View Source 
var ErrKeyUnavailable = errors.New("archera API key could not be resolved from " + EnvKeySecret)

ErrKeyUnavailable is returned when the API key secret cannot be resolved or yields an unusable client. The message is fixed so no vendor or secret text can reach a response.

View Source 
var ErrNotConfigured = errors.New("archera comparison is not configured")

ErrNotConfigured is returned (wrapped, naming the missing settings) when an explicit request arrives and one or more settings are absent.

View Source 
var ErrRecommendationIdentity = errors.New("stored recommendation identity is unavailable")

ErrRecommendationIdentity means a stored recommendation cannot be proven to be a supported savings plan.

View Source 
var ErrUnrepresentable = errors.New("archera value has no exact decimal representation")

ErrUnrepresentable is returned when a vendor number has no exact finite decimal form (the DTO never rounds or converts to float).

Functions

func CleanString 

func CleanString(s string) string

CleanString removes control, format and line/paragraph-separator characters from vendor text and caps it at 256 bytes on a rune boundary.

func Decimal 

func Decimal(r *big.Rat) (*string, error)

Decimal renders r as the shortest exact decimal string. nil (unknown) stays nil. The denominator of a reduced rational is finite in decimal exactly when it has no prime factor other than 2 and 5, and the digits needed equal max(power of 2, power of 5).

func ProjectContract 

func ProjectContract(c *insurance.Comparison, items []insurance.LineItem) ([]ComparisonIdentity, []LineItemIdentity, error)

ProjectContract projects the published comparison and line items into the identities MatchRecommendation joins.

Types

type CandidateAssociation 

type CandidateAssociation struct {
	OfferID              string
	Status               CandidateStatus
	Reason               Reason
	NativeIdentityStatus CandidateStatus
}

type CandidateIdentity 

type CandidateIdentity struct {
	OfferID, Provider, Type, Payment string
	SelectedAmount                   *big.Rat
}

type CandidateStatus 

type CandidateStatus string

CandidateStatus classifies a vendor candidate against the stored recommendation. 

const (
	CandidateVendorAlternative CandidateStatus = "vendor_alternative"
	CandidateUnavailable       CandidateStatus = "unavailable"
)

type ComparisonDTO 

type ComparisonDTO struct {
	Title                 string            `json:"title"`
	PlanID                string            `json:"plan_id"`
	FetchedAt             string            `json:"fetched_at"`
	Currency              *string           `json:"currency"`
	CurrencyNote          string            `json:"currency_note"`
	PremiumIncluded       bool              `json:"premium_included"`
	BasisNote             string            `json:"basis_note"`
	DeltaBasisNote        string            `json:"delta_basis_note"`
	Current               TotalsDTO         `json:"current"`
	Hypotheticals         []HypotheticalDTO `json:"hypotheticals"`
	Rows                  []RowDTO          `json:"rows"`
	NonGatingDisclosure   string            `json:"non_gating_disclosure"`
	SponsorshipDisclosure string            `json:"sponsorship_disclosure"`
}

ComparisonDTO is the platform response. No org ID is included.

func BuildComparison 

func BuildComparison(c *insurance.Comparison) (*ComparisonDTO, error)

BuildComparison maps the contract type to the platform DTO. Money is exact decimal text or null; every vendor string is cleaned and capped. It returns ErrUnrepresentable when any number has no exact decimal form.

type ComparisonIdentity 

type ComparisonIdentity struct {
	Region                                                            *string
	IsCurrent                                                         bool
	LineItemID, CurrentOfferID, Provider, CurrentType, CurrentPayment string
	CurrentSelectedAmount                                             *big.Rat
	Candidates                                                        []CandidateIdentity
}

type DeltaDTO 

type DeltaDTO struct {
	MonthlyNetSavings *string `json:"monthly_730h_net_savings"`
	UpfrontCost       *string `json:"upfront_one_time_cost"`
	DiscountRate      *string `json:"discount_rate"`
	BreakevenDays     *string `json:"breakeven_days"`
}

DeltaDTO is the vendor's candidate-minus-current difference.

type FinancialsDTO 

type FinancialsDTO struct {
	CommitmentCostTotal *string `json:"monthly_730h_commitment_cost_total"`
	CloudProviderCost   *string `json:"monthly_730h_cloud_provider_cost"`
	Premium             *string `json:"monthly_730h_archera_premium"`
	GrossSavings        *string `json:"monthly_730h_gross_savings"`
	NetSavings          *string `json:"monthly_730h_net_savings"`
	CoveredOnDemandCost *string `json:"monthly_730h_covered_on_demand_cost"`
}

FinancialsDTO carries the 730-hour monthly rate block.

type HypotheticalDTO 

type HypotheticalDTO struct {
	ContractTerm   *string              `json:"contract_term"`
	PaymentOption  string               `json:"payment_option"`
	Totals         TotalsDTO            `json:"totals"`
	DeltaVsCurrent HypotheticalDeltaDTO `json:"delta_vs_current"`
	LineItems      []LineItemDTO        `json:"line_items"`
}

HypotheticalDTO is a rollup for one (term, payment option) combination.

type HypotheticalDeltaDTO 

type HypotheticalDeltaDTO struct {
	MonthlyNetSavings     *string `json:"monthly_730h_net_savings"`
	MonthlyCommitmentCost *string `json:"monthly_730h_commitment_cost"`
	UpfrontCost           *string `json:"upfront_one_time_cost"`
}

HypotheticalDeltaDTO compares a hypothetical rollup against the current plan.

type LineItemDTO 

type LineItemDTO struct {
	LineItemID           string  `json:"line_item_id"`
	Reason               string  `json:"reason"`
	ActualTerm           *string `json:"actual_term"`
	ActualPaymentOption  *string `json:"actual_payment_option"`
	ActualCommitmentType *string `json:"actual_commitment_type"`
}

LineItemDTO is how one line item lands inside a hypothetical rollup.

type LineItemIdentity 

type LineItemIdentity struct {
	ID, PlanID, OfferID, Provider, SourceAccountID, ProviderOfferingID string
	Type, PlanType, Region, InstanceFamily, Payment                    string
	DurationSeconds, SelectedCommitment                                *big.Rat
}

type MatchStatus 

type MatchStatus string
const (
	MatchUnavailable   MatchStatus = "unavailable"
	ResourceAssociated MatchStatus = "resource_associated"
)

type OfferDTO 

type OfferDTO struct {
	OfferID              string            `json:"offer_id"`
	IsCurrent            bool              `json:"is_current"`
	Provider             string            `json:"provider"`
	CommitmentType       string            `json:"commitment_type"`
	Region               *string           `json:"region"`
	ContractTerm         *string           `json:"contract_term"`
	PaymentOption        *string           `json:"payment_option"`
	LeaseAttached        bool              `json:"lease_attached"`
	LeaseMenuItemID      *string           `json:"lease_menu_item_id"`
	ArcheraOfferName     *string           `json:"archera_offer_name,omitempty"`
	ArcheraOfferNameNote string            `json:"archera_offer_name_note,omitempty"`
	ProductSupport       ProductSupportDTO `json:"archera_product_support"`
	DiscountRate         *string           `json:"discount_rate"`
	BreakevenDays        *string           `json:"breakeven_days"`
	Monthly              FinancialsDTO     `json:"monthly"`
	UpfrontCost          *string           `json:"upfront_one_time_cost"`
	DeltaVsCurrent       DeltaDTO          `json:"delta_vs_current"`
}

OfferDTO is one offer (current or candidate) for a line item.

type ProductSupportDTO 

type ProductSupportDTO struct {
	Status              string `json:"status"`
	Source              string `json:"source,omitempty"`
	Evidence            string `json:"evidence,omitempty"`
	UnderwritingAllowed string `json:"underwriting_allowance"`
	CustomerEligibility string `json:"customer_eligibility"`
}

ProductSupportDTO is the documentation-derived verdict for one offer. Source and Evidence appear only for a supported verdict; allowance and customer eligibility are always unknown.

type Provider 

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

Provider builds the insurance client on first use. It holds the secret resolver and a *insurance.Client only, never the raw key or a Config value.

func NewProvider 

func NewProvider(settings Settings, resolver secrets.Resolver, hc *http.Client) *Provider

NewProvider returns a Provider. hc must be nil in production.

func (*Provider) Client 

func (p *Provider) Client(ctx context.Context) (insurance.QuoteClient, error)

Client returns the lazily built client. A failure is not cached: the next call retries (a mutex, not sync.Once, guards the build).

func (*Provider) Format 

func (p *Provider) Format(s fmt.State, _ rune)

Format keeps the provider's contents out of every fmt verb.

func (*Provider) PlanID 

func (p *Provider) PlanID() string

PlanID is the configured Archera plan ID.

func (*Provider) Status 

func (p *Provider) Status() Status

Status reports setting presence without any outbound call or secret read.

type Reason 

type Reason string

Reason names why a match, candidate, amount or economic status holds. 

const (
	ReasonIdentityUnproven           Reason = "identity_unproven"
	ReasonAmbiguousLineItems         Reason = "ambiguous_line_items"
	ReasonComparisonBasisUnproven    Reason = "comparison_basis_unproven"
	ReasonCandidateBasisUnproven     Reason = "candidate_basis_unproven"
	ReasonStoredDecimalOnly          Reason = "stored_decimal_only"
	ReasonUnavailableSourcePrecision Reason = "unavailable_source_precision"
)

type RecommendationAlternativeDTO 

type RecommendationAlternativeDTO struct {
	OfferID              string                  `json:"offer_id"`
	Status               CandidateStatus         `json:"status"`
	Reason               Reason                  `json:"reason"`
	NativeIdentityStatus CandidateStatus         `json:"native_identity_status"`
	Figures              *RecommendationOfferDTO `json:"figures"`
}

type RecommendationComparisonDTO 

type RecommendationComparisonDTO struct {
	RecommendationID      string                         `json:"recommendation_id"`
	Status                MatchStatus                    `json:"status"`
	Reason                Reason                         `json:"reason"`
	AmountProvenance      Reason                         `json:"amount_provenance"`
	EconomicStatus        Reason                         `json:"economic_status"`
	FetchedAt             string                         `json:"fetched_at"`
	Currency              *string                        `json:"currency"`
	CurrencyNote          string                         `json:"currency_note"`
	ComparableDelta       *string                        `json:"comparable_delta"`
	PremiumIncluded       bool                           `json:"premium_included"`
	Current               *RecommendationOfferDTO        `json:"current"`
	Candidates            []RecommendationAlternativeDTO `json:"candidates"`
	NonGatingDisclosure   string                         `json:"non_gating_disclosure"`
	SponsorshipDisclosure string                         `json:"sponsorship_disclosure"`
}

RecommendationComparisonDTO is the recommendation-only response: one current offer and its vendor-linked candidates. It carries no plan totals, deltas, guarantees, source account or org ID.

func BuildRecommendationComparison 

func BuildRecommendationComparison(id, planID string, rec *RecommendationIdentity, c *insurance.Comparison, items []insurance.LineItem) (*RecommendationComparisonDTO, error)

BuildRecommendationComparison matches the stored recommendation against the vendor line items and renders only the matched row. An unmatched result carries no figures. It returns ErrUnrepresentable when a rendered number has no exact decimal form.

type RecommendationIdentity 

type RecommendationIdentity struct {
	Provider, SourceAccountID, Service, PlanType, OfferingID string
	Region, TopLevelRegion, InstanceFamily, Payment          string
	CloudAccountID                                           string
	NativeDurationSeconds                                    int64
	HourlyCommitment                                         *big.Rat
}

func ProjectRecommendation 

func ProjectRecommendation(r *config.RecommendationRecord) (*RecommendationIdentity, error)

ProjectRecommendation turns a stored recommendation into the identity the vendor line items are matched against.

func (*RecommendationIdentity) Equal 

func (r *RecommendationIdentity) Equal(o *RecommendationIdentity) bool

Equal reports whether both identities are non-nil and agree on every projected field.

type RecommendationMatch 

type RecommendationMatch struct {
	Status                                   MatchStatus
	LineItemID                               string
	Reason, AmountProvenance, EconomicStatus Reason
	Candidates                               []CandidateAssociation
}

func MatchRecommendation 

func MatchRecommendation(planID string, rec *RecommendationIdentity, rows []ComparisonIdentity, items []LineItemIdentity) (RecommendationMatch, error)

type RecommendationOfferDTO 

type RecommendationOfferDTO struct {
	OfferID                  string        `json:"offer_id"`
	Provider                 string        `json:"provider"`
	CommitmentType           string        `json:"commitment_type"`
	HourlySelectedCommitment *string       `json:"hourly_selected_commitment"`
	NativeDurationSeconds    *string       `json:"native_duration_seconds"`
	NativePlanType           *string       `json:"native_plan_type"`
	NativeInstanceFamily     *string       `json:"native_instance_family"`
	EffectiveContractTerm    *string       `json:"effective_contract_term"`
	PaymentOption            *string       `json:"payment_option"`
	LeaseAttached            bool          `json:"lease_attached"`
	Monthly                  FinancialsDTO `json:"monthly"`
	UpfrontCost              *string       `json:"upfront_one_time_cost"`
}

RecommendationOfferDTO names the vendor's units explicitly. The native_* fields come from the line item and stay null on candidates, which the vendor does not give a native identity.

type RowDTO 

type RowDTO struct {
	LineItemID string     `json:"line_item_id"`
	Current    OfferDTO   `json:"current"`
	Candidates []OfferDTO `json:"candidates"`
}

RowDTO is a line item's current offer plus its alternatives.

type SelectStatus 

type SelectStatus string

SelectStatus says how many line items share the recommendation's resource identity. 

const (
	SelectOne       SelectStatus = "selected"
	SelectNone      SelectStatus = "none"
	SelectAmbiguous SelectStatus = "ambiguous"
)

func SelectLineItem 

func SelectLineItem(rec *RecommendationIdentity, items []LineItemIdentity) (string, SelectStatus)

SelectLineItem returns the ID of the single line item that is the recommendation's resource, or an empty ID with SelectNone (no match, or an unsupported recommendation) or SelectAmbiguous.

type Settings 

type Settings struct {
	OrgID        string
	PlanID       string
	KeySecretRef string
}

Settings are the non-secret Archera settings. KeySecretRef is a reference to the secret (name, ARN or URI), not the key itself.

func SettingsFromEnv 

func SettingsFromEnv() Settings

SettingsFromEnv reads the settings from the process environment.

func (Settings) Missing 

func (s Settings) Missing() []string

Missing lists the names (never values) of absent settings, in a fixed order.

func (Settings) Status 

func (s Settings) Status() Status

Status returns the presence-only status for the settings.

type Status 

type Status struct {
	Missing    []string `json:"missing"`
	Configured bool     `json:"configured"`
}

Status reports whether the three settings are present. It resolves nothing and never carries a value.

type TotalsDTO 

type TotalsDTO struct {
	FinancialsDTO
	UpfrontCost *string `json:"upfront_one_time_cost"`
}

TotalsDTO is a plan-wide rollup.

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.