doc updates for kong and srql #2339

Merged

mfreeman451 merged 1 commit from refs/pull/2339/head into main

2025-10-19 04:01:55 +00:00

mfreeman451 commented

2025-10-19 04:01:03 +00:00

(Migrated from github.com)

Owner

Imported from GitHub pull request.

Original GitHub pull request: #1804
Original author: @mfreeman451
Original URL: https://github.com/carverauto/serviceradar/pull/1804
Original created: 2025-10-19T04:01:03Z
Original updated: 2025-10-19T04:02:26Z
Original head: carverauto/serviceradar:docs/update_web_ui_kong
Original base: main
Original merged: 2025-10-19T04:01:55Z by @mfreeman451

PR Type

Documentation, Enhancement

Description

Introduce Kong API Gateway as central policy enforcement point for user-facing traffic
Add SRQL microservice documentation for query execution and Proton SQL translation
Replace API key authentication with RS256 JWT validation via JWKS endpoint
Update architecture diagrams to show Kong, SRQL, and Proton data layer components
Expand Web UI documentation with Kong configuration examples and JWT flow details

Diagram Walkthrough

flowchart LR
  Browser["Web Browser"]
  WebUI["Web UI<br/>Next.js + Nginx"]
  Kong["Kong API Gateway<br/>JWT Validation"]
  JWKS["Core JWKS<br/>/auth/jwks.json"]
  CoreAPI["Core Service<br/>:8090"]
  SRQL["SRQL Service<br/>:8080"]
  Proton["Proton/Timeplus<br/>Data Layer"]
  
  Browser -->|HTTPS| WebUI
  WebUI -->|REST + JWT| Kong
  Kong -->|Fetch keys| JWKS
  Kong -->|Validated request| CoreAPI
  Kong -->|Validated request| SRQL
  CoreAPI -->|Ingest + Queries| Proton
  SRQL -->|SQL Translation| Proton

File Walkthrough

Relevant files

Documentation

architecture.md

Restructure architecture for Kong and SRQL integration

docs/docs/architecture.md

Restructured architecture diagram to show Kong as policy enforcement
point between Web UI and backend services
Added SRQL microservice as dedicated query engine with /api/query and
/api/stream endpoints
Introduced Proton/Timeplus as explicit data layer component
Replaced API key authentication section with JWT + JWKS validation
flow diagram
Added detailed explanations of Kong JWT validation, SRQL SQL
translation, and mTLS for service-to-service communication
Updated component descriptions for Web UI, Kong, and SRQL with
technical details and port information

+85/-34

web-ui.md

Update Web UI docs for Kong and JWT authentication

docs/docs/web-ui.md

Updated Web UI overview to mention Kong gateway and JWT token
management
Revised architecture diagram to show Kong as intermediary between
Nginx and Core/SRQL services
Replaced API key security section with comprehensive JWT and Kong
gateway documentation
Added Kong configuration example with service routing, JWT plugin
setup, and JWKS URI
Documented JWT login flow, token storage in HttpOnly cookies, and
automatic key rotation
Updated troubleshooting section with Kong health checks and JWT
validation debugging guidance

+66/-25

