newsroom 5.2: Readeck export (ICB-147) #270
No reviewers
Labels
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
prskr/tools!270
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "ICB-147-newsroom-5-2-readeck-export"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Task 5.2 of the
newsroomOpenSpec change (ICB-147). Brief:newsroom/tasks/15-readeck-export.md.What
newsroom/internal/readeck: hand-rolled client (net/http+encoding/json, no new dependency) and a once-onlyExporter. Package doc states this is the one user-initiated write that calls out from the serving side.POST /ui/entry/{id}/exportreturns the re-rendered#export-control: Save button, or Saved linking to<baseURL>/bookmarks/<id>. The control sits in the reader action bar. Failure is shown inline (HTTP 200 so HTMX swaps it; a 4xx/5xx would not be swapped) and stores nothing.Link, neverOriginalLink, with the configured labels.readeck_exported_atreturns the stored id with zero HTTP calls. Exports are serialised by a mutex so a double-click cannot create two bookmarks before the first is recorded. The store write after a successful create usescontext.WithoutCancelso a cancelled request cannot lose a bookmark that already exists.web.WithExport(...)no control renders and the endpoint answers 501; the store is untouched.tasks.md.Readeck API verification
Not verified live (no Readeck instance reachable from here). Verified from the upstream docs source, tag 0.23.4 (
docs/api/bookmarks/routes-bookmarks.yaml,types.yaml,base.md,traits.yamlat codeberg.org/readeck/readeck):POST {base}/api/bookmarks, JSON body{"url", "title"?, "labels"?}✅ (spec)Authorization: Bearer <token>✅ (spec)Bookmark-Idresponse header (client falls back to the last segment ofLocation) ✅ (spec). Nothing to poll.Also unverified live: the
{base}/bookmarks/<id>UI URL used for the "Saved" link (derived from Readeck's web routes, not from the API spec).Token wiring for 6.1
readeck.NewClient(baseURL, token, labels)andreadeck.NewExporter(store, client); thenweb.Handler(lib, feeds, web.WithExport(exporter, cfg.Readeck.BaseURL)), only whencfg.Readeck != nil. Bind the token to a kong flag with an env var (e.g.READECK_TOKEN) in 6.1;NewClientrejects an empty token. The token appears in no error string or log line (tested).Verification
bazel test --config=remote //newsroom/...: 20/20 pass, including//newsroom/internal/web:web_integration_test(ran for real; includesTestExportOverRealStore: two exports → one POST to the stub, DB row set; failure leaves entry unexported),//newsroom/internal/readeck:readeck_test, nogo/nilaway/golangci clean.go test -cover ./newsroom/internal/readeck/: 90.5% statements (go test, notbazel coverage).bazel run //:formatfails with a git "dubious ownership" error; instead rangofumpt -l(clean) andgofmt -l(clean). CIValidatestill to be checked on this commit.find . -type lempty).Not covered / notes
/ui/POSTs (newsroom-cleanup 6.1 covers the new endpoint too). The export control follows the existing read/star fragment pattern for list context (cleanup 1.1); no back-link/context handling added.🤖 Generated with Claude Code
Hand-rolled Readeck client + once-only exporter, POST /ui/entry/{id}/export and a Save/Saved control in the reader actions. Disabled (no control, 501) without a readeck section. Token is a constructor parameter only. Co-Authored-By: Paperclip <noreply@paperclip.ing>Verdict: CHANGES REQUESTED (1 blocking, 3 should-fix, rest minor/nits)
PR: #270, reviewed commit
c5225c78ff8881b05f91452e413e2a13e2a03443, the only commit on the branch. Review done with/code-review(high), then each finding checked by hand. Not merged.Success condition tested
The brief
newsroom/tasks/15-readeck-export.mdplus the newsroom-ui spec "Readeck export is manual and idempotent" / "Readeck is optional and its token is protected". The ICB-148 plan checklist applies, and kong token binding and CSRF stay out of scope (6.1).Steps run (in a detached worktree of
c5225c7)Blocking
layout.templtheExportControllink is built withreadeck.BookmarkURL(ex.BaseURL, id), and thatBaseURLis the samereadeck.baseURLthe server uses to call the API (WithExport(exporter, cfg.Readeck.BaseURL)per the 6.1 notes).newsroom/config.yamldocumentsbaseURL: http://readeck.tools.svc:8000.http://readeck.tools.svc:8000/bookmarks/<id>, which a browser outside the cluster cannot resolve.readeck.publicURL, defaulting tobaseURL) and pass that toWithExport.WithExportalready takes the URL separately, so the change is mostly config. (b) If the owner wants a single URL, document thatbaseURLmust be reachable from the browser and change theconfig.yamlexample. If the choice is unclear, ask Steve Wozniak.Should fix (not blocking on their own)
export.goExport). Every export of every entry is serialised. If Readeck hangs, N clicks queue for up to N x 5s, and a request whose client has already gone still waits for the lock and then POSTs. The brief says "Readeck being slow must not hold an HTTP handler open". Suggested fix: lock per entry id, and/or acquire through achan struct{}semaphore withselectonctx.Done().SetReadeckExportoverwrites without a condition. Deploy isreplicas: 1withRollingUpdate, so two pods overlap only briefly. If clicks hit both pods in that window, two bookmarks are created and the second id silently replaces the first. Readeck's duplicate-URL behaviour is undocumented (Linus says so too), so local state is the only guard. In this homelab it hardly matters in practice, but at least make the write conditional (... WHERE readeck_exported_at IS NULL) so the first id is kept. Otherwise record this as a known limitation.Minor / nits
lib.GetEntry(r.Context())a second time. If the client disconnects, that fails withcontext.Canceled, andfail()logs it at ERROR and writes a 500. That is log noise on every abandoned click. Return the already-loaded entry fromExporttogether with the error instead.Locationfallback inbookmarkIDtakes the raw text after the last/, so a query or fragment would end up in the stored id. Upstream 0.23.4 only documentsBookmark-Id, so this is hypothetical. Usepath.Base(u.Path)afterurl.Parse.readeck.ErrEntryNotFoundduplicateslibrary.ErrNotFound, whichfail()already maps to 404.readeck_test.goexporter()and the dead-server block uset.Fatal/t.Errorfguards instead ofassert.NoErrorplus the sanctioned "Unreachable:" panic guard. The newslog.WarnContextline uses loose key/value pairs instead ofslog.Int64/slog.Any; the existingfail()does the same, so it matches local style.Checklist results
StatusErrorcarries only the status, the transport error is unwrapped, and the response body is discarded.TestTokenNeverInLogsOrErrorscovers status, missing id, a server that echoes the token, and a dead server. The inline UI messages are fixed strings.e.Linkis sent. Unit and integration tests assert this, and the fixture'sOriginalLinkdiffers fromLink.TestExportOverRealStore). Concurrency: see 2–3.POST /ui/entry/{id}/exportcalls Readeck, and renders only read stored state. The package doc explains why this call is allowed.context.WithTimeout(ctx, 5s)on the request ctx. The lock wait is not bounded: see 2.TestExportDisabled).POST /api/bookmarks,bookmarkCreate{url (required), labels[]},202with aBookmark-Idheader. Not verified: the UI path/bookmarks/<id>(the API doc only covers/api/...), duplicate-URL behaviour, and the bearer scheme name. The traits file was not opened, though the code uses the standard token form. No live instance.buttonfor Save. Output is templ-escaped and the id is path-escaped in the link. The link target is wrong: see 1.c5225c7, 5.2 ticked, no new dependency, coverage 90.3% (>70%), no symlinks.Not covered
Bookmark-Idand the UI path were not exercised for real.WithExportfrom config) is out of scope (6.1) and not reviewed. Until 6.1 lands, the feature cannot be switched on in production.Next owner: Linus Torvalds for #1 (plus #2–#4 if cheap). If the URL decision in #1 needs the owner, ask Steve Wozniak. I will re-review new commits with
/code-review.Verdict: PASS — re-review of PR #270 at
8ba37ec(fixes on top ofc5225c7). All blocking and should-fix items from the first review are resolved. Nothing blocks the merge.Success condition tested: the four items from my first verdict are fixed without regressions: (1) the "Saved" link can point at a browser-reachable Readeck URL; (2) the export lock is per entry and the wait honours ctx; (3) the first recorded bookmark id wins; (4) if the DB write fails after Create, the bookmark id is not lost silently. The original 5.2 acceptance criteria still hold: tests green including integration, CI
Validategreen, no new dependency, no symlinks, PR open and unmerged.Steps run (this commit, worktree
ICB-147-newsroom-5-2-readeck-export):git diff c5225c7 8ba37ec— 10 files changed, all scoped to the four findings. No scope creep.bazel test --config=remote --experimental_convenience_symlinks=ignore --nocache_test_results //newsroom/...→Executed 20 out of 20 tests: 20 tests pass.This includesstorage_integration_test(real Postgres via remote podman),web_integration_test,readeck_test, andwrite_dbgen_test. The integration targets are not taggedmanual, so the wildcard covers them.CGO_ENABLED=1 go test -race -count=20 -run Export ./newsroom/internal/readeck/→ok. Neither fix comment mentions a race-detector run, so I ran this for the new lock code.go test -race -count=5→ 5/5 PASS.8ba37ec→Validate / validate (pull_request) success; PR #270open,merged=false, head8ba37ec, basemain.find . -type l -not -path './.git/*'→ empty.Findings vs. first review:
readeck.publicURL(absolute-URL validated),UIURL()falls back tobaseURL; config tests cover both the invalid case and the default;config.yamldocuments both. 6.1 must passcfg.Readeck.UIURL()toWithExport.TestExportWaitForSameEntryHonoursContextplus my probe show the same entry is serialised and a different entry is not blocked. Race detector is clean.WHERE id = $1 AND readeck_exported_at IS NULLin both the query and the generated code. The storage integration test writes a second id and asserts the original id and time survive the re-upsert. The hand-edited sqlc output is confirmed equal to real generator output bywrite_dbgen_testpassing.slog.ErrorContextlogs entry + bookmark id; the error wraps it; tested (TestExportRecordFailureNamesBookmark). The log has no token.Minor (non-blocking, follow-up at the owner's discretion):
SetReadeckExport(:exec) updates 0 rows silently.Exportthen returns its own losing bookmark id as success, so that Readeck bookmark is orphaned and the UI shows a link that differs from the stored one until reload. This only happens with more than one replica; within one process the per-entry lock prevents it. Fix if wanted::execrows, then re-read the entry when 0 rows are updated.Not covered: no live Readeck instance, so the API shape (
Bookmark-Idheader,/bookmarks/<id>UI path) is still verified only from the upstream docs at 0.23.4, as in the first review. The cross-process race (m1) was analysed but not reproduced.bazel run //:formatandbazel coveragewere not rerun; CIValidatecovers format/lint. App wiring (kong, token env) is task 6.1, out of scope.Next owner: no fixes are needed from Linus Torvalds. PR #270 is ready to merge; that is the owner's decision via Steve Wozniak. I have not merged anything.