From 8d23905efb7f64caa25b2b72e35bcf69caaa556a Mon Sep 17 00:00:00 2001
From: mrbobbytables
Date: Sat, 19 Sep 2026 22:34:39 +0000
Subject: [PATCH 1/2] fix(kiosk): stagger initial api requests and retry http
429 during hydration
On first boot, the KubeStellar console dashboard mounts multiple cards
simultaneously, firing concurrent requests to /api/ endpoints that trigger
the console server's in-process client IP rate limiter (HTTP 429).
Intercept /api/ fetch calls in kiosk-gate.js to:
- Stagger initial burst requests across an interval window
- Automatically retry HTTP 429 responses with exponential backoff while
honoring Retry-After headers before bubbling up to cards
- Allow non-API requests (health checks, static assets) to pass through
unmodified
Closes #199
Assisted-by: Gemini 3.8 Flash via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: mrbobbytables
---
files/k0s/kiosk/kiosk-gate.js | 142 +++++++++++++++++++++++++--
tests/unit/test_kubestellar_kiosk.py | 136 +++++++++++++++++++++++++
2 files changed, 272 insertions(+), 6 deletions(-)
diff --git a/files/k0s/kiosk/kiosk-gate.js b/files/k0s/kiosk/kiosk-gate.js
index a75781ef..2ddfe65b 100644
--- a/files/k0s/kiosk/kiosk-gate.js
+++ b/files/k0s/kiosk/kiosk-gate.js
@@ -3,6 +3,119 @@
const healthURL = 'http://127.0.0.1:8585/health'
const gateID = 'kubestellar-kiosk-gate'
+ const INITIAL_BACKOFF_MS = 500
+ const BACKOFF_FACTOR = 2
+ const MAX_RETRIES = 4
+ const STAGGER_INTERVAL_MS = 75
+
+ let lastDispatchTime = -STAGGER_INTERVAL_MS
+
+ const sleep = (ms, signal) => new Promise((resolve, reject) => {
+ if (signal?.aborted) {
+ reject(new DOMException('Aborted', 'AbortError'))
+ return
+ }
+ const timer = setTimeout(resolve, ms)
+ signal?.addEventListener('abort', () => {
+ clearTimeout(timer)
+ reject(new DOMException('Aborted', 'AbortError'))
+ }, { once: true })
+ })
+
+ const isApiRequest = (input) => {
+ try {
+ let urlStr
+ if (typeof input === 'string') {
+ urlStr = input
+ } else if (input instanceof URL) {
+ urlStr = input.href
+ } else if (input && typeof input === 'object' && 'url' in input) {
+ urlStr = input.url
+ } else {
+ urlStr = String(input)
+ }
+
+ const origin = typeof window !== 'undefined' && window.location ? window.location.origin : 'http://localhost'
+ const parsed = new URL(urlStr, origin)
+ return parsed.origin === origin && (parsed.pathname === '/api' || parsed.pathname.startsWith('/api/'))
+ } catch {
+ return false
+ }
+ }
+
+ const staggerRequest = async (signal) => {
+ const now = Date.now()
+ const scheduledTime = Math.max(now, lastDispatchTime + STAGGER_INTERVAL_MS)
+ lastDispatchTime = scheduledTime
+ const waitMs = scheduledTime - now
+ if (waitMs > 0) {
+ await sleep(waitMs, signal)
+ }
+ }
+
+ const parseRetryAfter = (response) => {
+ try {
+ const header = response.headers?.get?.('Retry-After')
+ if (!header) return null
+ const seconds = Number(header)
+ if (!Number.isNaN(seconds) && seconds >= 0) {
+ return seconds * 1000
+ }
+ const dateMs = Date.parse(header)
+ if (!Number.isNaN(dateMs)) {
+ const diff = dateMs - Date.now()
+ return diff > 0 ? diff : 0
+ }
+ } catch {
+ // fallback
+ }
+ return null
+ }
+
+ const executeFetch = (originalFetch, input, init) => {
+ if (typeof Request !== 'undefined' && input instanceof Request) {
+ try {
+ return originalFetch(input.clone(), init)
+ } catch {
+ return originalFetch(input, init)
+ }
+ }
+ return originalFetch(input, init)
+ }
+
+ if (typeof window !== 'undefined' && typeof window.fetch === 'function') {
+ const originalFetch = window.fetch.bind(window)
+
+ window.fetch = async function (input, init) {
+ if (!isApiRequest(input)) {
+ return originalFetch(input, init)
+ }
+
+ const signal = init?.signal || (typeof Request !== 'undefined' && input instanceof Request ? input.signal : undefined)
+ if (signal?.aborted) {
+ throw new DOMException('The user aborted a request.', 'AbortError')
+ }
+
+ await staggerRequest(signal)
+
+ let attempt = 0
+ while (true) {
+ const response = await executeFetch(originalFetch, input, init)
+ if (response.status !== 429 || attempt >= MAX_RETRIES) {
+ return response
+ }
+
+ attempt++
+ const retryAfterMs = parseRetryAfter(response)
+ const backoffMs = retryAfterMs !== null
+ ? retryAfterMs
+ : INITIAL_BACKOFF_MS * Math.pow(BACKOFF_FACTOR, attempt - 1)
+
+ await sleep(backoffMs, signal)
+ }
+ }
+ }
+
const hasSession = () => {
try {
return window.localStorage.getItem(sessionKey) === 'true'
@@ -44,10 +157,27 @@
}
}
- document.addEventListener('keydown', (event) => {
- const gate = document.getElementById(gateID)
- if (gate && !gate.contains(event.target)) event.preventDefault()
- }, true)
- window.setInterval(() => void updateGate(), 2_000)
- void updateGate()
+ if (typeof document !== 'undefined') {
+ document.addEventListener('keydown', (event) => {
+ const gate = document.getElementById(gateID)
+ if (gate && !gate.contains(event.target)) event.preventDefault()
+ }, true)
+ }
+
+ if (typeof window !== 'undefined') {
+ window.setInterval(() => void updateGate(), 2_000)
+ void updateGate()
+ }
+
+ if (typeof module !== 'undefined' && module.exports) {
+ module.exports = {
+ isApiRequest,
+ parseRetryAfter,
+ staggerRequest,
+ INITIAL_BACKOFF_MS,
+ BACKOFF_FACTOR,
+ MAX_RETRIES,
+ STAGGER_INTERVAL_MS,
+ }
+ }
})()
diff --git a/tests/unit/test_kubestellar_kiosk.py b/tests/unit/test_kubestellar_kiosk.py
index ec608c72..092acfa2 100644
--- a/tests/unit/test_kubestellar_kiosk.py
+++ b/tests/unit/test_kubestellar_kiosk.py
@@ -1,6 +1,11 @@
"""Contracts for the KubeStellar kiosk proxy and authenticated agent gate."""
+import json
from pathlib import Path
+import shutil
+import subprocess
+
+import pytest
ROOT = Path(__file__).resolve().parents[2]
KIOSK = ROOT / "files" / "k0s" / "kiosk"
@@ -107,3 +112,134 @@ def test_proxy_is_the_only_public_console_endpoint() -> None:
"nginx@sha256:62223d644fa234c3a1cc785ee14242ec47a77364226f1c811d2f669f96dc2ac8"
in proxy
)
+
+
+def test_kiosk_gate_mitigates_dashboard_rate_limiting() -> None:
+ script = KIOSK_JS.read_text(encoding="utf-8")
+
+ assert "isApiRequest" in script
+ assert "Retry-After" in script
+ assert "429" in script
+ assert "INITIAL_BACKOFF_MS = 500" in script
+ assert "BACKOFF_FACTOR = 2" in script
+ assert "MAX_RETRIES = 4" in script
+ assert "STAGGER_INTERVAL_MS = 75" in script
+ assert "staggerRequest" in script
+ assert "parseRetryAfter" in script
+
+
+@pytest.mark.skipif(shutil.which("node") is None, reason="node not found")
+def test_kiosk_gate_fetch_interceptor_behavior() -> None:
+ node_test_script = f"""
+const fs = require('fs');
+const vm = require('vm');
+
+const kioskCode = fs.readFileSync({json.dumps(str(KIOSK_JS))}, 'utf8');
+
+function setupSandbox(mockFetch) {{
+ const sandbox = {{
+ window: {{
+ location: {{ origin: 'http://localhost:8080' }},
+ localStorage: {{ getItem: () => null }},
+ setInterval: () => {{}},
+ }},
+ document: {{
+ getElementById: () => null,
+ addEventListener: () => {{}},
+ body: {{ insertAdjacentHTML: () => {{}} }},
+ }},
+ setTimeout,
+ clearTimeout,
+ Date,
+ URL,
+ DOMException,
+ console,
+ }};
+ sandbox.window.fetch = mockFetch;
+ sandbox.window.window = sandbox.window;
+ vm.runInNewContext(kioskCode, sandbox);
+ return sandbox;
+}}
+
+(async () => {{
+ // 1. Non-API pass through
+ let nonApiCalled = false;
+ const s1 = setupSandbox(async () => {{
+ nonApiCalled = true;
+ return {{ status: 200, ok: true }};
+ }});
+ const res1 = await s1.window.fetch('http://127.0.0.1:8585/health');
+ if (!nonApiCalled || res1.status !== 200) throw new Error('Non-API pass-through failed');
+
+ // 2. 429 retry with Retry-After header
+ let flakyAttempts = 0;
+ const s2 = setupSandbox(async () => {{
+ flakyAttempts++;
+ if (flakyAttempts <= 2) {{
+ return {{
+ status: 429,
+ headers: {{ get: (k) => k.toLowerCase() === 'retry-after' ? '0.05' : null }}
+ }};
+ }}
+ return {{ status: 200, ok: true, data: 'hydrated' }};
+ }});
+ const res2 = await s2.window.fetch('/api/mcp/clusters');
+ if (res2.status !== 200 || flakyAttempts !== 3) {{
+ throw new Error(`Expected 3 attempts and 200 OK, got ${{flakyAttempts}} attempts and status ${{res2.status}}`);
+ }}
+
+ // 3. Staggering burst requests
+ const start = Date.now();
+ const dispatchTimes = [];
+ const s3 = setupSandbox(async () => {{
+ dispatchTimes.push(Date.now() - start);
+ return {{ status: 200, ok: true }};
+ }});
+ await Promise.all([
+ s3.window.fetch('/api/mcp/clusters'),
+ s3.window.fetch('/api/mcp/services'),
+ s3.window.fetch('/api/kagent/status'),
+ ]);
+ if (dispatchTimes.length !== 3) throw new Error('Expected 3 dispatch times');
+ if (dispatchTimes[1] - dispatchTimes[0] < 50) throw new Error('First stagger interval too short');
+ if (dispatchTimes[2] - dispatchTimes[1] < 50) throw new Error('Second stagger interval too short');
+
+ // 4. Max retries exhaustion
+ let always429Attempts = 0;
+ const s4 = setupSandbox(async () => {{
+ always429Attempts++;
+ return {{
+ status: 429,
+ headers: {{ get: () => '0.01' }}
+ }};
+ }});
+ const res4 = await s4.window.fetch('/api/stellar/state');
+ if (res4.status !== 429 || always429Attempts !== 5) {{
+ throw new Error(`Expected 5 attempts and status 429, got ${{always429Attempts}} attempts and ${{res4.status}}`);
+ }}
+
+ // 5. AbortSignal cancellation
+ const s5 = setupSandbox(async () => ({{ status: 200, ok: true }}));
+ const controller = new AbortController();
+ controller.abort();
+ try {{
+ await s5.window.fetch('/api/test', {{ signal: controller.signal }});
+ throw new Error('Should have aborted');
+ }} catch (err) {{
+ if (err.name !== 'AbortError') throw err;
+ }}
+
+ console.log('ALL_KIOSK_GATE_TESTS_PASSED');
+}})().catch(err => {{
+ console.error(err);
+ process.exit(1);
+}});
+"""
+ result = subprocess.run(
+ ["node", "-e", node_test_script],
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+ assert result.returncode == 0, f"Node test failed:\n{result.stderr}\n{result.stdout}"
+ assert "ALL_KIOSK_GATE_TESTS_PASSED" in result.stdout
From 4ea4d1c7c593d3bca2cbf0052f5c1db67dcbb3f7 Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Sat, 19 Sep 2026 23:40:59 -0400
Subject: [PATCH 2/2] fix(kiosk): install fetch gate before console bundle and
clamp retry delay
The interceptor was injected as a deferred script before
, so the
console bundle executed first and its first-boot hydration burst bypassed
the stagger/retry logic. Inject the gate synchronously at the end of
instead: a classic non-deferred script runs before any deferred or
module script and before end-of-body scripts, guaranteeing window.fetch is
patched before the bundle evaluates. The gate UI loop now waits for
DOMContentLoaded because document.body does not exist at that point.
Also clamp Retry-After (and exponential backoff) to 30s so a large or
clock-skewed server value cannot stall a dashboard card for minutes, and
document that the stagger cursor is page-lifetime by design.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
files/k0s/kiosk/kiosk-gate.js | 28 +++++++--
files/k0s/kiosk/nginx.conf | 7 ++-
tests/unit/test_kubestellar_kiosk.py | 85 ++++++++++++++++++++++++++--
3 files changed, 108 insertions(+), 12 deletions(-)
diff --git a/files/k0s/kiosk/kiosk-gate.js b/files/k0s/kiosk/kiosk-gate.js
index 2ddfe65b..d6122fb7 100644
--- a/files/k0s/kiosk/kiosk-gate.js
+++ b/files/k0s/kiosk/kiosk-gate.js
@@ -7,7 +7,11 @@
const BACKOFF_FACTOR = 2
const MAX_RETRIES = 4
const STAGGER_INTERVAL_MS = 75
+ const MAX_RETRY_DELAY_MS = 30_000
+ // Page-lifetime cursor: any concurrent /api burst is spaced, not only the
+ // first-boot hydration one, because the console rate limiter is also
+ // page-lifetime and periodic refreshes fan out the same way.
let lastDispatchTime = -STAGGER_INTERVAL_MS
const sleep = (ms, signal) => new Promise((resolve, reject) => {
@@ -53,18 +57,19 @@
}
}
+ const clampDelay = (ms) => Math.min(Math.max(ms, 0), MAX_RETRY_DELAY_MS)
+
const parseRetryAfter = (response) => {
try {
const header = response.headers?.get?.('Retry-After')
if (!header) return null
const seconds = Number(header)
if (!Number.isNaN(seconds) && seconds >= 0) {
- return seconds * 1000
+ return clampDelay(seconds * 1000)
}
const dateMs = Date.parse(header)
if (!Number.isNaN(dateMs)) {
- const diff = dateMs - Date.now()
- return diff > 0 ? diff : 0
+ return clampDelay(dateMs - Date.now())
}
} catch {
// fallback
@@ -109,7 +114,7 @@
const retryAfterMs = parseRetryAfter(response)
const backoffMs = retryAfterMs !== null
? retryAfterMs
- : INITIAL_BACKOFF_MS * Math.pow(BACKOFF_FACTOR, attempt - 1)
+ : clampDelay(INITIAL_BACKOFF_MS * Math.pow(BACKOFF_FACTOR, attempt - 1))
await sleep(backoffMs, signal)
}
@@ -164,20 +169,33 @@
}, true)
}
- if (typeof window !== 'undefined') {
+ const startGateLoop = () => {
window.setInterval(() => void updateGate(), 2_000)
void updateGate()
}
+ if (typeof window !== 'undefined') {
+ // The interceptor above is installed at parse time, but the gate markup
+ // needs document.body, which does not exist yet when this script runs
+ // synchronously from
.
+ if (typeof document !== 'undefined' && document.readyState === 'loading') {
+ document.addEventListener('DOMContentLoaded', startGateLoop, { once: true })
+ } else {
+ startGateLoop()
+ }
+ }
+
if (typeof module !== 'undefined' && module.exports) {
module.exports = {
isApiRequest,
parseRetryAfter,
staggerRequest,
+ clampDelay,
INITIAL_BACKOFF_MS,
BACKOFF_FACTOR,
MAX_RETRIES,
STAGGER_INTERVAL_MS,
+ MAX_RETRY_DELAY_MS,
}
}
})()
diff --git a/files/k0s/kiosk/nginx.conf b/files/k0s/kiosk/nginx.conf
index e34bf24b..afe0f50a 100644
--- a/files/k0s/kiosk/nginx.conf
+++ b/files/k0s/kiosk/nginx.conf
@@ -41,8 +41,11 @@ http {
proxy_set_header Accept-Encoding "";
proxy_set_header Connection "";
sub_filter_once on;
- sub_filter '' ' ';
- sub_filter '' '';
+ # Injected synchronously at the end of
so window.fetch is patched
+ # before the console bundle executes. Classic non-deferred scripts run
+ # before any deferred/module script and before end-of-body scripts, so
+ # the first-boot hydration burst is intercepted.
+ sub_filter '' ' ';
}
}
}
diff --git a/tests/unit/test_kubestellar_kiosk.py b/tests/unit/test_kubestellar_kiosk.py
index 092acfa2..c0f239b6 100644
--- a/tests/unit/test_kubestellar_kiosk.py
+++ b/tests/unit/test_kubestellar_kiosk.py
@@ -59,12 +59,11 @@ def test_proxy_injects_only_csp_safe_same_origin_assets() -> None:
assert "sub_filter_types" not in nginx
assert (
'sub_filter \'\' '
- '\' \';'
- ) in nginx
- assert (
- 'sub_filter \'\' '
- '\'\';'
+ '\' '
+ '\';'
) in nginx
+ assert "