kyle/kls

Files

Kyle Isom 0fa85cb300 migrate to SQLite and prepare for MCP deployment

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>

2026-03-27 16:18:37 -07:00

2.2 KiB

Raw Blame History

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

go build -o kls .
./kls -f /path/to/kls.conf

No Makefile, no tests. The binary is .gitignored.

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.

2.2 KiB Raw Blame History