@vibelord/lanes 1.2.0 → 1.5.0

package/payload/lanes/libexec/notify.py

@@ -31,10 +31,17 @@ NEEDS_YOU set. The six-word `state` is never read: the agent status is the only
     device_active).
   * Payload: `<lane name>: <agent task> — <status>` and, on a second line, the client command that opens the lane
     (`lanes-launch lane <id>`). No client registers a URL scheme for it, so the push carries a tappable action only
-    when `action_url` (a template over `{lane}`) is configured.
+    when `action_url` (a template over `{lane}`, and `{doc}` for a `published` event — `action_url()`) is configured.
   * A failed send is one journal line (lane id and the failure class — never the topic or the bearer) and is not
     retried; it never stops the service.
 
+Published documents (plan W10 W4): the docs service's publish pick-up (`lanes-docsd`, docsd.Pickup), not this
+service, calls `notify_published` once a document an agent published from a lane is stored — the same config, the
+same desk-presence rule (device_active) and the same `send`, at most one push per lane per minute (docsd's
+PUBLISHED_PUSH_S), best effort. Its payload is `{title: 'Published', message: '<lane name> published a document (<kind>,
+<size>)\n/lanes-docs/d/<id>', priority: 2}` and, when `action_url` is set, the tap target with `{doc}` resolved —
+never the document's title, name or content: the topic is the host's, and the document may be for one login only.
+
 Enrolment requests (W8 A5, LNS-44): the same service also watches `STATE/enrol-requests/` (lanes-enrold's store;
 read through `enrold.load_requests`, so a request announced is one `lanes enrol list` shows). A request that is
 pending — not approved, denied or past `expires_at` — and has not been announced yet yields ONE push:
@@ -55,7 +62,9 @@ Config `~/.config/lanes/notify.conf` (`LANES_NOTIFY_CONF` overrides the path), `
 `url` (ntfy server, http/https, required), `topic` (`[A-Za-z0-9_-]{1,64}`, required), `token_file` (a file holding
 an ntfy access token, optional — sent as a bearer, never logged; an unreadable one disables sending rather than
 sending unauthenticated), `quiet_when_device_active_s` (default 120; 0 never suppresses), `action_url` (optional
-template, e.g. `https://lanes.example/?lane={lane}`). Without a valid `url` and `topic` the service only tracks
+template, e.g. `https://lanes.example/?lane={lane}`; plan W10 W7 adds `{doc}`, the page `/lanes-docs/d/<id>` of the
+document a `published` push names — empty for a needs-you push; the docs service sends those, W4). Without a valid
+`url` and `topic` the service only tracks
 transitions and sends nothing. The config is re-read when notify.conf OR its `token_file` changes (inode, size,
 mtime or ctime, so a token written, rotated, removed or chmod-ed after notify.conf counts), and on every tick while
 sending is disabled, so a token that becomes readable switches the pushes on within one interval.
@@ -76,6 +85,7 @@ import urllib.request
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docs_store  # noqa: E402
 import enrold as E  # noqa: E402
 import lanes_lib as L  # noqa: E402
 import tokens  # noqa: E402
@@ -95,6 +105,8 @@ PRESENCE = '*.pid'                                        # clients/ files only
 SEEN = '.seen.json'                                       # a sidebar's opened-lane record; desk devices only
                                                           # (a .pid of any age, devices/<device>.json not mobile)
                                                           # users/<login>.json written by a desk device counts too
+PUBLISHED_TITLE = 'Published'                            # a document published from a lane (notify_published)
+PUBLISHED_PRIORITY = 2
 ENROL_DIR = 'enrol-requests'                              # STATE/<this>/<id>.json: lanes-enrold's requests
 ENROL_SEEN = 'notify.enrol-seen.json'                     # STATE/<this>: the request ids already announced
 ENROL_TITLE = 'Enrol request'
