askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
nav_entries.py · 9.6 KB · 253 lines
| 1 | """action_nav_entries -- the doors this caller may be shown, grouped. |
| 2 | |
| 3 | POST/GET {} -> {ok, groups: [{group, entries: [...]}], attention: [...], count} |
| 4 | |
| 5 | Every navigation surface on this server is meant to be a FOLD over one |
| 6 | registry rather than a list somebody maintains: the app switcher in |
| 7 | site_nav, the tile grid on site_home, and anything built next. This is |
| 8 | that fold, and it lives in an object rather than in each surface because |
| 9 | the visibility rule -- who is allowed to SEE a door -- is a rule, and a |
| 10 | rule copied into two renderers is a rule that will be enforced two |
| 11 | different ways within a year. |
| 12 | |
| 13 | Three tiers, decided here once: |
| 14 | |
| 15 | - `public` entries are returned to anyone, signed in or not. |
| 16 | - `member` entries need a signed-in identity. |
| 17 | - `operator` entries need an admin role, the same check system_scheduler |
| 18 | makes before it will draw the task board. |
| 19 | |
| 20 | Two kinds of row are never returned at all: `surface: hidden` (the |
| 21 | package registered a door it does not want rendered) and |
| 22 | `operator_hidden` (the operator took it off this deployment's menu). The |
| 23 | second is the reason they are separate columns -- the package says what |
| 24 | the app IS, the operator says what they want to SEE, and an install |
| 25 | restates the first without ever touching the second. |
| 26 | |
| 27 | This is a MENU, not a gate. Permissions decide who may actually open a |
| 28 | page; leaving a door off the menu hides nothing that was not already |
| 29 | protected, and putting one on it grants nothing. |
| 30 | |
| 31 | It also carries the ATTENTION counts, because they are the cheapest half |
| 32 | of a home screen and belong on a list people already look at: an entry |
| 33 | whose queue is non-empty comes back with `count`, `detail` and |
| 34 | `severity`, so the app list reads "Invoices - 5 overdue" with no second |
| 35 | surface to maintain. The numbers are read from `attention_counts`, the |
| 36 | small table the daemon's rollup writes; nothing here folds a business |
| 37 | collection, which is the rule that keeps this object's cost flat as |
| 38 | packages are installed. |
| 39 | |
| 40 | **Zero contributes nothing.** A row whose count is zero is dropped |
| 41 | entirely rather than returned as a zero, because an empty queue is not |
| 42 | news, and a surface that is handed zeros will eventually render them. |
| 43 | """ |
| 44 | |
| 45 | import os |
| 46 | |
| 47 | import object_records |
| 48 | |
| 49 | ACTOR = "action_nav_entries" |
| 50 | |
| 51 | _DEFAULT_GROUP = "Apps" |
| 52 | _DEFAULT_ORDER = 100 |
| 53 | _TRUE = ("true", "1", "yes", "on") |
| 54 | |
| 55 | # Loudest first on every surface that sorts by it. Three steps, because a |
| 56 | # scale with more is a scale nobody calibrates. |
| 57 | _SEVERITY_RANK = {"urgent": 0, "warning": 1, "normal": 2} |
| 58 | _DEFAULT_SEVERITY = "normal" |
| 59 | |
| 60 | |
| 61 | def _base_dir(): |
| 62 | return os.environ.get("DBBASIC_DATA_DIR", "data") |
| 63 | |
| 64 | |
| 65 | def _text(value): |
| 66 | return str(value if value is not None else "").strip() |
| 67 | |
| 68 | |
| 69 | def _order(row): |
| 70 | try: |
| 71 | return int(_text(row.get("order")) or _DEFAULT_ORDER) |
| 72 | except (TypeError, ValueError): |
| 73 | # A hand-edited order that will not parse sorts to the back |
| 74 | # rather than taking the whole menu down with it. |
| 75 | return _DEFAULT_ORDER |
| 76 | |
| 77 | |
| 78 | def _visible_surfaces(identity): |
| 79 | """Which tiers this caller may be shown. |
| 80 | |
| 81 | An anonymous visitor sees the public web; any signed-in user is a |
| 82 | member; an admin role additionally sees the operator surfaces. The |
| 83 | admin test is `"admin" in identity["roles"]`, copied from |
| 84 | system_scheduler rather than reinvented, so there is one answer on |
| 85 | this server to "is this an operator?". |
| 86 | """ |
| 87 | identity = identity or {} |
| 88 | surfaces = {"public"} |
| 89 | if _text(identity.get("user_id")): |
| 90 | surfaces.add("member") |
| 91 | if "admin" in (identity.get("roles") or []): |
| 92 | surfaces.add("operator") |
| 93 | return surfaces |
| 94 | |
| 95 | |
| 96 | def _count(row): |
| 97 | try: |
| 98 | return int(_text(row.get("count")) or 0) |
| 99 | except (TypeError, ValueError): |
| 100 | # A hand-edited count that will not parse is not a queue of |
| 101 | # unknown size, it is a broken cell: it contributes nothing rather |
| 102 | # than taking the whole menu down with it. |
| 103 | return 0 |
| 104 | |
| 105 | |
| 106 | def _attention_rows(identity): |
| 107 | """Every non-zero attention count this caller is entitled to see. |
| 108 | |
| 109 | Sorted loudest first: severity, then size, then label. That order is |
| 110 | decided here rather than in each renderer for the same reason the |
| 111 | visibility tiers are -- a rule copied into two surfaces is a rule that |
| 112 | will be enforced two different ways within a year. |
| 113 | |
| 114 | Anonymous visitors get nothing at all. These are internal work |
| 115 | queues, and how many receipts are unconfirmed is a fact about how a |
| 116 | business is running, not part of the public web. Rows that name a |
| 117 | nav entry are additionally held to that entry's own tier, so an |
| 118 | operator-only door does not leak a count to a member. |
| 119 | """ |
| 120 | if not _text((identity or {}).get("user_id")): |
| 121 | return [] |
| 122 | try: |
| 123 | rows = object_records.read_collection_records( |
| 124 | "attention_counts", base_dir=_base_dir()) |
| 125 | except Exception: |
| 126 | # The rollup is not installed, or has never run. No counts is a |
| 127 | # real answer and exactly what "nothing needs you" looks like. |
| 128 | return [] |
| 129 | |
| 130 | attention = [] |
| 131 | for row in rows: |
| 132 | count = _count(row) |
| 133 | if count <= 0: |
| 134 | continue # an empty queue is not news |
| 135 | severity = _text(row.get("severity")).lower() or _DEFAULT_SEVERITY |
| 136 | attention.append({ |
| 137 | "id": _text(row.get("id")), |
| 138 | "label": _text(row.get("label")), |
| 139 | "path": _text(row.get("path")), |
| 140 | "nav_id": _text(row.get("nav_id")), |
| 141 | "group": _text(row.get("group")) or _DEFAULT_GROUP, |
| 142 | "severity": severity, |
| 143 | "count": count, |
| 144 | "detail": _text(row.get("detail")), |
| 145 | "computed_at": _text(row.get("computed_at")), |
| 146 | "error": _text(row.get("error")), |
| 147 | }) |
| 148 | attention.sort(key=lambda row: (_SEVERITY_RANK.get(row["severity"], 9), |
| 149 | -row["count"], row["label"])) |
| 150 | return attention |
| 151 | |
| 152 | |
| 153 | def _decorate(entries, attention): |
| 154 | """Hang each entry's loudest count on it, in place. |
| 155 | |
| 156 | One count per door, deliberately. A menu line can carry one number, |
| 157 | and the full list -- including the queues whose package ships no door |
| 158 | at all -- is what the home band is for. When two sources name the |
| 159 | same entry the louder one wins, which is already the order |
| 160 | `attention` arrives in. |
| 161 | """ |
| 162 | by_nav = {} |
| 163 | for row in attention: |
| 164 | if row["nav_id"] and row["nav_id"] not in by_nav: |
| 165 | by_nav[row["nav_id"]] = row |
| 166 | for entry in entries: |
| 167 | row = by_nav.get(entry["id"]) |
| 168 | if row is None: |
| 169 | continue |
| 170 | entry["count"] = row["count"] |
| 171 | entry["detail"] = row["detail"] |
| 172 | entry["severity"] = row["severity"] |
| 173 | |
| 174 | |
| 175 | def _entries(request): |
| 176 | identity = request.get("_identity") or {} |
| 177 | surfaces = _visible_surfaces(identity) |
| 178 | try: |
| 179 | rows = object_records.read_collection_records("nav_entries", base_dir=_base_dir()) |
| 180 | except Exception: |
| 181 | # The registry is not installed yet. An empty menu is a real |
| 182 | # answer; the callers fall back to their own shipped list. |
| 183 | return [] |
| 184 | |
| 185 | visible = [] |
| 186 | for row in rows: |
| 187 | if _text(row.get("operator_hidden")).lower() in _TRUE: |
| 188 | continue |
| 189 | surface = _text(row.get("surface")).lower() or "member" |
| 190 | if surface not in surfaces: |
| 191 | continue |
| 192 | path = _text(row.get("path")) |
| 193 | if not path: |
| 194 | continue |
| 195 | visible.append({ |
| 196 | "id": _text(row.get("id")), |
| 197 | "label": _text(row.get("label")) or path, |
| 198 | "path": path, |
| 199 | "blurb": _text(row.get("blurb")), |
| 200 | "group": _text(row.get("group")) or _DEFAULT_GROUP, |
| 201 | "surface": surface, |
| 202 | "order": _order(row), |
| 203 | "package": _text(row.get("package")), |
| 204 | }) |
| 205 | |
| 206 | # A group sorts where its earliest entry sorts. Packages band their |
| 207 | # `order` values (Work in the 0s, Publishing the 200s, Money the |
| 208 | # 300s, and so on), so the reading order of the menu falls out of the |
| 209 | # same number that orders entries within a group -- rather than out |
| 210 | # of the alphabet, which would put System before Work, or out of a |
| 211 | # hardcoded group table, which would be a fourth list to maintain. |
| 212 | rank = {} |
| 213 | for entry in visible: |
| 214 | group = entry["group"] |
| 215 | rank[group] = min(rank.get(group, entry["order"]), entry["order"]) |
| 216 | visible.sort(key=lambda entry: (rank[entry["group"]], entry["group"], |
| 217 | entry["order"], entry["label"])) |
| 218 | return visible |
| 219 | |
| 220 | |
| 221 | def _grouped(entries): |
| 222 | """Group-preserving fold over an already-sorted list. |
| 223 | |
| 224 | The sort put every group together, so grouping is one pass and the |
| 225 | group order is the sort's order -- no second sort key to disagree |
| 226 | with the first one. |
| 227 | """ |
| 228 | groups = [] |
| 229 | for entry in entries: |
| 230 | if not groups or groups[-1]["group"] != entry["group"]: |
| 231 | groups.append({"group": entry["group"], "entries": []}) |
| 232 | groups[-1]["entries"].append(entry) |
| 233 | return groups |
| 234 | |
| 235 | |
| 236 | def POST(request): |
| 237 | entries = _entries(request) |
| 238 | attention = _attention_rows(request.get("_identity") or {}) |
| 239 | # A count attached to a door nobody may see would leak the door. The |
| 240 | # visible set is already decided above, so the filter is a membership |
| 241 | # test rather than a second copy of the tier rule. |
| 242 | visible_ids = {entry["id"] for entry in entries} |
| 243 | attention = [row for row in attention |
| 244 | if not row["nav_id"] or row["nav_id"] in visible_ids] |
| 245 | _decorate(entries, attention) |
| 246 | return {"ok": True, "groups": _grouped(entries), "entries": entries, |
| 247 | "attention": attention, "count": len(entries)} |
| 248 | |
| 249 | |
| 250 | def GET(request): |
| 251 | # Same answer either way: reading the menu is a read. GET is what the |
| 252 | # nav script fetches; POST is what a sibling object calls in-process. |
| 253 | return POST(request) |