Add '/v4/my-clas/identities' API and util script to test the entire 'MyCLAs' APIs group

[lukaszgryglicki]

cc @mlehotskylf @ahmedomosanya

Signed-off-by: Łukasz Gryglicki lgryglicki@cncf.io

Assisted by OpenAI

Assisted by GitHub Copilot

Assisted by Claude

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2f24a4be-1f76-4930-a9fe-dae77761f285

📥 Commits

Reviewing files that changed from the base of the PR and between 7119deb and 4e867cd.

📒 Files selected for processing (1)

• utils/local-fbsd-api.sh

🚧 Files skipped from review as they are similar to previous changes (1)

• utils/local-fbsd-api.sh

---

Walkthrough

Adds an authenticated My CLAs identities endpoint that combines EasyCLA and platform identities into a sorted, deduplicated response, with OpenAPI definitions, service tests, documentation, and command-line utilities.

Changes

My CLAs identities

Layer / File(s)	Summary
Identity API contract cla-backend-go/swagger/cla.v2.yaml, cla-backend-go/swagger/common/my-identity-list.yaml	Defines GET /my-clas/identities, authentication headers, error responses, and the my-identity-list response schema.
Identity handler and aggregation cla-backend-go/v2/my_clas/handlers.go, cla-backend-go/v2/my_clas/service.go, cla-backend-go/v2/my_clas/service_test.go	Authenticates the caller, loads EasyCLA and platform identities, deduplicates and sorts <type>:<value> entries, and tests successful and empty-username responses.
Endpoint documentation docs/MY_CLAS_API.md	Documents endpoint scope, identity sources, formatting, sorting, deduplication, authorization, and smoke-test usage.
Identity lookup and API utilities utils/get_ddb_user_identities.sh, utils/get_user_svc.sh, utils/my_clas.sh, utils/local-fbsd-api.sh	Adds DynamoDB and user-service lookup scripts, endpoint invocation modes, authentication handling, local execution, response formatting, and timing output.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant MyClasHandler
  participant MyClasService
  participant EasyCLARepository
  participant PlatformUserService
  Client->>MyClasHandler: GET /v4/my-clas/identities
  MyClasHandler->>MyClasService: GetMyIdentities(username)
  MyClasService->>EasyCLARepository: GetUsersByLFUsername(username)
  MyClasService->>PlatformUserService: loadPlatformIdentities(username)
  MyClasService-->>MyClasHandler: Sorted MyIdentityList
  MyClasHandler-->>Client: 200 response

Loading

Possibly related PRs

• linuxfoundation/easycla#5125: Modifies the same My CLAs handler and service area with authenticated routes and principal-based identity resolution.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description is generic metadata and does not describe the pull request changes.	Replace it with a brief summary of the new API endpoint, service changes, and utility scripts.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: a new My CLAs identities API plus a utility script.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch unicron-my-clas-api-test-utils

---

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Adds an authenticated /v4/my-clas/identities endpoint and diagnostic utilities for My CLAs identity resolution.

Changes:

• Defines and implements identity enumeration with unit coverage.
• Documents the endpoint and Self Serve integration.
• Adds local/API diagnostic scripts.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
utils/my_clas.sh	Exercises My CLAs endpoints.
utils/local-fbsd-api.sh	Starts a local FreeBSD backend.
utils/get_user_svc.sh	Inspects platform identities.
utils/get_ddb_user_identities.sh	Inspects EasyCLA identities.
docs/MY_CLAS_API.md	Documents identity enumeration.
cla-backend-go/v2/my_clas/service.go	Aggregates identity sources.
cla-backend-go/v2/my_clas/service_test.go	Tests identity aggregation.
cla-backend-go/v2/my_clas/handlers.go	Wires the endpoint handler.
cla-backend-go/swagger/common/my-identity-list.yaml	Defines the response model.
cla-backend-go/swagger/cla.v2.yaml	Defines the API operation.

Comments suppressed due to low confidence (2)

cla-backend-go/v2/my_clas/service.go:315

• loadPlatformIdentities deliberately converts user-service errors into an empty set for fail-closed authorization. Reusing it here turns an upstream outage into a successful but incomplete identity list, even though this endpoint promises the union of both sources; consumers cannot distinguish missing identities from a genuinely empty platform profile. Use a strict/error-returning load path for this listing endpoint and return 500 when either platform lookup fails.

	platform := s.loadPlatformIdentities(ctx, currentUsername)

utils/get_user_svc.sh:70

• A failed identities page (including any page after the first) is parsed as empty and terminates pagination with exit status 0, producing a partial identity list. Check curl's HTTP/transport status before printing or counting the page.

  page="$(curl -sS -XGET "${hdr[@]}" "${GW}/user-service/v1/users/${sfid}/identities?pageSize=100&offset=${offset}")"

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

