traceact 0.6.1__tar.gz → 0.6.2__tar.gz

{traceact-0.6.1/traceact.egg-info → traceact-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traceact
-Version: 0.6.1
+Version: 0.6.2
 Summary: X-ray vision for your code. Lightweight action-level tracing for Python.
 Author: Mohammed Shehu
 License-Expression: MIT

{traceact-0.6.1 → traceact-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "traceact"
-version = "0.6.1"
+version = "0.6.2"
 description = "X-ray vision for your code. Lightweight action-level tracing for Python."
 readme = "README.md"
 requires-python = ">=3.9"

traceact-0.6.2/tests/test_viewer_instance.py

@@ -0,0 +1,257 @@
+# tests/test_viewer_instance.py
+#
+# Tests for viewer instance coordination: source deduplication, the
+# ?source=NAME pin that makes an app open on its own source, and the
+# state-file gating that keeps a deliberately-separate viewer private.
+#
+# These three behaviours are interlocking — the failure they prevent is one
+# app's viewer showing another app's traces — so they are tested together.
+
+import json
+import unittest.mock as mock
+
+import pytest
+
+from traceact.viewer.server import ViewerState
+
+
+# ---------------------------------------------------------------------------
+# add_source deduplication
+# ---------------------------------------------------------------------------
+
+class TestAddSourceDedupe:
+    def test_same_path_twice_returns_same_name(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        f.write_text("")
+        state = ViewerState()
+        first = state.add_source(str(f))
+        second = state.add_source(str(f))
+        assert first == second
+        assert len(state.sources) == 1
+
+    def test_repeated_adds_do_not_accumulate(self, tmp_path):
+        # The reported symptom: an app calling launch_or_connect() on every
+        # run produced traces-2, traces-3, traces-4 ... for one unchanging file.
+        f = tmp_path / "traces.jsonl"
+        f.write_text("")
+        state = ViewerState()
+        for _ in range(5):
+            state.add_source(str(f))
+        assert list(state.sources) == ["traces"]
+
+    def test_relative_and_absolute_path_dedupe(self, tmp_path, monkeypatch):
+        f = tmp_path / "traces.jsonl"
+        f.write_text("")
+        monkeypatch.chdir(tmp_path)
+        state = ViewerState()
+        a = state.add_source("traces.jsonl")
+        b = state.add_source(str(f))
+        assert a == b
+        assert len(state.sources) == 1
+
+    def test_path_with_dotdot_dedupes(self, tmp_path):
+        sub = tmp_path / "sub"
+        sub.mkdir()
+        f = sub / "traces.jsonl"
+        f.write_text("")
+        state = ViewerState()
+        a = state.add_source(str(f))
+        b = state.add_source(str(sub / ".." / "sub" / "traces.jsonl"))
+        assert a == b
+        assert len(state.sources) == 1
+
+    def test_distinct_paths_still_get_distinct_names(self, tmp_path):
+        # Dedupe must not collapse genuinely different files that happen to
+        # share a basename.
+        a_dir = tmp_path / "a"
+        b_dir = tmp_path / "b"
+        a_dir.mkdir()
+        b_dir.mkdir()
+        (a_dir / "traces.jsonl").write_text("")
+        (b_dir / "traces.jsonl").write_text("")
+        state = ViewerState()
+        n1 = state.add_source(str(a_dir / "traces.jsonl"))
+        n2 = state.add_source(str(b_dir / "traces.jsonl"))
+        assert n1 != n2
+        assert len(state.sources) == 2
+
+    def test_explicit_name_still_dedupes_by_path(self, tmp_path):
+        # The path is the identity; a different label for the same file must
+        # not create a second entry pointing at the same data.
+        f = tmp_path / "traces.jsonl"
+        f.write_text("")
+        state = ViewerState()
+        first = state.add_source(str(f), name="alpha")
+        second = state.add_source(str(f), name="beta")
+        assert first == second == "alpha"
+        assert len(state.sources) == 1
+
+
+# ---------------------------------------------------------------------------
+# launch_or_connect returns a ?source= pin
+# ---------------------------------------------------------------------------
+
+class TestLaunchOrConnectSourcePin:
+    def test_existing_viewer_url_pins_added_source(self):
+        from traceact.viewer import instance
+
+        with mock.patch.object(
+            instance, "find_running",
+            return_value={"host": "127.0.0.1", "port": 8765},
+        ), mock.patch.object(
+            instance, "add_source_to",
+            return_value={"name": "mylog", "path": "/x/mylog.jsonl"},
+        ):
+            url = instance.launch_or_connect(source="/x/mylog.jsonl")
+        assert url == "http://127.0.0.1:8765/?source=mylog"
+
+    def test_name_is_url_quoted(self):
+        from traceact.viewer import instance
+
+        with mock.patch.object(
+            instance, "find_running",
+            return_value={"host": "127.0.0.1", "port": 8765},
+        ), mock.patch.object(
+            instance, "add_source_to",
+            return_value={"name": "my log/1", "path": "/x"},
+        ):
+            url = instance.launch_or_connect(source="/x")
+        assert " " not in url
+        assert "my%20log%2F1" in url
+
+    def test_no_source_returns_bare_url(self):
+        from traceact.viewer import instance
+
+        with mock.patch.object(
+            instance, "find_running",
+            return_value={"host": "127.0.0.1", "port": 8765},
+        ):
+            url = instance.launch_or_connect()
+        assert url == "http://127.0.0.1:8765/"
+
+    def test_failed_add_falls_back_to_bare_url(self):
+        # add_source_to returns None when the running viewer can't be reached;
+        # a URL pinning a source that was never registered would be worse than
+        # no pin at all.
+        from traceact.viewer import instance
+
+        with mock.patch.object(
+            instance, "find_running",
+            return_value={"host": "127.0.0.1", "port": 8765},
+        ), mock.patch.object(instance, "add_source_to", return_value=None):
+            url = instance.launch_or_connect(source="/x/mylog.jsonl")
+        assert url == "http://127.0.0.1:8765/"
+
+
+# ---------------------------------------------------------------------------
+# TraceLog.view() preserves the ?source= pin
+# ---------------------------------------------------------------------------
+
+class TestViewPreservesSourcePin:
+    def test_pin_survives_with_no_filters(self, tmp_path):
+        from traceact import TraceLog
+
+        f = tmp_path / "traces.jsonl"
+        f.write_text("")
+        with mock.patch(
+            "traceact.viewer.instance.launch_or_connect",
+            return_value="http://127.0.0.1:8765/?source=mylog",
+        ), mock.patch("webbrowser.open"):
+            url = TraceLog(str(f)).view(open_browser=False)
+        assert "source=mylog" in url
+
+    def test_pin_and_prefilters_both_present(self, tmp_path):
+        from traceact import TraceLog
+
+        f = tmp_path / "traces.jsonl"
+        f.write_text("")
+        with mock.patch(
+            "traceact.viewer.instance.launch_or_connect",
+            return_value="http://127.0.0.1:8765/?source=mylog",
+        ), mock.patch("webbrowser.open"):
+            url = TraceLog(str(f)).filter(status="failed").view(open_browser=False)
+        assert "source=mylog" in url
+        assert "pf_status=failed" in url
+
+    def test_bare_base_url_still_works(self, tmp_path):
+        # Backward compatibility: a launch_or_connect that returns no query
+        # (no source given) must still produce a valid pre-filter URL.
+        from traceact import TraceLog
+
+        f = tmp_path / "traces.jsonl"
+        f.write_text("")
+        with mock.patch(
+            "traceact.viewer.instance.launch_or_connect",
+            return_value="http://127.0.0.1:8765/",
+        ), mock.patch("webbrowser.open"):
+            url = TraceLog(str(f)).filter(status="failed").view(open_browser=False)
+        assert url.startswith("http://127.0.0.1:8765/?")
+        assert "pf_status=failed" in url
+
+
+# ---------------------------------------------------------------------------
+# State-file gating: a private instance must not claim the shared slot
+# ---------------------------------------------------------------------------
+
+class TestPrivateInstanceStateGating:
+    """
+    `traceact view --port N` / `--new` starts a deliberately separate viewer.
+    Writing the shared state file from one would point the next
+    launch_or_connect() caller — a different app entirely — at this instance.
+    """
+
+    def _run_view(self, argv, monkeypatch):
+        """Run cli._run_view with the server loop stubbed out; return mocks."""
+        from traceact.viewer import cli
+
+        write_state = mock.MagicMock()
+        clear_state = mock.MagicMock()
+        fake_server = mock.MagicMock()
+        # serve_forever returns immediately so _run_view falls through to the
+        # finally block without blocking the test.
+        fake_server.serve_forever.side_effect = lambda: None
+
+        monkeypatch.setattr(cli._instance, "write_state", write_state)
+        monkeypatch.setattr(cli._instance, "clear_state", clear_state)
+        monkeypatch.setattr(cli, "_start_server", lambda h, p, s: (fake_server, p))
+        monkeypatch.setattr(
+            cli._instance, "find_running", lambda: None
+        )
+
+        parser = cli._build_parser()
+        args = parser.parse_args(argv)
+        rc = cli._run_view(args)
+        return rc, write_state, clear_state
+
+    def test_default_port_writes_state(self, monkeypatch):
+        rc, write_state, _ = self._run_view(["view", "--no-browser"], monkeypatch)
+        assert rc == 0
+        assert write_state.called
+
+    def test_explicit_port_does_not_write_state(self, monkeypatch):
+        rc, write_state, _ = self._run_view(
+            ["view", "--no-browser", "--port", "8951"], monkeypatch
+        )
+        assert rc == 0
+        assert not write_state.called
+
+    def test_new_flag_does_not_write_state(self, monkeypatch):
+        rc, write_state, _ = self._run_view(
+            ["view", "--no-browser", "--new"], monkeypatch
+        )
+        assert rc == 0
+        assert not write_state.called
+
+    def test_private_instance_does_not_clear_shared_state_on_exit(self, monkeypatch):
+        # A private instance clearing the state file on shutdown would evict a
+        # still-running shared viewer's entry.
+        rc, _, clear_state = self._run_view(
+            ["view", "--no-browser", "--port", "8951"], monkeypatch
+        )
+        assert rc == 0
+        assert not clear_state.called
+
+    def test_shared_instance_clears_state_on_exit(self, monkeypatch):
+        rc, _, clear_state = self._run_view(["view", "--no-browser"], monkeypatch)
+        assert rc == 0
+        assert clear_state.called

{traceact-0.6.1 → traceact-0.6.2}/traceact/__init__.py

@@ -70,7 +70,7 @@
 #   TraceActASGIMiddleware — ASGI middleware (FastAPI, Starlette). Same as
 #                   above for async frameworks.
 
-__version__ = "0.6.1"
+__version__ = "0.6.2"
 
 from traceact.config import configure, reset_config, TraceConfig
 from traceact.budget import TraceBudget

{traceact-0.6.1 → traceact-0.6.2}/traceact/log.py

@@ -292,8 +292,17 @@ class TraceLog:
             key = f"pf_{field}" if op == "eq" else f"pf_{field}__{op}"
             params.append((key, str(value)))
 
-        base = base_url if base_url.endswith("/") else base_url + "/"
-        url = base + ("?" + urlencode(params) if params else "")
+        # launch_or_connect returns a URL that may already carry ?source=NAME
+        # pinning the viewer to this log's source. Merge the pre-filters onto
+        # it rather than rebuilding from the origin, which would drop that pin
+        # and let the viewer open on some other app's source.
+        from urllib.parse import urlsplit, urlunsplit, parse_qsl
+        parts = urlsplit(base_url)
+        merged = parse_qsl(parts.query) + params
+        path = parts.path if parts.path else "/"
+        url = urlunsplit(
+            (parts.scheme, parts.netloc, path, urlencode(merged), "")
+        )
 
         if open_browser:
             import threading

{traceact-0.6.1 → traceact-0.6.2}/traceact/viewer/cli.py

@@ -167,7 +167,14 @@ def _run_view(args: argparse.Namespace) -> int:
     print(f"TraceAct viewer running at {url}")
     print("Press Ctrl+C to stop.")
 
-    _instance.write_state(args.host, port)
+    # Only a default-port instance advertises itself as the shared viewer.
+    # An instance the user deliberately separated — via --new or an explicit
+    # --port — stays private: claiming the state file would point the next
+    # launch_or_connect() caller (another app entirely) at this instance, so
+    # that app's traces would be POSTed here and it would open a viewer
+    # showing this one's source instead of its own.
+    if not args.new and not user_chose_port:
+        _instance.write_state(args.host, port)
 
     if not args.no_browser:
         threading.Timer(0.4, lambda: webbrowser.open(url)).start()
@@ -179,7 +186,11 @@ def _run_view(args: argparse.Namespace) -> int:
     finally:
         server.shutdown()
         server.server_close()
-        _instance.clear_state()
+        # Only clear the state file if this instance wrote it. A private
+        # instance clearing it would evict a still-running shared viewer's
+        # entry, making the next caller spawn a duplicate.
+        if not args.new and not user_chose_port:
+            _instance.clear_state()
     return 0
 
 

{traceact-0.6.1 → traceact-0.6.2}/traceact/viewer/instance.py

@@ -121,16 +121,24 @@ def launch_or_connect(
     URL is returned immediately — no new process is started.  If nothing is
     running a background subprocess is spawned, waited on for `timeout` seconds,
     and then the URL is returned (the server is usually ready in < 0.5 s).
+
+    The returned URL carries ``?source=<name>`` when a source was given, so the
+    viewer opens on *that* source. Without it, the front-end selects whichever
+    source is first in the list — so an app adding its source to a viewer
+    another app had already started would open showing the other app's traces.
     """
     import subprocess
     import sys
     import time
+    from urllib.parse import quote
 
     existing = find_running()
     if existing is not None:
         h, p = existing["host"], existing["port"]
         if source is not None:
-            add_source_to(h, p, source)
+            added = add_source_to(h, p, source)
+            if added and added.get("name"):
+                return f"http://{h}:{p}/?source={quote(added['name'], safe='')}"
         return f"http://{h}:{p}/"
 
     # Not running — start one in the background.
@@ -147,6 +155,14 @@ def launch_or_connect(
             break
         time.sleep(0.1)
 
+    # A freshly spawned viewer was seeded with this source on the command
+    # line, so it's the only one registered — but name it explicitly anyway,
+    # so the URL stays correct if another app adds a source before the tab
+    # is opened.
+    if source is not None:
+        names = list_source_names(host, port)
+        if names:
+            return f"http://{host}:{port}/?source={quote(names[0], safe='')}"
     return f"http://{host}:{port}/"
 
 
@@ -167,3 +183,18 @@ def add_source_to(host: str, port: int, path: str,
             return json.loads(resp.read().decode("utf-8"))
     except Exception:
         return None
+
+
+def list_source_names(host: str, port: int,
+                      timeout: float = 1.0) -> list:
+    """
+    Return the names of the sources registered with a running viewer, in the
+    order the viewer reports them. Empty list on any failure.
+    """
+    url = f"http://{host}:{port}/api/sources"
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as resp:
+            sources = json.loads(resp.read().decode("utf-8"))
+        return [s["name"] for s in sources if isinstance(s, dict) and "name" in s]
+    except Exception:
+        return []

{traceact-0.6.1 → traceact-0.6.2}/traceact/viewer/server.py

@@ -120,8 +120,16 @@ class ViewerState:
         If no name is given, one is derived from the path: the folder name for a
         directory, or the file's stem for a file. Collisions get a numeric
         suffix so two files with the same name stay distinct.
+
+        Adding a path that is already registered returns the existing name
+        rather than registering it again — an app that calls
+        launch_or_connect() on every run would otherwise accumulate
+        traces-2, traces-3, ... entries for one unchanging file.
         """
         path = os.path.abspath(os.path.expanduser(path))
+        for existing_name, existing_path in self.sources.items():
+            if existing_path == path:
+                return existing_name
         if name is None:
             name = _derive_name(path)
         name = self._unique_name(name)

{traceact-0.6.1 → traceact-0.6.2}/traceact/viewer/static/app.js

@@ -58,12 +58,19 @@ function init() {
   initPreFilters();      // reads ?pf_* URL params seeded by TraceLog.view()
 
   refreshSources().then(() => {
-    // If a source was seeded on the command line, stream the first one.
-    if (state.sources.length > 0) {
-      selectSource(state.sources[0].name);
-    } else {
+    if (state.sources.length === 0) {
       renderLog();
+      return;
     }
+    // ?source=NAME selects a specific source (set by launch_or_connect so an
+    // app opens on its OWN source, not whichever happens to be first in a
+    // viewer another app already started). Falls back to the first source
+    // when the param is absent, or names one that isn't registered here.
+    const requested = new URLSearchParams(window.location.search).get("source");
+    const match = requested
+      ? state.sources.find((s) => s.name === requested)
+      : null;
+    selectSource(match ? match.name : state.sources[0].name);
   });
 }
 
@@ -289,42 +296,56 @@ function inspectorSummary(t) {
   const touches = (t.touches || []).length;
   const errors = (t.errors || []).length;
 
+  // Two-column [label, value] pairs rather than pre-padded strings. A plain
+  // padded-text block (the previous approach) has no column boundary of its
+  // own, so a long value — a full correlation ID, shown untruncated so it
+  // stays copyable — either overflows the card or, once wrapped, spills its
+  // continuation under the label column instead of staying in the value
+  // column. Rendering as a CSS grid (see .insp-summary) gives the value its
+  // own column to wrap within, independent of the label column's width.
+  //
   // Always show this trace's own id. Parent and root are only shown when they
   // add information: a root trace has no parent and is its own root, so those
-  // lines would be noise. A child trace shows both, so the chain is visible.
-  const lines = [`Trace:    ${shortId(t.trace_id)}`];
+  // rows would be noise. A child trace shows both, so the chain is visible.
+  const rows = [["Trace:", shortId(t.trace_id)]];
   if (t.parent_trace_id) {
-    lines.push(`Parent:   ${shortId(t.parent_trace_id)}`);
+    rows.push(["Parent:", shortId(t.parent_trace_id)]);
   }
   if (t.root_trace_id && t.root_trace_id !== t.trace_id) {
-    lines.push(`Root:     ${shortId(t.root_trace_id)}`);
+    rows.push(["Root:", shortId(t.root_trace_id)]);
   }
   if (t.upstream_trace_id) {
     // The trace in another service that triggered this one. Shown in full for
     // the same reason as correlation id: it is meant to be copied and searched
     // against that other service's traces.
-    lines.push(`Upstream: ${t.upstream_trace_id}`);
+    rows.push(["Upstream:", t.upstream_trace_id]);
   }
   if (t.correlation_id) {
     // Shown in full (not shortId-truncated): the point of a correlation id is
     // to copy/search it outside the app (search box, jq, grep), so a 6-char
     // truncation would defeat the purpose.
-    lines.push(`Corr:     ${t.correlation_id}`);
+    rows.push(["Corr:", t.correlation_id]);
   }
-  lines.push(`Kind:     ${t.kind || ""}`);
-  lines.push(`Duration: ${fmtDurLong(t.duration_ms)}`);
-  lines.push(`Touches:  ${touches}`);
-  lines.push(`Errors:   ${errors}`);
+  rows.push(["Kind:", t.kind || ""]);
+  rows.push(["Duration:", fmtDurLong(t.duration_ms)]);
+  rows.push(["Touches:", String(touches)]);
+  rows.push(["Errors:", String(errors)]);
   if (t.sampled_out) {
     // A failure recorded from a sampled-out trace: steps/events are empty
     // because nothing was recording while the action ran.
-    lines.push(`Sampled:  error-only record (detail was not recorded)`);
+    rows.push(["Sampled:", "error-only record (detail was not recorded)"]);
   }
 
+  const summaryHtml = rows
+    .map(([label, value]) =>
+      `<span class="insp-label">${esc(label)}</span><span class="insp-value">${esc(value)}</span>`
+    )
+    .join("");
+
   return `
     <div class="insp-title">${esc(t.action)}</div>
     <div class="status status-${t.status}">● ${esc(t.status)}</div>
-    <div class="insp-summary">${esc(lines.join("\n"))}</div>
+    <div class="insp-summary">${summaryHtml}</div>
     <div class="insp-actions">
       <button class="btn btn-primary" id="btn-view-map">View trace</button>
       <button class="btn" id="btn-copy">Copy JSON</button>

{traceact-0.6.1 → traceact-0.6.2}/traceact/viewer/static/index.html

@@ -73,11 +73,11 @@
             <table class="log-table">
               <thead>
                 <tr>
-                  <th>TIME</th>
-                  <th>ACTION</th>
-                  <th>STATUS</th>
-                  <th>DUR.</th>
-                  <th>T·E·B</th>
+                  <th title="When the trace started">TIME</th>
+                  <th title="The traced action's name">ACTION</th>
+                  <th title="completed, failed, running, or cancelled">STATUS</th>
+                  <th title="How long the action took">DUR.</th>
+                  <th title="Touches · Errors · Budget — resources touched, errors recorded, and whether a recording limit was hit (Y) or not (—)">T·E·B</th>
                 </tr>
               </thead>
               <tbody id="log-body"></tbody>

{traceact-0.6.1 → traceact-0.6.2}/traceact/viewer/static/styles.css

@@ -413,10 +413,26 @@ body {
   border: 1px solid var(--border);
   border-radius: var(--radius);
   padding: 16px;
-  white-space: pre;
   color: var(--text-dim);
   font-size: 12.5px;
-  line-height: 1.9;
+  /* A real two-column grid, not padded text: the label column sizes to its
+     widest label and the value column takes the rest. A long value (a full
+     correlation UUID, shown untruncated so it stays copyable) wraps within
+     its own column instead of either overflowing the card or, once wrapped,
+     spilling its continuation under the label column. */
+  display: grid;
+  grid-template-columns: auto 1fr;
+  column-gap: 14px;
+  row-gap: 9px;
+}
+
+.insp-label {
+  color: var(--text-faint);
+  white-space: nowrap;
+}
+
+.insp-value {
+  overflow-wrap: anywhere;
 }
 
 .insp-actions { display: flex; gap: 10px; margin-top: 16px; }

{traceact-0.6.1 → traceact-0.6.2/traceact.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traceact
-Version: 0.6.1
+Version: 0.6.2
 Summary: X-ray vision for your code. Lightweight action-level tracing for Python.
 Author: Mohammed Shehu
 License-Expression: MIT

{traceact-0.6.1 → traceact-0.6.2}/traceact.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ tests/test_sinks.py
 tests/test_sqlite_sink.py
 tests/test_trace_hardening.py
 tests/test_tracelog.py
+tests/test_viewer_instance.py
 tests/test_viewer_query.py
 traceact/__init__.py
 traceact/budget.py