Imported from GitHub pull request. Original GitHub pull request: #1804 Original author: @mfreeman451 Original URL: https://github.com/carverauto/serviceradar/pull/1804 Original created: 2025-10-19T04:01:03Z Original updated: 2025-10-19T04:02:26Z Original head: carverauto/serviceradar:docs/update_web_ui_kong Original base: main Original merged: 2025-10-19T04:01:55Z by @mfreeman451 --- ### **PR Type** Documentation, Enhancement ___ ### **Description** - Introduce Kong API Gateway as central policy enforcement point for user-facing traffic - Add SRQL microservice documentation for query execution and Proton SQL translation - Replace API key authentication with RS256 JWT validation via JWKS endpoint - Update architecture diagrams to show Kong, SRQL, and Proton data layer components - Expand Web UI documentation with Kong configuration examples and JWT flow details ___ ### Diagram Walkthrough ```mermaid flowchart LR Browser["Web Browser"] WebUI["Web UI<br/>Next.js + Nginx"] Kong["Kong API Gateway<br/>JWT Validation"] JWKS["Core JWKS<br/>/auth/jwks.json"] CoreAPI["Core Service<br/>:8090"] SRQL["SRQL Service<br/>:8080"] Proton["Proton/Timeplus<br/>Data Layer"] Browser -->|HTTPS| WebUI WebUI -->|REST + JWT| Kong Kong -->|Fetch keys| JWKS Kong -->|Validated request| CoreAPI Kong -->|Validated request| SRQL CoreAPI -->|Ingest + Queries| Proton SRQL -->|SQL Translation| Proton ``` <details> <summary><h3> File Walkthrough</h3></summary> <table><thead><tr><th></th><th align="left">Relevant files</th></tr></thead><tbody><tr><td><strong>Documentation</strong></td><td><table> <tr> <td> <details> <summary><strong>architecture.md</strong><dd><code>Restructure architecture for Kong and SRQL integration</code>      </dd></summary> <hr> docs/docs/architecture.md <ul><li>Restructured architecture diagram to show Kong as policy enforcement <br>point between Web UI and backend services<br> <li> Added SRQL microservice as dedicated query engine with <code>/api/query</code> and <br><code>/api/stream</code> endpoints<br> <li> Introduced Proton/Timeplus as explicit data layer component<br> <li> Replaced API key authentication section with JWT + JWKS validation <br>flow diagram<br> <li> Added detailed explanations of Kong JWT validation, SRQL SQL <br>translation, and mTLS for service-to-service communication<br> <li> Updated component descriptions for Web UI, Kong, and SRQL with <br>technical details and port information</ul> </details> </td> <td><a href="https://github.com/carverauto/serviceradar/pull/1804/files#diff-90abd06467420fd89391fd1a4d75ceb1f6a9381de4d13a95fffe606abff38d37">+85/-34</a>  </td> </tr> <tr> <td> <details> <summary><strong>web-ui.md</strong><dd><code>Update Web UI docs for Kong and JWT authentication</code>              </dd></summary> <hr> docs/docs/web-ui.md <ul><li>Updated Web UI overview to mention Kong gateway and JWT token <br>management<br> <li> Revised architecture diagram to show Kong as intermediary between <br>Nginx and Core/SRQL services<br> <li> Replaced API key security section with comprehensive JWT and Kong <br>gateway documentation<br> <li> Added Kong configuration example with service routing, JWT plugin <br>setup, and JWKS URI<br> <li> Documented JWT login flow, token storage in HttpOnly cookies, and <br>automatic key rotation<br> <li> Updated troubleshooting section with Kong health checks and JWT <br>validation debugging guidance</ul> </details> </td> <td><a href="https://github.com/carverauto/serviceradar/pull/1804/files#diff-7e4dc17ccc5b2fd5773b7e6c9583dbe0f597ab9ae21849a2ec0a31554a6337a3">+66/-25</a>  </td> </tr> </table></td></tr></tr></tbody></table> </details> ___

qodo-code-review[bot] commented

2025-10-19 04:01:33 +00:00

(Migrated from github.com)

Author

Owner

Imported GitHub PR comment.

Original author: @qodo-code-review[bot]
Original URL: https://github.com/carverauto/serviceradar/pull/1804#issuecomment-3419192827
Original created: 2025-10-19T04:01:33Z

