velocity-python 0.5.0__py3-none-any.whl → 0.6.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.
velocity/__init__.py CHANGED
@@ -1,4 +1,4 @@
1
- __version__ = version = "0.5.0"
1
+ __version__ = version = "0.6.0"
2
2
 
3
3
  import importlib as _importlib
4
4
 
@@ -19,6 +19,9 @@ in ``client_actions`` (``client_actions = MINE | WORKFLOW_ACTIONS``)::
19
19
  workflow-handover {to, stations?, route?} -> {ok, moved, kept}
20
20
  workflow-flow {route?, entity?} -> {flows, as_of}
21
21
  workflow-graph {docket, depth?} -> Graph
22
+ workflow-operator {route?, entity?} -> Console
23
+ workflow-operator-act {docket, position, verb, comment?, request_key}
24
+ -> {ok, replayed?}
22
25
 
23
26
  and :class:`WorkflowQueueMixin` to its queue handler (never reachable over
24
27
  HTTP): ``workflow-program`` (a program station's job), ``workflow-drain``
@@ -48,6 +51,17 @@ and ``workflow.docket.assign`` / ``workflow.docket.prioritize`` (a route
48
51
  owner, the station's lead, or ``workflow.position.assign`` for the docket's
49
52
  entity); a hand-over moves only the caller's own positions, to a receiver
50
53
  seated at their stations.
54
+
55
+ **The Operator console** (:mod:`velocity.workflow.operator`) opens for a
56
+ holder of ``workflow.operate`` (anywhere) or a route owner
57
+ (``workflow.operator``), over the routes and entities
58
+ :func:`velocity.workflow.access.operator_scope` gives; its site-wide
59
+ sections (integrations, scheduled jobs) only with ``workflow.operate``
60
+ granted site-wide. ``workflow-operator-act`` retries, skips or takes over a
61
+ problem-tray position: the viewer must see the docket and be allowed
62
+ ``workflow.problem.resolve`` (its problem owner, or ``workflow.operate`` for
63
+ its entity — recorded), and the engine's own problem action decides the rest
64
+ (skip and take-over only where the station is skippable).
51
65
  """
52
66
 
53
67
  from __future__ import annotations
@@ -207,18 +221,21 @@ class WorkflowMixin:
207
221
  def _wf_masquerading(self, principal) -> bool:
208
222
  return principal.real_user is not None
209
223
 
210
- def _wf_decider(self, context):
224
+ def _wf_decider(self, context, accept=frozenset()):
211
225
  """The viewer's ``may_view``: the site's authz decision on
212
226
  ``workflow.docket.view`` for one docket (a forbid rule hides it from
213
227
  trays and links too). A privileged permit (``view_any``) is not
214
- used here: listing is never a recorded use."""
228
+ used here: listing is never a recorded use. ``accept`` names the
229
+ audited rules a listing may still show (never recorded here): the
230
+ Operator console lists its problem dockets under
231
+ ``workflow.operator_view``."""
215
232
  wf = _workflow()
216
233
 
217
234
  def decide(docket, relations):
218
235
  decision = authz.decide(
219
236
  self, wf.access.VIEW, wf.access.resource(docket, relations), context
220
237
  )
221
- return decision.allowed and not decision.audit
238
+ return decision.allowed and (not decision.audit or decision.rule in accept)
222
239
 
223
240
  return decide
224
241
 
@@ -564,7 +581,7 @@ class WorkflowMixin:
564
581
  decision = authz.decide(self, wf.access.FLOW, resource, context)
565
582
  if not decision.allowed or decision.audit:
566
583
  return None
567
- scope = wf.access.flow_scope(seats, principal, route)
584
+ scope = wf.access.flow_scope(seats, principal, route, tx=tx)
568
585
  if entity is not None:
569
586
  scope = scope.narrowed(entity)
570
587
  if scope.empty:
@@ -790,6 +807,211 @@ class WorkflowMixin:
790
807
 
791
808
  self._wf_guarded(tx, context, work)
792
809
 
810
+ # ── the Operator console ───────────────────────────────────────────────
811
+
812
+ def _wf_can_resolve(self, tx, context, principal, seats):
813
+ """Whether ``workflow.problem.resolve`` would be allowed on a
814
+ problem position (display only: never recorded; nothing under
815
+ masquerade)."""
816
+ wf = _workflow()
817
+ masquerading = self._wf_masquerading(principal)
818
+
819
+ def can_resolve(docket, route, position, verb):
820
+ if masquerading:
821
+ return False
822
+ relations = wf.access.problem_relations(tx, docket, route, seats, position)
823
+ if not relations:
824
+ return False
825
+ decision = authz.decide(
826
+ self,
827
+ wf.access.RESOLVE,
828
+ wf.access.resource(docket, relations),
829
+ context,
830
+ )
831
+ if not decision.allowed:
832
+ return False
833
+ if verb == "take_over":
834
+ return authz.decide(
835
+ self,
836
+ wf.access.TAKE_OVER,
837
+ wf.access.resource(docket, ()),
838
+ context,
839
+ ).allowed
840
+ return True
841
+
842
+ return can_resolve
843
+
844
+ def OnActionWorkflowOperator(self, tx, context):
845
+ wf = _workflow()
846
+ payload = context.payload() or {}
847
+ principal = self._wf_principal(context)
848
+ seats = self._wf_seats(tx, context, principal)
849
+
850
+ def work():
851
+ entity = self._wf_entity(payload, seats)
852
+ truncated = False
853
+ named = payload.get("route") is not None
854
+ if named:
855
+ candidates = [self._wf_route(tx, payload.get("route"), entity, seats)]
856
+ else:
857
+ codes, truncated = wf.operator.route_codes(tx, seats, principal)
858
+ candidates = []
859
+ for code in codes:
860
+ try:
861
+ candidates.append(
862
+ wf.views.route_for(tx, code, entity=entity, seats=seats)
863
+ )
864
+ except wf.WorkflowError:
865
+ continue
866
+ self._wf_require_seat(
867
+ tx,
868
+ context,
869
+ wf.access.CONSOLE,
870
+ wf.access.console_resource(
871
+ wf.access.console_relations(seats, candidates)
872
+ ),
873
+ )
874
+ scopes = {}
875
+ for route in candidates:
876
+ scope = wf.access.operator_scope(seats, principal, route, tx=tx)
877
+ if entity is not None:
878
+ scope = scope.narrowed(entity)
879
+ if not scope.empty:
880
+ scopes[route.code] = scope
881
+ if named and not scopes:
882
+ # a route this viewer may not operate: refused like one that
883
+ # does not exist
884
+ raise AccessError(authz.REFUSED)
885
+ viewer = wf.contract.Viewer(
886
+ seats=seats,
887
+ principal=principal,
888
+ view_decider=self._wf_decider(
889
+ context,
890
+ accept=frozenset({wf.access.OPERATOR_VIEW_RULE}),
891
+ ),
892
+ )
893
+ body = wf.operator.console(
894
+ tx,
895
+ viewer,
896
+ [r for r in candidates if r.code in scopes],
897
+ scopes,
898
+ site=wf.access.site_wide(principal, wf.access.OPERATE),
899
+ can_resolve=self._wf_can_resolve(tx, context, principal, seats),
900
+ )
901
+ if truncated:
902
+ body["truncated"] = True
903
+ context.response().set_body(body)
904
+
905
+ self._wf_guarded(tx, context, work)
906
+
907
+ def OnActionWorkflowOperatorAct(self, tx, context):
908
+ wf = _workflow()
909
+ payload = context.payload() or {}
910
+ principal = self._wf_principal(context)
911
+ seats = self._wf_seats(tx, context, principal)
912
+
913
+ def work():
914
+ verb = payload.get("verb")
915
+ if verb not in wf.engine.PROBLEM_VERBS:
916
+ raise _Refusal(
917
+ BAD_REQUEST,
918
+ [
919
+ {
920
+ "code": "verb",
921
+ "text": "verb must be retry, skip or take_over.",
922
+ }
923
+ ],
924
+ )
925
+ docket, route = self._wf_docket(tx, payload)
926
+ try:
927
+ position = wf.engine._position(tx, payload.get("position"))
928
+ except wf.WorkflowError:
929
+ raise AccessError(authz.REFUSED) from None
930
+ if position["docket_id"] != docket["sys_id"]:
931
+ raise AccessError(authz.REFUSED)
932
+ request_key = payload.get("request_key")
933
+ if isinstance(request_key, str) and request_key.strip():
934
+ mark = wf.engine.acted_mark(
935
+ tx, docket["sys_id"], wf.engine.Actor.person(seats), request_key
936
+ )
937
+ if mark is not None:
938
+ # this person's own request again: the first answer
939
+ # only if it was this very action (the position has
940
+ # usually left the problem tray since)
941
+ if (
942
+ mark.get("action") != verb
943
+ or mark.get("position_id") != position["sys_id"]
944
+ ):
945
+ raise _Refusal(
946
+ CONFLICT,
947
+ [
948
+ {
949
+ "code": "request_key",
950
+ "text": "That request key was used for "
951
+ "another action.",
952
+ }
953
+ ],
954
+ )
955
+ # nothing under masquerade, and only for someone who may
956
+ # still see the docket or operate
957
+ if self._wf_masquerading(principal):
958
+ raise AccessError(authz.REFUSED)
959
+ seen = authz.decide(
960
+ self,
961
+ wf.access.VIEW,
962
+ wf.access.resource(
963
+ docket,
964
+ wf.access.view_relations(tx, docket, route, seats),
965
+ ),
966
+ context,
967
+ ).allowed
968
+ if not seen and not principal.holds_anywhere(wf.access.OPERATE):
969
+ raise AccessError(authz.REFUSED)
970
+ context.response().set_body({"ok": True, "replayed": True})
971
+ return
972
+ relations = wf.access.view_relations(tx, docket, route, seats)
973
+ self._wf_require(tx, context, wf.access.VIEW, docket, relations)
974
+ decision = self._wf_require(
975
+ tx,
976
+ context,
977
+ wf.access.RESOLVE,
978
+ docket,
979
+ wf.access.problem_relations(tx, docket, route, seats, position),
980
+ )
981
+ if verb == "take_over":
982
+ # the work taken over is then theirs to do (workflow.use for
983
+ # the docket's entity; a site rule may refuse it)
984
+ self._wf_require(tx, context, wf.access.TAKE_OVER, docket, ())
985
+ request_key = self._wf_request_key(payload)
986
+ comment = payload.get("comment")
987
+ if comment is not None and not isinstance(comment, str):
988
+ raise _Refusal(
989
+ BAD_REQUEST, [{"code": "comment", "text": "comment must be text."}]
990
+ )
991
+ actor = wf.engine.Actor.person(
992
+ seats,
993
+ operator=decision.rule == wf.access.OPERATOR_RULE,
994
+ allows=self._wf_allows(tx, context),
995
+ )
996
+ result = wf.engine.resolve_problem(
997
+ tx,
998
+ docket["sys_id"],
999
+ position["sys_id"],
1000
+ verb,
1001
+ actor,
1002
+ request_key,
1003
+ comment=comment,
1004
+ )
1005
+ if not result.ok:
1006
+ raise _Refusal(_reasons_status(result.reasons), result.reasons)
1007
+ self._wf_after_change(tx, context, docket["sys_id"])
1008
+ body = {"ok": True}
1009
+ if result.replayed:
1010
+ body["replayed"] = True
1011
+ context.response().set_body(body)
1012
+
1013
+ self._wf_guarded(tx, context, work)
1014
+
793
1015
  # ── notices ────────────────────────────────────────────────────────────
794
1016
 
795
1017
  def OnActionWorkflowNotices(self, tx, context):
velocity/aws/ops.py CHANGED
@@ -379,6 +379,14 @@ def _overview(tx, hours, now):
379
379
  }
