freelang-gogs-search-api

Advanced Gogs repository search API with filtering, classification, and statistics.

Features

• 🔍 Range-based filtering - Filter by type, size, activity, commits
• 🏷️ Repository classification - Automatically classify code vs data repos
• 📊 Statistics - Aggregated stats for any repository range
• ⚡ Fast - Caching-ready, <500ms response time
• 🔐 Secure - Helmet, CORS, rate limiting ready

Installation

npm install

Setup

Create .env file:

PORT=30026
NODE_ENV=production
GOGS_HOST=https://gogs.dclub.kr
GOGS_TOKEN=your_api_token

Running

Development

npm run dev

Production

npm start

With PM2

npm run pm2

API Endpoints

1. Description-based Search (NEW!)

GET /api/repos/search/query

Parameters:

• q or query: Search term (required)
• type: code, data, or all (default: all)
• sort: updated, size, commits, name, relevance (default: updated)
• order: asc, desc (default: desc)
• limit: 1-500 (default: 30)
• offset: Pagination offset (default: 0)
• case: Case-sensitive search (default: false)

Examples:

# Search for "api" in descriptions (sorted by relevance)
curl "http://localhost:30026/api/repos/search/query?q=api&sort=relevance"

# Search for "deploy" in code repos
curl "http://localhost:30026/api/repos/search/query?q=deploy&type=code&limit=20"

# Search for "database" (case-sensitive)
curl "http://localhost:30026/api/repos/search/query?q=database&case=true"

# Search "microservice" with pagination
curl "http://localhost:30026/api/repos/search/query?q=microservice&limit=50&offset=50"

Response:

{
  "status": "ok",
  "query": "api",
  "total_count": 9668,
  "search_count": 245,
  "results": [
    {
      "id": 123,
      "name": "api",
      "description": "REST API server",
      "repo_type": "code",
      "match_score": 100
    }
  ]
}

Search Scoring:

• Name match: +100 points
• Full name match: +50 points
• Description match: +25 points
• Sorted by relevance score when sort=relevance

2. Range-based Filtering

GET /api/repos/search/filter

Parameters:

• type: code, data, or all (default: all)
• data_type: geographic, test, shared, indexed (for data repos)
• size_min, size_max: Size range in KB
• commits_min, commits_max: Commit count range
• days_updated: Within N days (recent activity)
• days_abandoned: N+ days without updates
• sort: updated, size, commits, name (default: updated)
• order: asc, desc (default: desc)
• limit: 1-500 (default: 30)
• offset: Pagination offset (default: 0)
• exclude_empty: true/false (default: false)

Examples:

# Code repos 1GB-10GB, sorted by size
curl "http://localhost:30026/api/repos/search/filter?type=code&size_min=1048576&size_max=10485760&sort=size"

# Geographic data repos, updated in last 30 days
curl "http://localhost:30026/api/repos/search/filter?type=data&data_type=geographic&days_updated=30"

# Abandoned repos (90+ days)
curl "http://localhost:30026/api/repos/search/filter?days_abandoned=90&limit=50"

Response:

{
  "status": "ok",
  "total_count": 9668,
  "filtered_count": 42,
  "limit": 30,
  "offset": 0,
  "page": 1,
  "total_pages": 2,
  "results": [
    {
      "id": 123,
      "name": "api",
      "full_name": "kim/api",
      "size": 5368709,
      "commits": 1250,
      "updated_at": "2026-01-31T12:30:00Z",
      "repo_type": "code",
      "data_type": null
    }
  ],
  "response_time_ms": 145
}

2. Repository Classification

GET /api/repos/search/classify

Parameters:

• sample_size: Analysis sample size, 1-10000 (default: 1000)
• include_details: Include breakdown and examples (default: false)

Examples:

# Classify latest 1000 repos
curl "http://localhost:30026/api/repos/search/classify?sample_size=1000"

# With detailed breakdown
curl "http://localhost:30026/api/repos/search/classify?sample_size=1000&include_details=true"

Response:

{
  "status": "ok",
  "sample_size": 1000,
  "total_count": 9668,
  "analysis": {
    "code_repos": {
      "count": 600,
      "percentage": "60.0"
    },
    "data_repos": {
      "count": 400,
      "percentage": "40.0",
      "breakdown": {
        "geographic": 150,
        "test": 120,
        "indexed": 80,
        "shared": 50
      }
    }
  },
  "examples": {
    "code": ["api", "deploy", "llama.cpp"],
    "data_geographic": ["australia", "antarctica", "asia"]
  },
  "response_time_ms": 523
}