You are nearing your monthly Qodo Merge usage quota. For more information, please visit here.

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
⚪	Token cookie hardening Description: Storing refresh tokens in cookies requires strict settings; while HttpOnly and Secure are mentioned, SameSite is not referenced and HTTPS is only advised—deployments without enforced HTTPS and SameSite=strict/lax could enable CSRF/token theft risks. web-ui.md [170-186] Referred Code Adjust hostnames, upstream URLs, and plugin settings to match your deployment. Kong will automatically cache JWKS responses and only re-fetch keys when the `kid` changes. Register additional SRQL routes (for example, `/api/query`, `/api/stream`) so analytics features reach the OCaml backend. ## JWT & Kong Gateway ServiceRadar issues RS256-signed JSON Web Tokens (JWTs) for every authenticated user session. Kong validates those tokens before forwarding requests to the Core API. 1. Login flow – The Web UI posts credentials to `/api/auth/login` (proxied through Kong). The Core responds with a short-lived access token and a refresh token. 2. Token storage – Next.js stores the refresh token in an HttpOnly cookie and keeps the access token server-side. Browser requests never see the raw bearer token. 3. Gateway enforcement – Kong’s JWT plugin fetches the signing keys from `https://<core-host>/auth/jwks.json`, caches them, and rejects any request with an invalid signature, issuer, or audience. 4. Automatic rotation – When the Core rotates its signing key (new `kid`), Kong automatically refreshes the JWKS cache and continues validating new tokens. To enable RS256 + JWKS, update the core `auth` block as described in the [Authentication Configuration](./auth-configuration.md) guide. Kong should be configured with the `jwt` (or `openid-connect`) plugin pointing at that JWKS URL and the expected issuer (`iss`) claim. :::caution Protect the refresh token cookies with the `Secure` and `HttpOnly` flags and only expose Kong over HTTPS. Never surface the RS256 private key outside the Core service. :::
	JWKS fetch integrity Description: Example Kong config enables jwt via jwks_uri over HTTPS to a hostname; if TLS verification or SNI is misconfigured in deployments, MITM of JWKS could allow key injection—documentation should note enforcing TLS verification and pinning/issuer checks. web-ui.md [135-168] Referred Code `# Configure the ServiceRadar upstream kong config apply -s ' _format_version: "3.0" services: - name: serviceradar-core url: http://127.0.0.1:8090 routes: - name: serviceradar-api paths: - /api strip_path: false - name: serviceradar-srql url: http://127.0.0.1:8080 routes: - name: serviceradar-query paths: - /api/query - /api/stream strip_path: false plugins: - name: jwt ... (clipped 13 lines)`
	Weak JWT claims checks Description: JWT validation is centralized at the gateway; absence of explicit audience/issuer constraints and clock skew guidance in docs could lead to accepting tokens issued for other services—recommend documenting strict iss/aud checks. architecture.md [149-161] Referred Code - Terminates incoming Web UI API traffic on port 9080 (HTTP) or 9443 (HTTPS) - Validates RS256-signed JWTs using the Core service’s JWKS published at `/auth/jwks.json` - Applies rate limits, request shaping, and header normalization before forwarding to the Core API - Caches JWKS responses and refreshes keys automatically when the Core rotates signing material ### SRQL Service (Query Engine) The SRQL microservice executes ServiceRadar Query Language requests: - Exposes `/api/query` (HTTP) and `/api/stream` (WebSocket) for bounded and streaming query execution - Runs as an OCaml/Dream application that translates SRQL to Proton SQL before dispatching the query - Shares Kong’s JWT policy; validated user tokens grant access to query endpoints without additional secrets - Streams results back to the Web UI, which renders them in explorers and dashboards
Ticket Compliance
⚪	🎫 No ticket provided `- [ ] Create ticket/issue <!-- /create_ticket --create_ticket=true --> </details></td></tr>`
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
⚪	No custom compliance provided Follow the guide to enable custom compliance check.

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

