feat: resolve AsyncAPI references, apply traits and check cross-object rules
Stacked on #322, which is stacked on #321. Review those first; this PR's base is the #322 branch.
Why
After Stage 2 the asyncapi package models a whole document, but every $ref stays 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.- Resolved accessors:
GetObject()onReferenced*wrappers now returns the resolved object (same as OpenAPI). It also addsGetResolvedReference(),ReferenceObject.GetChannel/GetMessage/GetServer(),Tag.GetResolved(),AsyncAPI.GetResolvedExternalDocs()andAsyncAPI.GetResolvedSchema(). - Schema references: a native schema
$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. - Traits (
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. - Cross-object checks (
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.- Shared marshaller fix: syncing used to delete an authored
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
- Failures are diagnostics, not errors. Missing and wrong-kind targets, cycles, disallowed external refs and problems in loaded documents come back as validation errors at the referring
$ref. Errors found in another document haveDocumentLocationset. The returnederroris only for things that stop resolution, such as a cancelled context. - No guessing a base directory. Without
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. - Cache and refresh. The shared
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. - Resolution doesn't change the document.
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. - Walking is unchanged. It still visits only authored locations and doesn't follow resolved references.
- Known limits, also in the README:
$refs nested inside schema bodies aren't resolved yet.- An effective view's own references are only resolved when all its traits come from the same document as the object.
- Wrong-kind targets in other documents are caught by validating the loaded object rather than by checking its location.
Testing
asyncapi/resolve_test.gocovers:- in-document resolution through chains, including messages reached via
#/channels/x/messages/ythrough a referenced channel - multi-file relative chains with an in-memory
VirtualFS - remote relative chains with a fake HTTP client
- preserving an Avro resource unchanged
- a table of error cases: missing, wrong-kind, cycles, disabled, no location, missing file, denied client, each scope rule, format mismatch, Protocol Buffers, invalid external object
- trait precedence and null deletion, provenance, an inherited diagnostic, ignored forbidden trait fields
- refresh after edits and stale-target clearing
- no implicit I/O (counting filesystem and client)
- cancellation, walk unchanged after resolution, concurrent reads during resolution
- in-document resolution through chains, including messages reached via
marshaller/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, while Unmarshal, Validate, and Walk still 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.- Schema
$refs resolve by format: JSON Schema–based ones come back typed, other formats load unchanged, and a mismatchedschemaFormatis reported. - Resolved accessors:
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.- Cross-object checks: root operations use root channels, an operation's or reply's messages belong to its channel, root channels use root servers, and a reply with a runtime
addressneeds a channel without a fixed address.
Tooling
- New
openapi asyncapi validatecommand validates AsyncAPI 3.0/3.1 documents, optionally resolving external references. - Arazzo source validation now loads AsyncAPI sources and checks
channelPathtargets, that steps only send headers declared by the target's effective messages, and thatcorrelationIdis only used with messages that declare one. - Fixes a shared marshaller bug that deleted authored
key: nullentries during syncing; explicit nulls are preserved while the value is unset, replacing the workaround incore.Channel.SyncChanges, which is removed.