tunguyen35/pingvn

1. What this repo is

- This is a TypeScript/JavaScript measurement library, published as @cloudflare/speedtest.

- The core runtime is browser-side: it measures network quality from a client device against Cloudflare edge endpoints, using browser network timing APIs and WebRTC for packet loss.

2. Primary architecture boundary

- The main boundary is between the public API surface and the measurement engine internals.

- src/index.ts is the library entrypoint; consumers instantiate SpeedTest, configure it, and receive callbacks/results.

- Everything under src/engines, src/Results, src/config, src/utils, and src/logging supports that one public class.

3. Orchestration layer

- The speedtest is driven by a central orchestrator that sequences measurement steps: latency, download, upload, packet loss, and reachability.

- The configured measurement plan is an ordered list, so the system is fundamentally a pipeline of measurement tasks rather than a single monolithic test.

- The engine exposes lifecycle control: start, pause, restart, running state, finish state, and event callbacks.

4. Measurement engines

- src/engines/Latency is implemented through the download API with zero-byte requests and uses request timing to compute RTT-like latency.

- src/engines/BandwidthEngine handles download and upload ramps, including “loaded latency” sampling while transfers are in progress.

- src/engines/PacketLossEngine uses WebRTC/UDP via a TURN server to count lost packets.

- src/engines/ReachabilityEngine appears to be a lighter connectivity check stage.

- The Engine.ts abstraction suggests these are interchangeable measurement units behind a shared contract.

5. Data sources and network dependencies

- Download and upload measurements target Cloudflare HTTP APIs, defaulting to https://speed.cloudflare.com/__down and https://speed.cloudflare.com/__up.

- Latency and bandwidth calculations depend on PerformanceResourceTiming browser data, not just fetch completion time.

- Packet loss is a separate network path using TURN/WebRTC, with credentials optionally fetched from a credentials API or supplied directly.

6. Results pipeline

- src/Results is the post-processing layer that turns raw measurement points into derived metrics.

- It computes reduced values such as unloaded latency, jitter, download/upload bandwidth, packet loss ratio, total duration, and AIM scores.

- The results object is stateful and incremental: it can be queried while a test is still running, but some values are only final after completion.

7. Configuration and thresholds

- src/config centralizes defaults and internal config shape, including request sizes, throttles, duration thresholds, percentiles, and TURN settings.

- src/utils/scaleThreshold.ts and src/utils/numbers.ts indicate the repo relies on numeric reduction/selection logic for percentiles and thresholds.

- Configuration directly affects the measurement strategy, especially the ramp-up behavior for bandwidth and the sample windows for loaded latency.

8. Logging and UI-facing callbacks

- src/logging/logFinalResults.ts suggests the library emits a final structured summary for diagnostics or display.

- The public event model (onResultsChange, onFinish, onError, onRunningChange) is the main interface for integrating with UI or higher-level apps.

- This is an event-driven library, not a request/response API.

9. Browser app and demo surface

- The app/ directory is a browser application wrapper around the library, with index.html, app.js, style.css, manifest.json, sw.js, icons, and Android asset links.

- That makes it a PWA-style demo/host for the speedtest engine, likely the app behind the public Cloudflare speedtest experience.

- app/wrangler.toml indicates deployment as a Cloudflare Worker/Pages-style edge app rather than a traditional server.

10. Example integrations

- example/basic-page is a minimal static usage example.

- example/turn-worker is an integration example for packet-loss support: it provides a Worker-based TURN credential flow for Cloudflare Realtime TURN.

- This example exists because packet-loss measurement is architecturally optional and depends on external infrastructure the consumer must provide.

11. Testing structure

- Unit tests cover config defaults, utility math, result calculations, and URL construction.

- tests/e2e/speedtest.test.ts validates the full measurement flow, which is important because the behavior depends on browser timing APIs and network interactions.

- The test split reflects the repo’s main risk areas: numeric correctness and end-to-end orchestration.

12. Build, packaging, and release concerns

- The package is built from TypeScript and managed as a library, with configs for bundling and linting (tsdown, vitest, ESLint, Prettier).

- GitHub Actions handle build, release PR creation, npm publishing, and Semgrep scanning.

- These workflows don’t change runtime architecture, but they show the repo is designed to ship as a reusable package plus a deployed browser app.