marky

README.md (9604B)

---

 # marky
 
 A simple web API for bookmarking websites, written in Go. It stores bookmarks in a local SQLite database at `~/.marky/bookmarks.sql`, archives a plaintext rendering of each page, and exposes HTTP endpoints for CRUD and full‑text search. A minimal Vue‑enhanced frontend is embedded and served as a few discrete pages (e.g., `/`, `/u:{username}`, `/settings`).
 
 - Language: Go
 - Storage: SQLite (via `modernc.org/sqlite`, pure Go)
 - Default address: `:8080`
 - Frontend: Vue 3 (from CDN), embedded static files
 
 ## Requirements
 
 - Go 1.24+ (tested with 1.24.5)
 - Make (optional, for the provided Makefile)
   (Optional) For archiving, if a `w3m` binary is available in `PATH`, marky uses it to render pages to plaintext; otherwise it falls back to the built‑in Go HTML‑to‑text renderer.
 
 ## Build
 
 - `make build` — builds `bin/marky`
 - Or: `go build -o bin/marky cmd/marky.go`
 
 ## Run
 
 - `./bin/marky [options]`
 - The database file is created automatically (default: `~/.marky/bookmarks.sql`) and migrations are applied on startup.
 - Open the web UI at: `http://localhost:8080/` (or your configured address)
 
 Flags:
 - `--addr` listen address, default `:8080` (e.g., `127.0.0.1:9090`)
 - `--db` path to SQLite DB file (created if missing), default resolves to `~/.marky/bookmarks.sql`
 - `--disable-signup` disable the `/signup` route and hide signup in the UI
 - `--help` show usage and exit
 
 ## Authentication
 
 Marky supports session cookies (for the web UI) and API tokens (for scripts, feeds, and tools).
 
 - Session cookies: set after signup or login in the UI or via endpoints
   - POST `/signup` { username, password }
   - POST `/login` { username, password }
   - POST `/logout`
 
 - API tokens: per-user credential used with HTTP Basic, header, or query param
   - GET `/api/token` → `{ present: true|false }`
   - GET `/api/token?reveal=1` → `{ present: true, api_token: "..." }` when set
   - POST `/api/token` → `{ api_token: "..." }` (generate/regenerate)
 
 Use API tokens with requests:
 - Basic: `curl -u 'username:API_TOKEN' http://localhost:8080/bookmarks`
 - Header: `curl -H 'X-API-Token: API_TOKEN' http://localhost:8080/bookmarks`
 - Query: `curl 'http://localhost:8080/bookmarks?token=API_TOKEN'`
 
 Notes:
 - API tokens are unique (partial unique index) and can be regenerated.
 - Session cookies and tokens are both accepted; if both are present, either suffices.
 
 ## API
 
 ### POST /bookmarks
 
 Create a new bookmark.
 
 - Auth: required (session cookie or API token)
   - Session: set via `/login` or `/signup`
   - API token: provide via one of
     - Basic: `-u 'username:API_TOKEN'`
     - Header: `X-API-Token: API_TOKEN`
     - Query: `?token=API_TOKEN`
 
 - Request headers:
   - `Content-Type: application/json`
 - Request body:
 ```
 {
   "url": "https://example.com",              // required
   "title": "Example",                        // optional; fetched from page <title> if missing
   "description": "Optional description",     // optional
   "referrer": "https://referrer.example"     // optional; site that linked here
 }
 ```
 - Responses:
   - `201 Created` with JSON body of the created bookmark (archive stored synchronously)
   - `200 OK` if the URL already exists; the archive is refreshed and `updated_at` is touched (idempotent by URL)
   - `400 Bad Request` for invalid payload
   - `415 Unsupported Media Type` if not JSON
   - `422 Unprocessable Entity` if archiver fails to fetch content
   - `500 Internal Server Error` on unexpected errors
 - Response body:
 ```
 {
   "id": 1,
   "url": "https://example.com",
   "title": "Example",
   "description": "Optional description",
   "referrer": "https://referrer.example",
   "created_at": "2025-01-01T12:34:56Z",
   "updated_at": "2025-01-01T12:34:56Z"
 }
 ```
 - curl example:
 ```
 curl -i -X POST http://localhost:8080/bookmarks \
   -H 'Content-Type: application/json' \
   -d '{"url":"https://example.com","title":"Example","description":"Sample"}'
 ```
 
 ### GET /bookmarks
 
 List the authenticated user’s bookmarks in reverse chronological order, or search with full‑text. When `q` is provided, results include an `excerpt` with highlighted matches. The endpoint can return JSON (default) or RSS.
 
 - Auth: required (session cookie or API token). Returns `401 Unauthorized` when unauthenticated.
 - Query params:
   - `limit` (optional, default 50, max 200)
   - `offset` (optional, default 0)
   - `q` (optional) full-text query across title, url, description, and archived content
   - `format=rss` (optional) to return an RSS 2.0 feed
 - Responses:
   - `200 OK` with JSON array of bookmarks or RSS feed
   - `400 Bad Request` for invalid `limit` or `offset`
   - `500 Internal Server Error` on unexpected errors
 - curl examples (session or token required for private data):
 ```
 curl -s -u 'username:API_TOKEN' http://localhost:8080/bookmarks | jq
 curl -s -u 'username:API_TOKEN' 'http://localhost:8080/bookmarks?limit=20&offset=20' | jq
 curl -s -u 'username:API_TOKEN' 'http://localhost:8080/bookmarks?q=example' | jq
 curl -s -u 'username:API_TOKEN' 'http://localhost:8080/bookmarks?format=rss' | xmllint --format -
 curl -s -u 'username:API_TOKEN' 'http://localhost:8080/bookmarks.xml?q=example' | xmllint --format -
 ```
 
 Notes on search excerpts:
 - `excerpt` highlights matches using guillemets, e.g., `… some «example» text …`.
 - Ellipses `…` indicate omitted surrounding text, and snippets focus on the archived page content.
 
 ### PUT /bookmarks/{id}
 
 Update a bookmark’s URL, title, and/or description.
 
 - Auth: required (session cookie or API token)
 - Request headers:
   - `Content-Type: application/json`
 - Request body:
 ```
 {
   "url": "https://example.com",     // required
   "title": "New Title",              // required
   "description": "Updated notes"     // optional (omitted preserves existing)
 }
 ```
 - Responses:
   - `200 OK` with updated bookmark JSON
   - `400 Bad Request` for invalid payload
   - `404 Not Found` if the bookmark ID does not exist
   - `500 Internal Server Error` on unexpected errors
 - curl example:
 ```
 curl -s -X PUT http://localhost:8080/bookmarks/1 \
   -H 'Content-Type: application/json' \
   -d '{"url":"https://example.com","title":"Updated","description":"Notes"}' | jq
 ```
 
 ### DELETE /bookmarks/{id}
 
 Delete a bookmark (and its search index entry). Archived text is removed from search index but remains in `archives` table only if you retain rows; this implementation removes the FTS entry, and the foreign key setup will cascade archives removal if configured via migrations.
 
 - Auth: required (session cookie or API token)
 - Responses:
   - `204 No Content` on success
   - `404 Not Found` if the bookmark ID does not exist
   - `500 Internal Server Error` on unexpected errors
 - curl example:
 ```
 curl -i -X DELETE http://localhost:8080/bookmarks/1
 ```
 
 ### Per‑user feeds
 
 Feeds are normalized under `/u:{username}(.format)` where `format` is `json` or `rss`. When no format is provided, HTML is served.
 
 - Examples (include private when authenticated):
   - Basic: `curl -u 'dce:API_TOKEN' http://localhost:8080/u:dce.rss`
   - Header: `curl -H 'X-API-Token: API_TOKEN' http://localhost:8080/u:dce.json`
   - Query: `curl 'http://localhost:8080/u:dce.json?token=API_TOKEN'`
 
 Notes:
 - Unauthenticated or non‑owner requests return only public bookmarks.
 - Owner (session, Basic auth, header, or query token) sees all bookmarks (public + private).
 
 ### Bookmarklet
 
 - Open `/settings` while logged in to get a “Save to Marky” bookmarklet you can drag to your bookmarks bar.
 - Clicking the bookmarklet on any page opens a small popup with URL and title prefilled; you can adjust description and toggle public/private.
 - The popup submits to `/bookmarks` using your session or API token (embedded when present).
 
 ## Data Model
 
 Table: `bookmarks`
 - `id` INTEGER PRIMARY KEY AUTOINCREMENT (starts at 1)
 - `user_id` INTEGER NOT NULL REFERENCES `users(id)`
 - `url` TEXT NOT NULL (unique per user: `(user_id, url)`)
 - `title` TEXT NOT NULL
 - `description` TEXT NULL
 - `public` INTEGER NOT NULL DEFAULT 0
 - `created_at` TEXT NOT NULL (RFC3339)
 - `updated_at` TEXT NOT NULL (RFC3339)
 
 Migrations are embedded and applied automatically on startup.
 
 An `archives` table stores the plaintext dump per bookmark and is kept in sync on creation.
 
 ### GET /bookmarks/{id}/archive
 
 Return the archived plaintext for the given bookmark ID.
 
 - Auth: not required (returns plain text if the archive exists)
 - Responses:
   - `200 OK` with `text/plain; charset=utf-8`
   - `404 Not Found` if no archive exists for the bookmark
   - `500 Internal Server Error` on unexpected errors
 
 curl example:
 ```
 curl -s http://localhost:8080/bookmarks/1/archive
 ```
 
 ## Development
 
 - Code entrypoint: `cmd/marky.go`
 - Database and helpers: `internal/`
 - Migrations: `internal/migrations/*.sql`
 - Archiver: `internal/archiver.go` (pure-Go HTML-to-text)
 - Embedded web UI: `internal/web/` (discrete pages)
 
 ### Reverse proxy / HTTPS
 
 - When running behind a TLS-terminating proxy (e.g., Cloudflare, nginx), the app
   infers the public origin from standard headers and generates correct `https://`
   links for the bookmarklet and feeds.
 - Recognized headers: `X-Forwarded-Proto`, `X-Forwarded-Host`, `X-Forwarded-Scheme`,
   `X-Forwarded-Ssl`, `Forwarded`, and Cloudflare's `Cf-Visitor`.
 - To force a specific origin, set `--base-url` (e.g., `marky --base-url https://bookmarks.example.com`) or the env var `MARKY_BASE_URL`.
 
 ---
 
 ## Acknowledgments
 
 This project was developed with the assistance of [ChatGPT][1] for code generation.
 
 [1]: https://openai.com/chatgpt
 
 ## License
 
 MIT License -- see LICENSE for details.