feat(calm-hub): add versioned document endpoints (Issue #2982) - #3002
feat(calm-hub): add versioned document endpoints (Issue #2982)#3002101Steeps wants to merge 4 commits into
Conversation
|
|
9d3e9c1 to
d1ce321
Compare
| /** Temporary Java-side POC contract pending a published shared contract. */ | ||
| private final DocumentService documentService; | ||
| public DocumentResource(DocumentService documentService) { this.documentService = documentService; } | ||
| @GET @Path("{namespace}/documents/{documentType}") @PermissionsAllowed(CalmHubScopes.READ) |
There was a problem hiding this comment.
The formatting here is very dense compared to the rest of the codebase. Here's the style to follow -PatternResource.java L55–76 shows a single endpoint with:
- Each annotation (
@GET,@Path,@Produces,@Operation,@PermissionsAllowed) on its own line @Operationwith bothsummaryanddescriptionfields- Method params on separate lines
- Try/catch bodies expanded, not single-line
- Logger field (L44) and logging in each catch block (L73)
Could you reformat the new resource to match?
There was a problem hiding this comment.
Updated 'DocumentResource' to follow style in PatternResource
| } | ||
| private boolean hasMappingFrontmatter(String markdown) { | ||
| if (markdown == null) return false; | ||
| java.util.regex.Matcher frontmatter = java.util.regex.Pattern |
There was a problem hiding this comment.
The frontmatter regex is compiled on every call - Pattern.compile() is relatively expensive and the compiled Pattern is thread-safe and immutable, so it only needs to happen once.
I noticed VERSION_PATTERN in MongoDocumentStore and NitriteDocumentStore are already done correctly as static fields - same approach should be applied here.
There was a problem hiding this comment.
Moved the frontmatter regex to the static fields so 'DocumentResource' only compiles the pattern once and resuses for each request
| @@ -0,0 +1,3 @@ | |||
| package org.finos.calm.store.producer; | |||
There was a problem hiding this comment.
@101Steeps - per ask, did a first scan through before making PR beyond draft.
Think you need to do run the file formatter :)
Have you had a chance to read through calm-hub/AGENTS.md? It covers the codebase conventions we follow. Might be worth checking your agent has this.
There was a problem hiding this comment.
Changed the files to match the repo and calm hub formatting conventions. I've read through the Agents.md for Calm-hub now and made sure its now included in the review step.
| public static final String VERSION_REGEX = "^(0|[1-9][0-9]*)[-.]?(0|[1-9][0-9]*)[-.]?(0|[1-9][0-9]*)$"; | ||
| public static final String VERSION_MESSAGE = "version must match pattern '^(0|[1-9][0-9]*)[-.]?(0|[1-9][0-9]*)[-.]?(0|[1-9][0-9]*)$'"; | ||
| /** Temporary POC types pending a shared Java-consumable document contract. */ | ||
| public static final Set<String> DOCUMENT_TYPES = Set.of("pattern", "architecture", "interface", "flow", "control", "schema", "timeline", "adr"); |
There was a problem hiding this comment.
This is the allow-list for /documents/{documentType} - I don't think this is the right list. These are the existing CALM resource types which already have their own dedicated endpoints (/patterns, /architectures, etc.). This should be narrative document types like knowledge, sad — no?
Probably worth calling it NARRATIVE_DOCUMENT_TYPES although variable naming was never my forte
There was a problem hiding this comment.
Added 'NARRATIVE_DOCUMENT_TYPES' (happy to use this variable name), with supported values 'knowledge' and 'sad'. Document endpoints reject unsupported narrative document types. I've added additional test evidence to the PR description to show Swagger and the Quarkus audit log for this
404833d to
3c72dce
Compare
2 participants
Description
Implements the spec described in Issue #2982 as a part of Issue #2981
Excerpt from Issue #2982:
Add a first-class Document resource to CALM Hub so a document (Markdown + structured frontmatter) can be created, retrieved, and updated by document type. This is the storage/API foundation for the Documents PoC and implements the decision in #2791 (documents are first-class, not decorators) using the document shape agreed in #2866.
Type of Change
Affected Components
cli/)calm/)calm-ai/)calm-hub/)calm-hub-ui/)calm-server/)calm-widgets/)docs/)shared/)calm-plugins/vscode/)Commit Message Format ✅
Testing
I have tested my changes locally
I have added/updated unit tests
All existing tests pass
npm run buildpassed.npm test -- --coveragepassed.npm run lintpassed with 0 errors. The command reported 11 warnings../mvnw clean install -Ddependency-check.skip=truepassed.calm-hubunit tests passed: 2,772 tests.calm-hubintegration tests passed: 537 tests.JaCoCo coverage checks passed for
calm-hub.Swagger testing passed. The document create endpoint returned
201 Created.The Swagger response included the versioned
Locationheader.Swagger testing confirmed a successful document create request.
The endpoint returned
201 Created.The response included a versioned
Locationheader.The audit log recorded
CREATE,DOCUMENT,swaggeraudit, document ID1, version1.0.0, andSUCCESS.Swagger / Quarkus Testing
Swagger endpoint discovery: Document endpoints for listing, creating, retrieving, and versioning narrative documents.
Swagger manual test: Creating a
knowledgedocument returned201 Createdwith a versionedLocationheader.Checklist