budget_machines 0.4.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,158 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative 'budget_machines/version'
4
+
5
+ # Error-budget accounting and burn-rate alerting. Every value mirrors the Rust
6
+ # core's type of the same name, field for field.
7
+ module BudgetMachines
8
+ # Every value below validates through the core when built, by hand or by the
9
+ # gem alike: a non-Integer (or other wrong type) raises TypeError, a value
10
+ # the core's constructor rejects raises RangeError.
11
+
12
+ # Exact good and total event counts for one window: `Counts::new`, both in
13
+ # 0..2**64-1 with `good <= total`.
14
+ Counts = Data.define(:good, :total) do
15
+ def initialize(good:, total:)
16
+ good, total = BudgetMachines.__send__(:__counts, good, total)
17
+ super
18
+ end
19
+
20
+ def bad = total - good
21
+
22
+ # Component-wise sum, or nil when either would pass 2**64-1.
23
+ def checked_add(other) = BudgetMachines.__send__(:__checked_add, self, other)
24
+ end
25
+
26
+ # Service-level objective as an exact ratio: `good` of every `per` events,
27
+ # both in 0..2**32-1 with `good < per`.
28
+ Objective = Data.define(:good, :per) do
29
+ def initialize(good:, per:)
30
+ good, per = BudgetMachines.__send__(:__objective, good, per)
31
+ super
32
+ end
33
+
34
+ def tolerated = per - good
35
+
36
+ def allowance(total) = BudgetMachines.__send__(:__allowance, self, total)
37
+
38
+ def burn_milli_of(bad, total) = BudgetMachines.__send__(:__burn_milli_of, self, bad, total)
39
+
40
+ def burn_milli(counts) = BudgetMachines.__send__(:__burn_milli, self, counts)
41
+
42
+ def burns_at_least(counts, threshold_milli)
43
+ BudgetMachines.__send__(:__burns_at_least, self, counts, threshold_milli)
44
+ end
45
+ end
46
+
47
+ # Where a period stands against its allowance: :no_data when no events were
48
+ # observed this period, or one of the two values below.
49
+ module Standing
50
+ # Bad events are within the allowance; `remaining` (0..2**64-1) are still tolerated.
51
+ Within = Data.define(:remaining) do
52
+ def initialize(remaining:)
53
+ remaining = BudgetMachines.__send__(:__remaining, remaining)
54
+ super
55
+ end
56
+ end
57
+
58
+ # Bad events exceed the allowance by `overspent` (0..2**64-1).
59
+ Exhausted = Data.define(:overspent) do
60
+ def initialize(overspent:)
61
+ overspent = BudgetMachines.__send__(:__overspent, overspent)
62
+ super
63
+ end
64
+ end
65
+ end
66
+
67
+ # One compliance period's budget: `Account::new`, which refuses fields no
68
+ # ledger could produce (see the README).
69
+ Account = Data.define(:period, :counts, :base, :allowance, :standing, :consumed_milli) do
70
+ def initialize(period:, counts:, base:, allowance:, standing:, consumed_milli:)
71
+ period, counts, base, allowance, standing, consumed_milli =
72
+ BudgetMachines.__send__(:__account, period, counts, base, allowance, standing, consumed_milli)
73
+ super
74
+ end
75
+ end
76
+
77
+ # One window's reading: :no_data when the caller has none, or a
78
+ # Sample::Counts carrying exact counts.
79
+ module Sample
80
+ # Exact counts for the window.
81
+ Counts = Data.define(:counts) do
82
+ def initialize(counts:)
83
+ counts = BudgetMachines.__send__(:__sample, counts)
84
+ super
85
+ end
86
+ end
87
+ end
88
+
89
+ # The long and short window readings one rule is judged on. Each is a
90
+ # Sample: :no_data or a Sample::Counts.
91
+ Windows = Data.define(:long, :short) do
92
+ def initialize(long:, short:)
93
+ long, short = BudgetMachines.__send__(:__windows, long, short)
94
+ super
95
+ end
96
+ end
97
+
98
+ # A burn-rate rule: fire at `fire_milli`, clear below `clear_milli`, with
99
+ # `0 < clear_milli <= fire_milli` (both 0..2**32-1) and `severity` in 0..255.
100
+ Rule = Data.define(:fire_milli, :clear_milli, :severity) do
101
+ def initialize(fire_milli:, clear_milli:, severity:)
102
+ fire_milli, clear_milli, severity = BudgetMachines.__send__(:__rule, fire_milli, clear_milli, severity)
103
+ super
104
+ end
105
+ end
106
+
107
+ # One rule's outcome. `state` is :no_data, :quiet or :firing; `change` is
108
+ # :none, :raised or :cleared. `since` is the instant the rule entered
109
+ # `state`, in Integer nanoseconds as passed to `Monitor#evaluate`, or nil if
110
+ # it never left its start. `Decision::new` refuses fields no evaluation could
111
+ # produce.
112
+ Decision = Data.define(:state, :change, :long_milli, :short_milli, :since) do
113
+ def initialize(state:, change:, long_milli:, short_milli:, since:)
114
+ state, change, long_milli, short_milli, since =
115
+ BudgetMachines.__send__(:__decision, state, change, long_milli, short_milli, since)
116
+ super
117
+ end
118
+
119
+ # Both windows had data, so both burn rates are known; false when the
120
+ # no-data policy decided `state`.
121
+ def measured? = !long_milli.nil? && !short_milli.nil?
122
+ end
123
+
124
+ # Every rule's decision for one evaluation, in rule order (a frozen Array of
125
+ # at most CAPACITY), and the index of the firing rule with the highest
126
+ # severity (nil when nothing fires). `Verdict::new` refuses a `worst` that
127
+ # does not name a firing decision, or nil while one fires.
128
+ Verdict = Data.define(:decisions, :worst) do
129
+ def initialize(decisions:, worst:)
130
+ decisions, worst = BudgetMachines.__send__(:__verdict, decisions, worst)
131
+ super
132
+ end
133
+ end
134
+
135
+ # Sealed: no bare allocation or subclass can skip the validation above.
136
+ # Sealing stops accidents, not reflection (a subclass constant is bound
137
+ # before `inherited` raises, `Marshal.load` skips `initialize`), so the
138
+ # binding also checks every value it reads for its exact class and rebuilds
139
+ # it through the core.
140
+ [
141
+ Counts, Objective, Standing::Within, Standing::Exhausted, Account, Sample::Counts, Windows, Rule,
142
+ Decision, Verdict
143
+ ].each do |value|
144
+ value.singleton_class.undef_method(:allocate)
145
+ value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
146
+ end
147
+
148
+ # Native is required: no algorithm fallback. It resolves the classes above
149
+ # once, so they are defined first.
150
+ require 'budget_machines_native/budget_machines_native'
151
+
152
+ HOOKS = %i[
153
+ __allowance __burn_milli_of __burn_milli __burns_at_least __counts __checked_add __objective
154
+ __rule __remaining __overspent __sample __windows __account __decision __verdict
155
+ ].freeze
156
+ private_class_method(*HOOKS)
157
+ private_constant :HOOKS
158
+ end
@@ -0,0 +1,183 @@
1
+ module BudgetMachines
2
+ VERSION: String
3
+ CAPACITY: Integer
4
+ MILLI: Integer
5
+
6
+ type state = :no_data | :quiet | :firing
7
+ type change = :none | :raised | :cleared
8
+ type on_no_data = :hold | :reset | :fire
9
+ # Every symbol that means "this call was not honoured and changed nothing".
10
+ # Each method below lists exactly the ones it can answer.
11
+ type refusal = :stale_period | :overflow | :below_observed | :full | :shape | :time_regression
12
+ # A window reading: :no_data when the caller has none, or exact counts.
13
+ type sample = :no_data | Sample::Counts
14
+
15
+ # Every Data value validates through the core when built, by hand or by the
16
+ # gem: a wrong type raises TypeError, a value the core rejects RangeError.
17
+
18
+ # `good <= total`, both in 0..2**64-1; anything else raises TypeError or RangeError.
19
+ class Counts < Data
20
+ attr_reader good: Integer
21
+ attr_reader total: Integer
22
+ def self.new: (Integer good, Integer total) -> Counts
23
+ | (good: Integer, total: Integer) -> Counts
24
+ def bad: () -> Integer
25
+ # nil when a sum would pass 2**64-1; TypeError unless `other` is a Counts.
26
+ def checked_add: (Counts other) -> Counts?
27
+ end
28
+
29
+ # `good < per`, both in 0..2**32-1; anything else raises TypeError or RangeError.
30
+ class Objective < Data
31
+ attr_reader good: Integer
32
+ attr_reader per: Integer
33
+ def self.new: (Integer good, Integer per) -> Objective
34
+ | (good: Integer, per: Integer) -> Objective
35
+ def tolerated: () -> Integer
36
+ def allowance: (Integer total) -> Integer
37
+ def burn_milli_of: (Integer bad, Integer total) -> Integer?
38
+ def burn_milli: (Counts counts) -> Integer?
39
+ def burns_at_least: (Counts counts, Integer threshold_milli) -> bool
40
+ end
41
+
42
+ module Sample
43
+ class Counts < Data
44
+ attr_reader counts: BudgetMachines::Counts
45
+ def self.new: (BudgetMachines::Counts counts) -> Counts
46
+ | (counts: BudgetMachines::Counts) -> Counts
47
+ end
48
+ end
49
+
50
+ module Standing
51
+ # 0..2**64-1, like Exhausted's `overspent`.
52
+ class Within < Data
53
+ attr_reader remaining: Integer
54
+ def self.new: (Integer remaining) -> Within
55
+ | (remaining: Integer) -> Within
56
+ end
57
+
58
+ class Exhausted < Data
59
+ attr_reader overspent: Integer
60
+ def self.new: (Integer overspent) -> Exhausted
61
+ | (overspent: Integer) -> Exhausted
62
+ end
63
+ end
64
+
65
+ type standing = :no_data | Standing::Within | Standing::Exhausted
66
+
67
+ # `Account::new`: RangeError for fields no ledger could produce (base below
68
+ # the observed total, allowance above the base, a standing the counts and
69
+ # allowance do not give, a consumed_milli inconsistent with them).
70
+ class Account < Data
71
+ attr_reader period: Integer
72
+ attr_reader counts: Counts
73
+ attr_reader base: Integer
74
+ attr_reader allowance: Integer
75
+ attr_reader standing: standing
76
+ attr_reader consumed_milli: Integer?
77
+ def self.new: (Integer period, Counts counts, Integer base, Integer allowance, standing standing,
78
+ Integer? consumed_milli) -> Account
79
+ | (period: Integer, counts: Counts, base: Integer, allowance: Integer, standing: standing,
80
+ consumed_milli: Integer?) -> Account
81
+ end
82
+
83
+ # A Symbol other than :no_data raises RangeError; any other type TypeError.
84
+ class Windows < Data
85
+ attr_reader long: sample
86
+ attr_reader short: sample
87
+ def self.new: (sample long, sample short) -> Windows
88
+ | (long: sample, short: sample) -> Windows
89
+ end
90
+
91
+ # `0 < clear_milli <= fire_milli`, both in 0..2**32-1; `severity` in 0..255.
92
+ class Rule < Data
93
+ attr_reader fire_milli: Integer
94
+ attr_reader clear_milli: Integer
95
+ attr_reader severity: Integer
96
+ def self.new: (Integer fire_milli, Integer clear_milli, Integer severity) -> Rule
97
+ | (fire_milli: Integer, clear_milli: Integer, severity: Integer) -> Rule
98
+ end
99
+
100
+ # `Decision::new`: RangeError for an edge into the wrong state or without its
101
+ # instant, both rates (a measurement) with state :no_data, or an unknown
102
+ # state/change Symbol.
103
+ class Decision < Data
104
+ attr_reader state: state
105
+ attr_reader change: change
106
+ attr_reader long_milli: Integer?
107
+ attr_reader short_milli: Integer?
108
+ # Instant the rule entered `state`, Integer nanoseconds; nil if it never changed.
109
+ attr_reader since: Integer?
110
+ def self.new: (state state, change change, Integer? long_milli, Integer? short_milli,
111
+ Integer? since) -> Decision
112
+ | (state: state, change: change, long_milli: Integer?, short_milli: Integer?,
113
+ since: Integer?) -> Decision
114
+ # Both burn rates known; false when the no-data policy decided `state`.
115
+ def measured?: () -> bool
116
+ end
117
+
118
+ # `Verdict::new`: RangeError for more than CAPACITY decisions, a `worst`
119
+ # that is not a firing decision's index, or nil while one fires.
120
+ class Verdict < Data
121
+ # Frozen.
122
+ attr_reader decisions: Array[Decision]
123
+ attr_reader worst: Integer?
124
+ def self.new: (Array[Decision] decisions, Integer? worst) -> Verdict
125
+ | (decisions: Array[Decision], worst: Integer?) -> Verdict
126
+ end
127
+
128
+ class Ledger
129
+ def self.new: (Objective objective, Integer period) -> Ledger
130
+ def objective: () -> Objective
131
+ def period: () -> Integer
132
+ def counts: () -> Counts
133
+ # Honoured: :ok. Refused: :stale_period, :overflow.
134
+ def record: (Integer period, Counts counts) -> (:ok | :stale_period | :overflow)
135
+ # Honoured: :ok. Refused: :stale_period.
136
+ def replace: (Integer period, Counts counts) -> (:ok | :stale_period)
137
+ # Honoured: the closed period's Account. Refused: :stale_period.
138
+ def roll: (Integer period) -> (Account | :stale_period)
139
+ def account: () -> Account
140
+ # A pure query. Refused: :below_observed.
141
+ def account_against: (Integer planned_total) -> (Account | :below_observed)
142
+ end
143
+
144
+ class Monitor
145
+ def self.new: (Objective objective, on_no_data policy, Integer min_total) -> Monitor
146
+ # Honoured: the rule's index. Refused: :full.
147
+ def add_rule: (Rule rule) -> (Integer | :full)
148
+ def size: () -> Integer
149
+ def empty?: () -> bool
150
+ def capacity: () -> Integer
151
+ def objective: () -> Objective
152
+ def rule: (Integer index) -> Rule?
153
+ def state: (Integer index) -> state?
154
+ # Instant of the latest accepted evaluation, Integer nanoseconds.
155
+ def last: () -> Integer?
156
+ def worst: () -> Integer?
157
+ # `now` is Integer nanoseconds of monotonic time. Honoured: a Verdict,
158
+ # and `now` is recorded (every verdict is the rules' state as of `now`).
159
+ # Refused: :time_regression, :shape, recording nothing.
160
+ def evaluate: (Integer now, Array[Windows] windows) -> (Verdict | :time_regression | :shape)
161
+ end
162
+
163
+ # Private native hooks: each Data value's `initialize` validates its fields
164
+ # through one and stores what it answers; the Objective and Counts query
165
+ # methods delegate to the rest.
166
+ private def self.__counts: (Integer good, Integer total) -> [Integer, Integer]
167
+ private def self.__checked_add: (Counts left, Counts right) -> Counts?
168
+ private def self.__objective: (Integer good, Integer per) -> [Integer, Integer]
169
+ private def self.__allowance: (Objective objective, Integer total) -> Integer
170
+ private def self.__burn_milli_of: (Objective objective, Integer bad, Integer total) -> Integer?
171
+ private def self.__burn_milli: (Objective objective, Counts counts) -> Integer?
172
+ private def self.__burns_at_least: (Objective objective, Counts counts, Integer threshold_milli) -> bool
173
+ private def self.__remaining: (Integer remaining) -> Integer
174
+ private def self.__overspent: (Integer overspent) -> Integer
175
+ private def self.__account: (Integer period, Counts counts, Integer base, Integer allowance, standing standing,
176
+ Integer? consumed_milli) -> [Integer, Counts, Integer, Integer, standing, Integer?]
177
+ private def self.__sample: (Counts counts) -> Counts
178
+ private def self.__windows: (sample long, sample short) -> [sample, sample]
179
+ private def self.__rule: (Integer fire_milli, Integer clear_milli, Integer severity) -> [Integer, Integer, Integer]
180
+ private def self.__decision: (state state, change change, Integer? long_milli, Integer? short_milli,
181
+ Integer? since) -> [state, change, Integer?, Integer?, Integer?]
182
+ private def self.__verdict: (Array[Decision] decisions, Integer? worst) -> [Array[Decision], Integer?]
183
+ end
metadata ADDED
@@ -0,0 +1,89 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: budget_machines
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.4.4
5
+ platform: ruby
6
+ authors:
7
+ - Abdelkader Boudih
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 1980-01-02 00:00:00.000000000 Z
11
+ dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: rb_sys
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - "~>"
17
+ - !ruby/object:Gem::Version
18
+ version: '0.9'
19
+ - - ">="
20
+ - !ruby/object:Gem::Version
21
+ version: 0.9.130
22
+ type: :runtime
23
+ prerelease: false
24
+ version_requirements: !ruby/object:Gem::Requirement
25
+ requirements:
26
+ - - "~>"
27
+ - !ruby/object:Gem::Version
28
+ version: '0.9'
29
+ - - ">="
30
+ - !ruby/object:Gem::Version
31
+ version: 0.9.130
32
+ description: Exact integer error-budget accounting and multi-window burn-rate decisions
33
+ from supplied counts; not a metrics store or alert pipeline.
34
+ email:
35
+ - oss@seuros.com
36
+ executables: []
37
+ extensions:
38
+ - ext/budget_machines_native/extconf.rb
39
+ extra_rdoc_files: []
40
+ files:
41
+ - CHANGELOG.md
42
+ - Cargo.lock
43
+ - Cargo.toml
44
+ - LICENSE.txt
45
+ - README.md
46
+ - ext/budget_machines_native/core/CHANGELOG.md
47
+ - ext/budget_machines_native/core/Cargo.toml
48
+ - ext/budget_machines_native/core/README.md
49
+ - ext/budget_machines_native/core/src/ledger.rs
50
+ - ext/budget_machines_native/core/src/lib.rs
51
+ - ext/budget_machines_native/core/src/monitor.rs
52
+ - ext/budget_machines_native/extconf.rb
53
+ - ext/budget_machines_native/ffi/Cargo.toml
54
+ - ext/budget_machines_native/ffi/extconf.rb
55
+ - ext/budget_machines_native/ffi/src/classes.rs
56
+ - ext/budget_machines_native/ffi/src/init.rs
57
+ - ext/budget_machines_native/ffi/src/ledger.rs
58
+ - ext/budget_machines_native/ffi/src/lib.rs
59
+ - ext/budget_machines_native/ffi/src/monitor.rs
60
+ - ext/budget_machines_native/ffi/src/values.rs
61
+ - lib/budget_machines.rb
62
+ - lib/budget_machines/version.rb
63
+ - sig/budget_machines.rbs
64
+ homepage: https://github.com/seuros/budget_machines
65
+ licenses:
66
+ - MIT
67
+ metadata:
68
+ source_code_uri: https://github.com/seuros/budget_machines
69
+ rubygems_mfa_required: 'true'
70
+ cargo_crate_name: budget_machines_native
71
+ cargo_manifest_path: ext/budget_machines_native/ffi/Cargo.toml
72
+ rdoc_options: []
73
+ require_paths:
74
+ - lib
75
+ required_ruby_version: !ruby/object:Gem::Requirement
76
+ requirements:
77
+ - - ">="
78
+ - !ruby/object:Gem::Version
79
+ version: 4.0.0
80
+ required_rubygems_version: !ruby/object:Gem::Requirement
81
+ requirements:
82
+ - - ">="
83
+ - !ruby/object:Gem::Version
84
+ version: '0'
85
+ requirements: []
86
+ rubygems_version: 4.0.20
87
+ specification_version: 4
88
+ summary: SLO error-budget and burn-rate alert policies with a native Rust core
89
+ test_files: []