cla-backend-go/swagger/common/my-identity-list.yaml (1)

4-22: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Align the schema with the documented response invariants.

The response description promises lfUsername, resultCount, and a deduplicated identities array, but all properties are optional and duplicate array items are allowed. Add the required fields and uniqueItems: true so generated clients and validators enforce the endpoint contract.

Proposed schema fix

 type: object
 x-nullable: false
 title: My Identity List
 description: The deduplicated identities connected to the authenticated user, each formatted as "<type>:<value>"
+required:
+  - lfUsername
+  - resultCount
+  - identities
 properties:
...
   identities:
     type: array
+    uniqueItems: true

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cla-backend-go/swagger/common/my-identity-list.yaml` around lines 4 - 22,
Update the My Identity List schema properties to mark lfUsername, resultCount,
and identities as required, and add uniqueItems: true to the identities array.
Preserve the existing types, descriptions, and item definition while ensuring
generated clients and validators enforce the documented response invariants.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@cla-backend-go/v2/my_clas/service.go`:
- Around line 315-325: Update the identity aggregation flow around
loadPlatformIdentities so this endpoint uses a strict platform/profile and
connected-identity lookup that propagates either lookup failure instead of
returning an empty set. Preserve the union with EasyCLA identities on success,
return an error rather than a successful incomplete response on failure, and add
tests covering both platform lookup failure cases.

In `@utils/get_ddb_user_identities.sh`:
- Around line 19-24: Make both utilities fail on upstream lookup errors instead
of emitting empty identities: in utils/get_ddb_user_identities.sh lines 19-24,
enable pipefail so an AWS query failure propagates through the jq pipeline
before parsing; in utils/get_user_svc.sh lines 51-75, configure curl with
--fail-with-body or explicitly validate response status codes and exit before
parsing failed profile or page responses.

In `@utils/local-fbsd-api.sh`:
- Around line 1-6: Add a shell interpreter declaration and the
repository-required copyright/SPDX header to the setup script, then enable
fail-fast behavior before executing commands. Ensure failures from the directory
change, Go build, or environment-file sourcing stop execution so the final
cla-fbsd launch only occurs after successful setup.

---

Nitpick comments:
In `@cla-backend-go/swagger/common/my-identity-list.yaml`:
- Around line 4-22: Update the My Identity List schema properties to mark
lfUsername, resultCount, and identities as required, and add uniqueItems: true
to the identities array. Preserve the existing types, descriptions, and item
definition while ensuring generated clients and validators enforce the
documented response invariants.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 226faa0a-4363-4842-907b-679d7004d970

📥 Commits

Reviewing files that changed from the base of the PR and between 5ad085c and 9c3195d.

📒 Files selected for processing (10)

• cla-backend-go/swagger/cla.v2.yaml
• cla-backend-go/swagger/common/my-identity-list.yaml
• cla-backend-go/v2/my_clas/handlers.go
• cla-backend-go/v2/my_clas/service.go
• cla-backend-go/v2/my_clas/service_test.go
• docs/MY_CLAS_API.md
• utils/get_ddb_user_identities.sh
• utils/get_user_svc.sh
• utils/local-fbsd-api.sh
• utils/my_clas.sh

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

cla-backend-go/v2/my_clas/service.go:315

• loadPlatformIdentities deliberately converts user-service lookup/list failures into an empty set, so this new endpoint returns 200 with only the DynamoDB identities during a user-service outage. Consumers cannot distinguish that partial result from the documented complete union and may omit valid identities/CLAs. For this listing path, propagate platform lookup failures (while retaining fail-closed behavior for authorization) so the handler returns 500 instead of an authoritative-looking partial response.

	platform := s.loadPlatformIdentities(ctx, currentUsername)

utils/local-fbsd-api.sh:1

• This new shell source still lacks the repository-standard license header present in the other added utility scripts (utils/my_clas.sh:1-3, utils/get_user_svc.sh:1-3, and utils/get_ddb_user_identities.sh:1-3). Add it immediately after the shebang.

#!/bin/bash

utils/local-fbsd-api.sh:3

• If either cd or go build fails, the script continues and can launch a stale bin/cla-fbsd, making API validation run against old code. Exit on command failure before starting the server.

cd cla-backend-go
go build -o bin/cla-fbsd main.go

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

cla-backend-go/v2/my_clas/service.go:315

• loadPlatformIdentities deliberately turns user-service lookup/list failures into an empty or partial set (lines 501–550). Reusing it here therefore returns 200 with incomplete identities during an upstream outage, even though this endpoint promises the union/exact searchable set; consumers can silently miss CLAs. Use an error-reporting variant for this endpoint and propagate the failure, while preserving the authorization path's fail-closed behavior.

	platform := s.loadPlatformIdentities(ctx, currentUsername)