Initial service implementation

README.md

@@ -0,0 +1,110 @@
+# loc-via-git
+
+Tiny API that clones a Git repo and counts its non-empty lines of code.
+
+## Features
+
+- Plain text and JSON endpoints
+- Optional API key enforcement
+- Per-repo in-memory caching
+- Extension-based language breakdown
+- Basic rate limiting
+- Bounded concurrent scans so the host does not get hammered
+- SSH key file support for private repos
+- Docker Compose deployment
+
+## Endpoints
+
+- `GET /loc.txt?repo=<git-url>&ssh_key=<optional-key-file>&ref=<optional-ref>`
+  - Returns the line count as plain text.
+- `GET /loc?repo=<git-url>&ssh_key=<optional-key-file>&ref=<optional-ref>`
+  - Returns JSON metadata, including a language breakdown by files and non-empty lines.
+- `GET /health`
+  - Health plus queue/cache stats.
+
+## Auth
+
+No auth by default. If `API_KEY` is set, send it as either:
+
+- `x-api-key: ...`
+- `Authorization: Bearer ...`
+
+## SSH keys
+
+SSH keys live inside the Docker volume mounted at `/app/keys`, not in the repo or a host bind mount.
+
+You have two options:
+
+- Provide a key pair yourself inside the `ssh_keys` Docker volume
+- Let the service generate the default key by setting `GENERATE_SSH_KEY_IF_MISSING=true`
+
+Example:
+
+```bash
+curl "http://localhost:3000/loc?repo=ssh://git@example.com/org/repo.git&ssh_key=loc_via_git_ed25519"
+```
+
+Fetch the public key to add it on the Git host:
+
+```bash
+curl http://localhost:3000/ssh/public-key
+```
+
+You can also request a specific key:
+
+```bash
+curl "http://localhost:3000/ssh/public-key?ssh_key=loc_via_git_ed25519"
+```
+
+## Cleanup and caching
+
+- Every clone happens in a temporary directory and is deleted in a `finally` block after the scan finishes or fails.
+- The service also sweeps stale temp directories in case a process dies mid-scan.
+- Cache entries live in memory only and expire after `CACHE_TTL_MINUTES`.
+
+## Configuration
+
+Copy `.env.example` to `.env` and adjust:
+
+```env
+PORT=3000
+API_KEY=
+CACHE_TTL_MINUTES=5
+CACHE_SWEEP_INTERVAL_MINUTES=5
+RATE_LIMIT_WINDOW_MINUTES=5
+RATE_LIMIT_MAX=30
+MAX_CONCURRENT_SCANS=4
+CLONE_TIMEOUT_SECONDS=45
+DEFAULT_SSH_KEY_NAME=loc_via_git_ed25519
+GENERATE_SSH_KEY_IF_MISSING=false
+TRUST_PROXY=false
+SSH_KEYS_DIR=/app/keys
+TMP_DIR=/tmp/loc-via-git
+```
+
+## Local run
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+## Docker compose
+
+```bash
+docker compose up --build
+```
+
+To copy an existing key pair into the Docker volume:
+
+```bash
+docker cp ./id_ed25519 loc-via-git-api-1:/app/keys/loc_via_git_ed25519
+docker cp ./id_ed25519.pub loc-via-git-api-1:/app/keys/loc_via_git_ed25519.pub
+```
+
+## Smoke test
+
+```bash
+npm run smoke
+```