@drsamonline/canary 0.0.0-stage → 0.12.3

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.
Files changed (3) hide show
  1. package/package.json +23 -4
  2. package/src/index.js +156 -0
  3. package/README.md +0 -3
package/package.json CHANGED
@@ -1,6 +1,25 @@
1
1
  {
2
2
  "name": "@drsamonline/canary",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.12.3",
4
+ "description": "Canary rollout with SLO-tied automatic rollback (B9.2).",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "main": "./src/index.js",
8
+ "exports": {
9
+ ".": "./src/index.js",
10
+ "./src/*": "./src/*"
11
+ },
12
+ "files": [
13
+ "src"
14
+ ],
15
+ "repository": {
16
+ "type": "git",
17
+ "url": "git://github.com/drsamonline/sui.git",
18
+ "directory": "packages/canary"
19
+ },
20
+ "homepage": "https://github.com/drsamonline/sui#readme",
21
+ "publishConfig": {
22
+ "access": "public",
23
+ "registry": "https://registry.npmjs.org/"
24
+ }
25
+ }
package/src/index.js ADDED
@@ -0,0 +1,156 @@
1
+ /**
2
+ * @drsamonline/canary — canary rollout with SLO-tied rollback (B9.2).
3
+ *
4
+ * A canary is a percentage of traffic sent to a candidate instead of the baseline,
5
+ * watched against three numbers: success rate, p95 latency, and a minimum sample
6
+ * size before any judgement is allowed.
7
+ *
8
+ * Two rules that make the difference between a useful canary and a coin flip:
9
+ *
10
+ * 1. **No verdict on a handful of requests.** Until `minSamples` have been
11
+ * observed, the canary neither promotes nor rolls back.
12
+ * 2. **An outage is not a regression.** If the provider is resting, both arms
13
+ * fail, and rolling the candidate back would blame it for someone else's
14
+ * downtime. Those observations are counted separately and excluded.
15
+ */
16
+
17
+ export const STATES = ['running', 'promoted', 'rolled_back'];
18
+
19
+ const DEFAULT_SLO = {
20
+ minSuccessRate: 0.9,
21
+ maxP95Ms: 8000,
22
+ minSamples: 20,
23
+ };
24
+
25
+ /**
26
+ * @param {{
27
+ * id?: string, baseline: string, candidate: string, percent?: number,
28
+ * slo?: Partial<typeof DEFAULT_SLO>, now?: () => number, random?: () => number
29
+ * }} opts
30
+ */
31
+ export function createCanary(opts) {
32
+ if (!opts?.baseline || !opts?.candidate) {
33
+ throw new Error('A canary needs a baseline and a candidate.');
34
+ }
35
+ if (opts.baseline === opts.candidate) {
36
+ throw new Error('A canary cannot compare a combo with itself.');
37
+ }
38
+
39
+ const now = opts.now ?? Date.now;
40
+ const random = opts.random ?? Math.random;
41
+ const slo = { ...DEFAULT_SLO, ...(opts.slo ?? {}) };
42
+ const percent = Math.max(0, Math.min(100, Number(opts.percent ?? 10)));
43
+
44
+ /** @type {{ok: number, failed: number, latencies: number[], excluded: number}} */
45
+ const candidateStats = { ok: 0, failed: 0, latencies: [], excluded: 0 };
46
+ /** @type {Array<{at: number, event: string, detail: string}>} */
47
+ const events = [];
48
+
49
+ let state = 'running';
50
+
51
+ const stats = () => {
52
+ const samples = candidateStats.ok + candidateStats.failed;
53
+ const sorted = [...candidateStats.latencies].sort((a, b) => a - b);
54
+ const p95 = sorted.length ? sorted[Math.min(sorted.length - 1, Math.ceil(0.95 * sorted.length) - 1)] : 0;
55
+ return {
56
+ samples,
57
+ successRate: samples ? Math.round((candidateStats.ok / samples) * 1000) / 1000 : null,
58
+ p95Ms: p95,
59
+ excludedOutages: candidateStats.excluded,
60
+ };
61
+ };
62
+
63
+ const record = (event, detail) => events.push({ at: now(), event, detail });
64
+
65
+ return {
66
+ id: opts.id ?? `${opts.candidate}-canary`,
67
+ baseline: opts.baseline,
68
+ candidate: opts.candidate,
69
+ percent,
70
+ slo,
71
+
72
+ get state() {
73
+ return state;
74
+ },
75
+
76
+ /** Which arm should answer this request? */
77
+ pick() {
78
+ if (state !== 'running') return { arm: 'baseline', reason: `canary is ${state}` };
79
+ const candidate = random() * 100 < percent;
80
+ return {
81
+ arm: candidate ? 'candidate' : 'baseline',
82
+ combo: candidate ? opts.candidate : opts.baseline,
83
+ reason: candidate ? `${percent}% of traffic goes to the candidate` : 'baseline traffic',
84
+ };
85
+ },
86
+
87
+ /**
88
+ * Fold in one observation from the candidate arm.
89
+ * @param {{ok: boolean, latencyMs?: number, outage?: boolean}} observation
90
+ * @returns {{state: string, event: string|null, detail: string}}
91
+ */
92
+ observe(observation) {
93
+ if (state !== 'running') return { state, event: null, detail: 'canary is finished' };
94
+
95
+ // An outage is not evidence about the candidate: it is evidence about the
96
+ // provider, and it hits both arms equally.
97
+ if (observation.outage) {
98
+ candidateStats.excluded += 1;
99
+ return { state, event: null, detail: 'provider outage — observation excluded from the verdict' };
100
+ }
101
+
102
+ if (observation.ok) {
103
+ candidateStats.ok += 1;
104
+ if (Number.isFinite(observation.latencyMs)) candidateStats.latencies.push(Number(observation.latencyMs));
105
+ } else {
106
+ candidateStats.failed += 1;
107
+ }
108
+
109
+ const s = stats();
110
+ if (s.samples < slo.minSamples) {
111
+ return { state, event: null, detail: `${s.samples}/${slo.minSamples} samples — no verdict yet` };
112
+ }
113
+
114
+ if (s.successRate < slo.minSuccessRate) {
115
+ state = 'rolled_back';
116
+ const detail = `success rate ${Math.round(s.successRate * 100)}% fell below ${Math.round(slo.minSuccessRate * 100)}% over ${s.samples} samples`;
117
+ record('rolled_back', detail);
118
+ return { state, event: 'rolled_back', detail };
119
+ }
120
+
121
+ if (s.p95Ms > slo.maxP95Ms) {
122
+ state = 'rolled_back';
123
+ const detail = `p95 ${s.p95Ms}ms exceeded ${slo.maxP95Ms}ms over ${s.samples} samples`;
124
+ record('rolled_back', detail);
125
+ return { state, event: 'rolled_back', detail };
126
+ }
127
+
128
+ // Sample floor met and both SLOs held: the candidate has earned the traffic.
129
+ state = 'promoted';
130
+ const detail = `success ${Math.round(s.successRate * 100)}%, p95 ${s.p95Ms}ms over ${s.samples} samples`;
131
+ record('promoted', detail);
132
+ return { state, event: 'promoted', detail };
133
+ },
134
+
135
+ /** Roll back by hand — the operator always outranks the SLO. */
136
+ rollback(reason = 'rolled back by an operator') {
137
+ if (state !== 'running') return { state, event: null, detail: 'canary is finished' };
138
+ state = 'rolled_back';
139
+ record('rolled_back', reason);
140
+ return { state, event: 'rolled_back', detail: reason };
141
+ },
142
+
143
+ snapshot() {
144
+ return {
145
+ id: opts.id ?? `${opts.candidate}-canary`,
146
+ baseline: opts.baseline,
147
+ candidate: opts.candidate,
148
+ percent,
149
+ slo,
150
+ state,
151
+ stats: stats(),
152
+ events: [...events].slice(-20),
153
+ };
154
+ },
155
+ };
156
+ }
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.