texas2step 2.4.1__tar.gz → 2.4.3__tar.gz

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.
Files changed (67) hide show
  1. {texas2step-2.4.1 → texas2step-2.4.3}/PKG-INFO +1 -1
  2. {texas2step-2.4.1 → texas2step-2.4.3}/docs/configuration.md +18 -5
  3. {texas2step-2.4.1 → texas2step-2.4.3}/docs/roadmap.md +14 -10
  4. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/__init__.py +1 -1
  5. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/api/measure.py +4 -1
  6. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/app.py +4 -2
  7. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/logs.py +52 -3
  8. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/page.py +11 -0
  9. texas2step-2.4.3/src/texas2step/static/assets/app.js +8 -0
  10. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/static/index.html +1 -1
  11. texas2step-2.4.1/src/texas2step/static/assets/app.js +0 -8
  12. {texas2step-2.4.1 → texas2step-2.4.3}/.gitignore +0 -0
  13. {texas2step-2.4.1 → texas2step-2.4.3}/LICENSE.md +0 -0
  14. {texas2step-2.4.1 → texas2step-2.4.3}/README.md +0 -0
  15. {texas2step-2.4.1 → texas2step-2.4.3}/deploy/nginx/texas2step-http.conf +0 -0
  16. {texas2step-2.4.1 → texas2step-2.4.3}/deploy/nginx/texas2step-log.conf +0 -0
  17. {texas2step-2.4.1 → texas2step-2.4.3}/deploy/nginx/texas2step-speedtest.conf +0 -0
  18. {texas2step-2.4.1 → texas2step-2.4.3}/deploy/nginx/texas2step.conf +0 -0
  19. {texas2step-2.4.1 → texas2step-2.4.3}/deploy/texas2step-update.service +0 -0
  20. {texas2step-2.4.1 → texas2step-2.4.3}/deploy/texas2step-update.timer +0 -0
  21. {texas2step-2.4.1 → texas2step-2.4.3}/deploy/texas2step.default +0 -0
  22. {texas2step-2.4.1 → texas2step-2.4.3}/deploy/texas2step.service +0 -0
  23. {texas2step-2.4.1 → texas2step-2.4.3}/docs/access.md +0 -0
  24. {texas2step-2.4.1 → texas2step-2.4.3}/docs/api.md +0 -0
  25. {texas2step-2.4.1 → texas2step-2.4.3}/docs/development.md +0 -0
  26. {texas2step-2.4.1 → texas2step-2.4.3}/docs/experience.md +0 -0
  27. {texas2step-2.4.1 → texas2step-2.4.3}/docs/images/hero-dark.jpg +0 -0
  28. {texas2step-2.4.1 → texas2step-2.4.3}/docs/images/results-dark.jpg +0 -0
  29. {texas2step-2.4.1 → texas2step-2.4.3}/docs/images/results-light.jpg +0 -0
  30. {texas2step-2.4.1 → texas2step-2.4.3}/docs/images/upload-light.jpg +0 -0
  31. {texas2step-2.4.1 → texas2step-2.4.3}/docs/install.md +0 -0
  32. {texas2step-2.4.1 → texas2step-2.4.3}/docs/methodology.md +0 -0
  33. {texas2step-2.4.1 → texas2step-2.4.3}/docs/security.md +0 -0
  34. {texas2step-2.4.1 → texas2step-2.4.3}/docs/traffic.md +0 -0
  35. {texas2step-2.4.1 → texas2step-2.4.3}/legacy/README.md +0 -0
  36. {texas2step-2.4.1 → texas2step-2.4.3}/pyproject.toml +0 -0
  37. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/__main__.py +0 -0
  38. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/access.py +0 -0
  39. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/api/__init__.py +0 -0
  40. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/api/access.py +0 -0
  41. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/api/meta.py +0 -0
  42. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/api/results.py +0 -0
  43. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/api/wire.py +0 -0
  44. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/cli.py +0 -0
  45. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/cluster.py +0 -0
  46. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/config.py +0 -0
  47. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/config_edit.py +0 -0
  48. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/config_merge.py +0 -0
  49. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/config_template.toml +0 -0
  50. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/engine.py +0 -0
  51. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/iface.py +0 -0
  52. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/lockouts.py +0 -0
  53. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/payload.py +0 -0
  54. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/quality.py +0 -0
  55. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/rtc.py +0 -0
  56. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/static/assets/app.css +0 -0
  57. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/static/assets/swagger/LICENSE +0 -0
  58. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/static/assets/swagger/NOTICE +0 -0
  59. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/static/assets/swagger/swagger-ui-bundle.js +0 -0
  60. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/static/assets/swagger/swagger-ui-bundle.js.LICENSE.txt +0 -0
  61. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/static/assets/swagger/swagger-ui.css +0 -0
  62. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/static/favicon.svg +0 -0
  63. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/stats.py +0 -0
  64. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/store.py +0 -0
  65. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/traffic.py +0 -0
  66. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/update.py +0 -0
  67. {texas2step-2.4.1 → texas2step-2.4.3}/src/texas2step/words.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: texas2step
