fix: update the endpoint

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

Author: ulemons

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

@@ -12,7 +12,7 @@ import { getAkritesExternalContactDetailBatch } from '../packages/getAkritesExte
 import { getAkritesExternalPackageDetail } from '../packages/getAkritesExternalPackageDetail'
 import { getAkritesExternalPackageDetailBatch } from '../packages/getAkritesExternalPackageDetailBatch'
 import { getBlastRadiusJob } from '../packages/getBlastRadiusJob'
-import { refreshAkritesExternalContactDetail } from '../packages/refreshAkritesExternalContactDetail'
+import { ingestAkritesExternalContactDetail } from '../packages/ingestAkritesExternalContactDetail'
 import { submitBlastRadiusJob } from '../packages/submitBlastRadiusJob'
 
 const rateLimiter = createRateLimiter({ max: 60, windowMs: 60 * 1000 })
@@ -36,10 +36,10 @@ const blastRadiusRateLimiter = envTunableRateLimiter(
   60 * 60 * 1000,
 )
 
-// /contacts/refresh blocks ~10-20s per request (vs. the read-only /contacts/detail
+// /contacts/ingest blocks ~10-20s per request (vs. the read-only /contacts/detail
 // endpoints), so it gets its own limiter. Defaults to 20 requests/hour.
