Repository navigation
[AI:zf-builder] docs(openwiki): sync architecture documentation for hotcode-dev-zerohub - #181
Conversation
Task: zf-z-ce759582
Deploying zerohub with
|
| Latest commit: |
e4a078f
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://87db8fb7.zerohub.pages.dev |
| Branch Preview URL: | https://task-zf-z-ce759582.zerohub.pages.dev |
ntsd
left a comment
There was a problem hiding this comment.
[AI:zf-reviewer] [Reviewer Feedback] Round 1: Approved for human review.
Docs-only OpenWiki sync (14 files, all under openwiki/: 5 content pages, 6 .claims JSON, .page-manifest.json, .last-update.json). +791/-531. No source, test, dependency, or config changes.
Ponytail gatekeeping
- Rung 7 (diff scope/hygiene): CLEAN. Diff is confined to
openwiki/; no drive-by churn, no leftover.github/workflows/openwiki-update.ymlorCLAUDE.md(verified absent).AGENTS.mduntouched (unchanged, correctly not in diff). - Rungs 1/3/5/6: N/A — no code, no new dependencies, no abstractions.
- No test-suite run is warranted for a docs-only diff; nothing executable changed (precommit gate already ran at PR creation).
Accuracy spot-checks (all verified against source on this branch)
server/cmd/server.go:25-29— exactly three ZeroHub instances (static/random/IP) vianewZeroHubOrPanic; overview.md's "former 'permanent' mode merged into never-expiring static" matches.handler.go:58-60—Handlerinterface isServe()only (post-#164); server-signaling.md routing table matches.join_or_create_hub_ip.go— IP-hub ID is FNV-1a via stdlibhash/fnv(post-#178, no xxh3), matching the docs' "FNV-1a hash of the client IP".hub.go:181-249—RemovePeerIfLast/removePeerwithempty = !h.IsPermanent && ...; doc's "the hub is not permanent" faithfully mirrors the still-present internalIsPermanentflag.hub.go:263-299— sharedsendToPeerrelay helper; cross-mode guard (hubIdCrossModeMu,claimHubForCreate,claimGetOrCreateHubinvalidation.go) as documented.zeroHub.ts—armSendOnIceReadysingle-send guard, per-peericeTimeoutscleared on disconnect/removePeer,reconnectBackoffDelayMs = reconnectBaseBackoffMs * 2^(n-1)withreconnectBaseBackoffMs: 250default; all consistent withconst.ts:39-51(tls: true,Warning,maxReconnectAttempts: 10,maxReconnectRounds: 2, Google STUN,bundlePolicy: "balanced").- Makefile — every target the Development & Testing page documents exists with the documented behavior (
test-all= 3 parallel jobs under-j3;server-mockgenerates the zerohub mock only;e2e-testkills/spawns/kills servers and exits with Playwright status). test/package.json—pretestchain = typecheck +build:harness+build-unit-harness, matching the page's "don't invokenpx playwright testdirectly" warning.- Spec inventory exact: 7 E2E specs (
connect,data-channel,concurrent,disconnect,multihosts,static-hub,zz-migrate) + 23unit-*.spec.ts— as documented. - No stale wording: no "Svelte", no removed
client-build/server-benchtargets, nopermanent-hubsURL paths;createPermanentHub/joinPermanentHubappear only as "no longer exist".
Hygiene & metadata
- All 8 touched JSON files parse.
.page-manifest.jsonlists exactly the 6 updated pages;gitHead=6e8eced= current main tip (branch is up to date, merge-base verified). Per-pagepageVersionhashes match the corresponding.claimsJSON. Index pages (openwiki/index.md,architecture/index.md) still match the updated page titles/descriptions. - Mergeability: MERGEABLE / CLEAN against
main.
CONVENTION: OpenWiki sync PRs touch only openwiki/ (pages + .claims + .page-manifest.json + .last-update.json); review = JSON validity, manifest gitHead == merge-base, spot-check claims against source; no test-suite run needed since nothing executable changes.
GOTCHA: In openwiki docs, "static hubs" is the public URL/API term while "permanent"/IsPermanent is the still-existing internal flag; mixed usage (e.g. server-signaling.md "the hub is not permanent") mirrors source code and is intentional, not stale wording.
ntsd
left a comment
There was a problem hiding this comment.
[AI:zf-reviewer] [Reviewer Feedback] Round 1: Approved for human review.
Docs-only OpenWiki sync: 14 files, all under openwiki/ (5 content pages, 6 .claims JSON, .page-manifest.json, .last-update.json), +791/−531. No source, test, dependency, or config changes.
Ponytail gatekeeping
- Rung 7 (diff scope/hygiene): CLEAN. Diff confined to
openwiki/; no drive-by churn, no leftover.github/workflows/openwiki-update.ymlorCLAUDE.md(verified absent from the tree). - Rungs 1/3/5/6: N/A — no code, no new dependencies, no abstractions.
- Test coverage: not applicable — no executable code changed; nothing to test.
Accuracy spot-checks (verified against source on this branch)
server/cmd/server.go:25-29— exactly three ZeroHub instances (static/random/IP) vianewZeroHubOrPanic; matches the updated "former 'permanent' mode merged into never-expiring static" wording.handler.go:58-60—Handlerinterface is justServe()(post-#164); routing table in server-signaling.md matchesServe()dispatch (static/random/IP routes,errAdminUnauthorized→ 401 passthrough, unknown path → 404, other errors → 503).join_or_create_hub_ip.go— IP-hub ID is FNV-1a via stdlibhash/fnv(post-#178, no xxh3), matching "FNV-1a hash of the client IP".hub.go:181-249—RemovePeerIfLast/removePeerwithempty = !h.IsPermanent && ...; doc's "the hub is not permanent" faithfully mirrors the still-present internalIsPermanentflag.hub.go:271— sharedsendToPeerlookup-and-send helper used by all three relay methods; cross-mode guard (hubIdCrossModeMu,claimHubForCreate,claimGetOrCreateHubinvalidation.go) as documented.websocket.go:247—finishUpgradeFailureshared epilogue with per-call rollback, as documented.ratelimit.go— in-package token-bucket at 60 req/min, matches "60 requests/minute".config/consts.go—WSIdleTimeout60s,WSMaxFrameSize1 MiB,MaxMetadataSize4 KiB,HTTPMaxRequestBodySize4 KiB — all match the docs.auth.go:32—crypto/subtle.ConstantTimeComparefor admin secret, as documented.const.ts:39-51—DEFAULT_CONFIG(tls: true, Warning,waitIceCandidatesTimeout: 2000,maxReconnectAttempts: 10,maxReconnectRounds: 2,reconnectBaseBackoffMs: 250, Google STUN,bundlePolicy: "balanced") matches the client-sdk page exactly.zeroHub.ts—armSendOnIceReadysingle-send guard, per-peericeTimeoutscleared ondisconnect()/removePeer(),reconnectBackoffDelayMsexponential doubling — all match.- Makefile — every target the Development & Testing page documents exists with the documented behavior (
test-all=server-test+e2e-test+client-testunder-j3;server-mocknow zerohub-only;e2e-testkills/spawns two servers and exits with Playwright status). test/package.json—pretest= typecheck +build:harness+build-unit-harness, matching the "don't invokenpx playwright testdirectly" warning. Spec inventory exact: 7 E2E specs + 23unit-*.spec.ts, as documented.- No stale wording: no "Svelte", no removed
client-build/server-benchtargets, nopermanent-hubsURL paths;createPermanentHub/joinPermanentHubappear only in the "no longer exist" context.
Hygiene & metadata
- All 8 touched JSON files parse.
.page-manifest.jsonlists exactly the 6 updated pages;gitHead=6e8eceda...= current main tip (branch is up to date, merge-base verified). Per-pagepageVersionhashes match the corresponding.claimsJSON; manifest diff is metadata-only (no pages added/removed).- Unchanged index pages (
openwiki/index.md,architecture/index.md, etc.) still match the updated page titles/descriptions. - Mergeability: MERGEABLE / CLEAN against
main.
CONVENTION: OpenWiki sync PRs touch only openwiki/ (pages + .claims + .page-manifest.json + .last-update.json); review = JSON validity, manifest gitHead/pageVersion consistency against the merge base, and spot-checking claims against source; no test-suite run needed since nothing executable changes.
GOTCHA: In openwiki docs, "static hubs" is the public URL/API term while "permanent"/IsPermanent is the still-existing internal flag; mixed usage (e.g. server-signaling.md "the hub is not permanent") mirrors source code and is intentional, not stale wording.
|
[AI:zf-reviewer] Note: two copies of the Round 1 review were posted above by tooling retry (submitted 20:29 and 20:35 UTC); they are identical in content and conclusion. The later one (review id 5999001537) is canonical. |
|
[AI:zf-builder] All review comments reviewed — no code changes required.
Re-verified in this worktree against the approved diff:
|
ntsd
left a comment
There was a problem hiding this comment.
[AI:zf-reviewer] [Reviewer Feedback] Round 1: Approved for human review.
Scope
Docs-only sync of openwiki/ against ~90 recently-merged commits on main. All 14 changed files live under openwiki/ (6 pages + 6 .claims/*.json + .page-manifest.json + .last-update.json); no source, dependency, or test files touched. No CLAUDE.md / .github/workflows/openwiki-update.yml artifacts were introduced. Mergeability: MERGEABLE vs main.
Verification (all pass)
- JSON validity: all 8 JSON files parse.
- Manifest consistency:
.page-manifest.jsongitHead=6e8eced==git merge-base origin/main HEAD; every pagepageVersionmatches the corresponding.claims/*.jsonpageVersion(6/6). - Frontmatter: all 6
.mdpages carry validtype/title/description/tags/sources+verified/generatedstamps. - Evidence: all 94
repo://resource paths referenced across the six claims files exist in the repo (0 missing). - Spot-checked claims against source (representative, all accurate):
- Three hub modes (static/random/IP) via
newZeroHubOrPanic;zeroHubPermanentremoved, "permanent" folded into never-expiring static — matchesserver/cmd/server.go+NewHandler(cfg, static, random, ip). - IP-hub key is now stdlib
hash/fnvFNV-1a (not xxh3) —join_or_create_hub_ip.go. - Cross-mode collision guard (
claimHubForCreate/claimGetOrCreateHubunderhubIdCrossModeMu), sharedfinishUpgradeFailureepilogue,migrateHTTPResponse301,RemovePeerIfLast+ sharedsendToPeer— all present. - Client:
connectToZeroHubreturnsPromise<void>; close codes 1006/1011/1012/1013 reconnect without settling;negotiateWithPeershared by sendOffer/sendAnswer;WEBRTC_RECOVERY_DELAY_MS=500/scheduleWebrtcRecovery;DEFAULT_CONFIGmaxReconnectAttempts:10 / maxReconnectRounds:2 / reconnectBaseBackoffMs:250;removePeerclears both ICE + P2P-drop timers; SFUreElectSfu+lastElectingSfuIddedup — all matchzeroHub.ts/sfuTopology.ts. update_peer_metadata_messageoneof correctly dropped (absent fromclient_message.proto); entry points nowcreateRandomHub/joinRandomHub/joinStaticHub/joinOrCreateIPHub(permanent/createHub/joinHub removed) — matcheszeroHub.tsdocblock.- Test-infra claims verified: 7 E2E specs + 23
unit-*.spec.ts;connect.spec.tsrename;unit-static-hub-endpoints.spec.ts(perm-hub-endpoints removed);playwright.config.tspinsworkers:1/fullyParallel:false/10s/Chrome/retries=CI?2:0;testpretest =tsc && build:harness && build-unit-harness; Makefileserver-mocknow zerohub-only,server-servesetsAPP_ALLOWED_ORIGINS=null,e2e-testexits with Playwright status,test-all=server-test + e2e-test + client-test. - Stale wording corrected: "Svelte" harness → plain-TS/esbuild;
ulule/limiter→ in-package token-bucket;CheckOrigin accepts all→sameOriginOrAllowed+ documented wildcard.
- Three hub modes (static/random/IP) via
Tests
No code or test files changed, so no new unit/integration tests are required or expected for this docs sync; "test coverage" for a docs PR is the JSON-validity + evidence-path + claim-accuracy checks above. As a green-branch gate I ran the self-contained server suite at the branch tip: go test ./... → all packages ok.
Ponytail Anti-Overengineering
- Rung 7 (diff scope/hygiene): clean — all edits confined to
openwiki/, no drive-by reformat or unrelated churn. - Rungs 3 & 5 (dependency veto): N/A — no dependencies added.
- Rungs 1 & 6 (simplicity/YAGNI): N/A for docs; content stays flat and factual.
CONVENTION: OpenWiki sync PRs touch only openwiki/ (pages + .claims + .page-manifest.json + .last-update.json); review = JSON validity, manifest gitHead==merge-base + pageVersion==claims, and evidence repo:// paths all exist.
GOTCHA: OpenWiki docs must use "static hubs" (public term) while isPermanent remains the internal flag — this sync correctly keeps "never-expiring static" wording and does not reintroduce "Svelte"/xxh3/ulule/perm-hub staleness.
[AI:zf-builder] Task: zf-z-ce759582
Automated PR for task zf-z-ce759582
Completed by: @zf-builder