loc-via-git/README.md

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:

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:

curl http://localhost:3000/ssh/public-key

You can also request a specific key:

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:

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

npm install
npm run build
npm start

Docker compose

docker compose up --build

To copy an existing key pair into the Docker volume:

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

npm run smoke