Documentation
¶
Overview ¶
Package scheduler is the hourly tick of the engine: it walks the billing months that have ended, moves each of them from open into grace, and has the month whose grace window has passed metered and, where the deployment asks for it, closed. It is the whole of what tally-engine tick does.
The metering half is injected as an Executor rather than called here. A run needs the reporting database, the pricing model and the counter sources, all of which the CLI already assembles for tally-engine run. Finalization touches the engine database alone, so runs.Finalize is called directly.
The horizon of the walk comes from the stored state (the author's decision of 2026-08-24): it starts at the earliest billing_periods row and ends at the last month that has ended. It is neither a configured number of months back nor a question put to the reporting database. A CronJob that was down for months therefore catches up on its own, as long as one period row exists, and a month older than every stored period enters the walk by being run once with tally-engine run --period, which writes its row. Its length is capped at maxTickMonths all the same: nothing bounds how old the earliest row is, and a walk of thousands of months is a tick that never ends.
The two steps of the state machine are made against the status a month is stored with, so a month that has just ended moves into grace on one tick and is metered on a later one. At an hourly tick that costs an hour.
The normative specification is roadmap/03-phase-3-metering-rating.md, WP 3.8, its scheduler block.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Executor ¶
Executor meters one billing period and returns the run it recorded. It is what the CLI wires runs.Execute into: everything a run needs beside the engine database is the caller's, and the tick decides only which months it is called for.
type Month ¶
Month is one billing period of the walk: the half-open interval [From, To) of a UTC calendar month, the way internal/engine/period derives it.
type MonthReport ¶
type MonthReport struct {
// Month is the billing month, as YYYY-MM.
Month string
// Transition is the period status change this tick wrote, empty where it
// wrote none. The only one it writes is "open -> grace".
Transition string
// RunID is the run this tick metered or closed the month over, the zero id
// where it did neither.
RunID uuid.UUID
// Finalized says the tick closed the month over a completed run.
Finalized bool
// RetryAfter is when a month whose last runs failed is metered again, and
// Failures is how many of them failed in a row. Both are zero where this
// tick did not hold the month back.
RetryAfter time.Time
Failures int
// SkippedBefore is how many billing months older than this one the walk left
// out, and is set on the oldest month of the walk alone. The walk is capped
// at maxTickMonths, so a period row further back than that -- a database
// restored from an old backup, an installation re-enabled after a long
// shutdown -- names months no tick ever reaches. Reporting the count is what
// keeps them from being dropped without a trace; they are billed with
// tally-engine run --period.
SkippedBefore int
// Warning is what went wrong beside the month's step rather than in it: the
// month got where it was going and this names what did not. The one the tick
// reports is a run that could not give its period lock back, which leaves the
// run and the records it committed standing.
Warning error
// Err is what went wrong with this month. The fields above still carry what
// the month got to before it failed.
Err error
}
MonthReport is what one tick did with one month.
type Options ¶
type Options struct {
// GraceHours is how long a month that has ended waits before it is metered,
// so that events which arrive late are still billed into it.
GraceHours int
// AutoFinalize closes a month over its completed run without an operator.
// It is off where the numbers are reviewed before the month becomes
// immutable.
AutoFinalize bool
// Execute meters one month. It is called at most once per month per tick.
Execute Executor
}
Options is how one tick treats the months it walks.
type Report ¶
type Report []MonthReport
Report is what one tick did: one entry per month it walked, in the order it walked them. A month where nothing was due carries an entry too, so the report says which months were looked at rather than only which ones moved.
func Tick ¶
Tick walks the billing months that have ended and moves each of them one step, and is the whole of what tally-engine tick does. now is the clock, an argument rather than a reading, which is what makes the state machine testable; the CLI passes time.Now().UTC().
A month whose step fails is reported in its own MonthReport.Err and the walk goes on with the months after it: one month nothing prices must not keep the rest from being billed. The error Tick returns joins those failures, so the exit status of the CronJob still reports them. A canceled context ends the walk where it is and comes back as context.Canceled.
Source Files