Repository navigation
feat: resolve AsyncAPI references, apply traits and check cross-object rules - #323
Conversation
There was a problem hiding this comment.
All reported issues were addressed across 14 files
Shadow auto-approve: would not auto-approve because issues were found.
View guided diff | Turn on auto-fix | Re-trigger cubic
There was a problem hiding this comment.
All reported issues were addressed across 8 files (changes from recent commits).
Shadow auto-approve: would not auto-approve because issues were found.
View guided diff | Turn on auto-fix | Re-trigger cubic
There was a problem hiding this comment.
0 issues found across 1 file (changes from recent commits).
Confidence score: 5/5
- Automated review surfaced no issues in the provided summaries.
- No files require special attention.
Shadow auto-approve: would require human review. Adds AsyncAPI reference resolution, trait application and cross-object checks, plus a shared marshaller fix preserving explicit nulls. The resolver introduces file/URL loading with permissive defaults; that security boundary and the trait-merge contract need human sign-off.
View guided diff | Turn on auto-fix | Re-trigger cubic
…-stage3-references
…handling is generic
There was a problem hiding this comment.
All reported issues were addressed across 15 files (changes from recent commits).
Shadow auto-approve: would not auto-approve because issues were found.
View guided diff | Turn on auto-fix | Re-trigger cubic
There was a problem hiding this comment.
0 issues found across 4 files (changes from recent commits).
Confidence score: 5/5
- Automated review surfaced no issues in the provided summaries.
- No files require special attention.
Shadow auto-approve: would not auto-approve. Auto-approval blocked by 1 unresolved issue from previous reviews.
View guided diff | Turn on auto-fix | Re-trigger cubic
* feat: check AsyncAPI sources in Arazzo source validation * fix: treat an empty AsyncAPI operation messages list as no messages * test: cover AsyncAPI step target edge cases in Arazzo source validation * test: assert the load warning in the AsyncAPI source edge case tests * feat: add openapi asyncapi validate command (#326) * feat: add openapi asyncapi validate command * chore: update cmd/openapi to the root module with the asyncapi package * docs: describe the AsyncAPI header check in arazzo validate help * chore: pin the CLI to the latest AsyncAPI stack root module * test: cover the asyncapi CLI command wiring and resolution errors * test: don't execute the process-exiting asyncapi command in tests
04c5645
into
feat/asyncapi-stage2-document-model
…and walking (#322) * feat: add complete AsyncAPI 3.x document model with local validation and walking * fix: address AsyncAPI document model review feedback * test: cover the AsyncAPI stage 2 document model, walker and references * feat: resolve AsyncAPI references, apply traits and check cross-object rules (#323) * feat: resolve AsyncAPI references, apply traits and check cross-object rules * fix: address AsyncAPI reference resolution review feedback * perf: skip the explicit null lookup for fields that are set * test: drop the AsyncAPI channel SyncChanges error test now that null handling is generic * fix: report AsyncAPI diagnostics on trait-merged mappings at the winning contributor * test: cover AsyncAPI reference resolution, traits, checks and null syncing * test: address review feedback on AsyncAPI stage 3 coverage tests * feat: check AsyncAPI sources in Arazzo source validation (#324) * feat: check AsyncAPI sources in Arazzo source validation * fix: treat an empty AsyncAPI operation messages list as no messages * test: cover AsyncAPI step target edge cases in Arazzo source validation * test: assert the load warning in the AsyncAPI source edge case tests * feat: add openapi asyncapi validate command (#326) * feat: add openapi asyncapi validate command * chore: update cmd/openapi to the root module with the asyncapi package * docs: describe the AsyncAPI header check in arazzo validate help * chore: pin the CLI to the latest AsyncAPI stack root module * test: cover the asyncapi CLI command wiring and resolution errors * test: don't execute the process-exiting asyncapi command in tests
* feat: add AsyncAPI stage 1 foundations (version policy, root/info models, AsyncAPI JSON Schema) * fix: address AsyncAPI stage 1 review feedback * fix: don't repeat the location in AsyncAPI schema type mismatch messages * test: cover the AsyncAPI stage 1 schema, info and version models * feat: add complete AsyncAPI 3.x document model with local validation and walking (#322) * feat: add complete AsyncAPI 3.x document model with local validation and walking * fix: address AsyncAPI document model review feedback * test: cover the AsyncAPI stage 2 document model, walker and references * feat: resolve AsyncAPI references, apply traits and check cross-object rules (#323) * feat: resolve AsyncAPI references, apply traits and check cross-object rules * fix: address AsyncAPI reference resolution review feedback * perf: skip the explicit null lookup for fields that are set * test: drop the AsyncAPI channel SyncChanges error test now that null handling is generic * fix: report AsyncAPI diagnostics on trait-merged mappings at the winning contributor * test: cover AsyncAPI reference resolution, traits, checks and null syncing * test: address review feedback on AsyncAPI stage 3 coverage tests * feat: check AsyncAPI sources in Arazzo source validation (#324) * feat: check AsyncAPI sources in Arazzo source validation * fix: treat an empty AsyncAPI operation messages list as no messages * test: cover AsyncAPI step target edge cases in Arazzo source validation * test: assert the load warning in the AsyncAPI source edge case tests * feat: add openapi asyncapi validate command (#326) * feat: add openapi asyncapi validate command * chore: update cmd/openapi to the root module with the asyncapi package * docs: describe the AsyncAPI header check in arazzo validate help * chore: pin the CLI to the latest AsyncAPI stack root module * test: cover the asyncapi CLI command wiring and resolution errors * test: don't execute the process-exiting asyncapi command in tests * refactor: return AsyncAPI reference chain results by value * chore: pin cmd/openapi to the merged AsyncAPI root module commit * test: use a platform absolute path in the AsyncAPI absolute reference test * test: cover the remaining AsyncAPI patch lines and drop unreachable error branches * chore: pin cmd/openapi to the latest AsyncAPI root module commit
Stacked on #322, which is stacked on #321. Review those first; this PR's base is the #322 branch.
Why
After Stage 2 the
asyncapipackage models a whole document, but every$refstays unresolved. So callers can't follow an operation to its channel or messages, traits are never applied, and rules that span objects (like "an operation's messages must belong to its channel") can't be checked. This PR adds the explicit resolution step from the plan. That makes Stages 1 to 3 together the usable library.What changed
(*AsyncAPI).ResolveAllReferences(ctx, ResolveAllOptions)with the same options as OpenAPI:AsyncAPILocation,DisableExternalRefs,VirtualFSandHTTPClient. It resolves every Reference Object, within the document and across files and URLs, following chains and resolving each relative reference against the document that contains it.Unmarshal,ValidateandWalkstill never do I/O.GetObject()onReferenced*wrappers now returns the resolved object (same as OpenAPI). It also addsGetResolvedReference(),ReferenceObject.GetChannel/GetMessage/GetServer(),Tag.GetResolved(),AsyncAPI.GetResolvedExternalDocs()andAsyncAPI.GetResolvedSchema().$refresolves to a typed schema. A Multi Format Schema Object whoseschemais a$refis resolved according to its format. JSON Schema based formats come back typed. Other formats, such as the spec's Avroschema: {$ref: './user-create.avsc'}, are loaded and kept unchanged, and a target that declares a differentschemaFormatis reported. Protocol Buffers text resources aren't loaded and get a warning.asyncapi/traits.go):Operation.GetEffective()andMessage.GetEffective()return a separate snapshot with traits applied using ordered JSON Merge Patch, with the object's own values winning.GetTraitSource(field)reports which trait each top-level field came from. Diagnostics that only appear once traits are applied are reported, and ones already reported on the object or trait are not repeated.asyncapi/checks.go): root operations must use a root channel, an operation's or reply's messages must be messages of its channel, root channels must use root servers, and a reply with a runtimeaddressneeds a channel without a fixed address.asyncapi/README.mdwith usage and a support-limits table.key: nullwhenever the public field was nil, so everyMarshaldropped explicit nulls (in all packages, not just AsyncAPI). Explicit nulls are kept now while the value is unset. This replaces the Stage 2 workaround incore.Channel.SyncChanges, which is removed.Review notes
$ref. Errors found in another document haveDocumentLocationset. The returnederroris only for things that stop resolution, such as a cancelled context.AsyncAPILocation, a relative reference to another document is reported rather than resolved against the working directory. The default HTTP client isn't a sandbox; the README says so and tells callers to pass their own client for untrusted input.references.Resolveis used behind an AsyncAPI-ownedResolutionTargetthat namespaces cached objects by kind and schema format, so one location is never reused as the wrong type. Each call starts with a fresh cache and clears the previous call's state, so edits are picked up and stale targets aren't returned. Effective views from earlier calls stay as snapshots.ResolveAllReferencessyncs public edits into the backing nodes so traits see them. That's why the explicit-null fix was needed: without it, syncing removeddescription: nullfrom traits, which changed both the document and the merge result.$refs nested inside schema bodies aren't resolved yet.Testing
asyncapi/resolve_test.gocovers:#/channels/x/messages/ythrough a referenced channelVirtualFSmarshaller/syncing_test.gocovers the explicit-null fix.mise cipasses locally, including race detection. It has to run outside the sandbox because the JSON Schema suite needslocalhost:1234.Summary by cubic
Adds explicit reference resolution for AsyncAPI documents so
$refs can be followed, traits are applied, and rules spanning objects can be checked. Previously references stayed unresolved, traits were never applied, and cross-object rules couldn't be checked, whileUnmarshal,Validate, andWalkstill never perform I/O.ResolveAllReferencesresolves references in-document, across files and URLs, using the same options as OpenAPI (AsyncAPILocation,DisableExternalRefs,VirtualFS,HTTPClient); missing targets, cycles, and wrong-kind references come back as validation diagnostics.$refs resolve by format: JSON Schema–based ones come back typed, other formats load unchanged, and a mismatchedschemaFormatis reported.GetObject()onReferenced*wrappers,GetResolvedReference(),ReferenceObject.GetChannel/GetMessage/GetServer(),Tag.GetResolved(), andAsyncAPI.GetResolvedExternalDocs()/GetResolvedSchema().Operation.GetEffective()andMessage.GetEffective()return snapshots with traits applied via ordered JSON Merge Patch;GetTraitSource()reports the originating trait, and diagnostics on trait-merged fields are reported at the contributor.addressneeds a channel without a fixed address.Tooling
openapi asyncapi validatecommand validates AsyncAPI 3.0/3.1 documents, optionally resolving external references.channelPathtargets, that steps only send headers declared by the target's effective messages, and thatcorrelationIdis only used with messages that declare one.key: nullentries during syncing; explicit nulls are preserved while the value is unset, replacing the workaround incore.Channel.SyncChanges, which is removed.Written for commit b6b4880. Summary will update on new commits.