feat: adding gc endpoint

[helio-frota]

Related to #1980 (comment)

Summary by Sourcery

Introduce a new garbage collection endpoint for orphaned PURLs

New Features:

• Add GET /api/v2/purl/gc handler to invoke PurlService::gc_purls

Documentation:

• Update OpenAPI spec to include the garbageCollect operation for the /api/v2/purl/gc path

Tests:

• Add integration test to verify the garbage collection endpoint returns the expected count

[sourcery-ai]

Reviewer's Guide

Introduces a new GET /api/v2/purl/gc endpoint in the purl service that invokes the gc_purls method to perform garbage collection of orphaned packages, complete with route registration, API documentation, and an integration test.

Sequence diagram for the new garbage collection endpoint

sequenceDiagram
  participant Client
  participant "API Server"
  participant "PurlService"
  participant "Database"
  Client->>"API Server": GET /api/v2/purl/gc
  "API Server"->>"PurlService": gc_purls(db)
  "PurlService"->>"Database": Query for orphaned packages
  "Database"-->>"PurlService": List of orphaned packages
  "PurlService"->>"Database": Delete orphaned packages
  "Database"-->>"PurlService": Deletion result
  "PurlService"-->>"API Server": GC result (string)
  "API Server"-->>Client: 200 OK (GC result)

Loading

File-Level Changes

Change	Details	Files
Add garbage collection endpoint for purl service	Register GET /v2/purl/gc route in service config Implement gc handler invoking service.gc_purls and returning the result Annotate handler with utoipa for OpenAPI Update openapi.yaml to document /api/v2/purl/gc	modules/fundamental/src/purl/endpoints/mod.rs openapi.yaml
Add integration test for garbage collection endpoint	Write test to call /api/v2/purl/gc and verify HTTP 200 status Assert response body equals expected count Setup database and application context in test	modules/fundamental/src/purl/endpoints/test.rs

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey there - I've reviewed your changes - here's some feedback:

• The OpenAPI spec registers the GC response as text/plain but the handler returns JSON, so update the documented content type or change the response to plain text to keep them in sync.
• Garbage collection mutates data, so consider using a write-level permission guard instead of Require to prevent unauthorized access.
• Double-check that the route path in the handler ("/v2/purl/gc") aligns with how your service is mounted under "/api" to avoid unexpected 404 errors.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The OpenAPI spec registers the GC response as text/plain but the handler returns JSON, so update the documented content type or change the response to plain text to keep them in sync.
- Garbage collection mutates data, so consider using a write-level permission guard instead of Require<ReadSbom> to prevent unauthorized access.
- Double-check that the route path in the handler ("/v2/purl/gc") aligns with how your service is mounted under "/api" to avoid unexpected 404 errors.

## Individual Comments

### Comment 1
<location> `modules/fundamental/src/purl/endpoints/mod.rs:85-93` </location>
<code_context>
     Ok(HttpResponse::Ok().json(service.purls(search, paginated, db.as_ref()).await?))
 }

+#[utoipa::path(
+    operation_id = "garbageCollect",
+    tag = "purl",
+    responses(
+        (status = 200, description = "Performs garbage collection for orphaned packages", body = String),
+    ),
+)]
+#[get("/v2/purl/gc")]
+pub async fn gc(
+    service: web::Data<PurlService>,
+    db: web::Data<Database>,
</code_context>

<issue_to_address>
**issue:** The gc endpoint currently returns a JSON-encoded string, but the OpenAPI spec expects text/plain.

Use HttpResponse::Ok().body(...) to return plain text, or update the OpenAPI spec to expect application/json for this endpoint.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[jcrossley3]

Looks good. Just one minor nit.

[codecov]

Codecov Report

❌ Patch coverage is 88.88889% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 67.75%. Comparing base (89bf882) to head (bbb69bd).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
modules/fundamental/src/purl/endpoints/mod.rs	88.88%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1996      +/-   ##
==========================================
- Coverage   68.00%   67.75%   -0.25%     
==========================================
  Files         355      355              
  Lines       19807    19816       +9     
  Branches    19807    19816       +9     
==========================================
- Hits        13470    13427      -43     
- Misses       5557     5613      +56     
+ Partials      780      776       -4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[trustify-ci-bot]

Backport failed for release/0.3.z, because it was unable to cherry-pick the commit(s).

Please cherry-pick the changes locally and resolve any conflicts.

git fetch origin release/0.3.z
git worktree add -d .worktree/backport-1996-to-release/0.3.z origin/release/0.3.z
cd .worktree/backport-1996-to-release/0.3.z
git switch --create backport-1996-to-release/0.3.z
git cherry-pick -x 9d0f3ac52b6560ff412cd1a945d991446a85a457