-const contactRefreshRateLimiter = envTunableRateLimiter(
-  'AKRITES_CONTACT_REFRESH_RATE_LIMIT',
+const contactIngestRateLimiter = envTunableRateLimiter(
+  'AKRITES_CONTACT_INGEST_RATE_LIMIT',
   20,
   60 * 60 * 1000,
 )
@@ -74,19 +74,18 @@ export function akritesExternalRouter(): Router {
   // closest issued one — READ_MAINTAINER_ROLES (maintainer data) — NOT READ_PACKAGES.
   // TODO: swap for cdp:maintainers:read once issued.
   const contactsSubRouter = Router()
+  // rateLimiter first so requests failing the scope check still count against the quota
+  // (throttles repeated invalid-auth attempts, not just successful ones).
+  contactsSubRouter.use(rateLimiter)
   contactsSubRouter.use(requireScopes([SCOPES.READ_MAINTAINER_ROLES]))
-  contactsSubRouter.get('/detail', rateLimiter, safeWrap(getAkritesExternalContactDetail))
-  contactsSubRouter.post(
-    /^\/detail:batch\/?$/,
-    rateLimiter,
-    safeWrap(getAkritesExternalContactDetailBatch),
-  )
+  contactsSubRouter.get('/detail', safeWrap(getAkritesExternalContactDetail))
+  contactsSubRouter.post(/^\/detail:batch\/?$/, safeWrap(getAkritesExternalContactDetailBatch))
   // Sync, single-purl on-demand ingest — starts a Temporal workflow and blocks ~10-20s,
-  // so it gets the dedicated contactRefreshRateLimiter, not the shared rateLimiter above.
+  // so it stacks the dedicated contactIngestRateLimiter on top of the shared rateLimiter above.
   contactsSubRouter.post(
-    '/refresh',
-    contactRefreshRateLimiter,
-    safeWrap(refreshAkritesExternalContactDetail),
+    '/ingest',
+    contactIngestRateLimiter,
+    safeWrap(ingestAkritesExternalContactDetail),
   )
   router.use('/contacts', contactsSubRouter)
 

backend/src/api/public/v1/akrites-external/openapi.yaml

@@ -1247,9 +1247,9 @@ paths:
               schema:
                 $ref: '#/components/schemas/Error'
 
-  /akrites-external/contacts/refresh:
+  /akrites-external/contacts/ingest:
     post:
-      operationId: refreshContactDetail
+      operationId: ingestContactDetail
       summary: On-demand security-contacts ingest for a single PURL
       description: >
         Synchronous, single-purl only — no batch variant, since fanning this out over
@@ -1260,9 +1260,13 @@ paths:
         same purl attach to the same running workflow instead of starting duplicates.
 
 
+        Note: the underlying workflow only ingests contacts it has never seen before —
+        it does not refresh contacts already ingested for a purl.
+
+
         Rate limited independently of the other /contacts endpoints — default
-        20 requests/hour, tunable via AKRITES_CONTACT_REFRESH_RATE_LIMIT_MAX /
-        AKRITES_CONTACT_REFRESH_RATE_LIMIT_WINDOW_MS.
+        20 requests/hour, tunable via AKRITES_CONTACT_INGEST_RATE_LIMIT_MAX /
+        AKRITES_CONTACT_INGEST_RATE_LIMIT_WINDOW_MS.
 
 
         Not yet implemented: this is a synchronous, blocking call. Future work should

…reshAkritesExternalContactDetail.test.ts …gestAkritesExternalContactDetail.test.tsbackend/src/api/public/v1/packages/refreshAkritesExternalContactDetail.test.ts renamed to backend/src/api/public/v1/packages/ingestAkritesExternalContactDetail.test.ts backend/src/api/public/v1/packages/refreshAkritesExternalContactDetail.test.ts renamed to backend/src/api/public/v1/packages/ingestAkritesExternalContactDetail.test.ts

@@ -2,8 +2,9 @@ import type { Request, Response } from 'express'
 import { describe, expect, it, vi } from 'vitest'
 
 import type { AkritesExternalContactDetailRow } from '@crowd/data-access-layer'
+import { WorkflowIdConflictPolicy, WorkflowIdReusePolicy } from '@crowd/temporal'
 
-import { refreshAkritesExternalContactDetail } from './refreshAkritesExternalContactDetail'
+import { ingestAkritesExternalContactDetail } from './ingestAkritesExternalContactDetail'
 
 const { execute, getContactDetailsByPurls } = vi.hoisted(() => ({
   execute: vi.fn(),
@@ -54,20 +55,22 @@ function mockReqRes(body: unknown) {
   return { req, res, status, json }
 }
 
-describe('refreshAkritesExternalContactDetail', () => {
+describe('ingestAkritesExternalContactDetail', () => {
   it('executes ingestSecurityContactsForPurlWorkflow and returns the re-read contact detail', async () => {
     execute.mockResolvedValue({ found: true, repoId: 'repo-1' })
     getContactDetailsByPurls.mockResolvedValue([baseRow()])
 
     const { req, res, json } = mockReqRes({ purl: 'pkg:npm/lodash' })
 
-    await refreshAkritesExternalContactDetail(req, res)
+    await ingestAkritesExternalContactDetail(req, res)
 
     expect(execute).toHaveBeenCalledTimes(1)
     const [workflowType, options] = execute.mock.calls[0]
     expect(workflowType).toBe('ingestSecurityContactsForPurlWorkflow')
     expect(options.taskQueue).toBe('security-contacts-worker')
     expect(options.workflowId).toMatch(/^security-contacts-ondemand:[0-9a-f]{64}$/)
+    expect(options.workflowIdConflictPolicy).toBe(WorkflowIdConflictPolicy.USE_EXISTING)
+    expect(options.workflowIdReusePolicy).toBe(WorkflowIdReusePolicy.ALLOW_DUPLICATE)
     expect(options.args).toEqual(['pkg:npm/lodash'])
 
     expect(getContactDetailsByPurls).toHaveBeenCalledWith(expect.anything(), ['pkg:npm/lodash'])
@@ -79,11 +82,11 @@ describe('refreshAkritesExternalContactDetail', () => {
     getContactDetailsByPurls.mockResolvedValue([baseRow()])
 
     const { req: req1, res: res1 } = mockReqRes({ purl: 'pkg:npm/lodash' })
-    await refreshAkritesExternalContactDetail(req1, res1)
+    await ingestAkritesExternalContactDetail(req1, res1)
     const id1 = execute.mock.calls[0][1].workflowId
 
     const { req: req2, res: res2 } = mockReqRes({ purl: 'pkg:npm/lodash' })
-    await refreshAkritesExternalContactDetail(req2, res2)
+    await ingestAkritesExternalContactDetail(req2, res2)
     const id2 = execute.mock.calls[0][1].workflowId
 
     expect(id1).toBe(id2)
@@ -94,7 +97,7 @@ describe('refreshAkritesExternalContactDetail', () => {
 
     const { req, res } = mockReqRes({ purl: 'pkg:npm/left-pad' })
 
-    await expect(refreshAkritesExternalContactDetail(req, res)).rejects.toThrow()
+    await expect(ingestAkritesExternalContactDetail(req, res)).rejects.toThrow()
     expect(getContactDetailsByPurls).not.toHaveBeenCalled()
   })
 
@@ -104,13 +107,13 @@ describe('refreshAkritesExternalContactDetail', () => {
 
     const { req, res } = mockReqRes({ purl: 'pkg:npm/lodash' })
 
-    await expect(refreshAkritesExternalContactDetail(req, res)).rejects.toThrow()
+    await expect(ingestAkritesExternalContactDetail(req, res)).rejects.toThrow()
   })
 
   it('rejects a request missing purl without executing a workflow', async () => {
     const { req, res } = mockReqRes({})
 
-    await expect(refreshAkritesExternalContactDetail(req, res)).rejects.toThrow()
+    await expect(ingestAkritesExternalContactDetail(req, res)).rejects.toThrow()
     expect(execute).not.toHaveBeenCalled()
   })
 })

…s/refreshAkritesExternalContactDetail.ts …es/ingestAkritesExternalContactDetail.tsbackend/src/api/public/v1/packages/refreshAkritesExternalContactDetail.ts renamed to backend/src/api/public/v1/packages/ingestAkritesExternalContactDetail.ts backend/src/api/public/v1/packages/refreshAkritesExternalContactDetail.ts renamed to backend/src/api/public/v1/packages/ingestAkritesExternalContactDetail.ts

@@ -22,14 +22,18 @@ interface IngestSecurityContactsForPurlResult {
 // Deterministic, purl-derived workflowId: concurrent callers hitting the same purl attach
 // to the same running workflow (USE_EXISTING) instead of each starting their own ingest —
 // same pattern as integrationService.ts's github-nango-sync workflow start.
-function refreshWorkflowId(purl: string): string {
+function ingestWorkflowId(purl: string): string {
   return `${TemporalWorkflowId.SECURITY_CONTACTS_ONDEMAND}:${createHash('sha256').update(purl).digest('hex')}`
 }
 
 // Sync, single-purl on-demand ingest. Blocks ~10-20s (the worker's single-repo bound —
 // see security-contacts/workflows.ts's singleActs timeout) — no batch variant, since
 // fanning this out over many purls would multiply concurrent Temporal workflow starts.
-export async function refreshAkritesExternalContactDetail(
+//
+// Note: the workflow only ingests contacts it has never seen before — it does not
+// refresh/update contacts already ingested for a purl. That's why this endpoint is
+// named "ingest", not "refresh".
+export async function ingestAkritesExternalContactDetail(
   req: Request,
   res: Response,
 ): Promise<void> {
@@ -40,21 +44,21 @@ export async function refreshAkritesExternalContactDetail(
     (purl: string) => Promise<IngestSecurityContactsForPurlResult>
   >('ingestSecurityContactsForPurlWorkflow', {
     taskQueue: 'security-contacts-worker',
-    workflowId: refreshWorkflowId(purl),
+    workflowId: ingestWorkflowId(purl),
     workflowIdConflictPolicy: WorkflowIdConflictPolicy.USE_EXISTING,
     workflowIdReusePolicy: WorkflowIdReusePolicy.ALLOW_DUPLICATE,
     args: [purl],
   })
 
   if (!result.found) {
-    throw new NotFoundError()
+    throw new NotFoundError('Purl has no linked repository to ingest security contacts from')
   }
 
   const qx = await getPackagesQx()
   const [row] = await getContactDetailsByPurls(qx, [purl])
 
   if (!row) {
-    throw new NotFoundError()
+    throw new NotFoundError('Contact detail not found after ingest')
   }
 
   ok(res, toAkritesExternalContactDetail(row))