Organize scripts and add TWS plugins with HTTP timeouts

Vendor pinned T5 and T6 plugin sources under the new plugins layout. Add native HTTP deadlines, status and timing diagnostics, telemetry integration, and build/test tooling.
2026-10-09 11:02:20 -04:00
parent b172086301
commit 1121b44857
253 changed files with 28028 additions and 59 deletions
@@ -0,0 +1,78 @@
+# tws-t5-gsc-utils
+
+Source: [alicealys/t5-gsc-utils](https://github.com/alicealys/t5-gsc-utils).
+The baseline commit and dependency revisions are in [tws-t5-gsc-utils/upstream.json](tws-t5-gsc-utils/upstream.json).
+Source is tracked here directly; dependency checkouts are restored from that
+manifest and ignored. Follow the [build instructions](../../README.md#building-plugins).
+Upstream API documentation is in [tws-t5-gsc-utils/README.md](tws-t5-gsc-utils/README.md).
+
+## HTTP deadlines and diagnostics
+
+All native HTTP requests default to `connect_timeout_ms = 5000` and
+`timeout_ms = 15000`. The latter includes connection setup; the shorter limit
+wins during connection. Both can be overridden in the existing options array
+with positive integer milliseconds. Zero, negative and non-integer overrides
+are rejected before a request is created. Neither retries nor redirects are
+added. TLS certificate verification remains enabled.
+
+These are libcurl transfer deadlines, starting when a worker begins the request.
+Time waiting for a worker or the game thread to deliver completion is measured
+separately. A native timeout releases the request and emits `done` with
+`success = false`, a transport error, and diagnostics. Each request is sent once.
+The telemetry sender then logs the failed event and advances its ordered queue.
+A timeout does not prove the API did not already accept the event.
+
+The existing completion values remain in the same positions. An optional fourth
+value adds diagnostics:
+
+```c
+request waittill("done", response, success, error, diagnostics);
+```
+
+`success` continues to mean transport success, including completed HTTP 4xx/5xx
+responses. Existing scripts that read only the first three values still work.
+An updated reporter on an old plugin logs that diagnostics and native deadlines
+are unverified; deploy the matching DLL to enable the fix.
+
+| Field | Meaning |
+| --- | --- |
+| `http_status` | HTTP response code; `0` if none was received |
+| `curl_code` | libcurl result; `0` is transport success, `28` is timeout |
+| `dns_ms` | Time to finish name resolution |
+| `connect_ms` | Time to establish TCP |
+| `tls_ms` | Time to finish TLS; `0` if no TLS handshake completed |
+| `first_byte_ms` | Time to first response byte; `0` if none arrived |
+| `total_ms` | Total native transfer duration |
+| `worker_queue_ms` | Time waiting for the plugin worker pool |
+| `notify_ms` | Time from native completion to notifying GSC |
+| `connect_timeout_ms`, `timeout_ms` | Effective native deadlines |
+
+Curl milestone times are cumulative from transfer start, not durations to add
+together. Diagnostics are provided for failures as well as successful transfers;
+an unfinished milestone can be zero. No request headers, tokens or URLs are
+included in diagnostics. Responses retain the existing 20 KiB truncation behavior.
+
+Telemetry logs the status and timings for each completion at log level 1.
+Non-2xx responses log at level 0 with a bounded response preview. Health counters
+keep transport `completed`/`failed` and track `http_rejected` separately; an HTTP
+rejection is a completed transport. Producers, queue ordering and payloads are
+unchanged. Heartbeats are not coalesced, failed reports are not retried, and API
+receipt timestamps remain the existing behavior.
+
+## Validation and rollout
+
+Run `python3 tools/test_plugin_http.py` from the repository root for portable
+native HTTP tests. Build the x86 DLL on Windows, then on a test game server check:
+
+1. Updated telemetry reports HTTP status and all timing fields on normal requests.
+2. An endpoint that accepts a connection but does not reply produces a native
+   timeout near 15 seconds, followed by the next queued request.
+3. HTTP 401/429/500 responses increment `http_rejected` without blocking the queue;
+   transport errors increment `failed` instead.
+4. Leaderboard and older three-value HTTP consumers still receive completion.
+5. After a full server-process restart, verify all four telemetry event types in
+   Electric Cherry. A successful transport alone is not API acceptance.
+
+The localhost tests compile the actual HTTP utility against the host libcurl.
+They do not validate Windows linking, its Schannel backend or game VM notification
+handling. Those checks require the Windows build and a running Plutonium server.