3
- Version: 2.4.1
3
+ Version: 2.4.3
4
4
  Summary: Web-centric throughput, latency, jitter and packet-loss measurement between endpoints.
5
5
  Project-URL: Homepage, https://github.com/robert-patrick-texas/texas2step
6
6
  Project-URL: Documentation, https://robert-patrick-texas.github.io/texas2step/
@@ -167,11 +167,15 @@ url = "https://www.acme.example/accessibility"
167
167
  paragraph. The text is plain, but `[label](url)` makes a link of the label, by the same
168
168
  rules as the other links below. A URL ends at the first `)`. HTML isn't allowed, so it
169
169
  shows as typed. In TOML, `"""` lets the text run over several lines. The API explorer
170
- (`/api/docs`) is a separate page and has no footer of yours.
170
+ (`/api/docs`) is a separate page and has no footer of yours; it takes the name, as
171
+ "NetCheck API", and the logo as its icon.
171
172
  * **Logo.** SVG, PNG, JPEG, WebP or GIF, about 30 px tall on screen; wide logos keep their
172
- shape, up to 180 px wide. The `texas2step` service user must be able to read the file
173
- (`/etc/texas2step/` is a good place). If the file is missing or unreadable, the server
174
- logs a warning and keeps the star.
173
+ shape, up to 180 px wide. It is the browser tab's icon too, which browsers draw in a
174
+ small square, where a square logo works best. The `texas2step` service user must be
175
+ able to read the file (`/etc/texas2step/` is a good place). If the file is missing or
176
+ unreadable, the server logs a warning and keeps the star.
177
+ * **The command line.** The API tab's examples and History's hint name the `texas2step`
178
+ command, as it must be typed, on renamed sites too.
175
179
  * **Links** must start with `https://`, `http://`, `mailto:` or `tel:`, in
176
180
  `[[brand_links]]`, `[[brand_footer_links]]` and `brand_footer` alike. Anything else
177
181
  stops the server at startup with an error naming the setting. `[[brand_links]]` and
@@ -300,7 +304,8 @@ The service logs to the journal (`journalctl -u texas2step -f`), and by default
300
304
  needs attention:
301
305
 
302
306
  * start, stop and worker messages;
303
- * warnings and errors from texas2step and from the WebRTC libraries behind the UDP probe;
307
+ * warnings and errors from texas2step, from the WebRTC libraries behind the UDP probe,
308
+ and from any other library it uses;
304
309
  * a line for each request that failed (status 400 or above), such as an upload over
305
310
  `max_upload_bytes`:
306
311
 
@@ -308,6 +313,14 @@ needs attention:
308
313
  WARNING: 203.0.113.7 - "POST /api/v1/up HTTP/2.0" 413
