velocity-python 0.2.6__py3-none-any.whl → 0.2.7__py3-none-any.whl

velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.2.6"
+__version__ = version = "0.2.7"
 
 import importlib as _importlib
 

velocity/aws/failures.py

@@ -61,6 +61,13 @@ logger = logging.getLogger(__name__)
 EVENT_TYPE = "velocity.failure"
 EVENT_VERSION = 1
 TOPIC_CONFIG_KEY = "FailureTopicArn"
+# Where a person reads failures (a failure inbox screen); the email links it.
+INBOX_CONFIG_KEY = "FailureInboxUrl"
+# The site's IANA zone; the email shows when it happened there.
+TIMEZONE_CONFIG_KEY = "SiteTimezone"
+# SNS caps an email subject at 100 characters of plain ASCII.
+EMAIL_SUBJECT_LIMIT = 100
+SUMMARY_LIMIT = 300
 SOURCES = frozenset({"queue", "scheduler", "web", "webhook", "job"})
 
 MESSAGE_LIMIT = 1000
@@ -541,10 +548,17 @@ def build_event(
         "log_group": f"/aws/lambda/{function}" if function else None,
         "log_stream": os.environ.get("AWS_LAMBDA_LOG_STREAM_NAME") or None,
         "classification": None,
+        # for people (render_text / the alert email): where it failed, a
+        # one-line summary and what to do, from the exception's `summary` /
+        # `hint` attributes or `extra`
+        "where": frame or None,
+        "summary": _person_text(exc, extra, "summary", keys),
+        "hint": _person_text(exc, extra, "hint", keys),
     }
     if extra:
         event["extra"] = payload_excerpt(
-            {k: v for k, v in extra.items() if k != "message"}, keys
+            {k: v for k, v in extra.items() if k not in ("message", "summary", "hint")},
+            keys,
         )
     event["classification"] = _run_classify(
         classify if classify is not None else _classify, exc, event
@@ -552,55 +566,162 @@ def build_event(
     return event
 
 
+def _person_text(exc, extra, name, keys):
+    """An exception's ``summary``/``hint`` attribute, else ``extra[name]``;
+    scrubbed and trimmed, or None."""
+    value = getattr(exc, name, None) if exc is not None else None
+    if not value and extra:
+        value = extra.get(name)
+    if not value:
+        return None
+    return _truncate(scrub_text(" ".join(str(value).split()), keys), SUMMARY_LIMIT)
+
+
+def _local_time(occurred_at: Optional[str]) -> str:
+    """``Oct 20, 2026, 11:18 AM MDT`` in the site's zone (``SiteTimezone``),
+    else UTC; the raw value when it is not a timestamp."""
+    if not occurred_at:
+        return ""
+    try:
+        when = datetime.datetime.fromisoformat(str(occurred_at).replace("Z", "+00:00"))
+    except ValueError:
+        return str(occurred_at)
+    zone_name = None
+    try:
+        zone_name = _config(TIMEZONE_CONFIG_KEY)
+    except Exception:
+        zone_name = None
+    if zone_name:
+        try:
+            from zoneinfo import ZoneInfo
+
+            when = when.astimezone(ZoneInfo(str(zone_name)))
+        except Exception:
+            when = when.astimezone(datetime.timezone.utc)
+    hour = when.strftime("%I").lstrip("0") or "12"
+    return f"{when.strftime('%b')} {when.day}, {when.year}, {hour}:{when.strftime('%M %p %Z')}"
+
+
+def _cloudwatch_escape(value: str) -> str:
+    from urllib.parse import quote
+
+    return quote(quote(value, safe=""), safe="").replace("%", "$")
+
+
+def log_link(event: Optional[Dict[str, Any]]) -> str:
+    """The CloudWatch console page of the event's log stream, or ""."""
+    if not event or not event.get("log_group"):
+        return ""
+    region = os.environ.get("AWS_REGION")  # set in every Lambda
+    if not region:
+        return ""
+    url = (
+        f"https://{region}.console.aws.amazon.com/cloudwatch/home?region={region}"
+        f"#logsV2:log-groups/log-group/{_cloudwatch_escape(event['log_group'])}"
+    )
+    if event.get("log_stream"):
+        url += f"/log-events/{_cloudwatch_escape(event['log_stream'])}"
+    return url
+
+
+def _handled(event: Dict[str, Any]) -> Optional[bool]:
+    extra = event.get("extra")
+    if isinstance(extra, dict) and "handled" in extra:
+        return bool(extra["handled"])
+    return None
+
+
+_SOURCE_WORDS = {
+    "job": "a background job",
+    "queue": "a queued message",
+    "scheduler": "a scheduled task",
+    "request": "a request",
+}
+
+
 def render_text(event: Optional[Dict[str, Any]]) -> str:
-    """A plain-text rendering of an (already scrubbed) event, for email or
-    chat fallbacks. Contains nothing the event does not."""
+    """The failure for a person (the alert email, fallbacks): what failed,
+    the error in words, what to do, when (site-local time), whether it was
+    handled, where to look. Nothing beyond the event, the configured inbox
+    link and a log link."""
     if not event:
         return ""
-    lines = [
-        f"{event.get('site') or '?'} {event.get('env') or '?'} "
-        f"{event.get('source') or '?'} failure"
-        + (f" [{event['classification']}]" if event.get("classification") else ""),
-        "",
-    ]
-    for key in (
-        "function",
-        "action",
-        "job_id",
-        "request_id",
-        "message_id",
-        "receive_count",
-        "exception_type",
-        "message",
-        "occurred_at",
-        "fingerprint",
-        "log_group",
-        "log_stream",
+    site = event.get("site") or "?"
+    env = event.get("env") or "?"
+    exc_name = (event.get("exception_type") or "").rsplit(".", 1)[-1]
+    source = _SOURCE_WORDS.get(event.get("source"), event.get("source") or "something")
+    lines = [f"{site} ({env}): {source} failed", ""]
+
+    what = event.get("action") or event.get("source") or "?"
+    extra = event.get("extra") if isinstance(event.get("extra"), dict) else {}
+    details = [str(extra[k]) for k in ("capability",) if extra.get(k)]
+    subject = extra.get("subject")
+    lines.append(
+        f"What:     {what}"
+        + (f" ({', '.join(details)})" if details else "")
+        + (f", for {subject}" if subject else "")
+    )
+    error = event.get("summary") or event.get("message") or exc_name or "?"
+    lines.append(f"Error:    {error}" + (f" ({exc_name})" if exc_name else ""))
+    if event.get("hint"):
+        lines.append(f"To do:    {event['hint']}")
+    if event.get("occurred_at"):
+        lines.append(f"When:     {_local_time(event['occurred_at'])}")
+    handled = _handled(event)
+    if handled is True:
+        lines.append(
+            "Handled:  yes; it was recorded and the work is tried again on its next run"
+        )
+    elif handled is False:
+        lines.append("Handled:  no; the function stopped on it")
+    if event.get("classification"):
+        lines.append(f"Class:    {event['classification']}")
+    if event.get("receive_count"):
+        lines.append(f"Attempt:  {event['receive_count']}")
+    lines.append("")
+    if event.get("function"):
+        lines.append(f"Function: {event['function']}")
+    link = log_link(event)
+    if link:
+        lines.append(f"Log:      {link}")
+    inbox = None
+    try:
+        inbox = _config(INBOX_CONFIG_KEY)
+    except Exception:
+        inbox = None
+    if inbox:
+        lines.append(f"Inbox:    {inbox}")
+    lines.append("")
+    if event.get("where"):
+        lines.append(f"Where it failed: {event['where']}")
+    if (
+        event.get("summary")
+        and event.get("message")
+        and event["message"] != event["summary"]
     ):
-        value = event.get(key)
-        if value not in (None, ""):
-            lines.append(f"{key}: {value}")
-    for key in ("payload_excerpt", "extra"):
-        if event.get(key):
-            lines.append(f"{key}: {_render(event[key])}")
-    if event.get("traceback"):
-        lines.extend(["", "Traceback (scrubbed):", event["traceback"]])
+        lines.append(f"Raw message: {event['message']}")
+    if event.get("fingerprint"):
+        lines.append(f"Reference: {str(event['fingerprint'])[:12]}")
+    while lines and not lines[-1]:
+        lines.pop()
     return "\n".join(lines)
 
 
 def subject_line(event: Optional[Dict[str, Any]]) -> str:
-    """A one-line summary (≤ 200 chars) for an alert subject."""
+    """One line for an alert subject: site, env, what failed and the error in
+    words. Plain ASCII, at most 100 characters (SNS's email subject rules)."""
     if not event:
         return "Failure"
     exc_name = (event.get("exception_type") or "Failure").rsplit(".", 1)[-1]
-    parts = [
-        f"{(event.get('env') or '?').title()} {event.get('site') or ''}".strip(),
-        event.get("source") or "",
-        event.get("action") or "",
-    ]
-    label = f" [{event['classification']}]" if event.get("classification") else ""
-    head = " ".join(part for part in parts if part)
-    return _truncate(f"{head}: {exc_name}{label}", 200)
+    what = event.get("action") or event.get("source") or "something"
+    error = event.get("summary") or event.get("message") or exc_name
+    text = (
+        f"{event.get('site') or '?'} {event.get('env') or '?'}: {what} failed: {error}"
+    )
+    text = " ".join(text.split()).encode("ascii", "ignore").decode("ascii")
+    if len(text) > EMAIL_SUBJECT_LIMIT:
+        text = text[: EMAIL_SUBJECT_LIMIT - 3].rstrip() + "..."
+    return text
 
 
 def _run_fallback(event: Dict[str, Any]) -> None:
@@ -701,13 +822,7 @@ def report(
         return None
 
     try:
-        _client().publish(
-            TopicArn=topic_arn,
-            Message=_dumps(event),
-            MessageAttributes={
-                "velocity_event": {"DataType": "String", "StringValue": "failure"}
-            },
-        )
+        _client().publish(**publish_request(topic_arn, event))
     except Exception:
         logger.exception(
             "failures: publish to %s failed (fingerprint %s)",
@@ -718,6 +833,43 @@ def report(
     return event
 
 
+# SNS refuses a message over 256 KB; the email text is dropped to a short
+# form well before that (the inbox keeps the whole event).
+_SNS_MESSAGE_BUDGET = 240 * 1024
+
+
+def publish_request(topic_arn: str, event: Dict[str, Any]) -> Dict[str, Any]:
+    """The ``sns.publish`` arguments for one event. Subscribers each get their
+    own form (``MessageStructure="json"``): a Lambda (the failure inbox) and
+    every other protocol the event's JSON, unchanged; an ``email``
+    subscription the text a person reads (:func:`render_text`) under a
+    readable subject. The ``handled`` attribute ("true"/"false"/"unknown")
+    lets a subscription filter: the person's backstop email takes only
+    failures that were not handled."""
+    machine = _dumps(event)
+    person = render_text(event)
+    message = json.dumps({"default": machine, "email": person})
+    if len(message.encode("utf-8")) > _SNS_MESSAGE_BUDGET:
+        person = person[:4000] + "\n\n(shortened; the failure inbox has the rest)"
+        message = json.dumps({"default": machine, "email": person})
+    handled = _handled(event)
+    return {
+        "TopicArn": topic_arn,
+        "Message": message,
+        "MessageStructure": "json",
+        "Subject": subject_line(event),
+        "MessageAttributes": {
+            "velocity_event": {"DataType": "String", "StringValue": "failure"},
+            "handled": {
+                "DataType": "String",
+                "StringValue": (
+                    "unknown" if handled is None else ("true" if handled else "false")
+                ),
+            },
+        },
+    }
+
+
 def is_enabled() -> bool:
     """Whether ``FailureTopicArn`` resolves (events will be published)."""
     return bool(_config(TOPIC_CONFIG_KEY))

velocity/aws/handlers/context.py

@@ -27,7 +27,22 @@ from velocity.db.core.lazy_engine import LazyEngine
 engine = LazyEngine(velocity.db.postgres.initialize)
 
 
-cognito_client = boto3.client("cognito-idp")
+# The Cognito client is built on first use, not at import: creating it loads
+# Cognito's whole API model and resolves its endpoint (~13 MB and ~2 s on a
+# 128 MB Lambda), which every function importing a handler paid — a
+# Scheduler or queue worker that never signs anyone in included. Tests may
+# replace this attribute; whatever it holds is what `_cognito()` returns.
+cognito_client = None
+
+
+def _cognito():
+    """The shared Cognito client, created on first use."""
+    global cognito_client
+    if cognito_client is None:
+        cognito_client = boto3.client("cognito-idp")
+    return cognito_client
+
+
 logger = get_logger("velocity.aws.handlers.context")
 
 # Cognito User Pool id shape, e.g. "us-east-1_aBcD1234". Used to distinguish a
@@ -1036,18 +1051,19 @@ class Context:
         # one Cognito round trip per user per UserCacheSeconds per container
         # (velocity.cache); a lookup that fails is never cached
         def resolve():
+            client = _cognito()
             try:
                 self.perf.start("cognito admin_get_user")
-                response = cognito_client.admin_get_user(
+                response = client.admin_get_user(
                     UserPoolId=user_pool_id,
                     Username=user_sub,
                 )
                 self.perf.log("cognito admin_get_user")
                 resolved_username = response.get("Username")
-            except cognito_client.exceptions.UserNotFoundException:
+            except client.exceptions.UserNotFoundException:
                 try:
                     self.perf.start("cognito list_users")
-                    list_response = cognito_client.list_users(
+                    list_response = client.list_users(
                         UserPoolId=user_pool_id,
                         Filter=f'sub = "{user_sub}"',
                         Limit=1,

{velocity_python-0.2.6.dist-info → velocity_python-0.2.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.2.6
+Version: 0.2.7
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.2.6.dist-info → velocity_python-0.2.7.dist-info}/RECORD

@@ -1,4 +1,4 @@
-velocity/__init__.py,sha256=zI7efmr4RDHUvu7Mw3sLtHToFQqy55c8QIuqnJD8ZRo,362
+velocity/__init__.py,sha256=yFS8i5a6vkF9fvBhXU1pEodyDqxw4rkW3ZYGgOHV8g4,362
 velocity/cache.py,sha256=pthvw7gDVEXRzkTcQtA5YVf4Q1IxAamWsba4UReT0RE,8933
 velocity/logging.py,sha256=MAsZap1cDSdOBNRc_9ezQxup5dHOS0ARxU9NI_-UK3E,4037
 velocity/aws/__init__.py,sha256=XJJ79gnPlhg3aJij713PB8-vjQOt-BkqxYeGCBOxAu8,3460
@@ -8,7 +8,7 @@ velocity/aws/blobs.py,sha256=2TlTZ3KPxBdXDJ99aVSgDLR11wPQ8O3BbtNbY8mFQ28,9691
 velocity/aws/dirty_pipeline.py,sha256=DQHsCPQPWwiy_E7nxX8kO3DgvQTFkVDaDOjlBcmblyE,3331
 velocity/aws/email.py,sha256=CAvXTAUxJqMaT8ylpRwRcVEA4YLFMUuHCrwYLVE4G1E,6243
 velocity/aws/facets.py,sha256=vAXbp2PSjCTUzFpI84iUHvQoPXD1N-DJ6qIz9UhitFo,22574
-velocity/aws/failures.py,sha256=9H0yvo-mH2bfNytYAvDoocsOSjjGfDrRwwcAoB-SPrI,25172
+velocity/aws/failures.py,sha256=8rXWAikJZTVv7bybmcXI5geR6F_dfMw6ns-icuj9EN0,31378
 velocity/aws/feature_flags.py,sha256=G2S1Ifjjex1QEmaAnAwRISyawxfGTdzaKUh3150M5aw,9604
 velocity/aws/identity.py,sha256=u6f_oaVhDa3tNatsQkeXZPJDhMfXCzeDo1zGoTqW_Yo,5547
 velocity/aws/job_lifecycle.py,sha256=6ltzdrkSjU_pY0eU6UaGbGh_1X5RhE5F4hypEH6MoRA,2735
@@ -48,7 +48,7 @@ velocity/aws/deploy/reconcile.py,sha256=3xZXXiiVeCw4nUV8lKyk1XCgRbpNCLVYXIXbOLXe
 velocity/aws/deploy/targets.py,sha256=vmZzGbLDKNtWkwd2ado_ZhT8AT6nXYbJD5nIgDiBzRc,6632
 velocity/aws/handlers/__init__.py,sha256=0yvVADxMHK8JOhgGRxMIz1XkNGlUk08AOmdR4qhNP2U,906
 velocity/aws/handlers/base_handler.py,sha256=xa1H5lS3CCxuM5_LXva2bmvWxUzxARIqkjnkp7bux3s,19143
-velocity/aws/handlers/context.py,sha256=7tfhzhidxWEJExVpu5Uz_BWbGlC7Xj0n8sqyr67f0jI,47135
+velocity/aws/handlers/context.py,sha256=V6HOhVanplSibhmfNO_QgUQXkaQer3fLYfs2fDdl0zg,47707
 velocity/aws/handlers/context_factory.py,sha256=8rhYKrylzwQxBFqBckmF7jgWGZhfomLOT_Yu404CtJQ,784
 velocity/aws/handlers/exceptions.py,sha256=vChotaBjpPhvb_g058fGTnOG-vH1ZDMmHVwlj980DEg,2731
 velocity/aws/handlers/lambda_handler.py,sha256=WfB_tBoLZsQREUR3ZS4pkLLwevqozjJsA_yfHBrcc5Y,21358
@@ -223,9 +223,9 @@ velocity/payment/stripe_adapter.py,sha256=6EmVBZZchg2s3Teya0eQGA_8pvSK_teizr036U
 velocity/payment/stripe_mirror.py,sha256=6GKJk_PjAgySqFEuxbcuV423OfuGXupVTiGu9QwS5W8,12320
 velocity/testing/__init__.py,sha256=WtYMDHgCLxOq6mlemcOYV5Y9HqF_2QQgSfuAjFRg69Q,731
 velocity/testing/fake_db.py,sha256=phgdulk5owf3noUDpEfI7yFsVcKxRGZ82f2BJPYnaiU,53226
-velocity_python-0.2.6.dist-info/licenses/LICENSE,sha256=aoN245GG8s9oRUU89KNiGTU4_4OtnNmVi4hQeChg6rM,1076
-velocity_python-0.2.6.dist-info/METADATA,sha256=un8yKry0URcUzfnJhcmA7PolBjxeQvmk2WH7Ag0KHo0,17782
-velocity_python-0.2.6.dist-info/WHEEL,sha256=a-udL2m4V_6Yn8b-uKzWb12RjRxwwMo6ohYFM24tpaY,91
-velocity_python-0.2.6.dist-info/entry_points.txt,sha256=nXUKJHkOGQCSPoagdmMNd_qycrle1LVU-GhYknLGM1M,56
-velocity_python-0.2.6.dist-info/top_level.txt,sha256=JW2vJPmodgdgSz7H6yoZvnxF8S3fTMIv-YJWCT1sNW0,9
-velocity_python-0.2.6.dist-info/RECORD,,
+velocity_python-0.2.7.dist-info/licenses/LICENSE,sha256=aoN245GG8s9oRUU89KNiGTU4_4OtnNmVi4hQeChg6rM,1076
+velocity_python-0.2.7.dist-info/METADATA,sha256=jAHTQgrhvkAti0u-f01xNGRUki6kHB7euSsM3l-iPBY,17782
+velocity_python-0.2.7.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+velocity_python-0.2.7.dist-info/entry_points.txt,sha256=nXUKJHkOGQCSPoagdmMNd_qycrle1LVU-GhYknLGM1M,56
+velocity_python-0.2.7.dist-info/top_level.txt,sha256=JW2vJPmodgdgSz7H6yoZvnxF8S3fTMIv-YJWCT1sNW0,9
+velocity_python-0.2.7.dist-info/RECORD,,

{velocity_python-0.2.6.dist-info → velocity_python-0.2.7.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (84.2.0)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any