Skip to content

Document WS_ENDPOINT in .env.sample for local dev#3166

Merged
simo6529 merged 13 commits into
mainfrom
docs/env-sample-ws-endpoint
Jul 17, 2026
Merged

Document WS_ENDPOINT in .env.sample for local dev#3166
simo6529 merged 13 commits into
mainfrom
docs/env-sample-ws-endpoint

Conversation

@brookr

@brookr brookr commented Jul 7, 2026

Copy link
Copy Markdown
Collaborator

Issue

  • WS_ENDPOINT isn't in .env.sample, so local dev typically leaves it unset. The realtime websocket URL then derives from API_ENDPOINT via .replace("https://api", "wss://ws"), which only rewrites the production host shape. A localhost API (http://localhost:3000) becomes an insecure ws://localhost:3000 URL, which the CSP connect-src (wss: only, no ws:) blocks — so live wave updates silently fail locally, with only a console CSP violation to hint at why.

Fix

  • Add a documented WS_ENDPOINT= entry to .env.sample explaining the production value and why to set it locally.

Changes

  • .env.sample: one new documented var. No code.

Validation

  • Docs/sample only; WS_ENDPOINT already exists in the env schema (optional). No behavior change.

Risk

  • Level: none — sample-file documentation.

Deployment

  • None.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Added the WS_ENDPOINT environment variable to the sample configuration.
    • Documented the expected WebSocket URL formats for production (wss://...) and local development.
    • Clarified how the app derives a WebSocket URL from API_ENDPOINT when WS_ENDPOINT is not set, and noted that some non-production API_ENDPOINT values require WS_ENDPOINT to work properly.
    • Commented out WS_ENDPOINT by default to avoid validation failures when left empty.

Without WS_ENDPOINT set, the realtime websocket URL is derived from
API_ENDPOINT via a replace that only rewrites the production
'https://api...' host. A localhost API then yields an insecure
'ws://localhost' URL that the CSP connect-src (wss: only) blocks, so
live wave updates silently fail in local dev. Documenting the var
spares developers that confusion.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: brookr <11095+brookr@users.noreply.github.com>
@brookr
brookr requested a review from a team July 7, 2026 08:36
@coderabbitai

coderabbitai Bot commented Jul 7, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d4f8f472-f989-4bec-908d-d11883f1c744

📥 Commits

Reviewing files that changed from the base of the PR and between ab37473 and c00df30.

📒 Files selected for processing (1)
  • .env.sample
🚧 Files skipped from review as they are similar to previous changes (1)
  • .env.sample

📝 Walkthrough

Walkthrough

Adds documented WS_ENDPOINT configuration to .env.sample, including production and local WebSocket URLs, fallback behavior from API_ENDPOINT, and validation notes.

Changes

WebSocket endpoint configuration

Layer / File(s) Summary
Document WS_ENDPOINT configuration
.env.sample
Adds WS_ENDPOINT guidance for production and local development, including fallback behavior and empty-value validation.

Estimated code review effort: 1 (Trivial) | ~2 minutes

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the main change: documenting WS_ENDPOINT in .env.sample for local development.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/env-sample-ws-endpoint

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@6529bot

6529bot Bot commented Jul 7, 2026

Copy link
Copy Markdown

6529bot general PR review - f3c6ecd

Verdict: Good to merge

Documentation-only change to .env.sample. The added WS_ENDPOINT entry (.env.sample:4-11) is accurate and clearly explains the CSP/ws://localhost derivation pitfall. No correctness, security, or data-integrity concerns.

One minor note: the comment states CSP allows wss: only while the example suggests ws://localhost:3000 for local dev — this is internally consistent only if the local CSP is relaxed to permit ws:. Not blocking, but worth confirming the local CSP actually allows the suggested ws://localhost value, otherwise the documented workaround would still be blocked.

@6529bot

6529bot Bot commented Jul 7, 2026

Copy link
Copy Markdown

6529bot WCAG 2.2 AA analysis - f3c6ecd

Verdict: No WCAG findings

Documentation-only change to .env.sample (.env.sample:4-11). No user-facing UI, markup, or component behavior is affected, so there is nothing to evaluate against WCAG 2.2 AA.

@6529bot

6529bot Bot commented Jul 7, 2026

Copy link
Copy Markdown

6529bot i18n analysis - f3c6ecd

Verdict: No i18n findings

Documentation-only change to .env.sample adding a WS_ENDPOINT comment and empty variable. No user-facing React copy, accessible names, or locale-sensitive formatting are touched, so the frontend i18n/localization standard does not apply here.

@6529bot

6529bot Bot commented Jul 7, 2026

Copy link
Copy Markdown

6529bot crypto security analysis - f3c6ecd

Verdict: No security findings

Documentation-only change to .env.sample (.env.sample:4-11) adding a commented WS_ENDPOINT entry with an empty value. No wallet, auth, signature, token, or crypto/web3 code is touched. The added text accurately describes the CSP/ws://localhost derivation behavior and introduces no secrets or exploitable behavior.

@6529bot

6529bot Bot commented Jul 7, 2026

Copy link
Copy Markdown

6529bot GLM Swarm Review

Verdict: Advisory only

This GLM swarm review is advisory and complements, not replaces, existing tests and reviewbots.

Important

  • .env.sample:5 — The comment implies a localhost API endpoint derives an insecure ws://localhost URL, but derivation from http://localhost:3000 would typically preserve the port (ws://localhost:3000). Verify the actual WS URL derivation logic in the client code and align the comment with real behavior (port preserved vs. stripped). If the port is stripped, that may indicate a code bug rather than a documentation issue.

Nice-to-have

  • Confirm WS_ENDPOINT matches the variable name expected by the app's config loader to avoid a typo/orphaned-key mismatch.

Testing feedback loop

  • No new tests required for the .env.sample change itself.
  • If Codex wants regression coverage, consider a unit test for the API_ENDPOINT → WS URL derivation covering both https://api.6529.io (→ wss://) and http://localhost:PORT (→ ws:// with correct port handling).
  • If a CI lane lints/validates .env.sample keys against consumed env vars, ensure it runs on this PR.

@6529bot

6529bot Bot commented Jul 7, 2026

Copy link
Copy Markdown

6529bot responsiveness review - f3c6ecd

Verdict: Responsive checks passed

Root Cause / Summary

All 32 checks passed across four contexts with zero deterministic failures, zero blank screenshots, and contentReady=true on every route. Both simulated app-shell contracts activated correctly: native-mobile reports hasCapacitorNativeClass=true, viewport-fit=cover, and bottomNavigationVisible=true (64px) on every route; electron-desktop reports electronDetected=true on every route. Screenshots confirm intact, responsive layouts on web-desktop sidebar, web-mobile SmallScreenLayout, native AppLayout, and the Electron renderer branch. The nine warnings are non-blocking: a recurring native plugin-shim/console-error pattern (expected in browser-level Capacitor simulation), one console-error cluster on Electron /rememes, and one full-page screenshot timeout that safely fell back to viewport capture.

Blocking Findings

None. No deterministic failures, no blank/near-white evidence (screenshotBlankLike=false everywhere), no missing native-shell or Electron contract, no Next.js asset failures (nextAssetFailures=0), and no Next.js error overlay (nextErrorOverlay=false on all routes; overlay text strings are the reviewbot issues badge, not a Next.js diagnostic).

Non-Blocking Findings

  • native-mobile EULA gate on multiple routes — On several native routes (/ screenshot, /waves screenshot, /the-memes, /network, /meme-calendar) the "End User License Agreement / Agree" modal is displayed over content. This is the expected native first-run consent gate, and the shell (header + bottom nav) still renders behind it, so it is polish/state context, not a layout defect.
  • native-mobile Capacitor plugin shims unavailable (app-wide) — Every native route emits Keyboard plugin shim is unavailable and App plugin shim is unavailable plus 2 console errors. This is an expected limitation of the browser-level Capacitor simulation, not real device behavior.
  • native-mobile /the-memes full-page screenshot timeout — Full-page capture exceeded 20s and fell back to a viewport screenshot (screenshot); contentReady=true and evidence is valid. Timing/asset-heavy route, not a rendering failure.
  • electron-desktop /rememes 6 console errorsscreenshot shows a fully rendered grid; errors did not block content. Worth a quick console triage but non-blocking.
  • electron-desktop /network skeletonsscreenshot captured loading placeholders before the table populated (the web-desktop equivalent shows the full ranked list). Capture-timing artifact, not a layout break.

Platform Coverage

  • web-desktop (1440×900): WebLayout/sidebar exercised correctly; layoutRootDataMobile/Narrow/Small=false. Root, waves, network, meme-calendar, and collection grids all render cleanly.
  • web-mobile: SmallScreenLayout branch active (no capacitor class, no bottom nav, layoutRootData*=none), hamburger header and stacked layouts render correctly across all routes.
  • native-mobile: Browser-level Capacitor simulation — app-shell contract satisfied (capacitor-native class, viewport-fit=cover, bottom nav 64px). Plugin-shim warnings and console errors are simulation boundaries; this is not packaged iOS/Android behavior.
  • electron-desktop: Chromium renderer simulation with Electron user-agent — electronDetected=true on all 8 routes, confirming the Electron branch activated. This is not a packaged desktop launch.

No blocking issues found; the run is clean and ready to merge from a responsiveness standpoint.

Screenshot evidence: native-mobile /the-memes, native-mobile /meme-lab, native-mobile /rememes, native-mobile /network, native-mobile /waves, native-mobile /, native-mobile /meme-calendar, native-mobile /discover, electron-desktop /rememes, web-mobile /the-memes, web-desktop /meme-lab, web-desktop /the-memes and 20 more in the details.

Deterministic responsiveness details

Verdict: Responsive checks passed

Responsiveness runner summary

6529bot Responsiveness Summary

Status: pass
Duration: 460.5s
Profile: 6529 Seize frontend
Contexts: web-desktop, web-mobile, native-mobile, electron-desktop
Routes: /, /waves, /network, /the-memes, /meme-lab, /rememes, /meme-calendar, /discover
Checks completed: 32/32
Failures: 0
Warnings: 9

Platform Context

  • web-desktop should exercise WebLayout/sidebar at 1440x900.
  • web-mobile should exercise SmallScreenLayout, not the native AppLayout.
  • native-mobile/native-ios/native-android are fast browser-level Capacitor simulations of AppLayout, bottom navigation, viewport-fit, keyboard/app/deep-link plugins, and body class.
  • electron-desktop is a fast browser-level Electron renderer simulation using the Electron user-agent branch; it is not a packaged desktop app launch.
  • Access/restricted pages intentionally bypass the standard app layout shell.

Platform Matrix

  • electron-desktop: 8 check(s), failures=0, warnings=1, avg=18.9s
  • native-mobile: 8 check(s), failures=0, warnings=8, avg=26.3s
  • web-desktop: 8 check(s), failures=0, warnings=0, avg=23.0s
  • web-mobile: 8 check(s), failures=0, warnings=0, avg=20.5s

Warnings

  • electron-desktop /rememes: 6 console error(s)
  • native-mobile /discover: 6529 native profile: Keyboard plugin shim is unavailable; 6529 native profile: App plugin shim is unavailable; 2 console error(s)
  • native-mobile /meme-calendar: 6529 native profile: Keyboard plugin shim is unavailable; 6529 native profile: App plugin shim is unavailable; 2 console error(s)
  • native-mobile /meme-lab: 6529 native profile: Keyboard plugin shim is unavailable; 6529 native profile: App plugin shim is unavailable; 2 console error(s)
  • native-mobile /network: 6529 native profile: Keyboard plugin shim is unavailable; 6529 native profile: App plugin shim is unavailable; 2 console error(s)
  • native-mobile /rememes: 6529 native profile: Keyboard plugin shim is unavailable; 6529 native profile: App plugin shim is unavailable; 2 console error(s)
  • native-mobile /: 6529 native profile: Keyboard plugin shim is unavailable; 6529 native profile: App plugin shim is unavailable; 2 console error(s)
  • native-mobile /the-memes: full-page screenshot failed; used viewport fallback: page.screenshot: Timeout 20000ms exceeded. Call log: �[2m - taking page screenshot�[22m �[2m - waiting for fonts to load...�[22m �[2m - fonts loaded�[22m ; 6529 native profile: Keyboard plugin shim is unavailable; 6529 native profile: App plugin shim is unavailable; 2 console error(s)
  • native-mobile /waves: 6529 native profile: Keyboard plugin shim is unavailable; 6529 native profile: App plugin shim is unavailable; 2 console error(s)

Slowest Checks

@6529bot

6529bot Bot commented Jul 14, 2026

Copy link
Copy Markdown

6529bot follow-up commit review - c301ed2

Verdict: No new findings

The commit set is unchanged from the previously reviewed head (f3c6ecdd4b61); this is the same documentation-only .env.sample addition already covered across all prior 6529bot lanes. Nothing new to evaluate.

The one open question worth confirming (raised previously by the general review and GLM swarm) remains: whether the derived ws://localhost URL actually strips the port, and whether the local CSP truly blocks ws:. That is a code-behavior verification item, not a defect in this diff.

@6529bot

6529bot Bot commented Jul 14, 2026

Copy link
Copy Markdown

6529bot follow-up commit review - ab37473

Verdict: No new findings

The diff since the prior same-lane marker (c301ed296df0) is identical to the previously reviewed documentation-only .env.sample addition (.env.sample:4-11) — no new commits or content to evaluate. All lanes have already covered this change.

The one open verification item carried from earlier reviews still stands and is not a defect in this diff: confirm whether the API_ENDPOINT → ws://localhost derivation actually preserves the port, and whether the local CSP truly blocks ws:. That is a code-behavior check for the client config, not something resolvable within this docs-only change.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.env.sample:
- Around line 6-9: Update the localhost WebSocket guidance in the environment
configuration so it accurately reflects the fallback behavior: localhost API
endpoints are passed unchanged to new WebSocket(), while only the production
https://api host is rewritten to wss://ws. Adjust the note in the surrounding
environment configuration without changing unrelated settings.
- Line 10: Remove the empty WS_ENDPOINT assignment from the sample environment
file and update its local-fallback note to match the actual behavior in
useWaveWebSocket, which only rewrites the documented api-to-ws host pattern; do
not imply that localhost API URLs are automatically converted to the websocket
host.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f84fa1ae-5660-4710-b98e-213586157434

📥 Commits

Reviewing files that changed from the base of the PR and between 44eecf7 and ab37473.

📒 Files selected for processing (1)
  • .env.sample

Comment thread .env.sample Outdated
Comment thread .env.sample Outdated
CodeRabbit caught two problems: an uncommented empty WS_ENDPOINT= fails
env validation when the sample is copied verbatim (the schema rejects
empty strings and next.config fail-fasts), and the note claimed a CSP
block when a localhost API_ENDPOINT actually reaches the WebSocket
constructor unchanged and fails there.

Signed-off-by: brookr <11095+brookr@users.noreply.github.com>
@6529bot

6529bot Bot commented Jul 14, 2026

Copy link
Copy Markdown

6529bot follow-up commit review - e3d3f9b

Verdict: No new findings

Resolved since last review

  • The two CodeRabbit inline findings on .env.sample are addressed in e3d3f9bdd:
    • The empty WS_ENDPOINT= is now commented out (.env.sample:15), avoiding the env-validation failure when the sample is copied verbatim.
    • The fallback note is corrected (.env.sample:4-14): it now accurately states that only the production https://api... host is rewritten to wss://ws..., and any other API_ENDPOINT (e.g. localhost) reaches the WebSocket constructor unchanged and fails there — no longer misattributing the failure to a CSP block.

This also resolves the long-standing open verification item carried across prior lanes (CSP vs. constructor failure). The documentation now matches the described client behavior. No new issues introduced.

@6529bot

6529bot Bot commented Jul 14, 2026

Copy link
Copy Markdown

6529bot follow-up commit review - c00df30

Verdict: No new findings

The diff since the prior same-lane marker (e3d3f9bdd1b2) is identical to the head already reviewed in that marker's follow-up — the full patch series (both commits) is shown here, but there are no commits beyond e3d3f9bdd1b2. Nothing new to evaluate.

The two CodeRabbit inline findings and the long-standing CSP-vs-constructor verification item were all resolved in e3d3f9bdd and confirmed by both the human author (@brookr) and CodeRabbit; those are already acknowledged in the prior follow-up review. No regressions and no new issues introduced by this docs-only .env.sample change.

@6529bot

6529bot Bot commented Jul 14, 2026

Copy link
Copy Markdown

6529bot follow-up commit review - 25f4701

Verdict: No new findings

The diff since the prior same-lane marker (c00df30d2c41) contains no commits beyond the already-reviewed head — the full two-commit series is shown, but nothing exists past e3d3f9bdd1b2. There is nothing new to evaluate.

Both CodeRabbit inline findings (empty WS_ENDPOINT= failing env validation, and the misleading CSP-block wording) were resolved in e3d3f9bdd, confirmed by @brookr and CodeRabbit, and already acknowledged in earlier follow-up reviews. No regressions in this docs-only .env.sample change.

@6529bot

6529bot Bot commented Jul 14, 2026

Copy link
Copy Markdown

6529bot follow-up commit review - 5821274

Verdict: No new findings

The diff since the prior same-lane marker (25f470185b4e) contains no commits beyond the already-reviewed head — the full two-commit series (f3c6ecdde3d3f9bdd) is shown, but nothing exists past e3d3f9bdd1b2. There is nothing new to evaluate.

Both CodeRabbit inline findings (empty WS_ENDPOINT= failing env validation, and the misleading CSP-block wording) were resolved in e3d3f9bdd, confirmed by @brookr and CodeRabbit, and already acknowledged across earlier follow-up reviews. No regressions in this docs-only .env.sample change.

@6529bot

6529bot Bot commented Jul 14, 2026

Copy link
Copy Markdown

6529bot follow-up commit review - a0c2eaa

6529bot follow-up commit review

Verdict: No new findings

The diff since the prior same-lane marker (5821274d908f) contains no commits beyond the already-reviewed head. The full two-commit series (f3c6ecdde3d3f9bdd) is shown, but nothing exists past e3d3f9bdd1b2. There is nothing new to evaluate.

Both CodeRabbit inline findings (empty WS_ENDPOINT= failing env validation, and the misleading CSP-block wording) were resolved in e3d3f9bdd, confirmed by @brookr and CodeRabbit, and already acknowledged across earlier follow-up reviews. No regressions in this docs-only .env.sample change.

@6529bot

6529bot Bot commented Jul 14, 2026

Copy link
Copy Markdown

6529bot follow-up commit review - f10b65e

6529bot follow-up commit review

Verdict: No new findings

The diff since the prior same-lane marker (a0c2eaab5b0e) contains no commits beyond the already-reviewed head. The full two-commit series (f3c6ecdde3d3f9bdd) is shown, but nothing exists past e3d3f9bdd1b2. There is nothing new to evaluate.

Both CodeRabbit inline findings (empty WS_ENDPOINT= failing env validation, and the misleading CSP-block wording) were resolved in e3d3f9bdd, confirmed by @brookr and CodeRabbit, and already acknowledged across earlier follow-up reviews. No regressions in this docs-only .env.sample change.

@6529bot

6529bot Bot commented Jul 14, 2026

Copy link
Copy Markdown

6529bot follow-up commit review - 656d7fc

6529bot follow-up commit review

Verdict: No new findings

The diff since the prior same-lane marker (f10b65e70ccd) contains no commits beyond the already-reviewed head. The full two-commit series (f3c6ecdde3d3f9bdd) is shown, but nothing exists past e3d3f9bdd1b2. There is nothing new to evaluate.

Both CodeRabbit inline findings (empty WS_ENDPOINT= failing env validation, and the misleading CSP-block wording) were resolved in e3d3f9bdd, confirmed by @brookr and CodeRabbit, and already acknowledged across earlier follow-up reviews. No regressions in this docs-only .env.sample change.

@6529bot

6529bot Bot commented Jul 16, 2026

Copy link
Copy Markdown

6529bot follow-up commit review - 3409bd4

6529bot follow-up commit review

Verdict: No new findings

The diff since the prior same-lane marker (656d7fc457d1) contains no commits beyond the already-reviewed head. The full two-commit series (f3c6ecdde3d3f9bdd) is shown, but nothing exists past e3d3f9bdd1b2. There is nothing new to evaluate.

Both CodeRabbit inline findings (empty WS_ENDPOINT= failing env validation, and the misleading CSP-block wording) were resolved in e3d3f9bdd, confirmed by @brookr and CodeRabbit, and already acknowledged across earlier follow-up reviews. No regressions in this docs-only .env.sample change.

@simo6529
simo6529 merged commit 373221c into main Jul 17, 2026
10 of 11 checks passed
@simo6529
simo6529 deleted the docs/env-sample-ws-endpoint branch July 17, 2026 05:34
@6529bot

6529bot Bot commented Jul 17, 2026

Copy link
Copy Markdown

6529bot follow-up commit review - bc800de

Verdict: No new findings

The diff since the prior same-lane marker (3409bd48f7db) contains no commits beyond the already-reviewed head. The full two-commit series (f3c6ecdde3d3f9bdd) is shown, but nothing exists past e3d3f9bdd1b2. There is nothing new to evaluate.

Both CodeRabbit inline findings (empty WS_ENDPOINT= failing env validation, and the misleading CSP-block wording) were resolved in e3d3f9bdd, confirmed by @brookr and CodeRabbit, and already acknowledged across earlier follow-up reviews. No regressions in this docs-only .env.sample change.

@sonarqubecloud

Copy link
Copy Markdown

@6529bot

6529bot Bot commented Jul 17, 2026

Copy link
Copy Markdown

6529bot follow-up commit review - 8c71130

Verdict: No new findings

The diff since the prior same-lane marker (bc800de17e1c) contains no commits beyond the already-reviewed head. The full two-commit series (f3c6ecdde3d3f9bdd) is shown, but nothing exists past e3d3f9bdd1b2. There is nothing new to evaluate.

Both CodeRabbit inline findings (empty WS_ENDPOINT= failing env validation, and the misleading CSP-block wording) were resolved in e3d3f9bdd, confirmed by @brookr and CodeRabbit, and already acknowledged across earlier follow-up reviews. No regressions in this docs-only .env.sample change.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants