@doccov/api 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @doccov/api
 
+## 0.3.0
+
+### Minor Changes
+
+- add rate limiting middleware and job store abstractions
+
+### Patch Changes
+
+- Updated dependencies
+  - @openpkg-ts/spec@0.4.1
+
+## 0.2.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @openpkg-ts/spec@0.4.0
+
 ## 0.2.2
 
 ### Patch Changes

package/api/scan-stream.ts

@@ -1,14 +1,14 @@
 import { Writable } from 'node:stream';
-import type { VercelRequest, VercelResponse } from '@vercel/node';
-import { Sandbox } from '@vercel/sandbox';
 import {
-  SandboxFileSystem,
   detectBuildInfo,
   detectMonorepo,
   detectPackageManager,
   getInstallCommand,
   getPrimaryBuildScript,
+  SandboxFileSystem,
 } from '@doccov/sdk';
+import type { VercelRequest, VercelResponse } from '@vercel/node';
+import { Sandbox } from '@vercel/sandbox';
 
 export const config = {
   runtime: 'nodejs',
@@ -153,7 +153,13 @@ async function runScanWithProgress(
           // Try fetching the ref first (might be a tag not fetched by shallow clone)
           await sandbox.runCommand({
             cmd: 'git',
-            args: ['fetch', '--depth', '1', 'origin', `refs/tags/${options.ref}:refs/tags/${options.ref}`],
+            args: [
+              'fetch',
+              '--depth',
+              '1',
+              'origin',
+              `refs/tags/${options.ref}:refs/tags/${options.ref}`,
+            ],
           });
           const retryResult = await sandbox.runCommand({
             cmd: 'git',
@@ -174,7 +180,9 @@ async function runScanWithProgress(
 
       // Detect package manager using SDK
       const pmInfo = await detectPackageManager(fs);
-      const pmMessage = pmInfo.lockfile ? `Detected ${pmInfo.name} project` : 'No lockfile detected';
+      const pmMessage = pmInfo.lockfile
+        ? `Detected ${pmInfo.name} project`
+        : 'No lockfile detected';
       sendEvent({ type: 'progress', stage: 'detecting', message: pmMessage, progress: 15 });
 
       // Early monorepo detection - fail fast if monorepo without package param
@@ -189,9 +197,7 @@ async function runScanWithProgress(
             progress: 17,
           });
 
-          const availablePackages = mono.packages
-            .filter((p) => !p.private)
-            .map((p) => p.name);
+          const availablePackages = mono.packages.filter((p) => !p.private).map((p) => p.name);
 
           await sandbox.stop();
           sendEvent({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/api",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "DocCov API - Badge endpoint and coverage services",
   "keywords": [
     "doccov",
@@ -27,10 +27,11 @@
     "format": "biome format --write src/"
   },
   "dependencies": {
-    "@openpkg-ts/spec": "^0.3.0",
+    "@openpkg-ts/spec": "^0.4.1",
     "@vercel/sandbox": "^1.0.3",
     "hono": "^4.0.0",
-    "ms": "^2.1.3"
+    "ms": "^2.1.3",
+    "zod": "^3.25.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/index.ts

@@ -1,5 +1,6 @@
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
+import { rateLimit } from './middleware/rate-limit';
 import { badgeRoute } from './routes/badge';
 import { leaderboardRoute } from './routes/leaderboard';
 import { scanRoute } from './routes/scan';
@@ -10,6 +11,16 @@ const app = new Hono();
 // Middleware
 app.use('*', cors());
 
+// Rate limit /scan endpoint: 10 requests per minute per IP
+app.use(
+  '/scan/*',
+  rateLimit({
+    windowMs: 60 * 1000,
+    max: 10,
+    message: 'Too many scan requests. Please try again in a minute.',
+  }),
+);
+
 // Health check
 app.get('/', (c) => {
   return c.json({

package/src/middleware/rate-limit.ts

@@ -0,0 +1,112 @@
+import type { Context, MiddlewareHandler, Next } from 'hono';
+
+interface RateLimitOptions {
+  /** Time window in milliseconds */
+  windowMs: number;
+  /** Max requests per window */
+  max: number;
+  /** Message to return when rate limited */
+  message?: string;
+}
+
+interface RateLimitEntry {
+  count: number;
+  resetAt: number;
+}
+
+/**
+ * In-memory rate limiter store
+ * Can be swapped for Redis in production
+ */
+class RateLimitStore {
+  private store = new Map<string, RateLimitEntry>();
+
+  get(key: string): RateLimitEntry | undefined {
+    const entry = this.store.get(key);
+    if (entry && Date.now() > entry.resetAt) {
+      this.store.delete(key);
+      return undefined;
+    }
+    return entry;
+  }
+
+  increment(key: string, windowMs: number): RateLimitEntry {
+    const now = Date.now();
+    const existing = this.get(key);
+
+    if (existing) {
+      existing.count++;
+      return existing;
+    }
+
+    const entry: RateLimitEntry = {
+      count: 1,
+      resetAt: now + windowMs,
+    };
+    this.store.set(key, entry);
+    return entry;
+  }
+
+  cleanup(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store.entries()) {
+      if (now > entry.resetAt) {
+        this.store.delete(key);
+      }
+    }
+  }
+}
+
+const store = new RateLimitStore();
+
+// Cleanup expired entries every minute
+setInterval(() => store.cleanup(), 60 * 1000).unref();
+
+/**
+ * Get client IP from request
+ */
+function getClientIp(c: Context): string {
+  // Check common proxy headers
+  const forwarded = c.req.header('x-forwarded-for');
+  if (forwarded) {
+    return forwarded.split(',')[0].trim();
+  }
+
+  const realIp = c.req.header('x-real-ip');
+  if (realIp) {
+    return realIp;
+  }
+
+  // Vercel-specific
+  const vercelIp = c.req.header('x-vercel-forwarded-for');
+  if (vercelIp) {
+    return vercelIp.split(',')[0].trim();
+  }
+
+  return 'unknown';
+}
+
+/**
+ * Rate limiting middleware for Hono
+ */
+export function rateLimit(options: RateLimitOptions): MiddlewareHandler {
+  const { windowMs, max, message = 'Too many requests, please try again later' } = options;
+
+  return async (c: Context, next: Next) => {
+    const ip = getClientIp(c);
+    const key = `ratelimit:${ip}`;
+
+    const entry = store.increment(key, windowMs);
+
+    // Set rate limit headers
+    c.header('X-RateLimit-Limit', String(max));
+    c.header('X-RateLimit-Remaining', String(Math.max(0, max - entry.count)));
+    c.header('X-RateLimit-Reset', String(Math.ceil(entry.resetAt / 1000)));
+
+    if (entry.count > max) {
+      return c.json({ error: message }, 429);
+    }
+
+    await next();
+  };
+}

package/src/routes/scan.ts

@@ -3,26 +3,37 @@ import * as path from 'node:path';
 import { Hono } from 'hono';
 import { isSandboxAvailable, runScanInSandbox } from '../sandbox-runner';
 import { type ScanJob, type ScanResult, scanJobStore } from '../scan-worker';
+import { scanRequestSchema } from '../schemas/scan';
 
 export const scanRoute = new Hono();
 
-interface ScanRequestBody {
-  url: string;
-  ref?: string;
-  package?: string;
-}
-
 /**
  * POST /scan
  * Start a new scan job
  */
 scanRoute.post('/', async (c) => {
-  const body = await c.req.json<ScanRequestBody>();
+  // Parse JSON with error handling
+  let rawBody: unknown;
+  try {
+    rawBody = await c.req.json();
+  } catch {
+    return c.json({ error: 'Invalid JSON' }, 400);
+  }
 
-  if (!body.url) {
-    return c.json({ error: 'url is required' }, 400);
+  // Validate request body with Zod schema
+  const parsed = scanRequestSchema.safeParse(rawBody);
+  if (!parsed.success) {
+    return c.json(
+      {
+        error: 'Validation failed',
+        details: parsed.error.issues.map((i) => i.message),
+      },
+      400,
+    );
   }
 
+  const body = parsed.data;
+
   // Generate job ID
   const jobId = `scan-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 

package/src/scan-worker.ts

@@ -2,6 +2,8 @@
  * Scan job store and caching layer
  */
 
+import type { JobStore } from './stores/job-store.interface';
+
 export interface ScanResult {
   owner: string;
   repo: string;
@@ -42,8 +44,9 @@ const JOB_TTL_MS = 10 * 60 * 1000; // 10 minutes
 
 /**
  * In-memory job store with caching
+ * Implements JobStore interface for easy swap to Redis/KV
  */
-class ScanJobStore {
+class ScanJobStore implements JobStore {
   private jobs = new Map<string, ScanJob>();
   private cache = new Map<string, CacheEntry>();
 
@@ -123,9 +126,10 @@ class ScanJobStore {
 export const scanJobStore = new ScanJobStore();
 
 // Periodic cleanup every 5 minutes
+// Use .unref() to prevent keeping the process alive
 setInterval(
   () => {
     scanJobStore.cleanup();
   },
   5 * 60 * 1000,
-);
+).unref();

package/src/schemas/scan.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+
+/**
+ * Schema for POST /scan request body
+ * Validates and restricts URLs to GitHub only
+ */
+export const scanRequestSchema = z.object({
+  url: z
+    .string()
+    .url('Invalid URL format')
+    .regex(/^https:\/\/github\.com\//, 'Only GitHub URLs are allowed'),
+  ref: z.string().optional(),
+  package: z.string().optional(),
+});
+
+export type ScanRequestBody = z.infer<typeof scanRequestSchema>;

package/src/stores/job-store.interface.ts

@@ -0,0 +1,25 @@
+import type { ScanJob, ScanResult } from '../scan-worker';
+
+/**
+ * Interface for scan job storage
+ * Allows swapping in-memory store for Redis/KV in production
+ */
+export interface JobStore {
+  /** Get a job by ID */
+  get(jobId: string): ScanJob | undefined | Promise<ScanJob | undefined>;
+
+  /** Set/update a job */
+  set(jobId: string, job: ScanJob): void | Promise<void>;
+
+  /** Get cached scan result */
+  getFromCache(key: string): ScanResult | undefined | Promise<ScanResult | undefined>;
+
+  /** Cache a scan result */
+  setCache(key: string, result: ScanResult): void | Promise<void>;
+
+  /** Cleanup expired entries */
+  cleanup(): void | Promise<void>;
+
+  /** Get store statistics */
+  stats(): { jobs: number; cache: number } | Promise<{ jobs: number; cache: number }>;
+}