309
314
  ```
310
315
 
316
+ The journal files each line at its level, so you can leave out the start and stop
317
+ messages:
318
+
319
+ ```bash
320
+ journalctl -u texas2step -p warning # warnings, errors and failed requests
321
+ journalctl -u texas2step -p err # errors only
322
+ ```
323
+
311
324
  The address is the client's, as `/api/v1/whoami` reports it: behind nginx, it comes from
312
325
  `X-Forwarded-For` (see `trusted_proxies`), and the HTTP version is the one the client
313
326
  used with nginx. Successful requests aren't logged, because nginx's access log already
@@ -51,16 +51,6 @@ is. Call quality, responsiveness, one stream and Monitor's call profiles came in
51
51
  name that shares its IP address and is covered by the same certificate, and a wildcard
52
52
  certificate makes that likely.
53
53
 
54
- ### Branding
55
-
56
- The [branding settings](configuration.md#branding-and-themes) replace the name, logo,
57
- links and footer credit. Three places still say texas2step:
58
-
59
- - [ ] **The browser tab's icon** is the texas2step star, even with `brand_logo` set. It
60
- could use that logo.
61
- - [ ] **The API explorer** (`/api/docs`) is titled "texas2step - Swagger UI".
62
- - [ ] **The API tab's command-line examples** name the `texas2step` CLI.
63
-
64
54
  ### Security
65
55
 
66
56
  - [ ] **DTLS 1.3 for the UDP probe.** The probe's data channel uses DTLS 1.2
@@ -122,6 +112,20 @@ links and footer credit. Three places still say texas2step:
122
112
 
123
113
  Newest first. Each release's notes have the details and its upgrade steps.
124
114
 
115
+ ### [2.4.3](https://github.com/robert-patrick-texas/texas2step/releases/tag/v2.4.3) (2026-10-26)
116
+
117
+ - [x] With `brand_logo` set, the logo is the browser tab's icon, in the API explorer too.
118
+ - [x] The API explorer takes `brand_name`, in its title and heading.
119
+ - [x] The API tab's command-line examples keep the `texas2step` command, which they need
120
+ to work, and install it from PyPI.
121
+
122
+ ### [2.4.2](https://github.com/robert-patrick-texas/texas2step/releases/tag/v2.4.2) (2026-10-26)
123
+
124
+ - [x] The journal files each line at its level, so `journalctl -u texas2step -p warning`
125
+ shows warnings, errors and failed requests.
126
+ - [x] History asks for the access code only where the server gives it, which logged a
127
+ warning on servers with codes off.
128
+
125
129
  ### [2.4.1](https://github.com/robert-patrick-texas/texas2step/releases/tag/v2.4.1) (2026-10-26)
126
130
 
127
131
  - [x] A UDP session closed while it connects stops its connection checks, which logged
@@ -1,3 +1,3 @@
1
1
  """texas2step: web-centric throughput, latency, jitter and packet-loss measurement."""
2
2
 
3
- __version__ = "2.4.1"
3
+ __version__ = "2.4.3"
@@ -28,7 +28,10 @@ _slots = asyncio.Semaphore(2)
28
28
 
29
29
  class Target(BaseModel):
30
30
  model_config = ConfigDict(str_strip_whitespace=True)
31
- target: str = Field(description="Base URL of a texas2step server, e.g. https://peer.example")
31
+ target: str = Field(
32
+ description="Base URL of the server to measure toward, e.g. https://peer.example: "
33
+ "one in [[locations]], unless allow_any_target is set"
34
+ )
32
35
 
33
36
 
34
37
  class LatencyRequest(Target):
@@ -10,6 +10,7 @@ import logging
10
10
  import re
11
11
  from collections.abc import AsyncGenerator
12
12
  from contextlib import asynccontextmanager
13
+ from html import escape
13
14
  from pathlib import Path
14
15
  from typing import ClassVar
15
16
  from urllib.parse import urlsplit
@@ -512,6 +513,7 @@ def create_app(settings: Settings | None = None) -> FastAPI:
512
513
  # FastAPI would record the first prefix it sees in "servers" for good. Set it per
513
514
  # request instead, so "Try it out" targets the address the explorer was opened at.
514
515
  spec = {**app.openapi(), "servers": [{"url": request.scope.get("root_path", "") or "/"}]}
516
+ spec["info"] = {**spec["info"], "title": settings.brand_name} # the explorer's heading
515
517
  if not shows_version(request): # as the page has it: not for visitors who need a code
516
518
  spec["info"] = {**spec["info"], "version": ""}
517
519
  return JSONResponse(spec)
@@ -524,10 +526,10 @@ def create_app(settings: Settings | None = None) -> FastAPI:
524
526
  assets = f"{root}/assets/swagger"
525
527
  explorer = get_swagger_ui_html(
526
528
  openapi_url=root + "/api/openapi.json",
527
- title=f"{app.title} - Swagger UI",
529
+ title=escape(f"{settings.brand_name} API"), # FastAPI writes it in as it is
528
530
  swagger_js_url=f"{assets}/swagger-ui-bundle.js?v={stamps.get('swagger-ui-bundle.js')}",
529
531
  swagger_css_url=f"{assets}/swagger-ui.css?v={stamps.get('swagger-ui.css')}",
530
- swagger_favicon_url=f"{root}/favicon.svg",
532
+ swagger_favicon_url=f"{root}/{shell.icon}",
531
533
  )
532
534
  explorer.headers["Content-Security-Policy"] = content_policy(
533
535
  bytes(explorer.body).decode(), []
@@ -1,7 +1,8 @@
1
1
  """What the server logs: quiet by default, verbose with ``debug = true``.
2
2
 
3
3
  uvicorn applies :func:`config` in every worker. Lines go to stderr, which systemd sends
4
- to the journal. One line per request comes from texas2step (``app.RequestLog``), with the
4
+ to the journal, each with its level as a syslog priority in front for journald to file
5
+ it by. One line per request comes from texas2step (``app.RequestLog``), with the
5
6
  client's real address behind nginx: successes at INFO and failures at WARNING, so the
6
7
  ``texas2step`` logger's level decides which are written.
7
8
  """
@@ -9,8 +10,12 @@ client's real address behind nginx: successes at INFO and failures at WARNING, s
9
10
  from __future__ import annotations
10
11
 
11
12
  import logging
13
+ import os
14
+ import sys
12
15
  from typing import Any
13
16
 
17
+ from uvicorn.logging import DefaultFormatter
18
+
14
19
  # uvicorn's own WebSocket lines, by their format strings. They show the proxy's address,
15
20
  # and RequestLog writes the same events with the client's.
16
21
  UVICORN_WEBSOCKET = ('"WebSocket %s"', "connection open", "connection closed")
@@ -21,9 +26,48 @@ class NoUvicornWebSockets(logging.Filter):
21
26
  return not any(text in str(record.msg) for text in UVICORN_WEBSOCKET)
22
27
 
23
28
 
29
+ def to_journal() -> bool:
30
+ """Whether stderr is systemd's stream to the journal, which it names in JOURNAL_STREAM
31
+ as device:inode. A program the service starts inherits the variable, not always the
32
+ stream."""
33
+ try:
34
+ device, inode = (int(n) for n in os.environ["JOURNAL_STREAM"].split(":"))
35
+ stat = os.fstat(sys.stderr.fileno())
36
+ except (KeyError, ValueError, OSError, AttributeError):
37
+ return False
38
+ return (stat.st_dev, stat.st_ino) == (device, inode)
39
+
40
+
41
+ def priority(level: int) -> int:
42
+ """The syslog priority of a logging level: 2 critical, 3 error, 4 warning, 6 info, 7 debug."""
43
+ for floor, value in ((logging.CRITICAL, 2), (logging.ERROR, 3), (logging.WARNING, 4)):
44
+ if level >= floor:
45
+ return value
46
+ return 6 if level >= logging.INFO else 7
47
+
48
+
49
+ class Formatter(DefaultFormatter):
50
+ """uvicorn's, with ``journal``: each line starts with its priority, as ``<4>``, which
51
+ journald files it by and drops (sd-daemon(3)). Without it, journald files every line
52
+ as info, and ``journalctl -p warning`` finds nothing. A traceback goes as many lines,
53
+ so each gets one."""
54
+
55
+ def __init__(self, *args: Any, journal: bool = False, **kwargs: Any) -> None:
56
+ super().__init__(*args, **kwargs)
57
+ self.journal = journal
58
+
59
+ def format(self, record: logging.LogRecord) -> str:
60
+ text = super().format(record)
61
+ if not self.journal:
62
+ return text
63
+ prefix = f"<{priority(record.levelno)}>"
64
+ return "\n".join(prefix + line for line in text.split("\n"))
65
+
66
+
24
67
  def config(debug: bool) -> dict[str, Any]:
25
68
  """A logging.config.dictConfig for uvicorn.run."""
26
69
  level = "DEBUG" if debug else "WARNING"
70
+ journal = to_journal()
27
71
 
28
72
  def logger(handler: str, level: str | None = None) -> dict[str, Any]:
29
73
  return {"handlers": [handler], "propagate": False} | ({"level": level} if level else {})
@@ -34,14 +78,16 @@ def config(debug: bool) -> dict[str, Any]:
34
78
  "filters": {"no_websockets": {"()": NoUvicornWebSockets}},
35
79
  "formatters": {
36
80
  "plain": {
37
- "()": "uvicorn.logging.DefaultFormatter",
81
+ "()": Formatter,
38
82
  "fmt": "%(levelprefix)s %(message)s",
39
83
  "use_colors": None,
84
+ "journal": journal,
40
85
  },
41
86
  "named": {
42
- "()": "uvicorn.logging.DefaultFormatter",
87
+ "()": Formatter,
43
88
  "fmt": "%(levelprefix)s %(name)s: %(message)s",
44
89
  "use_colors": None,
90
+ "journal": journal,
45
91
  },
46
92
  },
47
93
  "handlers": {
@@ -70,4 +116,7 @@ def config(debug: bool) -> dict[str, Any]:
70
116
  "aiortc": logger("named", level),
71
117
  "aiortc.rtcsctptransport": {"level": "INFO" if debug else "WARNING"},
72
118
  },
119
+ # Any other library's warnings and errors, such as asyncio's "Task exception was
120
+ # never retrieved", which logging's last resort used to write without a level.
121
+ "root": {"handlers": ["named"], "level": "WARNING"},
73
122
  }
@@ -65,6 +65,12 @@ class Shell:
65
65
  def __init__(self, settings: Settings, logo: Path | None) -> None:
66
66
  self.settings = settings
67
67
  self.logo_version = hashlib.sha256(logo.read_bytes()).hexdigest()[:10] if logo else None
68
+ self.logo_type = LOGO_TYPES[logo.suffix.lower()] if logo else None
69
+
70
+ @property
71
+ def icon(self) -> str:
72
+ """The browser tab's icon, relative to the site: the logo, or texas2step's star."""
73
+ return f"brand/logo?v={self.logo_version}" if self.logo_version else "favicon.svg"
68
74
 
69
75
  def render(
70
76
  self, template: str, root_path: str, version: str, hide: frozenset[str] = frozenset()
@@ -106,6 +112,11 @@ class Shell:
106
112
  if self.logo_version:
107
113
  mark = f'<img class="brand-mark" src="brand/logo?v={self.logo_version}" alt="" />'
108
114
  page = _fill(page, "mark", mark)
115
+ page = page.replace(
116
+ '<link rel="icon" href="favicon.svg" type="image/svg+xml" />',
117
+ f'<link rel="icon" href="{self.icon}" type="{self.logo_type}" />',
118
+ 1,
119
+ )
109
120
  if s.brand_notice:
110
121
  notice = f'<div class="notice" role="note">{escape(s.brand_notice)}</div>'
111
122
  page = _fill(page, "notice", notice)