3. Range Statistics

GET /api/repos/search/stats

Parameters:

• type: code, data, or all (default: all)
• size_min, size_max: Size range filter
• days_updated: Activity filter (N days)
• days_abandoned: Inactivity filter (N+ days)

Examples:

# Stats for all code repos
curl "http://localhost:30026/api/repos/search/stats?type=code"

# Stats for 1GB-10GB code repos
curl "http://localhost:30026/api/repos/search/stats?type=code&size_min=1048576&size_max=10485760"

# Stats for recently active repos
curl "http://localhost:30026/api/repos/search/stats?days_updated=7"

Response:

{
  "status": "ok",
  "filter": {
    "type": "code",
    "size_min": null,
    "size_max": null
  },
  "stats": {
    "total_repos": 6000,
    "total_size_kb": 2097152000,
    "total_size_readable": "2TB",
    "avg_size_kb": 349525,
    "total_commits": 2700000,
    "avg_commits": 450,
    "activity": {
      "recent_7days": 1200,
      "active_30days": 3600,
      "inactive_90days": 900,
      "abandoned_90plus": 300
    },
    "size_distribution": {
      "0-100MB": 1500,
      "100MB-1GB": 2500,
      "1GB-10GB": 1500,
      "10GB+": 500
    }
  },
  "response_time_ms": 234
}

4. Range Statistics

GET /api/repos/search/stats

Parameters:

• type: code, data, or all (default: all)
• size_min, size_max: Size range filter
• days_updated: Activity filter (N days)
• days_abandoned: Inactivity filter (N+ days)

Examples:

# Stats for all code repos
curl "http://localhost:30026/api/repos/search/stats?type=code"

# Stats for 1GB-10GB code repos
curl "http://localhost:30026/api/repos/search/stats?type=code&size_min=1048576&size_max=10485760"

# Stats for recently active repos
curl "http://localhost:30026/api/repos/search/stats?days_updated=7"

Response:

{
  "status": "ok",
  "filter": {
    "type": "code",
    "size_min": null,
    "size_max": null
  },
  "stats": {
    "total_repos": 6000,
    "total_size_kb": 2097152000,
    "total_size_readable": "2TB",
    "avg_size_kb": 349525,
    "total_commits": 2700000,
    "avg_commits": 450,
    "activity": {
      "recent_7days": 1200,
      "active_30days": 3600,
      "inactive_90days": 900,
      "abandoned_90plus": 300
    },
    "size_distribution": {
      "0-100MB": 1500,
      "100MB-1GB": 2500,
      "1GB-10GB": 1500,
      "10GB+": 500
    }
  }
}

5. Health Check

GET /health

Classification Logic

Repository Types

• Code: Real projects, services, frameworks, libraries, tools
• Data: Geographic data, test datasets, indexed storage, shared folders

Data Subtypes

• geographic: australia, antarctica, asia, europe, etc.
• test: testdata, snapshots, processing, textsplitters
• shared: SHARED, shared_folders
• indexed: id-40945, id-3, id-62 patterns

Performance

• Typical response time: 100-500ms
• Max results per request: 500
• Supports pagination via limit/offset
• Ready for caching (5-60 min TTL)

Size Units

All size values are in KB:

• 100MB = 102,400 KB
• 1GB = 1,048,576 KB
• 10GB = 10,485,760 KB
• 1TB = 1,048,576,000 KB

Activity Thresholds

Common patterns:

• days_updated=7 - Active in last week
• days_updated=30 - Active in last month
• days_abandoned=90 - Not updated for 3 months
• days_abandoned=180 - Not updated for 6 months

Integration with api-hub

This API is registered in dns.dclub.kr/api-hub.html with endpoints:

• /api/repos/search/filter
• /api/repos/search/classify
• /api/repos/search/stats

Implementation Details

Language: Node.js + Express 5.0 Dependencies: axios, helmet, cors, morgan, dotenv Binary size: ~50MB (node_modules) Memory: ~100MB Startup: ~2-3 seconds

Related

• freelang-gogs-client: Low-level Gogs API client (FreeLang)
• freelang-repo-search: CLI for this API (FreeLang)

License

MIT