Imported GitHub PR comment. Original author: @qodo-code-review[bot] Original URL: https://github.com/carverauto/serviceradar/pull/1804#issuecomment-3419192827 Original created: 2025-10-19T04:01:33Z --- _You are nearing your monthly Qodo Merge usage quota. For more information, please visit [here](https://qodo-merge-docs.qodo.ai/installation/qodo_merge/#cloud-users)._ ## PR Compliance Guide 🔍  Below is a summary of compliance checks for this PR:<br> <table><tbody><tr><td colspan='2'><strong>Security Compliance</strong></td></tr> <tr><td rowspan=3>⚪</td> <td><details><summary><strong>Token cookie hardening </strong></summary><br> <b>Description:</b> Storing refresh tokens in cookies requires strict settings; while HttpOnly and Secure are <br>mentioned, SameSite is not referenced and HTTPS is only advised—deployments without <br>enforced HTTPS and SameSite=strict/lax could enable CSRF/token theft risks.<br> <strong><a href='https://github.com/carverauto/serviceradar/pull/1804/files#diff-7e4dc17ccc5b2fd5773b7e6c9583dbe0f597ab9ae21849a2ec0a31554a6337a3R170-R186'>web-ui.md [170-186]</a></strong><br> <details open><summary>Referred Code</summary> ```markdown Adjust hostnames, upstream URLs, and plugin settings to match your deployment. Kong will automatically cache JWKS responses and only re-fetch keys when the `kid` changes. Register additional SRQL routes (for example, `/api/query`, `/api/stream`) so analytics features reach the OCaml backend. ## JWT & Kong Gateway ServiceRadar issues RS256-signed JSON Web Tokens (JWTs) for every authenticated user session. Kong validates those tokens before forwarding requests to the Core API. 1. **Login flow** – The Web UI posts credentials to `/api/auth/login` (proxied through Kong). The Core responds with a short-lived access token and a refresh token. 2. **Token storage** – Next.js stores the refresh token in an HttpOnly cookie and keeps the access token server-side. Browser requests never see the raw bearer token. 3. **Gateway enforcement** – Kong’s JWT plugin fetches the signing keys from `https://<core-host>/auth/jwks.json`, caches them, and rejects any request with an invalid signature, issuer, or audience. 4. **Automatic rotation** – When the Core rotates its signing key (new `kid`), Kong automatically refreshes the JWKS cache and continues validating new tokens. To enable RS256 + JWKS, update the core `auth` block as described in the [Authentication Configuration](./auth-configuration.md) guide. Kong should be configured with the `jwt` (or `openid-connect`) plugin pointing at that JWKS URL and the expected issuer (`iss`) claim. :::caution Protect the refresh token cookies with the `Secure` and `HttpOnly` flags and only expose Kong over HTTPS. Never surface the RS256 private key outside the Core service. ::: ``` </details></details></td></tr> <tr><td><details><summary><strong>JWKS fetch integrity </strong></summary><br> <b>Description:</b> Example Kong config enables jwt via jwks_uri over HTTPS to a hostname; if TLS verification <br>or SNI is misconfigured in deployments, MITM of JWKS could allow key <br>injection—documentation should note enforcing TLS verification and pinning/issuer checks.<br> <strong><a href='https://github.com/carverauto/serviceradar/pull/1804/files#diff-7e4dc17ccc5b2fd5773b7e6c9583dbe0f597ab9ae21849a2ec0a31554a6337a3R135-R168'>web-ui.md [135-168]</a></strong><br> <details open><summary>Referred Code</summary> ```markdown # Configure the ServiceRadar upstream kong config apply -s ' _format_version: "3.0" services: - name: serviceradar-core url: http://127.0.0.1:8090 routes: - name: serviceradar-api paths: - /api strip_path: false - name: serviceradar-srql url: http://127.0.0.1:8080 routes: - name: serviceradar-query paths: - /api/query - /api/stream strip_path: false plugins: - name: jwt ... (clipped 13 lines) ``` </details></details></td></tr> <tr><td><details><summary><strong>Weak JWT claims checks </strong></summary><br> <b>Description:</b> JWT validation is centralized at the gateway; absence of explicit audience/issuer <br>constraints and clock skew guidance in docs could lead to accepting tokens issued for <br>other services—recommend documenting strict iss/aud checks.<br> <strong><a href='https://github.com/carverauto/serviceradar/pull/1804/files#diff-90abd06467420fd89391fd1a4d75ceb1f6a9381de4d13a95fffe606abff38d37R149-R161'>architecture.md [149-161]</a></strong><br> <details open><summary>Referred Code</summary> ```markdown - Terminates incoming Web UI API traffic on port 9080 (HTTP) or 9443 (HTTPS) - Validates RS256-signed JWTs using the Core service’s JWKS published at `/auth/jwks.json` - Applies rate limits, request shaping, and header normalization before forwarding to the Core API - Caches JWKS responses and refreshes keys automatically when the Core rotates signing material ### SRQL Service (Query Engine) The SRQL microservice executes ServiceRadar Query Language requests: - Exposes `/api/query` (HTTP) and `/api/stream` (WebSocket) for bounded and streaming query execution - Runs as an OCaml/Dream application that translates SRQL to Proton SQL before dispatching the query - Shares Kong’s JWT policy; validated user tokens grant access to query endpoints without additional secrets - Streams results back to the Web UI, which renders them in explorers and dashboards ``` </details></details></td></tr> <tr><td colspan='2'><strong>Ticket Compliance</strong></td></tr> <tr><td>⚪</td><td><details><summary>🎫 <strong>No ticket provided </summary></strong> - [ ] Create ticket/issue  </details></td></tr> <tr><td colspan='2'><strong>Codebase Duplication Compliance</strong></td></tr> <tr><td>⚪</td><td><details><summary><strong>Codebase context is not defined </strong></summary> Follow the <a href='https://qodo-merge-docs.qodo.ai/core-abilities/rag_context_enrichment/'>guide</a> to enable codebase context checks. </details></td></tr> <tr><td colspan='2'><strong>Custom Compliance</strong></td></tr> <tr><td>⚪</td><td><details><summary><strong>No custom compliance provided</strong></summary> Follow the <a href='https://qodo-merge-docs.qodo.ai/tools/compliance/'>guide</a> to enable custom compliance check. </details></td></tr> <tr><td align="center" colspan="2">   </td></tr></tbody></table> <details><summary>Compliance status legend</summary> 🟢 - Fully Compliant<br> 🟡 - Partial Compliant<br> 🔴 - Not Compliant<br> ⚪ - Requires Further Human Verification<br> 🏷️ - Compliance label<br> </details>

