Fixes#1323
## Summary
Adds a small in-memory cache of the community-maintained
hashtag-channels
catalogue (`marcelverdult/meshcore-channels`) and exposes it as
`GET /api/known-channels?region=XX` plus a collapsed sidebar section on
the Channels view ("Known channels (catalogue)") with a one-click
"+ Add" button per row.
Per triage (#1323): new `cmd/server/known_channels_cache.go`, new
`GET /api/known-channels?region=…`, frontend section in
`public/channels.js`. No new DB tables — cache is in-memory only.
## What changed
- `cmd/server/known_channels_cache.go` — `knownChannelsCache` with an
atomic snapshot pointer, 24h default refresh, 30s HTTP timeout, 4 MB
body cap, custom `User-Agent`. Fail-soft: a failed refresh leaves the
last-known snapshot in place. Background goroutine started from
`main.go` after the neighbor-graph recomputer; never blocks startup.
- `cmd/server/known_channels_route.go` — `GET
/api/known-channels?region=`
serves the cached snapshot off the atomic pointer (never blocks on
upstream). Region filter is case-insensitive ISO 3166-1 alpha-2.
Empty/missing cache returns 200 with an empty entries list (fail-soft
for the UI).
- `cmd/server/config.go` — `KnownChannelsURL` +
`KnownChannelsRefreshMs`.
- `config.example.json` — example values + `_comment_knownChannels`.
- `public/channels.js` — new collapsed sidebar section "Known channels
(catalogue)" that lazy-fetches `/api/known-channels` on first render
and renders rows with a "+ Add" button. The button calls the existing
`addUserChannel(name)` path, so adding catalogue channels reuses the
full save-key + decrypt flow that user-typed hashtags already use.
- `cmd/server/known_channels_cache_test.go` — failing-first tests:
- `TestKnownChannelsParseFixture` asserts the parser populates
`GeneratedAt`/`License` and region-stamps every entry while skipping
empty countries.
- `TestKnownChannelsRouteRegionFilter` asserts the route returns 200
with exactly the filtered subset for `?region=be`.
- `TestKnownChannelsFailSoftOn500` asserts a failed upstream fetch
leaves the prior snapshot in place and bumps `failCount`.
## Upstream pinning
The default URL is pinned to the specific file
`channels-by-country.json`
on `main`:
>
https://raw.githubusercontent.com/marcelverdult/meshcore-channels/main/channels-by-country.json
Shape (verified 2026-05-24):
```json
{
"generated_at": "...",
"license": "CC0-1.0",
"countries": { "be": [{"channel": "#antwerpen", "description": "..."}], ... }
}
```
## Test plan
```
cd cmd/server && go test -run 'TestKnownChannels' -count=1 .
ok github.com/corescope/server 0.008s
```
Red commit: 5c43cff3 (all three tests fail on assertions, build clean).
Green commit: 54a1080e (parser + cache + route implemented, all three
pass).
## TDD evidence (red → green)
- **Red commit `5c43cff3427afd8aa2f3cce20c31058190aebc37`** — tests
added
with stub implementations that compile but return zero/empty so each
test fails on an assertion (not a compile/import error). `go test -run
TestKnownChannels` output captured in the commit message.
- **Green commit `54a1080e45fd2e10da2caa156f376bf4d0212976`** — parser,
cache, route, main-wiring, frontend section land; all three tests
pass.
## Frontend verification
Browser verified: http://analyzer-stg.00id.net/#/channels (with the
`/api/known-channels` response stubbed in DevTools to simulate the cache
being populated on staging, which is still on master and doesn't have
the new endpoint yet).
E2E assertion added: cmd/server/known_channels_cache_test.go:71 —
asserts the route returns 200 and the response body's `entries` length
matches the filtered subset.
## Limitations / follow-ups (not in scope of this PR)
- The catalogue only ships PSK keys for a small subset of entries (the
upstream schema makes `key` optional). For entries WITHOUT a `key`,
the "+ Add" button still wires through `addUserChannel("#name")` —
which derives the standard public-channel key from the name (the same
path used today when a user types `#foo` into the Add Channel modal).
For entries WITH a `key`, a follow-up PR can pass the key through to
`addUserChannel` so the UX matches "paste-a-PSK". Today the key is
shown in the JSON payload but not yet wired into the FE button.
- No deduplication against the in-memory `/api/channels` list — the
catalogue section is intentionally separate so the user sees which
channels exist worldwide even if their server hasn't seen traffic.
- No per-section region selector yet — the section shows the full
catalogue regardless of the page-level region filter. Future work:
add a dropdown.
## Preflight
```
═══ Preflight clean. ═══
```
cross-stack: justified — issue #1323 spans `cmd/server` (cache + route)
and `public/channels.js` (sidebar surface); same feature, both halves
required.
---------
Co-authored-by: Kpa-clawbot <bot@corescope.local>
