velocity-python 0.6.0__py3-none-any.whl → 0.7.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.6.0"
1
+ __version__ = version = "0.7.0"
2
2
 
3
3
  import importlib as _importlib
4
4
 
@@ -22,6 +22,16 @@ in ``client_actions`` (``client_actions = MINE | WORKFLOW_ACTIONS``)::
22
22
  workflow-operator {route?, entity?} -> Console
23
23
  workflow-operator-act {docket, position, verb, comment?, request_key}
24
24
  -> {ok, replayed?}
25
+ workflow-routes {} -> {routes, truncated?}
26
+ workflow-route {route_id} -> {version: RouteVersion}
27
+ workflow-route-draft {from, request_key} -> {ok, replayed, version}
28
+ workflow-route-edit {route_id, revision, changes} -> {ok, version}
29
+ workflow-route-lint {route_id} -> {lint}
30
+ workflow-route-simulate {route_id, sample} -> {simulation}
31
+ workflow-route-test {route_id} -> {tests}
32
+ workflow-route-publish {route_id, revision, effective_from, comment?, request_key}
33
+ -> {ok, replayed, in_flight, version}
34
+ workflow-route-archive {route_id} -> {ok, replayed, version}
25
35
 
26
36
  and :class:`WorkflowQueueMixin` to its queue handler (never reachable over
27
37
  HTTP): ``workflow-program`` (a program station's job), ``workflow-drain``
@@ -62,6 +72,18 @@ problem-tray position: the viewer must see the docket and be allowed
62
72
  ``workflow.problem.resolve`` (its problem owner, or ``workflow.operate`` for
63
73
  its entity — recorded), and the engine's own problem action decides the rest
64
74
  (skip and take-over only where the station is skippable).
75
+
76
+ **The Route designer** (:mod:`velocity.workflow.designer`): every action
77
+ names a route version (``route_id``; ``from`` for a new draft) and is
78
+ decided on the route (its code and entity): ``workflow.designer`` to open,
79
+ lint, simulate and test it (``workflow.route.design`` for the route's
80
+ entity, or owning the route with ``workflow.use`` there),
81
+ ``workflow.designer.edit`` to create, edit and archive drafts (the same),
82
+ and ``workflow.designer.publish`` to publish (``workflow.route.publish`` for
83
+ the route's entity AND owning the route — by the version in force, never
84
+ the draft's own owner role; recorded). A version the person may not open is
85
+ refused exactly like one that does not exist. Masquerade forbids every
86
+ designer write. Simulations and tests write nothing.
65
87
  """
66
88
 
67
89
  from __future__ import annotations
@@ -1012,6 +1034,282 @@ class WorkflowMixin:
1012
1034
 
1013
1035
  self._wf_guarded(tx, context, work)
1014
1036
 
1037
+ # ── the Route designer ────────────────────────────────────────────────
1038
+
1039
+ def _wf_design_target(self, tx, context, payload, seats, action, key="route_id"):
1040
+ """The route version ``payload[key]`` names, once ``action`` is
1041
+ allowed on its route: ``(row, relations)``. A missing version and one
1042
+ the person may not reach are refused alike."""
1043
+ wf = _workflow()
1044
+ try:
1045
+ row = wf.designer.route_row(tx, (payload or {}).get(key))
1046
+ except wf.WorkflowError:
1047
+ raise AccessError(authz.REFUSED) from None
1048
+ relations = self._wf_design_relations(tx, seats, row)
1049
+ self._wf_require_seat(
1050
+ tx,
1051
+ context,
1052
+ action,
1053
+ wf.access.design_resource(row["code"], row.get("entity"), relations),
1054
+ )
1055
+ return row, relations
1056
+
1057
+ def _wf_design_relations(self, tx, seats, row):
1058
+ wf = _workflow()
1059
+ owner_role = wf.designer.owner_role_of(
1060
+ tx, row, wf.designer.today_for(tx, row.get("entity"), _now())
1061
+ )
1062
+ return wf.access.route_owner_relations(
1063
+ seats, row["code"], owner_role, row.get("entity")
1064
+ )
1065
+
1066
+ def _wf_design_can(self, context, principal, row, relations):
1067
+ """What the designer offers on ``row`` (display only: the server
1068
+ decides again; nothing is offered under masquerade)."""
1069
+ wf = _workflow()
1070
+ if self._wf_masquerading(principal):
1071
+ writes = publishes = False
1072
+ else:
1073
+ resource = wf.access.design_resource(
1074
+ row["code"], row.get("entity"), relations
1075
+ )
1076
+ edit = authz.decide(self, wf.access.DESIGNER_EDIT, resource, context)
1077
+ writes = edit.allowed and not edit.audit
1078
+ publishes = authz.decide(
1079
+ self, wf.access.DESIGNER_PUBLISH, resource, context
1080
+ ).allowed
1081
+ draft = row.get("status") == wf.definitions.DRAFT
1082
+ return {
1083
+ "edit": writes and draft,
1084
+ "archive": writes and draft,
1085
+ "publish": publishes and draft,
1086
+ "create_draft": writes and row.get("status") != wf.definitions.ARCHIVED,
1087
+ "simulate": True,
1088
+ "test": True,
1089
+ }
1090
+
1091
+ def _wf_version_body(self, tx, context, principal, seats, route_id):
1092
+ wf = _workflow()
1093
+ row = wf.designer.route_row(tx, route_id)
1094
+ relations = self._wf_design_relations(tx, seats, row)
1095
+ return wf.designer.version(
1096
+ tx,
1097
+ row["sys_id"],
1098
+ can=self._wf_design_can(context, principal, row, relations),
1099
+ now=_now(),
1100
+ )
1101
+
1102
+ def OnActionWorkflowRoutes(self, tx, context):
1103
+ wf = _workflow()
1104
+ principal = self._wf_principal(context)
1105
+ seats = self._wf_seats(tx, context, principal)
1106
+
1107
+ def may_design(code, entity, owner_role):
1108
+ relations = wf.access.route_owner_relations(seats, code, owner_role, entity)
1109
+ decision = authz.decide(
1110
+ self,
1111
+ wf.access.DESIGNER,
1112
+ wf.access.design_resource(code, entity, relations),
1113
+ context,
1114
+ )
1115
+ return decision.allowed and not decision.audit
1116
+
1117
+ def work():
1118
+ body = wf.designer.list_routes(tx, may_design=may_design, now=_now())
1119
+ context.response().set_body(body)
1120
+
1121
+ self._wf_guarded(tx, context, work)
1122
+
1123
+ def OnActionWorkflowRoute(self, tx, context):
1124
+ wf = _workflow()
1125
+ payload = context.payload() or {}
1126
+ principal = self._wf_principal(context)
1127
+ seats = self._wf_seats(tx, context, principal)
1128
+
1129
+ def work():
1130
+ row, _relations = self._wf_design_target(
1131
+ tx, context, payload, seats, wf.access.DESIGNER
1132
+ )
1133
+ body = self._wf_version_body(tx, context, principal, seats, row["sys_id"])
1134
+ context.response().set_body({"version": body})
1135
+
1136
+ self._wf_guarded(tx, context, work)
1137
+
1138
+ def OnActionWorkflowRouteDraft(self, tx, context):
1139
+ wf = _workflow()
1140
+ payload = context.payload() or {}
1141
+ principal = self._wf_principal(context)
1142
+ seats = self._wf_seats(tx, context, principal)
1143
+
1144
+ def work():
1145
+ row, _relations = self._wf_design_target(
1146
+ tx, context, payload, seats, wf.access.DESIGNER_EDIT, key="from"
1147
+ )
1148
+ if row.get("status") == wf.definitions.ARCHIVED:
1149
+ raise _Refusal(
1150
+ CONFLICT,
1151
+ [
1152
+ {
1153
+ "code": "archived",
1154
+ "text": "An archived draft can't be copied.",
1155
+ }
1156
+ ],
1157
+ )
1158
+ draft_id, replayed = wf.designer.create_draft(
1159
+ tx,
1160
+ row["sys_id"],
1161
+ by=seats.person,
1162
+ request_key=payload.get("request_key"),
1163
+ now=_now(),
1164
+ )
1165
+ body = self._wf_version_body(tx, context, principal, seats, draft_id)
1166
+ context.response().set_body(
1167
+ {"ok": True, "replayed": replayed, "version": body}
1168
+ )
1169
+
1170
+ self._wf_guarded(tx, context, work)
1171
+
1172
+ def OnActionWorkflowRouteEdit(self, tx, context):
1173
+ wf = _workflow()
1174
+ payload = context.payload() or {}
1175
+ principal = self._wf_principal(context)
1176
+ seats = self._wf_seats(tx, context, principal)
1177
+
1178
+ def work():
1179
+ row, _relations = self._wf_design_target(
1180
+ tx, context, payload, seats, wf.access.DESIGNER_EDIT
1181
+ )
1182
+ wf.designer.edit_draft(
1183
+ tx,
1184
+ row["sys_id"],
1185
+ payload.get("changes"),
1186
+ revision=payload.get("revision"),
1187
+ by=seats.person,
1188
+ now=_now(),
1189
+ )
1190
+ body = self._wf_version_body(tx, context, principal, seats, row["sys_id"])
1191
+ context.response().set_body({"ok": True, "version": body})
1192
+
1193
+ self._wf_guarded(tx, context, work)
1194
+
1195
+ def OnActionWorkflowRouteLint(self, tx, context):
1196
+ wf = _workflow()
1197
+ payload = context.payload() or {}
1198
+ principal = self._wf_principal(context)
1199
+ seats = self._wf_seats(tx, context, principal)
1200
+
1201
+ def work():
1202
+ row, _relations = self._wf_design_target(
1203
+ tx, context, payload, seats, wf.access.DESIGNER
1204
+ )
1205
+ context.response().set_body(
1206
+ {"lint": wf.designer.lint_version(tx, row["sys_id"], now=_now())}
1207
+ )
1208
+
1209
+ self._wf_guarded(tx, context, work)
1210
+
1211
+ def OnActionWorkflowRouteSimulate(self, tx, context):
1212
+ wf = _workflow()
1213
+ payload = context.payload() or {}
1214
+ principal = self._wf_principal(context)
1215
+ seats = self._wf_seats(tx, context, principal)
1216
+
1217
+ def work():
1218
+ row, _relations = self._wf_design_target(
1219
+ tx, context, payload, seats, wf.access.DESIGNER
1220
+ )
1221
+ body = wf.designer.simulate_version(
1222
+ tx, row["sys_id"], payload.get("sample"), now=_now()
1223
+ )
1224
+ context.response().set_body({"simulation": body})
1225
+
1226
+ self._wf_guarded(tx, context, work)
1227
+
1228
+ def OnActionWorkflowRouteTest(self, tx, context):
1229
+ wf = _workflow()
1230
+ payload = context.payload() or {}
1231
+ principal = self._wf_principal(context)
1232
+ seats = self._wf_seats(tx, context, principal)
1233
+
1234
+ def work():
1235
+ row, _relations = self._wf_design_target(
1236
+ tx, context, payload, seats, wf.access.DESIGNER
1237
+ )
1238
+ context.response().set_body(
1239
+ {"tests": wf.designer.test_version(tx, row["sys_id"], now=_now())}
1240
+ )
1241
+
1242
+ self._wf_guarded(tx, context, work)
1243
+
1244
+ def OnActionWorkflowRoutePublish(self, tx, context):
1245
+ wf = _workflow()
1246
+ payload = context.payload() or {}
1247
+ principal = self._wf_principal(context)
1248
+ seats = self._wf_seats(tx, context, principal)
1249
+
1250
+ def work():
1251
+ row, _relations = self._wf_design_target(
1252
+ tx, context, payload, seats, wf.access.DESIGNER
1253
+ )
1254
+ if self._wf_masquerading(principal):
1255
+ raise AccessError(authz.REFUSED)
1256
+ self._wf_design_target(
1257
+ tx, context, payload, seats, wf.access.DESIGNER_PUBLISH
1258
+ )
1259
+ request_key = self._wf_request_key(payload)
1260
+ if wf.designer.publish_replay(
1261
+ tx, row["sys_id"], by=seats.person, request_key=request_key
1262
+ ):
1263
+ # this person's own publish again: answer as it is now
1264
+ body = self._wf_version_body(
1265
+ tx, context, principal, seats, row["sys_id"]
1266
+ )
1267
+ context.response().set_body(
1268
+ {"ok": True, "replayed": True, "in_flight": 0, "version": body}
1269
+ )
1270
+ return
1271
+ result = wf.designer.publish_draft(
1272
+ tx,
1273
+ row["sys_id"],
1274
+ effective_from=payload.get("effective_from"),
1275
+ comment=payload.get("comment"),
1276
+ by=seats.person,
1277
+ request_key=request_key,
1278
+ revision=payload.get("revision"),
1279
+ now=_now(),
1280
+ )
1281
+ body = self._wf_version_body(tx, context, principal, seats, row["sys_id"])
1282
+ context.response().set_body(
1283
+ {
1284
+ "ok": True,
1285
+ "replayed": result["replayed"],
1286
+ "in_flight": result["in_flight"],
1287
+ "version": body,
1288
+ }
1289
+ )
1290
+
1291
+ self._wf_guarded(tx, context, work)
1292
+
1293
+ def OnActionWorkflowRouteArchive(self, tx, context):
1294
+ wf = _workflow()
1295
+ payload = context.payload() or {}
1296
+ principal = self._wf_principal(context)
1297
+ seats = self._wf_seats(tx, context, principal)
1298
+
1299
+ def work():
1300
+ row, _relations = self._wf_design_target(
1301
+ tx, context, payload, seats, wf.access.DESIGNER_EDIT
1302
+ )
1303
+ replayed = wf.designer.archive_draft(
1304
+ tx, row["sys_id"], by=seats.person, now=_now()
1305
+ )
1306
+ body = self._wf_version_body(tx, context, principal, seats, row["sys_id"])
1307
+ context.response().set_body(
1308
+ {"ok": True, "replayed": replayed, "version": body}
1309
+ )
1310
+
1311
+ self._wf_guarded(tx, context, work)
1312
+
1015
1313
  # ── notices ────────────────────────────────────────────────────────────
1016
1314
 
1017
1315
  def OnActionWorkflowNotices(self, tx, context):
@@ -18,7 +18,8 @@ An application supplies, in code: :func:`register_subject`,
18
18
  :func:`register_person_label`, :func:`register_station_people`,
19
19
  :func:`register_time_zone`, :func:`register_heartbeats`,
20
20
  :func:`register_role_label`). :mod:`.views` draws the Station Board, the
21
- Flow map and the Dependency view; :mod:`.operator` the Operator console.
21
+ Flow map and the Dependency view; :mod:`.operator` the Operator console;
22
+ :mod:`.designer` the Route designer.
22
23
  Nothing here names a business. See
23
24
  docs/workflow.md.
24
25
  """
@@ -27,6 +28,7 @@ from . import (
27
28
  access,
28
29
  contract,
29
30
  definitions,
31
+ designer,
30
32
  engine,
31
33
  hooks,
32
34
  notices,
@@ -25,6 +25,13 @@ Permissions (granted by the site, :mod:`velocity.aws.permissions` or its
25
25
  it is granted for: see dockets with a problem-tray
26
26
  item and Retry / Skip / Take over them (recorded);
27
27
  site-wide, also integrations and scheduled jobs
28
+ ``workflow.route the Route designer for the routes of the entities it
29
+ .design`` is granted for (a shared route, with no entity:
30
+ granted site-wide): open versions, create, edit and
31
+ archive drafts, lint, simulate and run route tests
32
+ ``workflow.route publish a draft — only together with owning the route
33
+ .publish`` (its owner role or ``Seats.oversees``) in the route's
34
+ entity (privileged: every publish is recorded)
28
35
  ===================== =======================================================
29
36
 
30
37
  Actions and the rules that allow them, first match wins:
@@ -67,8 +74,22 @@ Actions and the rules that allow them, first match wins:
67
74
  own listing accepts it without recording.
68
75
  ``workflow.problem ``workflow.problem_take_over``: ``workflow.use``
69
76
  .take_over`` for the docket's entity (what take-over needs)
77
+ ``workflow.designer``, ``workflow.route_designer``: ``workflow.route
78
+ ``workflow.designer.edit`` .design`` for the route's entity scope;
79
+ ``workflow.route_owner_design``: ``workflow.use``
80
+ there and ``owns_route``
81
+ ``workflow.designer ``workflow.route_publisher``: ``workflow.route
82
+ .publish`` .publish`` for the route's entity scope and
83
+ ``owns_route`` (audited: every publish recorded)
70
84
  ========================== ==================================================
71
85
 
86
+ Route designer resources are :class:`SeatResource` of type
87
+ ``workflow_route`` (id: the route code; scopes: the route's entity's) whose
88
+ only relation is ``owns_route`` — what :func:`route_owner_relations` finds
89
+ in the person's seats for the route's entity (its owner role, or
90
+ ``Seats.oversees``; a station lead is not an owner). Masquerade forbids
91
+ ``workflow.designer.edit`` and ``workflow.designer.publish``.
92
+
72
93
  A station's lead (``"route/station"`` in ``EntitySeats.oversees``) is
73
94
  related to a docket as ``leads`` while it has an open position at that
74
95
  station: they see it (``workflow.involved``) and may assign and prioritize
@@ -114,6 +135,14 @@ CONSOLE = "workflow.operator"
114
135
  RESOLVE = "workflow.problem.resolve"
115
136
  # taking a problem over makes its work the viewer's: workflow.use there
116
137
  TAKE_OVER = "workflow.problem.take_over"
138
+ # the Route designer (WorkModel §7.8)
139
+ ROUTE_DESIGN = "workflow.route.design"
140
+ ROUTE_PUBLISH = "workflow.route.publish"
141
+ DESIGNER = "workflow.designer"
142
+ DESIGNER_EDIT = "workflow.designer.edit"
143
+ DESIGNER_PUBLISH = "workflow.designer.publish"
144
+ OWNS_ROUTE = "owns_route"
145
+ PUBLISH_RULE = "workflow.route_publisher"
117
146
 
118
147
  RESOURCE_TYPE = "workflow_docket"
119
148
  STATION_RESOURCE_TYPE = "workflow_station"
@@ -242,6 +271,21 @@ authz.permission(
242
271
  group="Workflow",
243
272
  privileged=True,
244
273
  )
274
+ authz.permission(
275
+ ROUTE_DESIGN,
276
+ label="Design routes",
277
+ description="Open routes in the Route designer, create and edit drafts, "
278
+ "lint, simulate and test them, for the entities you are granted.",
279
+ group="Workflow",
280
+ )
281
+ authz.permission(
282
+ ROUTE_PUBLISH,
283
+ label="Publish routes",
284
+ description="Publish a route draft you own (the route's owner role) "
285
+ "from an effective date. Each publish is recorded.",
286
+ group="Workflow",
287
+ privileged=True,
288
+ )
245
289
  authz.permission(
246
290
  ACT_ANY,
247
291
  label="Act on any docket",
@@ -336,6 +380,24 @@ RULES = (
336
380
  audit=True,
337
381
  ),
338
382
  authz.permit("workflow.problem_take_over", {TAKE_OVER}, when=authz.holds_for(USE)),
383
+ authz.permit(
384
+ "workflow.route_designer",
385
+ {DESIGNER, DESIGNER_EDIT},
386
+ when=authz.holds_for(ROUTE_DESIGN),
387
+ ),
388
+ authz.permit(
389
+ "workflow.route_owner_design",
390
+ {DESIGNER, DESIGNER_EDIT},
391
+ when=authz.all_of(authz.holds_for(USE), related({OWNS_ROUTE})),
392
+ ),
393
+ authz.permit(
394
+ # publishing changes how every new docket of the route moves: the
395
+ # permission AND owning the route, and every use is recorded
396
+ PUBLISH_RULE,
397
+ {DESIGNER_PUBLISH},
398
+ when=authz.all_of(authz.holds_for(ROUTE_PUBLISH), related({OWNS_ROUTE})),
399
+ audit=True,
400
+ ),
339
401
  authz.permit(
340
402
  "workflow.data_write",
341
403
  {SHEET_WRITE, HOLD_RELEASE},
@@ -366,6 +428,8 @@ FORBID_MASQUERADE = authz.forbid(
366
428
  HANDOVER,
367
429
  RESOLVE,
368
430
  TAKE_OVER,
431
+ DESIGNER_EDIT,
432
+ DESIGNER_PUBLISH,
369
433
  },
370
434
  when=authz.masquerading,
371
435
  )
@@ -708,6 +772,30 @@ def console_resource(relations) -> SeatResource:
708
772
  return SeatResource(CONSOLE_RESOURCE_TYPE, id="*", relations=frozenset(relations))
709
773
 
710
774
 
775
+ def route_owner_relations(seats: Seats, code, owner_role, entity) -> frozenset:
776
+ """``owns_route`` when ``seats`` own route ``code`` (``owner_role``, or
777
+ ``Seats.oversees``) for the route's ``entity`` — the person must have
778
+ seats there. A station lead is not an owner."""
779
+ if not seats.person or not seats.in_entity(entity):
780
+ return frozenset()
781
+ if seats.oversees_route(str(code), owner_role, entity=entity):
782
+ return frozenset({OWNS_ROUTE})
783
+ return frozenset()
784
+
785
+
786
+ def design_resource(code, entity, relations) -> SeatResource:
787
+ """A route (all its versions for one entity) for the Route designer's
788
+ actions, scoped by the route's entity (a shared route has no scope: the
789
+ permissions must be held site-wide)."""
790
+ return SeatResource(
791
+ ROUTE_RESOURCE_TYPE,
792
+ id=str(code),
793
+ tenant=entity,
794
+ scopes=entity_scope(entity),
795
+ relations=frozenset(relations),
796
+ )
797
+
798
+
711
799
  def resource(docket, relations, permission=None) -> DocketResource:
712
800
  return DocketResource(
713
801
  RESOURCE_TYPE,
@@ -720,6 +808,15 @@ def resource(docket, relations, permission=None) -> DocketResource:
720
808
 
721
809
 
722
810
  __all__ = [
811
+ "DESIGNER",
812
+ "DESIGNER_EDIT",
813
+ "DESIGNER_PUBLISH",
814
+ "OWNS_ROUTE",
815
+ "PUBLISH_RULE",
816
+ "ROUTE_DESIGN",
817
+ "ROUTE_PUBLISH",
818
+ "design_resource",
819
+ "route_owner_relations",
723
820
  "ACT",
724
821
  "ACT_ANY",
725
822
  "ASSIGN",