qodo-code-review[bot] commented

2025-10-19 04:02:26 +00:00

(Migrated from github.com)

Author

Owner

Imported GitHub PR comment.

Original author: @qodo-code-review[bot]
Original URL: https://github.com/carverauto/serviceradar/pull/1804#issuecomment-3419193256
Original created: 2025-10-19T04:02:26Z

You are nearing your monthly Qodo Merge usage quota. For more information, please visit here.

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Apply JWT plugin to services individually The Kong configuration incorrectly applies the JWT plugin globally, which blocks the `/api/auth/login` endpoint. The plugin should be applied selectively to avoid protecting the login route. docs/docs/web-ui.md [154-166] plugins: - name: jwt + service: serviceradar-core + config: + key_claim_name: kid + secret_is_base64: false + claims_to_verify: + - exp + uri_param_names: + - token + header_names: + - Authorization + run_on_preflight: true + jwks_uri: https://serviceradar-core.local/auth/jwks.json +- name: jwt + service: serviceradar-srql config: key_claim_name: kid secret_is_base64: false claims_to_verify: - exp uri_param_names: - token header_names: - Authorization run_on_preflight: true jwks_uri: https://serviceradar-core.local/auth/jwks.json Apply / Chat Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a critical flaw in the Kong configuration where the global JWT plugin would block the login endpoint, making authentication impossible. While the proposed fix is also flawed, it highlights a major bug in the provided documentation example that needs to be addressed.	High
More

Imported GitHub PR comment. Original author: @qodo-code-review[bot] Original URL: https://github.com/carverauto/serviceradar/pull/1804#issuecomment-3419193256 Original created: 2025-10-19T04:02:26Z --- _You are nearing your monthly Qodo Merge usage quota. For more information, please visit [here](https://qodo-merge-docs.qodo.ai/installation/qodo_merge/#cloud-users)._ ## PR Code Suggestions ✨  Explore these optional code suggestions: <table><thead><tr><td><strong>Category</strong></td><td align=left><strong>Suggestion                                                                                                                                    </strong></td><td align=center><strong>Impact</strong></td></tr><tbody><tr><td rowspan=1>Possible issue</td> <td> <details><summary>Apply JWT plugin to services individually</summary> ___ **The Kong configuration incorrectly applies the JWT plugin globally, which blocks <br>the <code>/api/auth/login</code> endpoint. The plugin should be applied selectively to avoid <br>protecting the login route.** [docs/docs/web-ui.md [154-166]](https://github.com/carverauto/serviceradar/pull/1804/files#diff-7e4dc17ccc5b2fd5773b7e6c9583dbe0f597ab9ae21849a2ec0a31554a6337a3R154-R166) ```diff plugins: - name: jwt + service: serviceradar-core + config: + key_claim_name: kid + secret_is_base64: false + claims_to_verify: + - exp + uri_param_names: + - token + header_names: + - Authorization + run_on_preflight: true + jwks_uri: https://serviceradar-core.local/auth/jwks.json +- name: jwt + service: serviceradar-srql config: key_claim_name: kid secret_is_base64: false claims_to_verify: - exp uri_param_names: - token header_names: - Authorization run_on_preflight: true jwks_uri: https://serviceradar-core.local/auth/jwks.json ``` - [ ] **Apply / Chat**  <details><summary>Suggestion importance[1-10]: 9</summary> __ Why: The suggestion correctly identifies a critical flaw in the Kong configuration where the global JWT plugin would block the login endpoint, making authentication impossible. While the proposed fix is also flawed, it highlights a major bug in the provided documentation example that needs to be addressed. </details></details></td><td align=center>High </td></tr> <tr><td align="center" colspan="2"> - [ ] More  </td><td></td></tr></tbody></table>