The owner asked for this after failing to find it, which is the whole argument: a
gear in a header is where a settings control is easy to write and not where
anybody looks for one. The bottom of a sidebar is its conventional home, and a
labelled row rather than an icon means it says what it is.
The form opens ABOVE the button so the control does not move when you use it. A
disclosure that walks away from the pointer as it expands is the small kind of
wrong that makes a thing feel unfinished.
`aria-expanded` on the button, because it is a disclosure and a screen reader has
no other way to know the state of one.
The error path still force-opens it - "no account is mapped to you" is the state
every user starts in, and the fix is in that form.
It loaded once. A bookmark is not finished when it is saved - Karakeep crawls it
afterwards, and the picture, description and favicon arrive minutes later - so
the panel sat on "fetching…" while the work quietly completed behind it.
Worse, the page most likely to be full of unfinished ones is the FIRST page.
Newest first, and the crawler works through the backlog, so a fresh import shows
exactly the page with the least on it. Measured while diagnosing: 79 of 97
crawled, and all 16 pending sitting on page one - which reads as a stalled
crawler and is the opposite.
Polls every five seconds while anything is pending, through the same code path as
a first load so a refresh cannot drift from it. Self-limiting and needs no
switch: it re-arms only while something is actually pending, so a settled library
makes no requests at all.
A list of titles and addresses is what a browser's own bookmark bar does. The
reason to keep pages here is that they have been fetched and archived, and a
grid of covers is the cheapest way to show that.
── Which picture, and the trade it costs ──
A crawled bookmark carries two: `content.imageUrl`, the page's own og:image, and
a `screenshot` asset Karakeep took and stores itself. The screenshot is better -
archived, cannot rot, never leaves the house - and it is unreachable from an
`<img>`: Officer authenticates with a bearer token in a header and a browser
cannot put a header on an image request, so the asset route answers 401 from
markup. Fetching each as a blob would work and costs a request, a decode and an
object URL per card.
So the origin's image, with referrerPolicy="no-referrer" so those sites learn
nothing about where the request came from, and loading="lazy" so a long grid does
not fetch a hundred at once. The honest cost, written at the point of use:
viewing your bookmarks makes requests to the sites they point at. Proxying the
archived asset is the fix if that ever matters.
── The empty state is three states ──
Not crawled yet, crawled with nothing to find, and a picture that failed to load.
The first is temporary and the others are not, so it says "fetching…" and the
header counts how many are still going. Measured on the live instance while
writing this: 6 of 50 crawled, the rest pending - so a fresh import spends a
while looking like a broken panel unless it explains itself.
Grid is auto-fill on a minimum width rather than a column count, because this is
one pane of a layout the owner can drag and the columns have to follow the width
it is actually given.
Every response shape written from source was right: lists, bookmarks, search and
the bookmark item's own fields. The door answers 200 with an API key and 401
without, from outside over the public hostname, first attempt - no NEXTAUTH_URL,
no cookies, no container recreate, which is the whole argument for this upstream.
The loopback trap caught this instance too: alpha:3001 answers 200 from anywhere
except alpha, where the name resolves to 127.0.1.1 and nothing is bound. Officer
runs there, so the config holds 127.0.0.1:3001.
Same model as Vault: one instance per install, a sidecar that is the only thing
knowing where it is, two doors - one authenticated for our own UI that injects
the caller's credential, one unauthenticated for a client that carries its own -
and an account per Officer user.
── Why this upstream ──
Linkwarden authenticates its extension through NextAuth: host-scoped cookies,
CSRF checked against the host, absolute URLs baked from NEXTAUTH_URL. Proxying
that means telling the upstream the address the CLIENT uses, which is not the
address the SIDECAR dials, and getting it wrong bounces the extension out of the
proxy mid-login. It cost a NEXTAUTH_URL change, a container recreate, a lost csrf
cookie, and it retired the upstream's own web login as the price of going through
Officer.
Karakeep's extension holds an API key and sends it as a header. Nothing is
host-pinned, so none of that exists. And provisioning needs nothing pasted:
users.create and apiKeys.exchange are both public procedures, so Officer creates
the account, chooses the password, and mints the key itself - where Linkwarden
could only take a key a person made by hand.
── Carried over deliberately ──
Two fixes from the Linkwarden build, both upstream-agnostic and both found by
running it rather than reading it. `content-encoding` stripped from proxied
responses, because fetch decompresses the body while the headers still claim
gzip - which hides until the first response big enough to compress. And
Set-Cookie copied with append rather than set, because it is the one header that
legitimately repeats. Karakeep should never need the second one; it is here
because a proxy correct only for the traffic its author tested is a trap for
whoever changes the upstream later.
Also carried: the unauthenticated door is hand-written rather than the shared
createSidecarProxy router, which does ctx.get("user").id and 500s where there is
no session.
Written against source, not yet run. The response shapes in the panels come from
packages/api/routes/ and are the first thing to check against a live instance.
No provisioning yet.
pastilhas