Kyle Isom
0fa85cb300
Switch from PostgreSQL to SQLite (modernc.org/sqlite, pure Go) for simpler deployment on the MCP platform. Fix URL normalization to preserve query parameters so sites like YouTube deduplicate correctly. Add Dockerfile, Makefile, and MCP service definition. Add pg2sqlite migration tool. Support $PORT env var for MCP port assignment. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
44 lines
2.2 KiB
Markdown
44 lines
2.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What is kls
|
|
|
|
A URL shortener web service. Users submit a URL, get back a 5-character short code. Visiting `/<code>` redirects to the original URL. Admin routes (POST, /list) are protected with HTTP Basic Auth.
|
|
|
|
## Build and Run
|
|
|
|
```bash
|
|
go build -o kls .
|
|
./kls -f /path/to/kls.conf
|
|
```
|
|
|
|
No Makefile, no tests. The binary is `.gitignore`d.
|
|
|
|
## Configuration
|
|
|
|
Uses `goutils/config` to load a key=value config file (default `~/.config/kls/kls.conf`). Required keys:
|
|
|
|
- `DB_PASSWORD`, `DB_HOST` — no defaults
|
|
- `HTTP_USER`, `HTTP_PASS` — Basic Auth credentials
|
|
- `HTTP_ADDR` — bind address
|
|
|
|
Optional (have defaults): `DB_ENGINE` (postgres), `DB_NAME` (kls), `DB_USER` (kls), `DB_PORT` (5432), `HTTP_PORT` (8000).
|
|
|
|
## Architecture
|
|
|
|
- **`main.go`** — entry point: loads config, connects to DB, starts HTTP server.
|
|
- **`handler.go`** — HTTP routing and handlers on the `server` struct. Implements `ServeHTTP` directly (no router library). GET requests matching a valid short code bypass auth and redirect; everything else requires Basic Auth. Templates are embedded via `//go:embed`.
|
|
- **`links/`** — core domain package:
|
|
- `url.go` — `URL` model, CRUD operations (Store, Lookup, StoreURL, RetrieveURL, FetchAll), URL normalization (strips query/fragment by default), and cleaning logic. Uses squirrel for query building with PostgreSQL dollar placeholders.
|
|
- `db.go` — PostgreSQL connection setup via pgx/v4 pool.
|
|
- `alphabet.go` — short code generation: 5 random characters from an unambiguous alphabet (`ABCDEFGHJKMNPQRSTUVWXYZ23456789`, excludes 0/O/1/I/L). `ValidShortCode` regex is used for routing.
|
|
- **`schema.sql`** — single `urls` table with `id` (UUID), `url`, `nurl` (normalized), `short` (unique), `created_at`.
|
|
- **`templates/`** — Go HTML templates (`index.tpl` for submit form, `list.tpl` for listing all URLs).
|
|
|
|
## Key behaviors
|
|
|
|
- **Deduplication**: `StoreURL` checks for an existing normalized URL before creating a new entry.
|
|
- **URL cleaning**: By default, query strings are stripped. The "rawp" form checkbox preserves the original query string.
|
|
- **No router**: `server.ServeHTTP` handles all dispatch — check there when adding routes.
|