From bf6d9f5cb31615a55ed822cf6df371ea43aeb203 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Padez?= Date: Sat, 5 Sep 2026 21:38:47 +0100 Subject: [PATCH] verified against a live instance 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. --- README.md | 30 +++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 3cfb8a6..345eee8 100644 --- a/README.md +++ b/README.md @@ -62,14 +62,30 @@ Both were bugs found by running it, and both are upstream-agnostic: repeats. Karakeep should never need this; it is here because a proxy that is correct only for the traffic its author happened to test is a trap for whoever changes the upstream later. -## State +## Verified against a live instance -Written against the source, **not yet run**. The response shapes below come from -`packages/api/routes/`, and are the first thing to verify against a live instance: +2026-09-05, against Karakeep on alpha. Every shape written from source turned out to be right: -- `GET /api/v1/lists` → `{ lists: [...] }` -- `GET /api/v1/bookmarks` → `{ bookmarks: [...], nextCursor }` -- `GET /api/v1/bookmarks/search?q=` → the same, paginated -- `GET /api/v1/lists/:listId/bookmarks` → the same +| | | +| --- | --- | +| `GET /api/v1/lists` | `{ lists: [...] }` | +| `GET /api/v1/bookmarks` | `{ bookmarks: [...], nextCursor }` | +| `GET /api/v1/bookmarks/search?q=` | the same, paginated | +| a bookmark | `title`, `tags[]`, `content: { type: 'link', url, title, description }` | + +And the door works from outside, over the public hostname, first attempt: + +``` +https:///api/karakeep/kk/api/v1/bookmarks + with an API key → 200, 20 bookmarks + without one → 401 +``` + +No `NEXTAUTH_URL`, no cookies, no container recreate — which is the entire argument for this upstream +over the last one. + +**The address the sidecar dials is loopback**, `http://127.0.0.1:3001`, and this bit again: `alpha:3001` +answers 200 from anywhere else and **000 from alpha itself**, because the name resolves to 127.0.1.1 +there and Karakeep binds 127.0.0.1 and 100.64.0.1. Officer runs on that host. No provisioning yet — `api/accounts.ts` is the next piece.