pubdeploy 0.8.0__py3-none-any.whl

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 (45) hide show
  1. pubdeploy/__init__.py +532 -0
  2. pubdeploy/channels.py +188 -0
  3. pubdeploy/cli.py +120 -0
  4. pubdeploy/config.py +140 -0
  5. pubdeploy/contract.py +87 -0
  6. pubdeploy/github.py +61 -0
  7. pubdeploy/hooks.py +82 -0
  8. pubdeploy/implied.py +179 -0
  9. pubdeploy/journal.json +207 -0
  10. pubdeploy/k8s.py +472 -0
  11. pubdeploy/machine.py +363 -0
  12. pubdeploy/model.py +229 -0
  13. pubdeploy/names.py +25 -0
  14. pubdeploy/order.py +101 -0
  15. pubdeploy/providers.py +75 -0
  16. pubdeploy/registry.py +96 -0
  17. pubdeploy/release-commit +1 -0
  18. pubdeploy/schema.json +127 -0
  19. pubdeploy/schema.py +238 -0
  20. pubdeploy/store.py +127 -0
  21. pubdeploy/testing/__init__.py +94 -0
  22. pubdeploy/testing/fixtures/deploy-app/.github/workflows/deploy.yml +11 -0
  23. pubdeploy/testing/fixtures/deploy-app/k8s/admin/network-policy.yaml +11 -0
  24. pubdeploy/testing/fixtures/deploy-app/k8s/app.yaml +63 -0
  25. pubdeploy/testing/fixtures/deploy-app/k8s/kustomization.yaml +6 -0
  26. pubdeploy/testing/fixtures/deploy-app/pubrules.json +27 -0
  27. pubdeploy/testing/fixtures/deploy-app/rendered.yaml +86 -0
  28. pubdeploy/testing/fixtures/deploy-app/zones.json +8 -0
  29. pubdeploy/testing/plugin.py +26 -0
  30. pubdeploy/testing/steps.py +1124 -0
  31. pubdeploy/testing/world.py +569 -0
  32. pubdeploy/types/__init__.py +181 -0
  33. pubdeploy/types/auth.py +199 -0
  34. pubdeploy/types/github.py +110 -0
  35. pubdeploy/types/k8s.py +609 -0
  36. pubdeploy/types/net.py +237 -0
  37. pubdeploy/types/rollout.py +186 -0
  38. pubdeploy/units.py +177 -0
  39. pubdeploy/walk.py +325 -0
  40. pubdeploy-0.8.0.dist-info/METADATA +520 -0
  41. pubdeploy-0.8.0.dist-info/RECORD +45 -0
  42. pubdeploy-0.8.0.dist-info/WHEEL +5 -0
  43. pubdeploy-0.8.0.dist-info/entry_points.txt +11 -0
  44. pubdeploy-0.8.0.dist-info/licenses/LICENSE +202 -0
  45. pubdeploy-0.8.0.dist-info/top_level.txt +1 -0