380
380
 
381
381
 
382
+ def schedules(tx, *, now=None):
383
+ """Every schedule in ``sys_task_triggers`` as :func:`shape_schedule`
384
+ (``health``: ok / never / overdue / disabled), by name; ``[]`` when the
385
+ table does not exist. What the dashboard's schedule section and the
386
+ workflow Operator console's scheduled jobs both read."""
387
+ return _schedules(tx, now or _utcnow())
388
+
389
+
382
390
  def _schedules(tx, now):
383
391
  if not _has(tx, TRIGGERS_TABLE):
384
392
  return []
velocity/db/_pgddl.py CHANGED
@@ -141,12 +141,104 @@ def execute_all(tx, statements: Iterable[str]) -> None:
141
141
  tx.execute(statement)
142
142
 
143
143
 
144
+ # A trigger velocity installed carries this comment: a digest of the CREATE
145
+ # statement that made it, so a re-run can tell an unchanged trigger.
146
+ TRIGGER_COMMENT_PREFIX = "velocity:"
147
+ _DROP_TRIGGER = "DROP TRIGGER IF EXISTS "
148
+ _CREATE_TRIGGERS = ("CREATE TRIGGER ", "CREATE CONSTRAINT TRIGGER ")
149
+ _TRIGGER_STATE_SQL = (
150
+ "SELECT t.tgenabled::text AS enabled, d.description "
151
+ "FROM pg_catalog.pg_trigger t "
152
+ "LEFT JOIN pg_catalog.pg_description d ON d.objoid = t.oid "
153
+ "AND d.classoid = 'pg_catalog.pg_trigger'::regclass "
154
+ "WHERE t.tgrelid = pg_catalog.to_regclass(%s) AND t.tgname = %s "
155
+ "AND NOT t.tgisinternal"
156
+ )
157
+
158
+
159
+ def is_trigger_bookkeeping(sql: str) -> bool:
160
+ """Whether ``sql`` is :func:`execute_ddl`'s own (the installed-trigger
161
+ probe or the fingerprint comment), not one of the caller's statements."""
162
+ return sql == _TRIGGER_STATE_SQL or sql.startswith("COMMENT ON TRIGGER ")
163
+
164
+
165
+ def trigger_fingerprint(create_sql: str) -> str:
166
+ """The comment an installed trigger carries for ``create_sql``."""
167
+ digest = hashlib.sha256(create_sql.encode("utf-8")).hexdigest()[:32]
168
+ return TRIGGER_COMMENT_PREFIX + digest
169
+
170
+
171
+ def _trigger_pair(drop_sql: str, create_sql: str):
172
+ """``(quoted name, quoted table)`` of a ``DROP TRIGGER IF EXISTS`` that
173
+ the matching ``CREATE TRIGGER`` re-makes, else ``None``."""
174
+ create = next((p for p in _CREATE_TRIGGERS if create_sql.startswith(p)), None)
175
+ if not drop_sql.startswith(_DROP_TRIGGER) or create is None:
176
+ return None
177
+ name, sep, target = drop_sql[len(_DROP_TRIGGER) :].partition(" ON ")
178
+ if not sep or not create_sql[len(create) :].startswith(name + " "):
179
+ return None
180
+ if f" ON {target} " not in create_sql:
181
+ return None
182
+ return name, target
183
+
184
+
185
+ def _unquote(quoted: str) -> str:
186
+ return quoted[1:-1].replace('""', '"') if quoted.startswith('"') else quoted
187
+
188
+
189
+ def trigger_unchanged(tx, name: str, target: str, create_sql: str) -> bool:
190
+ """Whether the trigger ``name`` (quoted) on ``target`` (quoted table) is
191
+ enabled for ordinary sessions and was made by exactly ``create_sql``."""
192
+ rows = tx.execute(_TRIGGER_STATE_SQL, (target, _unquote(name))).all()
193
+ return (
194
+ bool(rows)
195
+ and rows[0].get("enabled") in ("O", "A")
196
+ and (rows[0].get("description") == trigger_fingerprint(create_sql))
197
+ )
198
+
199
+
200
+ def execute_ddl(tx, statements: Iterable[str]) -> None:
201
+ """:func:`execute_all`, except that a ``DROP TRIGGER IF EXISTS`` followed
202
+ by the ``CREATE TRIGGER`` that re-makes it is skipped when the installed
203
+ trigger is enabled and carries that statement's fingerprint, and a
204
+ trigger it does make is marked with one. ``DROP TRIGGER`` takes an
205
+ ACCESS EXCLUSIVE lock, so re-making unchanged triggers on every schema
206
+ lane run blocks (and can deadlock with) a live database's readers."""
207
+ statements = list(statements)
208
+ i = 0
209
+ while i < len(statements):
210
+ statement = statements[i]
211
+ pair = (
212
+ _trigger_pair(statement, statements[i + 1])
213
+ if i + 1 < len(statements)
214
+ else None
215
+ )
216
+ if pair is None:
217
+ tx.execute(statement)
218
+ i += 1
219
+ continue
220
+ name, target = pair
221
+ create_sql = statements[i + 1]
222
+ if not trigger_unchanged(tx, name, target, create_sql):
223
+ tx.execute(statement)
224
+ tx.execute(create_sql)
225
+ tx.execute(
226
+ f"COMMENT ON TRIGGER {name} ON {target} IS "
227
+ f"{quote_literal(trigger_fingerprint(create_sql))}"
228
+ )
229
+ i += 2
230
+
231
+
144
232
  __all__ = [
145
233
  "DDL_LOCK_KEY",
146
234
  "DEFAULT_SCHEMA",
147
235
  "FUNCTION_SEARCH_PATH",
148
236
  "bounded_name",
149
237
  "execute_all",
238
+ "execute_ddl",
239
+ "is_trigger_bookkeeping",
240
+ "trigger_fingerprint",
241
+ "trigger_unchanged",
150
242
  "function_schema",
151
243
  "identifier",
152
244
  "identifiers",
velocity/db/audit.py CHANGED
@@ -567,7 +567,7 @@ def require_audit(
567
567
  if ensure_table:
568
568
  ensure_audit_log(tx, audit_table, on_existing_conflicts="ignore")
569
569
  _assert_owned(tx, "audit table", _pgddl.quote_table(audit_table, "audit table"))
570
- _pgddl.execute_all(tx, statements)
570
+ _pgddl.execute_ddl(tx, statements)
571
571
  _assert_owned(
572
572
  tx, "audit capture function", f"{fn_schema}.{FUNCTION_NAME}()", function=True
573
573
  )
velocity/db/integrity.py CHANGED
@@ -202,7 +202,7 @@ def require_append_only(
202
202
  _pgddl.require_postgres(tx, "require_append_only")
203
203
  statements = row_lock_sql(table, mutable_columns=mutable_columns)
204
204
  tx.advisory_lock(DDL_LOCK_KEY)
205
- _pgddl.execute_all(tx, statements)
205
+ _pgddl.execute_ddl(tx, statements)
206
206
 
207
207
 
208
208
  def require_posted_lock(
@@ -231,7 +231,7 @@ def require_posted_lock(
231
231
  )
232
232
  _assert_column_exists(tx, table, posted_column)
233
233
  tx.advisory_lock(DDL_LOCK_KEY)
234
- _pgddl.execute_all(tx, statements)
234
+ _pgddl.execute_ddl(tx, statements)
235
235
 
236
236
 
237
237
  def drop_row_lock(tx, table: str) -> None:
@@ -736,7 +736,7 @@ def require_period_lock(
736
736
  time_zone=time_zone,
737
737
  )
738
738
  tx.advisory_lock(DDL_LOCK_KEY)
739
- _pgddl.execute_all(tx, statements)
739
+ _pgddl.execute_ddl(tx, statements)
740
740
 
741
741
 
742
742
  def drop_period_lock(tx, table: str) -> None:
@@ -16,8 +16,10 @@ An application supplies, in code: :func:`register_subject`,
16
16
  :func:`register_program`, :func:`register_sheet`, :func:`register_seats`
17
17
  (and optionally :func:`register_recipients`, :func:`register_contact`,
18
18
  :func:`register_person_label`, :func:`register_station_people`,
19
- :func:`register_time_zone`). :mod:`.views` draws the Station Board, the
20
- Flow map and the Dependency view. Nothing here names a business. See
19
+ :func:`register_time_zone`, :func:`register_heartbeats`,
20
+ :func:`register_role_label`). :mod:`.views` draws the Station Board, the
21
+ Flow map and the Dependency view; :mod:`.operator` the Operator console.
22
+ Nothing here names a business. See
21
23
  docs/workflow.md.
22
24
  """
23
25
 
@@ -28,6 +30,7 @@ from . import (
28
30
  engine,
29
31
  hooks,
30
32
  notices,
33
+ operator,
31
34
  outbox,
32
35
  points,
33
36
  schema,
@@ -69,6 +72,7 @@ from .engine import ( # noqa: F401
69
72
  place_hold,
70
73
  prioritize,
71
74
  release_hold,
75
+ resolve_problem,
72
76
  resume_wait,
73
77
  run_program,
74
78
  run_route_tests,
@@ -90,10 +94,12 @@ from .hooks import ( # noqa: F401
90
94
  register_calendar,
91
95
  register_contact,
92
96
  register_entity_scope,
97
+ register_heartbeats,
93
98
  register_person_label,
94
99
  register_person_seats,
95
100
  register_program,
96
101
  register_recipients,
102
+ register_role_label,
97
103
  register_seats,
98
104
  register_sheet,
99
105
  register_station_people,
@@ -148,16 +154,19 @@ __all__ = [
148
154
  "register_channel",
149
155
  "register_contact",
150
156
  "register_entity_scope",
157
+ "register_heartbeats",
151
158
  "register_person_label",
152
159
  "register_person_seats",
153
160
  "register_program",
154
161
  "register_recipients",
162
+ "register_role_label",
155
163
  "register_seats",
156
164
  "register_sheet",
157
165
  "register_station_people",
158
166
  "register_subject",
159
167
  "register_time_zone",
160
168
  "release_hold",
169
+ "resolve_problem",
161
170
  "resume_wait",
162
171
  "retire",
163
172
  "route_from",