@@ -275,6 +287,18 @@ def device_active(clients_dir, window, now, devices_dir=None, users_dir=None, me
     return any(within(at, window) for _login, at in marks)
 
 
+def action_url(template, lane_id, doc_id=None):
+    """notify.conf's `action_url` template made a push's tap target -> the URL, or '' without a template. `{lane}` is
+    the lane id; `{doc}` (plan W10 W7) the page of the document a `published` event is about, `/lanes-docs/d/<id>`
+    (docs_store.URL; a docs_store id, else nothing), and nothing for an event without one (a needs-you push) — so
+    `https://<host>:8443{doc}` opens the document. Both are percent-quoted."""
+    if not template:
+        return ''
+    doc = docs_store.URL.format(doc_id) if isinstance(doc_id, str) and docs_store.ID_RE.match(doc_id) else ''
+    return (template.replace('{lane}', urllib.parse.quote(lane_id, safe=''))
+            .replace('{doc}', urllib.parse.quote(doc, safe='/')))
+
+
 def _note(lane_id, status, agent, names, config):
     label = LABELS.get(status, status)
     name = _text(names.get(lane_id) or lane_id)
@@ -282,14 +306,50 @@ def _note(lane_id, status, agent, names, config):
     first = _line(f'{name}: {task} — {label}' if task else f'{name} — {label}')
     note = {'lane': lane_id, 'status': status, 'title': label,
             'message': f'{first}\nlanes-launch lane {lane_id}', 'priority': PRIORITY.get(status, 3)}
-    template = config.get('action_url') or ''
-    if template:
-        url = template.replace('{lane}', urllib.parse.quote(lane_id, safe=''))
+    url = action_url(config.get('action_url') or '', lane_id)
+    if url:
         note['click'] = url
         note['actions'] = [{'action': 'view', 'label': 'Open lane', 'url': url}]
     return note
 
 
+def _size(size):
+    if size < 1024:
+        return f'{size} B'
+    return f'{size / 1024:.1f} KiB' if size < 1024 * 1024 else f'{size / (1024 * 1024):.1f} MiB'
+
+
+def published_note(lane_id, meta, names, config):
+    """The push for a document stored from lane `lane_id` (`meta` its docs_store meta): the lane's name, the kind and
+    the size, and the document's page (module docstring) — never its title, name or content."""
+    name = _text(names.get(lane_id) or lane_id)
+    first = _line(f"{name} published a document ({_text(meta.get('kind'))}, {_size(int(meta.get('bytes') or 0))})")
+    note = {'lane': lane_id, 'status': 'published', 'doc': meta['id'], 'title': PUBLISHED_TITLE,
+            'message': f"{first}\n{docs_store.URL.format(meta['id'])}", 'priority': PUBLISHED_PRIORITY}
+    url = action_url(config.get('action_url') or '', lane_id, meta['id'])
+    if url:
+        note['click'] = url
+        note['actions'] = [{'action': 'view', 'label': 'Open document', 'url': url}]
+    return note
+
+
+def notify_published(lane_id, meta, names=None, conf_path=None, state=None, now=None, opener=None):
+    """Send the `published` push for a stored document (the docs service's pick-up calls it, W4) -> the note sent, or
+    None: sending disabled (no valid notify.conf at `conf_path`, else $LANES_NOTIFY_CONF, else the default), somebody
+    at a desk (device_active over `state`, default L.STATE), or the send failed (one journal line). Never raises for a
+    failed send; the caller rate-limits."""
+    config = read_config(conf_path or os.environ.get('LANES_NOTIFY_CONF') or DEFAULT_CONF)
+    if not config['enabled']:
+        return None
+    state = Path(state) if state is not None else L.STATE
+    now = time.time() if now is None else now
+    window = int(config.get('quiet_when_device_active_s', DEFAULT_QUIET) or 0)
+    if device_active(state / 'clients', window, now, state / 'devices'):
+        return None
+    note = published_note(lane_id, meta, names or {}, config)
+    return note if send(note, config, opener) else None
+
+
 def notify_changes(prev_status, new_status, config, names=None, now=None, clients_dir=None, devices_dir=None):
     """The notifications for lanes whose agent status ENTERED needs-you between two status.json documents.
     `prev_status` None = the first read: seed only, nothing is news. Empty when a desk device is present."""