# 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.

You can also pass `query=<git-url>` as a compatibility alias for `repo`.
This is considered unsafe and discouraged because the name is too generic and easier to misuse or collide with upstream tooling.
Prefer `repo` unless you explicitly need legacy compatibility.

## 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
```