pubdeploy/walk.py ADDED
@@ -0,0 +1,325 @@
1
+ """Check mode: run every need's check, in order, and keep what each found.
2
+
3
+ Each check runs in a thread the walk waits for up to the type's budget; one
4
+ that takes longer is left behind and its need is `unknown`, "took longer than
5
+ N s". A check that raises is `unknown` too, named by the exception's type
6
+ alone, since its message might hold a value. A need is still checked when
7
+ something it waits for is not ready, since checks are read-only and cheap:
8
+ its own result stands, unless it is `missing` while a need it waits for is
9
+ not ready, and then it is `blocked`, "waits for" that need.
10
+
11
+ Fulfil mode (`walk --fulfil`) runs every check first, then `planned` lists
12
+ the needs it will act on: each missing, drifted or blocked one whose grade is
13
+ auto, whose finding its fulfil can make, whose context has what the fulfil
14
+ needs, and whose dependencies are ready or are acted on before it. Once the
15
+ plan is confirmed, `fulfil` visits them in order: a need whose dependency was
16
+ fulfilled is checked again first, then, while every dependency is ready, it
17
+ is fulfilled within its fulfil_budget and checked again, and that check is
18
+ its result, `fulfilled`. A fulfil that fails leaves the need as it was, with
19
+ the failure as a detail, and the walk goes on with what does not wait for it.
20
+ A propose or human need is never acted on: a propose type's fulfil, which
21
+ changes nothing, gives its proposal as the fix.
22
+ """
23
+
24
+ from __future__ import annotations
25
+
26
+ import threading
27
+ import time
28
+ from collections.abc import Mapping
29
+
30
+ from .model import FULFIL_BUDGET, STATES, Context, Journal, Need, NeedType, Result, no_server
31
+ from .order import edges, topological
32
+
33
+ ACTING = ("missing", "drift", "blocked")
34
+ SLICE = 0.2 # seconds a check or a fulfil is waited for at a time
35
+ # Set by SIGUSR1, a live run's Stop for a need that shortens (shorten()): what is still
36
+ # running ends now, as unknown, and the walk prints and journals what it has.
37
+ SHORTENED = threading.Event()
38
+
39
+
40
+ def shorten(_signum: int = 0, _frame: object = None) -> None:
41
+ SHORTENED.set()
42
+ # What a fulfil may need of its context, and the fix when the context lacks it.
43
+ LACKS = {"server": "needs the admin channel (--server HOST), the one that runs commands on the server",
44
+ "kubectl-write": "needs the admin channel or the plane",
45
+ "write-token": "needs a Bitwarden write token: run the walk at a terminal"}
46
+
47
+
48
+ def stamp(ctx: Context) -> str:
49
+ return ctx.now().strftime("%Y-%m-%dT%H:%M:%SZ")
50
+
51
+
52
+ def timed(kind: NeedType, need: Need, ctx: Context, step: str = "check") -> Result:
53
+ """One check, or one fulfil, within its budget."""
54
+ box: list[Result | BaseException] = []
55
+ budget = kind.budget if step == "check" else fulfil_budget(kind)
56
+ if ctx.budget_cap is not None:
57
+ budget = max(0.0, min(budget, ctx.budget_cap))
58
+ method = kind.check if step == "check" else kind.fulfil
59
+
60
+ def run() -> None:
61
+ try:
62
+ box.append(method(need, ctx))
63
+ except BaseException as e: # noqa: BLE001 - any failure is the need's, not the walk's
64
+ box.append(e)
65
+
66
+ started = time.monotonic()
67
+ if SHORTENED.is_set(): # a Stop already shortened the walk: the step never starts
68
+ return Result("unknown", f"the {step} was not started: a Stop shortened the walk",
69
+ fix="walk the need again when it may take its time", seconds=0.0)
70
+ worker = threading.Thread(target=run, name=f"{step} {need.id}", daemon=True)
71
+ worker.start()
72
+ # Waited for in slices, so a Stop that shortens (SIGUSR1: SHORTENED) ends it at once.
73
+ while worker.is_alive() and not SHORTENED.is_set() and time.monotonic() - started < budget:
74
+ worker.join(min(SLICE, max(0.0, budget - (time.monotonic() - started))))
75
+ seconds = time.monotonic() - started
76
+ if not box and SHORTENED.is_set():
77
+ result = Result("unknown", f"the {step} was ended after {seconds:.1f} s: a Stop shortened it",
78
+ fix="walk the need again when it may take its time")
79
+ elif not box:
80
+ result = Result("unknown", f"the {step} took longer than {budget:g} s, and was left",
81
+ fix=f"run it again; if it is always slow, see what {need.type} waits on")
82
+ elif isinstance(box[0], BaseException):
83
+ result = Result("unknown", f"the {step} failed ({type(box[0]).__name__})",
84
+ fix=f"this is a fault in {need.type}'s {step}: report it")
85
+ elif (result := foreign(box[0])) is None:
86
+ result = Result("unknown", f"the {step} returned no result ({type(box[0]).__name__})",
87
+ fix=f"this is a fault in {need.type}'s {step}: report it")
88
+ else:
89
+ if seconds > budget:
90
+ result.details.append(f"took {seconds:.1f} s, over its budget of {budget:g} s")
91
+ result.seconds = seconds
92
+ return result
93
+
94
+
95
+ def foreign(given: object) -> Result | None:
96
+ """A Result, from pubrules's or from any object with its state and summary,
97
+ as a provider that imports nothing of pubrules's returns."""
98
+ if isinstance(given, Result):
99
+ return given
100
+ state, summary = getattr(given, "state", None), getattr(given, "summary", None)
101
+ if state not in STATES or not isinstance(summary, str):
102
+ return None
103
+ fix, details = getattr(given, "fix", ""), getattr(given, "details", [])
104
+ return Result(state, summary, fix if isinstance(fix, str) else "",
105
+ [str(d) for d in details] if isinstance(details, list | tuple) else [],
106
+ fixable=getattr(given, "fixable", True) is not False, step=str(getattr(given, "step", "") or ""))
107
+
108
+
109
+ def fulfil_budget(kind: NeedType) -> float:
110
+ return float(getattr(kind, "fulfil_budget", FULFIL_BUDGET))
111
+
112
+
113
+ def grade_of(kind: NeedType, need: Need) -> str:
114
+ """The need's own grade: its type's, unless the type grades by params."""
115
+ by = getattr(kind, "grade_for", None)
116
+ return by(need) if callable(by) else kind.grade
117
+
118
+
119
+ def lacking(kind: NeedType, need: Need, ctx: Context, token_coming: bool = False) -> str | None:
120
+ """What the need's fulfil needs that the context lacks, as the fix."""
121
+ required = getattr(kind, "requires", lambda _need: ())(need)
122
+ for what in required:
123
+ if what == "server" and ctx.server is no_server:
124
+ return LACKS[what]
125
+ if what == "kubectl-write" and ctx.channel == "deploy":
126
+ return LACKS[what]
127
+ if what == "write-token" and ctx.bitwarden_writer is None and not token_coming:
128
+ return LACKS[what]
129
+ return None
130
+
131
+
132
+ def action(kind: NeedType, need: Need, ctx: Context) -> str:
133
+ said = getattr(kind, "action", None)
134
+ return f"{need.id}: {said(need, ctx) if callable(said) else 'fulfil it'}"
135
+
136
+
137
+ def checked(kind: NeedType, need: Need, ctx: Context, waits: set[str], order: list[str]) -> Result:
138
+ """A check, stamped, and blocked when missing while a need it waits for is not ready."""
139
+ if ctx.offline and not kind.offline:
140
+ result = Result("unknown", "not checked offline")
141
+ else:
142
+ result = timed(kind, need, ctx)
143
+ result.checked_at = stamp(ctx)
144
+ late = [d for d in order if d in waits and ctx.results.get(d, Result("ready", "")).state != "ready"]
145
+ if result.state == "missing" and late:
146
+ result = Result("blocked", f"waits for {late[0]}: {result.summary}", result.fix, result.details,
147
+ result.checked_at, result.seconds, fixable=result.fixable, step=result.step)
148
+ return result
149
+
150
+
151
+ def walk(needs: Mapping[str, Need], types: Mapping[str, NeedType], ctx: Context, service: dict[str, str],
152
+ by: str = "", origin: str = "laptop") -> Journal:
153
+ """Check every need, in order; under ctx.offline only the offline types."""
154
+ order = topological(needs, types)
155
+ waits = edges(needs, types)
156
+ ctx.types = dict(types)
157
+ ctx.needs = dict(needs)
158
+ ctx.results = {}
159
+ started = time.monotonic()
160
+ journal = Journal(service=service, walk={"mode": "check", "offline": ctx.offline, "started_at": stamp(ctx),
161
+ "seconds": 0.0, "by": by, "from": origin})
162
+ for i in order:
163
+ need, kind = needs[i], types[needs[i].type]
164
+ journal.grades[i] = grade_of(kind, need)
165
+ result = checked(kind, need, ctx, waits[i], order)
166
+ ctx.results[i] = result
167
+ journal.entries.append((need, result))
168
+ journal.walk["seconds"] = round(time.monotonic() - started, 3)
169
+ return journal
170
+
171
+
172
+ def refilled(kind: NeedType, need: Need, ctx: Context, among: set[str]) -> list[str]:
173
+ """The needs among `among` whose value this need is made from: a Secret
174
+ ready by its keys still holds the value a filler had before this walk
175
+ made a new one, so it is made again from the new one."""
176
+ made_from = getattr(kind, "made_from", None)
177
+ return [i for i in made_from(need, ctx) if i in among] if callable(made_from) else []
178
+
179
+
180
+ def planned(journal: Journal, types: Mapping[str, NeedType], ctx: Context,
181
+ token_coming: bool = False) -> list[tuple[str, str]]:
182
+ """The needs fulfil acts on, in walk order, each with its plan's line.
183
+ `token_coming`: a write token will be asked for, so the needs that want
184
+ one are planned."""
185
+ waits = edges(ctx.needs, types)
186
+ expected = {n.id for n, r in journal.entries if r.state == "ready"}
187
+ out = []
188
+ for need, result in journal.entries:
189
+ kind = types[need.type]
190
+ changed = refilled(kind, need, ctx, {i for i, _ in out}) if result.state == "ready" else []
191
+ if (changed and grade_of(kind, need) == "auto" and result.fixable
192
+ and not lacking(kind, need, ctx, token_coming)):
193
+ out.append((need.id, f"{action(kind, need, ctx)}, again: {changed[0]} changes"))
194
+ continue
195
+ if (result.state not in ACTING or not result.fixable or grade_of(kind, need) != "auto"
196
+ or lacking(kind, need, ctx, token_coming) or not waits[need.id] <= expected):
197
+ continue
198
+ expected.add(need.id)
199
+ out.append((need.id, action(kind, need, ctx)))
200
+ return out
201
+
202
+
203
+ def wants_token(plan: list[tuple[str, str]], types: Mapping[str, NeedType], ctx: Context) -> bool:
204
+ return any("write-token" in getattr(types[ctx.needs[i].type], "requires", lambda _n: ())(ctx.needs[i])
205
+ for i, _ in plan)
206
+
207
+
208
+ def unable(journal: Journal, types: Mapping[str, NeedType], ctx: Context, declined: bool = False) -> None:
209
+ """Each auto need not ready whose fulfil needs what the context lacks
210
+ becomes unknown, saying what it needs, and what its check found. When
211
+ the plan was declined, no token was asked for: a need wanting one keeps
212
+ what its check found."""
213
+ for k, (need, result) in enumerate(journal.entries):
214
+ kind = types[need.type]
215
+ if result.state not in ACTING or not result.fixable or grade_of(kind, need) != "auto":
216
+ continue
217
+ why = lacking(kind, need, ctx)
218
+ if why == LACKS["write-token"] and declined:
219
+ continue
220
+ if why is not None:
221
+ new = Result("unknown", f"not fulfilled: {why.split(':')[0]}", why,
222
+ [f"found {result.state}: {result.summary}", *result.details], result.checked_at,
223
+ result.seconds)
224
+ journal.entries[k] = (need, new)
225
+ ctx.results[need.id] = new
226
+
227
+
228
+ def fulfil(journal: Journal, types: Mapping[str, NeedType], ctx: Context, approved: set[str]) -> Journal:
229
+ """Act on the approved needs, in order, as the module says; propose needs give their proposal."""
230
+ waits = edges(ctx.needs, types)
231
+ order = [n.id for n, _ in journal.entries]
232
+ at = {n.id: k for k, (n, _) in enumerate(journal.entries)}
233
+ started = time.monotonic()
234
+ journal.walk["mode"] = "fulfil"
235
+ done: set[str] = set()
236
+
237
+ def keep(i: str, result: Result) -> None:
238
+ ctx.results[i] = result
239
+ journal.entries[at[i]] = (ctx.needs[i], result)
240
+
241
+ for i in order:
242
+ need, kind = ctx.needs[i], types[ctx.needs[i].type]
243
+ result = ctx.results[i]
244
+ if result.state == "ready":
245
+ changed = refilled(kind, need, ctx, done) if i in approved else []
246
+ if not changed:
247
+ continue
248
+ result = Result("drift", f"{result.summary}, made before this walk changed {changed[0]}",
249
+ result.fix, result.details, result.checked_at, result.seconds, fixable=True)
250
+ keep(i, result)
251
+ elif waits[i] & done:
252
+ result = checked(kind, need, ctx, waits[i], order)
253
+ keep(i, result)
254
+ grade = grade_of(kind, need)
255
+ if result.state not in ACTING:
256
+ continue
257
+ if grade == "propose":
258
+ proposal = timed(kind, need, ctx, "fulfil")
259
+ if proposal.fix and proposal.state != "unknown":
260
+ result.fix = proposal.fix
261
+ continue
262
+ if grade != "auto" or i not in approved or not result.fixable:
263
+ continue
264
+ late = [d for d in order if d in waits[i] and ctx.results[d].state != "ready"]
265
+ if late:
266
+ result.details.append(f"not fulfilled: waits for {late[0]}, which is {ctx.results[late[0]].state}")
267
+ continue
268
+ made = timed(kind, need, ctx, "fulfil")
269
+ if made.state == "blocked":
270
+ # The fulfil found what only someone else can change (a grant, say): it stands.
271
+ keep(i, Result("blocked", made.summary, made.fix, [*result.details, *made.details],
272
+ result.checked_at, result.seconds + made.seconds))
273
+ continue
274
+ if made.state != "ready":
275
+ result.details.append(f"fulfil failed: {made.summary}" + (f"; {made.fix}" if made.fix else ""))
276
+ result.details += made.details
277
+ continue
278
+ again = checked(kind, need, ctx, waits[i], order)
279
+ again.fulfilled = True
280
+ again.details[:0] = [f"fulfilled: {made.summary}", *made.details]
281
+ again.seconds += made.seconds
282
+ keep(i, again)
283
+ done.add(i)
284
+ journal.walk["seconds"] = round(journal.walk["seconds"] + time.monotonic() - started, 3)
285
+ return journal
286
+
287
+
288
+ def counted(journal: Journal, types: Mapping[str, NeedType], offline: bool) -> list[tuple[Need, Result]]:
289
+ """The entries the exit code counts: under --offline, only the offline types'."""
290
+ return [(n, r) for n, r in journal.entries if not offline or types[n.type].offline]
291
+
292
+
293
+ def outcomes(journal: Journal, approved: set[str]) -> list[str]:
294
+ """How each need the walk was to act on ended: its state, what it found, and the fix
295
+ when it is not ready, as `lines` says them; for stderr, beside the plan."""
296
+ out = []
297
+ for need, result in journal.entries:
298
+ if need.id not in approved:
299
+ continue
300
+ made = " (fulfilled)" if result.fulfilled else ""
301
+ out.append(f" {result.state:<7} {need.id} {result.summary}{made}")
302
+ out += [f" {d}" for d in result.details]
303
+ if result.state != "ready" and result.fix:
304
+ out += [f" to do: {line}" for line in result.fix.splitlines()]
305
+ return out
306
+
307
+
308
+ def lines(journal: Journal) -> list[str]:
309
+ """The human form: a line per need, then what to do about each one not ready, then the count."""
310
+ out = []
311
+ for need, result in journal.entries:
312
+ made = " (fulfilled)" if result.fulfilled else ""
313
+ out.append(f"{result.state:<7} {need.id} {result.summary}{made}")
314
+ out += [f" {d}" for d in result.details]
315
+ waiting = [(n, r) for n, r in journal.entries if r.state != "ready" and r.fix]
316
+ if waiting:
317
+ out.append("")
318
+ out.append("to do:")
319
+ for need, result in waiting:
320
+ out.append(f" {need.id}")
321
+ out += [f" {line}" for line in result.fix.splitlines()]
322
+ c = journal.counts()
323
+ out.append(f"deploy: {len(journal.entries)} needs, {c['ready']} ready, {c['missing']} missing, "
324
+ f"{c['drift']} drift, {c['blocked']} blocked, {c['unknown']} unknown")
325
+ return out