feat: add comments

Signed-off-by: Umberto Sgueglia <usgueglia@contractor.linuxfoundation.org>

Author: ulemons

backend/src/api/public/v1/akrites/index.ts

@@ -15,28 +15,37 @@ import { escalateHandler } from '../stewardships/escalate'
 import { openStewardship } from '../stewardships/openStewardship'
 import { updateStatusHandler } from '../stewardships/updateStatus'
 
-const rateLimiter = createRateLimiter({ max: 60, windowMs: 60 * 1000 })
+// Separate instances match the original per-router isolation: packages and stewardships each had
+// their own createRateLimiter() call, giving independent 60 req/min buckets per IP.
+const packagesRateLimiter = createRateLimiter({ max: 60, windowMs: 60 * 1000 })
+const stewardshipsRateLimiter = createRateLimiter({ max: 60, windowMs: 60 * 1000 })
 
 export function akritesRouter(): Router {
   const router = Router()
 
   router.get('/metrics', safeWrap(metricsHandler))
-  // /packages/scatter must be registered before /packages to avoid Express treating 'scatter' as a path param
+  // /packages/scatter registered before router.use('/packages', ...) so Express evaluates this
+  // explicit route first; without this ordering the sub-router would receive the request first
+  // and call next() on no match, adding unnecessary overhead.
   router.get('/packages/scatter', safeWrap(packageScatterHandler))
   router.get('/packages', safeWrap(packageListHandler))
   router.get('/activity', safeWrap(activityFeedHandler))
 
   // --- packages ---
-  router.post(/^\/packages:batch-stewardship\/?$/, rateLimiter, safeWrap(batchGetStewardship))
+  router.post(
+    /^\/packages:batch-stewardship\/?$/,
+    packagesRateLimiter,
+    safeWrap(batchGetStewardship),
+  )
   const packagesSubRouter = Router()
-  packagesSubRouter.use(rateLimiter)
+  packagesSubRouter.use(packagesRateLimiter)
   packagesSubRouter.get('/metrics', safeWrap(getPackagesMetrics))
   packagesSubRouter.get('/detail', safeWrap(getPackage))
   router.use('/packages', packagesSubRouter)
 
   // --- stewardships ---
   const stewardshipsSubRouter = Router()
-  stewardshipsSubRouter.use(rateLimiter)
+  stewardshipsSubRouter.use(stewardshipsRateLimiter)
   stewardshipsSubRouter.post('/', safeWrap(openStewardship))
   stewardshipsSubRouter.put('/:id/steward', safeWrap(assignStewardHandler))
   stewardshipsSubRouter.put('/:id/escalate', safeWrap(escalateHandler))

backend/src/api/public/v1/ossprey/index.ts

@@ -7,7 +7,8 @@ import { metricsHandler } from './metrics'
 import { packageListHandler } from './packageList'
 import { packageScatterHandler } from './packageScatter'
 
-// TODO[deprecate]: superseded by /v1/akrites/ossprey — remove once consumers have migrated
+// TODO[deprecate]: superseded by /v1/akrites — ossprey endpoints are now at /v1/akrites/metrics,
+// /v1/akrites/packages, /v1/akrites/packages/scatter, /v1/akrites/activity — remove once consumers have migrated
 export function osspreyRouter(): Router {
   const router = Router()
 

backend/src/api/public/v1/packages/index.ts

@@ -12,7 +12,11 @@ import { listPackages } from './listPackages'
 
 const rateLimiter = createRateLimiter({ max: 60, windowMs: 60 * 1000 })
 
-// TODO[deprecate]: superseded by /v1/akrites/packages — remove once consumers have migrated
+// TODO[deprecate]: /packages/metrics and /packages/detail are superseded by /v1/akrites/packages/metrics
+// and /v1/akrites/packages/detail — remove once consumers have migrated.
+// NOTE: GET /packages (listPackages) is intentionally NOT replicated in /v1/akrites because it has a
+// different response shape from GET /v1/akrites/packages (ossprey packageListHandler). Before removing,
+// verify no consumer calls GET /v1/packages — if unused, delete listPackages and this route entirely.
 export function packagesRouter(): Router {
   const router = Router()