forecast

type Basis struct {
	// Samples is how many observations were used.
	Samples int `json:"samples"`
	// ObservedFor is how long the samples span.
	ObservedFor time.Duration `json:"observed_for"`
	// Coverage is the fraction of the cycle the samples span.
	Coverage float64 `json:"coverage"`
	// BytesPerDay is the observed average rate, which is the projection's slope.
	BytesPerDay float64 `json:"bytes_per_day"`
	// Uncertainty is the projection's relative error, from the spread of the per-interval rates.
	//
	// Estimated from the observed variance of the rate rather than asserted: a node with a steady
	// transfer has a small one and a node with a daily peak has a large one, and an operator deciding
	// whether to buy headroom needs to know which they are looking at. It is the relative standard
	// error of the mean rate times the projection's extrapolation factor, which is the honest
	// consequence of projecting further than you observed.
	Uncertainty float64 `json:"uncertainty"`
	// CycleDays is the cycle's length in days.
	CycleDays float64 `json:"cycle_days"`
}

type Forecast struct {
	// Method is how the projection was reached, or MethodInsufficient.
	Method Method `json:"method"`
	// Reason explains an insufficient forecast, in the terms the operator needs: what was missing.
	Reason string `json:"reason,omitempty"`

	// UsedBytes is the observed total at Now, which is reported even when no projection is made: an
	// operator asking "how much have I used" deserves an answer even when the cycle is too young to
	// project.
	UsedBytes int64 `json:"used_bytes"`
	// ProjectedBytes is the cycle's projected end total. Zero when Method is insufficient.
	ProjectedBytes int64 `json:"projected_bytes"`

	// LimitSet is false when the node has no plan limit, in which case there is nothing to project
	// against and no crossing date to report.
	LimitSet bool `json:"limit_set"`
	// ProjectedFraction is ProjectedBytes / LimitBytes. Zero when no limit is set.
	ProjectedFraction float64 `json:"projected_fraction"`
	// WouldExceed is whether the projection reaches the limit before the cycle ends.
	WouldExceed bool `json:"would_exceed"`

	// CrossesAt is when the limit would be reached, and CrossesInDays how far away that is. Both are
	// zero when no crossing can be computed within time.Duration and JSON's year 0..9999 range.
	CrossesAt     time.Time `json:"crosses_at,omitempty"`
	CrossesInDays float64   `json:"crosses_in_days,omitempty"`
	// CrossesInCycle is whether the crossing falls inside this cycle. A crossing after the cycle ends
	// is not a problem this cycle, and saying so is the difference between a warning and noise.
	CrossesInCycle bool `json:"crosses_in_cycle"`

	// Basis is the arithmetic behind the projection, stated so a reader can check it.
	Basis Basis `json:"basis"`

	// Warning is set when the projection crosses the threshold and a notification is warranted.
	Warning *Warning `json:"warning,omitempty"`
}

type Method string

type Request struct {
	// CycleStart and CycleEnd bound the billing cycle. The window is half-open, matching how the
	// ledger rotates: `[start, end)`.
	CycleStart time.Time
	CycleEnd   time.Time
	// Samples are the cycle's observations, in any order.
	Samples []Sample
	// LimitBytes is the plan's traffic allowance. Zero means no limit is set, and a node with no
	// limit is not forecast at all — see Forecast.LimitSet.
	LimitBytes int64
	// Threshold is the fraction of the limit at which a warning is worth raising, 0 < Threshold <= 1.
	// Zero means the default.
	Threshold float64
}

type Sample struct {
	// At is when the total was observed.
	At time.Time
	// Total is the cycle-to-date traffic in bytes at that instant.
	Total int64
}

type Warning struct {
	// Threshold is the fraction that was crossed.
	Threshold float64 `json:"threshold"`
	// ProjectedFraction is the projection's fraction of the limit.
	ProjectedFraction float64 `json:"projected_fraction"`
	// Message is a sentence for a human.
	Message string `json:"message"`
}