docs(adr): add ADR for configurable SBOM duplicate handling #2188
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Proposes onDuplicate parameter with three modes (ingest, ignore, replace) to handle SBOMs with duplicate document identifiers. Assisted-by: Claude Signed-off-by: Dejan Bosanac <dbosanac@redhat.com>
Contributor
Reviewer's GuideAdds a new ADR describing a configurable onDuplicate parameter with three handling modes (ingest, ignore, replace) for SBOMs with duplicate document identifiers, including API and importer configuration and high-level implementation scope. Sequence diagram for SBOM upload with configurable onDuplicate handlingsequenceDiagram
actor Client
participant ApiV2 as ApiV2SbomEndpoint
participant Ingestor as IngestorService
participant Graph as GraphLayer
participant DB as Database
participant Store as SbomStorage
Client->>ApiV2: POST /api/v2/sbom (sbom, onDuplicate)
ApiV2->>Ingestor: ingest(sbomContent, onDuplicate, source, metadata)
Ingestor->>Graph: get_sbom_by_document_id(documentId)
Graph-->>Ingestor: existingSbom or null
alt onDuplicate = ingest or existingSbom is null
Ingestor->>Store: saveSbomBlob(sbomContent)
Store-->>Ingestor: storageLocation
Ingestor->>DB: insertSbomRecord(documentId, hash, storageLocation)
DB-->>Ingestor: sbomRecord
Ingestor-->>ApiV2: NewSbomInfo
ApiV2-->>Client: 201 Created
else onDuplicate = ignore and existingSbom not null
Ingestor-->>ApiV2: ExistingSbomInfo
ApiV2-->>Client: 200 OK (duplicate ignored)
else onDuplicate = replace and existingSbom not null
Ingestor->>Store: deleteSbomBlob(existingSbom.storageLocation)
Ingestor->>DB: deleteSbomRecord(existingSbom.id)
DB-->>Ingestor: deleted
Ingestor->>Store: saveSbomBlob(sbomContent)
Store-->>Ingestor: storageLocation
Ingestor->>DB: insertSbomRecord(documentId, hash, storageLocation)
DB-->>Ingestor: sbomRecord
Ingestor-->>ApiV2: NewSbomInfo
ApiV2-->>Client: 200 OK (replaced)
end
Sequence diagram for importer using onDuplicate behaviorsequenceDiagram
participant Scheduler
participant Importer as SbomImporter
participant Remote as SbomSource
participant Ingestor as IngestorService
participant Graph as GraphLayer
participant DB as Database
participant Store as SbomStorage
Scheduler->>Importer: triggerImport()
Importer->>Remote: fetchSbomList()
Remote-->>Importer: sbomReferences
loop for each sbomReference
Importer->>Remote: fetchSbom(sbomReference)
Remote-->>Importer: sbomContent
Importer->>Ingestor: ingest(sbomContent, config.onDuplicate, importerName, metadata)
Ingestor->>Graph: get_sbom_by_document_id(documentId)
Graph-->>Ingestor: existingSbom or null
alt config.onDuplicate = ignore and existingSbom not null
Ingestor-->>Importer: ExistingSbomInfo (skipped)
else config.onDuplicate = replace and existingSbom not null
Ingestor->>Store: deleteSbomBlob(existingSbom.storageLocation)
Ingestor->>DB: deleteSbomRecord(existingSbom.id)
DB-->>Ingestor: deleted
Ingestor->>Store: saveSbomBlob(sbomContent)
Store-->>Ingestor: storageLocation
Ingestor->>DB: insertSbomRecord(documentId, hash, storageLocation)
DB-->>Ingestor: sbomRecord
Ingestor-->>Importer: NewSbomInfo (replaced)
else other cases
Ingestor->>Store: saveSbomBlob(sbomContent)
Store-->>Ingestor: storageLocation
Ingestor->>DB: insertSbomRecord(documentId, hash, storageLocation)
DB-->>Ingestor: sbomRecord
Ingestor-->>Importer: NewSbomInfo (ingested)
end
end
Class diagram for configurable onDuplicate handlingclassDiagram
class ApiV2SbomEndpoint {
+uploadSbom(requestBody, onDuplicateQuery, sourceHeader)
+parseOnDuplicate(onDuplicateQuery) OnDuplicateMode
}
class ImporterConfigEndpoint {
+createSbomImporter(name, source, onDuplicate, period)
+updateSbomImporter(name, source, onDuplicate, period)
}
class SbomImporter {
+string name
+string source
+OnDuplicateMode onDuplicate
+string period
+run()
+fetchSbomReferences()
+fetchSbom(reference)
}
class IngestorService {
+ingest(sbomContent, onDuplicate, source, metadata) SbomInfo
-handleIngestMode(sbomContent, documentId, source, metadata) SbomInfo
-handleIgnoreMode(existingSbom) SbomInfo
-handleReplaceMode(existingSbom, sbomContent, documentId, source, metadata) SbomInfo
}
class GraphLayer {
+get_sbom_by_document_id(documentId) SbomRecord
}
class SbomRecord {
+string id
+string documentId
+string hash
+string storageLocation
+string format
}
class SbomInfo {
+string id
+string documentId
+string status
+string modeApplied
}
class OnDuplicateMode {
<<enumeration>>
ingest
ignore
replace
}
class Database {
+insertSbomRecord(documentId, hash, storageLocation, format) SbomRecord
+deleteSbomRecord(id)
}
class SbomStorage {
+saveSbomBlob(sbomContent) string
+deleteSbomBlob(storageLocation)
}
ApiV2SbomEndpoint --> IngestorService : uses
ImporterConfigEndpoint --> SbomImporter : configures
SbomImporter --> IngestorService : calls ingest
IngestorService --> GraphLayer : queries
IngestorService --> Database : writes
IngestorService --> SbomStorage : manages blobs
GraphLayer --> SbomRecord : returns
Database --> SbomRecord : persists
IngestorService --> SbomInfo : returns
SbomImporter --> OnDuplicateMode
ApiV2SbomEndpoint --> OnDuplicateMode
IngestorService --> OnDuplicateMode
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey there - I've reviewed your changes - here's some feedback:
- The ADR filename is
00013-...but the heading uses# 00011. ...; consider aligning the ADR number in the title with the filename/sequence for consistency. - It would be useful to clarify how
onDuplicateshould behave when an SBOM is missing adocumentNamespace/serialNumberor has an invalid/blank identifier (e.g., fallback to hash-based behavior or treat asingest).
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The ADR filename is `00013-...` but the heading uses `# 00011. ...`; consider aligning the ADR number in the title with the filename/sequence for consistency.
- It would be useful to clarify how `onDuplicate` should behave when an SBOM is missing a `documentNamespace`/`serialNumber` or has an invalid/blank identifier (e.g., fallback to hash-based behavior or treat as `ingest`).
## Individual Comments
### Comment 1
<location> `docs/adrs/00013-configurable-sbom-duplicate-handling.md:1` </location>
<code_context>
+# 00011. Configurable SBOM Duplicate Handling
+
+## Status
</code_context>
<issue_to_address>
**issue (typo):** ADR number in the title does not match the filename and may be confusing.
The file is named `00013-...` but the ADR title starts with `00011.` Please update the heading number to match the filename, or add a brief note if the mismatch is intentional, to avoid confusion when referencing this ADR.
```suggestion
# 00013. Configurable SBOM Duplicate Handling
```
</issue_to_address>
### Comment 2
<location> `docs/adrs/00013-configurable-sbom-duplicate-handling.md:48-50` </location>
<code_context>
+Add optional `onDuplicate` query parameter to SBOM upload endpoint:
+
+```bash
+# Ignore duplicates - skip if already exists
+cat sbom.json | http POST localhost:8080/api/v2/sbom onDuplicate=ignore
+
</code_context>
<issue_to_address>
**nitpick (typo):** Minor grammar tweak: add "it" to read more naturally.
Suggest rephrasing this line to `# Ignore duplicates - skip if it already exists` for smoother readability.
```suggestion
Add optional `onDuplicate` query parameter to SBOM upload endpoint:
```bash
# Ignore duplicates - skip if it already exists
cat sbom.json | http POST localhost:8080/api/v2/sbom onDuplicate=ignore
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
| @@ -0,0 +1,118 @@ | |||
| # 00011. Configurable SBOM Duplicate Handling | |||
Contributor
There was a problem hiding this comment.
issue (typo): ADR number in the title does not match the filename and may be confusing.
The file is named 00013-... but the ADR title starts with 00011. Please update the heading number to match the filename, or add a brief note if the mismatch is intentional, to avoid confusion when referencing this ADR.
Suggested change
| # 00011. Configurable SBOM Duplicate Handling | |
| # 00013. Configurable SBOM Duplicate Handling |
Comment on lines
+48
to
+50
| Add optional `onDuplicate` query parameter to SBOM upload endpoint: | ||
|
|
||
| ```bash |
Contributor
There was a problem hiding this comment.
nitpick (typo): Minor grammar tweak: add "it" to read more naturally.
Suggest rephrasing this line to # Ignore duplicates - skip if it already exists for smoother readability.
Suggested change
| Add optional `onDuplicate` query parameter to SBOM upload endpoint: | |
| ```bash | |
| Add optional `onDuplicate` query parameter to SBOM upload endpoint: | |
| ```bash | |
| # Ignore duplicates - skip if it already exists | |
| cat sbom.json | http POST localhost:8080/api/v2/sbom onDuplicate=ignore |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #2188 +/- ##
=======================================
Coverage 68.24% 68.24%
=======================================
Files 376 376
Lines 21208 21208
Branches 21208 21208
=======================================
Hits 14473 14473
+ Misses 5868 5864 -4
- Partials 867 871 +4 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
ruromero
approved these changes
Dec 18, 2025
Contributor
ruromero
left a comment
ruromero
left a comment
There was a problem hiding this comment.
I agree with the suggested approach. I could suggest adding versioning to the existing solutions in case you want to add more complex capabilities but the suggested ones add enough flexibility
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Proposes onDuplicate parameter with three modes (ingest, ignore, replace) to handle SBOMs with duplicate document identifiers.
Assisted-by: Claude
Summary by Sourcery
Documentation: